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.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! The HTTP/1.0 and HTTP/1.1 driver: one connection's worth of requests, read//! off a byte stream and answered on it.//!//! This is the only file in the library that knows what a chunk looks like or//! that `Content-Length` is spelled with a hyphen. Everything a handler//! touches is in `protocol` and `server`, which is what makes the promise at//! the top of `root.zig` a real one rather than a hope: an HTTP/2 driver is a//! sibling of this file, not a rewrite of the things above it.//!//! ## Framing is the whole job//!//! Almost everything here is about where a message ends, because that is//! where HTTP/1.1 is dangerous. Two participants that disagree about it see//! two different sequences of requests in the same bytes, and the one in//! front — a cache, a load balancer — can be made to hand the one behind a//! request the client never sent. RFC 9112 §6.3 gives the precedence rules//! and §11.2 explains what happens when they are not followed. Where the//! standard offers a choice between rejecting a message and guessing at it,//! this rejects it.//!//! ## What is deliberately not here//!//! * `CONNECT`, which is answered `501`. See `root.zig` for why it is out of//! scope rather than unfinished.//! * Content codings. A request arriving `Content-Encoding: gzip` is passed//! to the handler still compressed, which is correct — content coding is//! part of the representation, not the framing — but a `Transfer-Encoding`//! other than `chunked` is refused with `501`, because that one *is*//! framing.//! * Trailer fields, which are parsed and discarded rather than exposed.
const std = @import("std");const Io = std.Io;const Allocator = std.mem.Allocator;const assert = std.debug.assert;
const protocol = @import("../protocol.zig");const transport = @import("../transport.zig");const head_mod = @import("head.zig");
const Field = protocol.Field;const Headers = protocol.Headers;const Length = protocol.Length;const Method = protocol.Method;const Status = protocol.Status;const Target = protocol.Target;const Version = protocol.Version;const token = protocol.token;
const Handler = @import("../server/Handler.zig");const Request = @import("../server/Request.zig");const Response = @import("../server/Response.zig");const compression = @import("../server/compression.zig");
const log = std.log.scoped(.http1);
pub const Config = struct { /// The most a request head may occupy. Bounds the longest single header /// line as well, since a head is read into one buffer. max_head_len: usize = 16 * 1024, /// The most field lines one request may carry. max_header_count: usize = 100, /// How many requests one connection may serve before it is closed. /// /// Not a limit on anything dangerous — it is there so that a long-lived /// connection eventually gives its memory back and a rolling deploy /// eventually reaches every client. max_requests: usize = 1000, /// How much of a request body a handler did not read will be thrown away /// so that the connection can be used again. Past this the connection is /// closed, because reading a gigabyte nobody wants is a cheaper way to /// occupy a server than sending one. max_drain_len: u64 = 1 << 20, /// The most a chunked body's trailer section may occupy. max_trailer_len: usize = 4096, /// The most request body this server will read for one request, or null /// for no limit beyond what the handler chooses to read. A request whose /// `Content-Length` is over it is answered `413` before the handler runs. /// A chunked one that runs past it has its body read fail at the limit, /// and is answered `413` unless the handler has already begun a response. /// Either way the connection is closed, since the rest of the body is /// still on it. The same option exists on the HTTP/2 and HTTP/3 servers. max_body_len: ?u64 = null, /// The buffer a handler reads the request body through. body_read_buffer_len: usize = 4096, /// The buffer a handler writes the response body through. In a chunked /// response this is also the largest chunk that will be emitted, so it is /// the difference between one chunk header per write and one per /// buffer-full. body_write_buffer_len: usize = 4096, /// What to send as `Server`, or null to send none. server_name: ?[]const u8 = "zig-http", /// Whether to send a `Date`. RFC 9110 §6.6.1 requires an origin server /// with a clock to send one; a server without a clock — and `Io.failing` /// is one, its `now` being zero — should turn this off rather than /// insist it is 1970. send_date: bool = true, /// Whether to code a response body, and how. Null is a server that does /// not compress; `server.compression.Config` carries the policy and its /// defaults — `text/*` and the rest, above four kilobytes. compression: ?compression.Config = null, /// Whether to undo a content coding on a request body before the handler /// sees it. Null leaves it coded, which §8.4 of RFC 9110 makes a /// perfectly good representation to hand over and is what this did before /// the option existed. request_decoding: ?compression.RequestDecoding = null,};
/// The fields this driver writes for itself. A handler that sets one of them/// is overruled: the first two are framing, which belongs to the driver/// because only the driver knows what version it is speaking, and the rest/// are HTTP/1.1 connection management, which HTTP/2 makes a connection error/// to send at all.fn isDriverField(name: []const u8) bool { const managed = [_][]const u8{ "content-length", "transfer-encoding", "connection", "keep-alive", "upgrade", "proxy-connection", }; for (managed) |m| { if (token.eqlIgnoreCase(name, m)) return true; } return false;}
pub const Error = Allocator.Error;
/// Serves requests on `conn` until it ends, and then returns. Does not close/// the connection; the caller that opened it closes it.////// It ends when the client stops sending, when either side says/// `Connection: close`, when a request cannot be answered and still leave the/// connection in step, after `config.max_requests`, or when a handler upgrades/// it to another protocol. None of those is an error: a malformed request is/// answered with its `4xx` and a failed handler with a `500` where that is/// still possible, and the only error returned is failing to allocate the/// connection's buffers before the first request.pub fn serve( io: Io, gpa: Allocator, conn: *transport.Connection, handler: Handler, config: Config,) Error!void { var session: Session = undefined; try session.init(io, gpa, conn, handler, config); defer session.deinit(); session.run();}
test serve { const gpa = std.testing.allocator; var memory: transport.memory.Connection = try .init( gpa, "GET /a HTTP/1.1\r\nHost: a.example\r\n\r\n" ++ "GET /b HTTP/1.1\r\nHost: a.example\r\nConnection: close\r\n\r\n", .{}, ); defer memory.deinit();
const hello: Handler = .initStateless(struct { fn respond(req: *Request, res: *Response) Handler.Error!void { try res.send(req.target.path); } }.respond);
var conn = memory.connection(); // `Io.failing` is enough: a memory transport needs no I/O, and with no // clock there is no `Date` to send. try serve(std.Io.failing, gpa, &conn, hello, .{ .send_date = false, .server_name = null });
try std.testing.expectEqualStrings( "HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\n/a" ++ "HTTP/1.1 200 OK\r\nContent-Length: 2\r\nConnection: close\r\n\r\n/b", memory.written(), );}
/// One connection's state, kept across the requests on it so that the head/// buffer and the field list are allocated once rather than per request.const Session = struct { io: Io, gpa: Allocator, conn: *transport.Connection, handler: Handler, config: Config,
arena: std.heap.ArenaAllocator, head_buf: []u8, body_read_buf: []u8, body_write_buf: []u8, fields: std.ArrayList(Field),
// Per exchange, and meaningless outside one. version: Version, method: Method, keep_alive: bool, expect_continue: bool, continue_sent: bool, head_written: bool, /// Set once the connection has been handed to another protocol. Nothing /// further may be read or written here as HTTP. upgraded: bool, body_reader: BodyReader, body_writer: BodyWriter,
fn init( s: *Session, io: Io, gpa: Allocator, conn: *transport.Connection, handler: Handler, config: Config, ) Allocator.Error!void { const head_buf = try gpa.alloc(u8, config.max_head_len); errdefer gpa.free(head_buf); const body_read_buf = try gpa.alloc(u8, config.body_read_buffer_len); errdefer gpa.free(body_read_buf); const body_write_buf = try gpa.alloc(u8, config.body_write_buffer_len); errdefer gpa.free(body_write_buf);
s.* = .{ .io = io, .gpa = gpa, .conn = conn, .handler = handler, .config = config, .arena = .init(gpa), .head_buf = head_buf, .body_read_buf = body_read_buf, .body_write_buf = body_write_buf, .fields = .empty, .version = .http_1_1, .method = .get, .keep_alive = false, .expect_continue = false, .continue_sent = false, .head_written = false, .upgraded = false, .body_reader = undefined, .body_writer = undefined, }; }
fn deinit(s: *Session) void { s.fields.deinit(s.gpa); s.arena.deinit(); s.gpa.free(s.head_buf); s.gpa.free(s.body_read_buf); s.gpa.free(s.body_write_buf); s.* = undefined; }
fn run(s: *Session) void { var served: usize = 0; while (true) { served += 1; const last = served >= s.config.max_requests; switch (s.exchange(last)) { .keep_alive => {}, .close => return, } } }
const Outcome = enum { keep_alive, close };
/// One request and its response. fn exchange(s: *Session, last_allowed: bool) Outcome { _ = s.arena.reset(.retain_capacity); s.fields.clearRetainingCapacity(); // Reset before the head is read rather than after it is parsed, so // that a request that fails to parse is answered on its own terms and // not on the previous request's: without this a `HEAD` followed by an // unparseable request would have its answer sent bodiless. s.version = .http_1_1; s.method = .get; s.keep_alive = false; s.expect_continue = false; s.continue_sent = false; s.head_written = false; s.upgraded = false;
const raw_head = head_mod.read(s.conn.input, s.head_buf) catch |err| switch (err) { // A kept-alive connection the client finished with. Not a // failure, and not something to answer. error.EndOfStream => return .close, error.ReadFailed, error.IncompleteHead => return .close, error.HeadTooLong => return s.fail(.request_header_fields_too_large), };
// The field list is grown from `gpa` and not from the arena: it // outlives an arena reset, and a list whose capacity points into // freed arena memory is a use-after-free the next time it is // cleared. What the fields point *at* is the head buffer, which is // owned by the session and reused deliberately. const parsed = head_mod.parse( raw_head, s.gpa, &s.fields, s.config.max_header_count, ) catch |err| return s.fail(switch (err) { error.UnsupportedVersion => .http_version_not_supported, error.TooManyFields => .request_header_fields_too_large, error.OutOfMemory => .internal_server_error, else => .bad_request, });
s.version = parsed.version; s.method = parsed.method; const headers: Headers = .initBorrowed(s.fields.items);
// RFC 9112 §3.2: an HTTP/1.1 request must carry exactly one `Host`, // and it must be one this server could act on. Two that disagree is // how a request is routed to one origin by a proxy and to another by // the server behind it. if (s.validateHost(&headers, parsed.target)) |status| return s.fail(status);
const framing: Length = switch (s.requestFraming(&headers)) { .fail => |status| return s.fail(status), .length => |length| length, }; // §15.5.14 of RFC 9110, and before the handler or a `100 Continue`: // a body this server will not read is not one to ask for. if (framing == .exact and framing.exact > s.config.max_body_len orelse std.math.maxInt(u64)) { return s.fail(.payload_too_large); }
// Whether the connection survives this exchange, decided before the // handler runs because the answer has to go in the response head. s.keep_alive = !last_allowed and switch (s.version) { .http_1_0 => headers.containsToken("connection", "keep-alive"), else => !headers.containsToken("connection", "close"), };
if (headers.get("expect")) |expect| { if (token.containsToken(expect, "100-continue")) { // Only HTTP/1.1 clients understand an interim response; an // HTTP/1.0 client that sent this is not waiting for one. s.expect_continue = s.version == .http_1_1; } else { // RFC 9110 §10.1.1: an expectation that is not understood // must be refused rather than ignored. return s.fail(.expectation_failed); } }
s.body_reader = .init(s, framing); s.body_writer = .{ .interface = .{ .vtable = &BodyWriter.vtable, .buffer = s.body_write_buf }, .out = s.conn.output, .mode = .discard, .remaining = 0, };
// §8.4 of RFC 9110: undone before the handler sees it, when this // server was asked to. Computed here rather than in the literal // because it can fail, and a failure has to be answered -- handing a // handler coded octets after being configured to decode them would be // a wrong answer rather than an error. var body: Request.Body = .{ .reader = &s.body_reader.interface, .length = framing, }; if (s.config.request_decoding) |decoding| { const decoded = compression.decodeRequest( s.arena.allocator(), decoding, headers.get("content-encoding"), body.reader, body.length, ) catch return s.fail(.internal_server_error); body = .{ .reader = decoded.reader, .length = decoded.length }; }
var request: Request = .{ .io = s.io, .arena = s.arena.allocator(), .version = parsed.version, .method = parsed.method, .target = parsed.target, .headers = headers, .connection = s.conn.info, .body = body, };
var response: Response = .{ .headers = .empty, .arena = s.arena.allocator(), .version = parsed.version, .context = s, .vtable = &response_vtable, // The driver has both halves; `Response` is written against a // response and never sees the request that caused it. .accept_encoding = headers.get("accept-encoding"), .compress = s.config.compression, };
s.handler.serve(&request, &response) catch |err| { // A handler that failed before writing anything still gets a // response; one that failed part way through a body cannot, // because the head is already on the wire saying how long the // body was going to be. Closing is the only way left to tell the // client that what it has is not the whole thing. log.debug("handler failed for {s} {s}: {s}", .{ request.method.name, request.target.raw, @errorName(err), }); if (response.state == .head) return s.fail(if (s.body_reader.tooLarge()) .payload_too_large else .internal_server_error); // Whatever the handler did manage to write goes out before the // connection ends, so that the client sees a body that is // shorter than the `Content-Length` it was promised -- which is // detectable -- rather than a response that silently vanished. s.body_writer.interface.flush() catch {}; s.conn.output.flush() catch {}; return .close; };
// The connection is no longer speaking HTTP, and the handler has // finished with whatever replaced it. There is nothing to frame, no // body to drain, and no next request. if (response.state == .upgraded) return .close;
// A handler that returned without saying anything meant `200` with an // empty body. if (response.state == .head) { // A handler that read past the limit and let the failure go has // not answered the request it was given, so the limit does. if (s.body_reader.tooLarge()) return s.fail(.payload_too_large); response.send("") catch return .close; } else if (response.state == .body) { response.end() catch return .close; }
if (!s.keep_alive) return .close; if (!s.drainRequestBody()) return .close; return .keep_alive; }
/// Checks the `Host` field against RFC 9112 §3.2, returning the status to /// answer with when it does not pass. fn validateHost(s: *Session, headers: *const Headers, target: Target) ?Status { // "A server MUST respond with a 400 (Bad Request) status code to any // HTTP/1.1 request message that lacks a Host header field and to any // request message that contains more than one Host header field line" // -- more than one line, even two that agree, which `getUnique` would // let through. if (headers.count("host") > 1) return .bad_request; const host = headers.get("host");
if (host) |value| { // An absolute-form target carries its own authority and wins, so // the `Host` need only be well formed -- but an empty one is not. if (value.len != 0) { _ = Target.parseAuthority(value) catch return .bad_request; } else if (target.authority == null) { return .bad_request; } } else if (s.version == .http_1_1 and target.authority == null) { return .bad_request; }
// CONNECT is a tunnel, not a request, and this driver has nowhere to // hand the connection to. if (target.form == .authority) return .not_implemented; // `*` is only meaningful in a server-wide OPTIONS. if (target.form == .asterisk and !s.method.eql(Method.options)) { return .bad_request; } return null; }
/// Works out how long the request body is, by RFC 9112 §6.3. /// /// The order of the tests is the order in the standard, and it matters: /// `Transfer-Encoding` beats `Content-Length`, and a message carrying /// both is refused rather than resolved, because a recipient that /// resolved it the other way would see a different request. /// Either the length of the request body, or the status to refuse the /// request with. const Framing = union(enum) { length: Length, fail: Status };
fn requestFraming(s: *Session, headers: *const Headers) Framing { var codings = headers.values("transfer-encoding"); var last_coding: ?[]const u8 = null; var coding_count: usize = 0; var has_transfer_encoding = false; while (codings.next()) |value| { has_transfer_encoding = true; var it = token.list(value); while (it.next()) |coding| { last_coding = coding; coding_count += 1; } }
if (has_transfer_encoding) { // A message with both is ambiguous, and RFC 9112 §6.3 requires // it to be rejected. if (headers.has("content-length")) return .{ .fail = .bad_request }; // `Transfer-Encoding` was not in HTTP/1.0 at all, so a 1.0 // request carrying one was written by something that does not // know what it is doing, or by something trying to get a body // past a 1.0 intermediary that will ignore the field. if (s.version == .http_1_0) return .{ .fail = .bad_request };
const last = last_coding orelse return .{ .fail = .bad_request }; // RFC 9112 §6.1: chunked must be the final coding, or the length // cannot be determined and the message must be refused. if (!token.eqlIgnoreCase(last, "chunked")) return .{ .fail = .bad_request }; // Any coding under the chunking would have to be decoded to find // the content, and this decodes none of them. if (coding_count != 1) return .{ .fail = .not_implemented }; return .{ .length = .unknown }; }
const content_length = headers.getUnique("content-length") catch return .{ .fail = .bad_request }; if (content_length) |value| { const n = protocol.parseContentLength(value) orelse return .{ .fail = .bad_request }; return .{ .length = if (n == 0) .none else .{ .exact = n } }; }
// No framing field at all: a request has no body. Unlike a response, // it cannot be delimited by the end of the connection, because the // client still needs the connection to hear the answer. return .{ .length = .none }; }
/// Writes a minimal response and gives up on the connection. /// /// Written straight to the connection rather than through a `Response`, /// because this is reached when there may be no valid request to build /// one from — including when the request line itself did not parse. fn fail(s: *Session, status: Status) Outcome { if (s.head_written) return .close; const out = s.conn.output; const phrase = status.phrase() orelse "Error"; var body_buf: [64]u8 = undefined; const body = std.fmt.bufPrint(&body_buf, "{d} {s}\n", .{ @backingInt(status), phrase, }) catch "";
out.print("{s} {d} {s}\r\n", .{ s.version.toString(), @backingInt(status), phrase, }) catch return .close; s.writeDate() catch return .close; s.writeServer() catch return .close; out.print( "Content-Type: text/plain; charset=utf-8\r\nContent-Length: {d}\r\nConnection: close\r\n\r\n", .{body.len}, ) catch return .close; // A `HEAD` that failed still gets the length and not the body. A // request line that did not parse has no method at all, and the reset // at the top of `exchange` is what makes that `GET` rather than // whatever the connection was asked for last. if (s.method.responseHasBody()) out.writeAll(body) catch return .close; out.flush() catch return .close; return .close; }
fn writeDate(s: *Session) Io.Writer.Error!void { if (!s.config.send_date) return; const now = Io.Clock.real.now(s.io); const seconds: i64 = @intCast(@divFloor(now.nanoseconds, std.time.ns_per_s)); var buf: [protocol.date.imf_len]u8 = undefined; const formatted = protocol.date.formatImf(&buf, seconds) catch return; try s.conn.output.writeAll("Date: "); try s.conn.output.writeAll(formatted); try s.conn.output.writeAll("\r\n"); }
fn writeServer(s: *Session) Io.Writer.Error!void { const name = s.config.server_name orelse return; try s.conn.output.writeAll("Server: "); try s.conn.output.writeAll(name); try s.conn.output.writeAll("\r\n"); }
/// Reads and throws away whatever is left of the request body, so that /// the next request on the connection starts where it should. /// /// Returns false when there was more than `max_drain_len` of it, in which /// case the connection is closed instead: finishing the read would mean /// doing work for a client that has already been answered. fn drainRequestBody(s: *Session) bool { const r = &s.body_reader; if (r.finished) return true; // Never wake a client that is waiting for a `100 Continue` just to // throw away what it would have sent. if (s.expect_continue and !s.continue_sent) return false; var left = s.config.max_drain_len; while (left > 0) { const n = r.interface.discard(.limited64(left)) catch |err| switch (err) { error.EndOfStream => return true, error.ReadFailed => return false, }; left -= n; } return r.finished; }
// -- the `Response` seam ------------------------------------------------
const response_vtable: Response.VTable = .{ .beginBody = beginBody, .end = endBody, .sendInterim = sendInterim, .upgrade = upgrade, };
/// Writes `101 Switching Protocols` and hands the byte stream over. /// /// The checks before it are the whole of what makes this safe: /// /// * HTTP/1.0 has no `Upgrade`, and a `101` to a client that does not /// know what one is will be read as the response itself. /// * RFC 9110 §7.8 forbids switching to a protocol the client did not /// list. Switching anyway means both ends are speaking, confidently, /// two different things. /// * An unread request body is still in the stream. Its octets sit in /// front of the new protocol's first octet, and the new protocol will /// read them as its own. fn upgrade(res: *Response, protocol_name: []const u8) Response.UpgradeError!Response.Upgrade { const s: *Session = @ptrCast(@alignCast(res.context.?)); if (s.version != .http_1_1) return error.UpgradeUnavailable;
const headers: Headers = .initBorrowed(s.fields.items); if (!headers.containsToken("connection", "upgrade")) return error.NotOffered; if (!headers.containsToken("upgrade", protocol_name)) return error.NotOffered; if (!s.body_reader.finished) return error.BodyNotConsumed;
const out = s.conn.output; out.writeAll("HTTP/1.1 101 Switching Protocols\r\nConnection: Upgrade\r\nUpgrade: ") catch return error.WriteFailed; out.writeAll(protocol_name) catch return error.WriteFailed; out.writeAll("\r\n") catch return error.WriteFailed; // `Connection` and `Upgrade` are written above and are refused from // the handler by `isDriverField`; everything else it set goes out, // which is where `Sec-WebSocket-Accept` belongs. for (res.headers.fields.items) |field| { if (isDriverField(field.name)) continue; out.writeAll(field.name) catch return error.WriteFailed; out.writeAll(": ") catch return error.WriteFailed; out.writeAll(field.value) catch return error.WriteFailed; out.writeAll("\r\n") catch return error.WriteFailed; } out.writeAll("\r\n") catch return error.WriteFailed; // Flushed here and not by the caller: the client is waiting for this // before it says anything, so a handler that read first would // deadlock against its own unsent handshake. out.flush() catch return error.WriteFailed;
s.head_written = true; s.upgraded = true; return .{ .input = s.conn.input, .output = s.conn.output }; }
fn beginBody(res: *Response, length: Length) Response.Error!*Io.Writer { const s: *Session = @ptrCast(@alignCast(res.context.?)); const out = s.conn.output;
// What may be declared, and what may actually be sent. They are not // the same question: a `HEAD` response carries the `Content-Length` // the matching `GET` would have had and none of the octets. // A client that is waiting to be asked for its body will still be // holding it when this response arrives, and nothing will ever read // it, so the connection cannot be reused. It has to be decided here // rather than after the handler returns, because by then the head // -- which is where `Connection: close` has to appear -- is written. if (s.expect_continue and !s.continue_sent) s.keep_alive = false;
const allows_body = Response.statusAllowsBody(res.status); const emits_body = allows_body and s.method.responseHasBody(); const declared: Length = if (allows_body or res.status == .not_modified) length else .none;
out.print("{s} {d} {s}\r\n", .{ res.version.toString(), @backingInt(res.status), res.status.phrase() orelse "Unknown", }) catch return error.WriteFailed;
var mode: BodyWriter.Mode = .discard; var remaining: u64 = 0; switch (declared) { .none => { // `Content-Length: 0` is worth saying for a status that could // have had a body, and is forbidden for one that could not. if (allows_body) { out.writeAll("Content-Length: 0\r\n") catch return error.WriteFailed; } }, .exact => |n| { out.print("Content-Length: {d}\r\n", .{n}) catch return error.WriteFailed; if (emits_body) { mode = .exact; remaining = n; } }, .unknown => switch (res.version) { .http_1_1, .http_2, .http_3 => { out.writeAll("Transfer-Encoding: chunked\r\n") catch return error.WriteFailed; if (emits_body) mode = .chunked; }, .http_1_0 => { // HTTP/1.0 has no chunked coding, so a body of unknown // length ends where the connection does -- which means // the connection cannot be kept. s.keep_alive = false; if (emits_body) mode = .until_close; }, }, }
if (!s.keep_alive) { out.writeAll("Connection: close\r\n") catch return error.WriteFailed; } else if (res.version == .http_1_0) { // An HTTP/1.0 client keeps the connection only if told to. out.writeAll("Connection: keep-alive\r\n") catch return error.WriteFailed; }
if (!res.headers.has("date")) s.writeDate() catch return error.WriteFailed; if (!res.headers.has("server")) s.writeServer() catch return error.WriteFailed;
for (res.headers.fields.items) |field| { if (isDriverField(field.name)) continue; out.writeAll(field.name) catch return error.WriteFailed; out.writeAll(": ") catch return error.WriteFailed; out.writeAll(field.value) catch return error.WriteFailed; out.writeAll("\r\n") catch return error.WriteFailed; } out.writeAll("\r\n") catch return error.WriteFailed; s.head_written = true;
s.body_writer.mode = mode; s.body_writer.remaining = remaining; // A body of declared length gets a buffer no larger than what is left // to write, so that a handler writing past the length it declared // forces a drain and is refused there. With a buffer larger than the // body, the excess would sit in it until the flush and the handler // would be told far too late that what it wrote will not be sent. s.body_writer.interface.buffer = switch (mode) { .exact => s.body_write_buf[0..@min(s.body_write_buf.len, remaining)], .discard, .until_close, .chunked => s.body_write_buf, }; s.body_writer.interface.end = 0; return &s.body_writer.interface; }
fn endBody(res: *Response) Response.Error!void { const s: *Session = @ptrCast(@alignCast(res.context.?)); try s.body_writer.finishWithTrailers(&res.trailers); s.conn.output.flush() catch return error.WriteFailed; // A body that ended because the connection did has to actually end // it, or the client cannot tell a complete response from a truncated // one. if (s.body_writer.mode == .until_close) s.conn.shutdownWrite(s.io); }
fn sendInterim(res: *Response, status: Status, headers: *const Headers) Response.Error!void { const s: *Session = @ptrCast(@alignCast(res.context.?)); // An HTTP/1.0 client has no idea what an interim response is and // will read it as the real one. if (s.version == .http_1_0) return; const out = s.conn.output; // §4 of RFC 9112: the reason phrase may be empty, and for a code // with no phrase of its own an empty one is better than a borrowed one. out.print("HTTP/1.1 {d} {s}\r\n", .{ @backingInt(status), status.phrase() orelse "", }) catch return error.WriteFailed; for (headers.fields.items) |field| { if (isDriverField(field.name)) continue; out.writeAll(field.name) catch return error.WriteFailed; out.writeAll(": ") catch return error.WriteFailed; out.writeAll(field.value) catch return error.WriteFailed; out.writeAll("\r\n") catch return error.WriteFailed; } out.writeAll("\r\n") catch return error.WriteFailed; out.flush() catch return error.WriteFailed; }};
/// The request body, with the transfer coding taken off.const BodyReader = struct { interface: Io.Reader, session: *Session, mode: Mode, /// In `.exact`, how much of the body is left. In `.chunked`, how much of /// the current chunk is left. remaining: u64, /// Whether the CRLF that ends the current chunk is still to be consumed. chunk_end_pending: bool, finished: bool, err: ?Fault, /// How much of a chunked body has been read, against /// `Config.max_body_len`. received: u64,
const Mode = enum { none, exact, chunked };
/// What went wrong with the body, kept here because the `Io.Reader` /// interface has only `error.ReadFailed` to say it with. The driver reads /// it after a failed read, the way `net.Stream.Reader` is read. const Fault = error{ /// The connection ended before the body did. IncompleteBody, /// A chunk size that is not hexadecimal, a chunk not followed by /// CRLF, or a trailer section that does not end. InvalidChunk, /// The trailer section was longer than the configured limit. TrailersTooLong, /// The `100 Continue` could not be sent, so the client will never /// send the body it is waiting to be asked for. ContinueFailed, /// A chunked body ran past `Config.max_body_len`. BodyTooLarge, };
fn tooLarge(b: *const BodyReader) bool { const err = b.err orelse return false; return err == error.BodyTooLarge; }
fn init(session: *Session, length: Length) BodyReader { return .{ .interface = .{ .vtable = &.{ .stream = stream }, .buffer = session.body_read_buf, .seek = 0, .end = 0, }, .session = session, .mode = switch (length) { .none => .none, .exact => .exact, .unknown => .chunked, }, .remaining = switch (length) { .exact => |n| n, else => 0, }, .chunk_end_pending = false, .finished = length == .none, .err = null, .received = 0, }; }
fn stream(r: *Io.Reader, w: *Io.Writer, limit: Io.Limit) Io.Reader.StreamError!usize { const b: *BodyReader = @alignCast(@fieldParentPtr("interface", r)); if (b.finished) return error.EndOfStream; try b.sendContinue();
const in = b.session.conn.input; switch (b.mode) { .none => { b.finished = true; return error.EndOfStream; }, .exact => { if (b.remaining == 0) { b.finished = true; return error.EndOfStream; } const n = in.stream(w, limit.min(.limited64(b.remaining))) catch |err| switch (err) { error.EndOfStream => { b.err = error.IncompleteBody; return error.ReadFailed; }, else => |e| return e, }; b.remaining -= n; return n; }, .chunked => { while (b.remaining == 0) { if (b.chunk_end_pending) { try b.expectCrlf(); b.chunk_end_pending = false; } const size = try b.readChunkSize(); if (size == 0) { try b.readTrailers(); b.finished = true; return error.EndOfStream; } // Known before any of the chunk is read, and refused // before the excess reaches the handler. if (b.received + size > b.session.config.max_body_len orelse std.math.maxInt(u64)) { b.err = error.BodyTooLarge; return error.ReadFailed; } b.received += size; b.remaining = size; } const n = in.stream(w, limit.min(.limited64(b.remaining))) catch |err| switch (err) { error.EndOfStream => { b.err = error.IncompleteBody; return error.ReadFailed; }, else => |e| return e, }; b.remaining -= n; if (b.remaining == 0) b.chunk_end_pending = true; return n; }, } }
/// Answers a `100-continue` expectation the moment the handler asks for /// the first octet of the body, and not before. /// /// Waiting until then is the whole point of the expectation: a handler /// that is going to answer `401` or `413` can do it without the client /// ever sending the gigabyte it was offering. fn sendContinue(b: *BodyReader) Io.Reader.Error!void { const s = b.session; if (!s.expect_continue or s.continue_sent or s.head_written) return; s.continue_sent = true; const out = s.conn.output; out.writeAll("HTTP/1.1 100 Continue\r\n\r\n") catch { b.err = error.ContinueFailed; return error.ReadFailed; }; out.flush() catch { b.err = error.ContinueFailed; return error.ReadFailed; }; }
fn takeLine(b: *BodyReader) Io.Reader.Error![]const u8 { const line = b.session.conn.input.takeDelimiterInclusive('\n') catch |err| switch (err) { error.ReadFailed => return error.ReadFailed, error.EndOfStream => { b.err = error.IncompleteBody; return error.ReadFailed; }, // A line longer than the connection's read buffer. A chunk size // is never that long, so this is not a line. error.StreamTooLong => { b.err = error.InvalidChunk; return error.ReadFailed; }, }; if (line.len < 2 or line[line.len - 2] != '\r') { b.err = error.InvalidChunk; return error.ReadFailed; } return line[0 .. line.len - 2]; }
fn expectCrlf(b: *BodyReader) Io.Reader.Error!void { const line = try b.takeLine(); if (line.len != 0) { b.err = error.InvalidChunk; return error.ReadFailed; } }
fn readChunkSize(b: *BodyReader) Io.Reader.Error!u64 { const line = try b.takeLine(); // Chunk extensions are allowed and mean nothing to anybody. const digits = line[0 .. std.mem.indexOfScalar(u8, line, ';') orelse line.len]; if (digits.len == 0 or digits.len > 16) { b.err = error.InvalidChunk; return error.ReadFailed; } var size: u64 = 0; for (digits) |c| { const d = std.fmt.charToDigit(c, 16) catch { b.err = error.InvalidChunk; return error.ReadFailed; }; size = size * 16 + d; } return size; }
/// Reads the trailer section and throws it away. /// /// Throwing it away is a decision rather than an oversight: a trailer /// arrives after the handler has seen the whole body and, in most /// handlers, after it has already begun the response, so there is nowhere /// useful to put it. What matters here is that it is consumed exactly, so /// that the next request on the connection starts where it should. fn readTrailers(b: *BodyReader) Io.Reader.Error!void { var used: usize = 0; while (true) { const line = try b.takeLine(); if (line.len == 0) return; used += line.len + 2; if (used > b.session.config.max_trailer_len) { b.err = error.TrailersTooLong; return error.ReadFailed; } } }};
/// The response body, in whichever framing the head declared.const BodyWriter = struct { interface: Io.Writer, out: *Io.Writer, mode: Mode, /// In `.exact`, how many octets are still owed. remaining: u64,
const Mode = enum { /// The head declared a body that this response does not send: a /// `HEAD`, or a status that may not carry one. Writes are counted /// against the declared length and dropped. discard, /// Straight through, held to the declared length. exact, /// Straight through with no length at all: the body ends where the /// connection does, which is the only framing HTTP/1.0 has for a /// response whose length is not known in advance. until_close, /// Each drain becomes one chunk. chunked, };
const vtable: Io.Writer.VTable = .{ .drain = drain };
fn drain(w: *Io.Writer, data: []const []const u8, splat: usize) Io.Writer.Error!usize { const b: *BodyWriter = @alignCast(@fieldParentPtr("interface", w)); const buffered = w.buffered(); const from_data = Io.Writer.countSplat(data, splat); const total = buffered.len + from_data;
switch (b.mode) { .discard => {}, .until_close => try b.writeThrough(buffered, data, splat), .exact => { // A handler that writes more than it said it would has // already made the message unparseable; the octets must not // go out. if (total > b.remaining) return error.WriteFailed; try b.writeThrough(buffered, data, splat); b.remaining -= total; }, .chunked => if (total != 0) { // A zero-length chunk is the end of the body, so an empty // drain must emit nothing at all rather than an empty chunk. try b.out.print("{x}\r\n", .{total}); try b.writeThrough(buffered, data, splat); try b.out.writeAll("\r\n"); }, }
w.end = 0; return from_data; }
fn writeThrough( b: *BodyWriter, buffered: []const u8, data: []const []const u8, splat: usize, ) Io.Writer.Error!void { if (buffered.len != 0) try b.out.writeAll(buffered); for (data[0 .. data.len - 1]) |bytes| try b.out.writeAll(bytes); const pattern = data[data.len - 1]; for (0..splat) |_| try b.out.writeAll(pattern); }
fn finish(b: *BodyWriter) Response.Error!void { const none: Headers = .empty; return b.finishWithTrailers(&none); }
/// RFC 9112 §7.1.2: the trailer section, which only the chunked coding /// has anywhere to put. /// /// "A trailer section is only possible when the message framing allows /// it" (§6.6.2 of RFC 9110), and the other three modes here do not: a /// declared length ends where it said it would, and a body that ends by /// closing the connection has nothing after it by definition. So the /// fields are dropped, which is what a trailer field is for -- §6.5.1 /// forbids putting anything the recipient needs in one precisely because /// it may not arrive. fn finishWithTrailers(b: *BodyWriter, trailers: *const Headers) Response.Error!void { b.interface.flush() catch return error.WriteFailed; switch (b.mode) { .discard, .until_close => {}, .exact => { // Owing octets is as bad as sending too many: the head said // how long the body would be and it is not that long. if (b.remaining != 0) return error.LengthMismatch; }, .chunked => { // §7.1: the last chunk, then the trailer section, then the // empty line that ends it -- so the terminator is split in // two rather than written as one literal. b.out.writeAll("0\r\n") catch return error.WriteFailed; for (trailers.fields.items) |f| { if (Response.isForbiddenTrailer(f.name)) continue; b.out.print("{s}: {s}\r\n", .{ f.name, f.value }) catch return error.WriteFailed; } b.out.writeAll("\r\n") catch return error.WriteFailed; }, } }};
test isDriverField { try std.testing.expect(isDriverField("Content-Length")); try std.testing.expect(isDriverField("transfer-encoding")); try std.testing.expect(isDriverField("CONNECTION")); try std.testing.expect(!isDriverField("Content-Type")); try std.testing.expect(!isDriverField("Content-Encoding"));}
/// Serves `input` with a handler that answers "ok", and returns what was/// written back, for the tests below.fn serveOk(input: []const u8) ![]u8 { const gpa = std.testing.allocator; var memory: transport.memory.Connection = try .init(gpa, input, .{}); defer memory.deinit(); const ok: Handler = .initStateless(struct { fn respond(req: *Request, res: *Response) Handler.Error!void { _ = req; try res.send("ok"); } }.respond); var conn = memory.connection(); try serve(std.Io.failing, gpa, &conn, ok, .{ .send_date = false, .server_name = null }); return gpa.dupe(u8, memory.written());}
test "RFC 9112 3.2: two Host field lines are a 400 even when they agree" { const got = try serveOk("GET / HTTP/1.1\r\nHost: a.example\r\nHost: a.example\r\n\r\n"); defer std.testing.allocator.free(got); try std.testing.expect(std.mem.startsWith(u8, got, "HTTP/1.1 400 "));}
test "RFC 9110 4.2.1: an http URI with an empty host is rejected" { const got = try serveOk("GET http://:80/ HTTP/1.1\r\nHost: a.example\r\n\r\n"); defer std.testing.allocator.free(got); try std.testing.expect(std.mem.startsWith(u8, got, "HTTP/1.1 400 "));}
test "RFC 9110 4.2.4: an http URI with userinfo is rejected" { const got = try serveOk("GET http://u@a.example/ HTTP/1.1\r\nHost: a.example\r\n\r\n"); defer std.testing.allocator.free(got); try std.testing.expect(std.mem.startsWith(u8, got, "HTTP/1.1 400 "));}
/// Serves `input` with `max_body_len` of 4 and a handler that reads the whole/// body before answering "ok", and returns what was written back.fn serveLimited(input: []const u8) ![]u8 { const gpa = std.testing.allocator; var memory: transport.memory.Connection = try .init(gpa, input, .{}); defer memory.deinit(); const reads: Handler = .initStateless(struct { fn respond(req: *Request, res: *Response) Handler.Error!void { _ = try req.body.reader.discardRemaining(); try res.send("ok"); } }.respond); var conn = memory.connection(); try serve(std.Io.failing, gpa, &conn, reads, .{ .send_date = false, .server_name = null, .max_body_len = 4, }); return gpa.dupe(u8, memory.written());}
test "a Content-Length over max_body_len is a 413 before the handler" { const got = try serveLimited("POST / HTTP/1.1\r\nHost: a\r\nExpect: 100-continue\r\nContent-Length: 5\r\n\r\nhello"); defer std.testing.allocator.free(got); // Not asked for with a `100 Continue` first. try std.testing.expect(std.mem.startsWith(u8, got, "HTTP/1.1 413 ")); try std.testing.expect(std.mem.indexOf(u8, got, "Connection: close\r\n") != null);}
test "a chunked body that runs past max_body_len is a 413" { const got = try serveLimited("POST / HTTP/1.1\r\nHost: a\r\nTransfer-Encoding: chunked\r\n\r\n3\r\nabc\r\n2\r\nde\r\n0\r\n\r\n"); defer std.testing.allocator.free(got); try std.testing.expect(std.mem.startsWith(u8, got, "HTTP/1.1 413 "));
// Up to the limit is read as ever, in either framing. const chunked = try serveLimited("POST / HTTP/1.1\r\nHost: a\r\nTransfer-Encoding: chunked\r\n\r\n2\r\nab\r\n2\r\ncd\r\n0\r\n\r\n"); defer std.testing.allocator.free(chunked); try std.testing.expect(std.mem.startsWith(u8, chunked, "HTTP/1.1 200 ")); const exact = try serveLimited("POST / HTTP/1.1\r\nHost: a\r\nContent-Length: 4\r\n\r\nabcd"); defer std.testing.allocator.free(exact); try std.testing.expect(std.mem.startsWith(u8, exact, "HTTP/1.1 200 "));}