Something went wrong. Try again.
An HTTP library for Zig 0.17, server and client, HTTP/1.0 through HTTP/3, with the protocol in a module that owns no socket.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! One request, as a handler sees it.//!//! Everything here is HTTP semantics and none of it is HTTP/1.1: the method,//! the target, the fields and the body are the same four things an HTTP/2//! HEADERS frame and its DATA frames carry, and a driver for that version//! would fill in exactly this struct. What is deliberately *not* here is the//! framing — there is no way to ask whether the body arrived chunked, because//! a handler that cared could not be run over HTTP/2, where the question has//! no answer.//!//! Nothing in here outlives the call to the handler. The names and values//! point into the buffer the head was read into, which the next request on a//! kept-alive connection will overwrite, and `arena` is reset at the same//! moment. A handler that wants to keep something must copy it somewhere of//! its own.
const std = @import("std");const Io = std.Io;const Allocator = std.mem.Allocator;
const protocol = @import("../protocol.zig");const transport = @import("../transport.zig");const Headers = protocol.Headers;const Length = protocol.Length;const Method = protocol.Method;const Target = protocol.Target;const Version = protocol.Version;
const Request = @This();
/// The `Io` the connection is being served on. A handler that needs to do I/O/// of its own — open a file, make a request onward — takes it from here/// rather than reaching for an implementation, so that a test can serve the/// whole thing on `Io.failing` and a fuzzer can drive it with no I/O at all.io: Io,/// Scratch for the length of this exchange, and no longer. Reset between/// requests on the same connection.arena: Allocator,version: Version,method: Method,target: Target,headers: Headers,/// What the transport knows about the channel this arrived on.connection: transport.Connection.Info,body: Body,/// The `:protocol` of RFC 8441's extended CONNECT, when the request carried/// one.////// This is HTTP/2's replacement for `Upgrade`, and it is deliberately not/// surfaced as one: a handler asks `offersUpgrade`, which answers from/// whichever mechanism the version in front of it actually has. Null for/// every HTTP/1.x request and for every HTTP/2 request that is not an/// extended CONNECT.connect_protocol: ?[]const u8 = null,
/// The request body, already decoded: whatever transfer coding it arrived/// under has been taken off, so this is the content and not the framing.pub const Body = struct { reader: *Io.Reader, /// How long the body is, if the message said. `.unknown` is an HTTP/1.1 /// chunked body, whose length is not known until it ends. length: Length,
pub const empty_reader: *Io.Reader = Io.Reader.ending;
/// Whether there is a body at all. pub fn isPresent(b: Body) bool { return b.length != .none; }
pub const ReadError = Io.Reader.LimitedAllocError;
/// Reads the whole body into memory, refusing to read more than `limit`. /// /// The limit is not optional and there is no overload without one. A body /// of unknown length is whatever the client decides to send, and a server /// that reads it into memory until it stops is a server that can be /// stopped by one client. pub fn readAlloc(b: Body, gpa: Allocator, limit: usize) ReadError![]u8 { return b.reader.allocRemaining(gpa, .limited(limit)); }};
/// The value of the first field with this name, or null.pub fn header(r: *const Request, name: []const u8) ?[]const u8 { return r.headers.get(name);}
/// The authority the request is for: the host and optional port it was/// addressed to.////// An absolute-form target carries it, and when it does it wins over the/// `Host` field — RFC 9112 §3.2.2 is explicit, and the reason is that a/// client and a proxy that disagree about which to believe is the whole shape/// of a cache poisoning attack. Everything else falls back to `Host`, which/// an HTTP/1.1 request must carry and an HTTP/1.0 request need not.pub fn authority(r: *const Request) ?[]const u8 { if (r.target.authority) |a| return a; return r.headers.get("host");}
/// The scheme the request arrived over: `https` when the transport is/// confidential, `http` otherwise, unless an absolute-form target said/// something else.pub fn scheme(r: *const Request) []const u8 { if (r.target.scheme) |s| return s; return if (r.connection.secure) "https" else "http";}
/// Whether the client said it would take a particular content coding —/// `gzip`, `br`, `zstd`.////// A blunt membership test rather than a reading of the quality values: it/// answers "may I send this" and not "what would this client most like",/// which is what nearly every caller wants and all that can be answered/// without allocating.pub fn acceptsEncoding(r: *const Request, coding: []const u8) bool { return r.headers.containsToken("accept-encoding", coding);}
/// Whether the client offered to switch this connection to `protocol_name`.////// The two versions ask entirely different questions and this is the point of/// the question being asked here rather than in the handler. Over HTTP/1.1 it/// is RFC 9110 §7.8's `Upgrade`, and both halves have to be there: `Upgrade`/// lists the protocols on offer, and `Connection: upgrade` is what marks that/// list as meant for this hop rather than forwarded by a proxy that did not/// understand it. Over HTTP/2 there is no `Upgrade` at all — those fields are/// forbidden by §8.2.2 — and the offer is RFC 8441's `:protocol` on an/// extended CONNECT.////// So a handler that wants to speak WebSocket writes the same two lines/// whichever version it is serving, which is the whole point of this library/// having a `Request` that is not a wire format.pub fn offersUpgrade(r: *const Request, protocol_name: []const u8) bool { if (r.connect_protocol) |offered| { // RFC 8441 §4: the value comes from the HTTP Upgrade Token registry, // whose tokens are compared case-insensitively like every other // token in HTTP. return protocol.token.eqlIgnoreCase(offered, protocol_name); } if (!r.headers.containsToken("connection", "upgrade")) return false; return r.headers.containsToken("upgrade", protocol_name);}
/// Whether the client asked for a conditional request to be evaluated —/// any of the `If-` fields.pub fn isConditional(r: *const Request) bool { return r.headers.has("if-match") or r.headers.has("if-none-match") or r.headers.has("if-modified-since") or r.headers.has("if-unmodified-since") or r.headers.has("if-range");}
test { std.testing.refAllDecls(@This());}