// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // 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()); }