// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! Reading and parsing an HTTP/1.x request head — the request line and the //! field lines that follow it, up to the empty line that ends them. //! //! Two steps, deliberately separate. `read` gets the octets off the //! connection and into a buffer of their own; `parse` takes that buffer apart //! and never touches the connection. Keeping them apart is what lets the //! parser be tested and fuzzed on a string, and it is also what keeps the //! head valid for the length of the exchange: the head lives in a buffer of //! its own rather than in the connection's, so reading the body cannot //! overwrite the field values a handler is still holding. //! //! ## What is refused, and why //! //! Most of the rules here exist because two participants that disagree about //! where a message ends can be made to see two different messages in one //! stream. RFC 9112 §11.2 calls it request smuggling; the defence is to //! refuse anything ambiguous rather than to pick an interpretation: //! //! * A line folded onto the next with leading whitespace — `obs-fold` — is //! refused. RFC 9112 §5.2 allows a server to replace it with spaces //! instead, but a folded `Content-Length` is a value that a recipient which //! unfolds and a recipient which does not will read differently. //! * Whitespace between a field name and its colon is refused, which RFC 9112 //! §5.1 requires: `Content-Length : 5` is a field some implementations read //! and others ignore. //! * A bare CR or LF anywhere in the head is refused, by being neither a //! valid token character nor a valid field-value character. A head is //! terminated by CRLFCRLF and by nothing else. //! * Anything but exactly one space between the three parts of the request //! line is refused. const std = @import("std"); const Io = std.Io; const Allocator = std.mem.Allocator; const protocol = @import("../protocol.zig"); const Field = protocol.Field; const Method = protocol.Method; const Target = protocol.Target; const Version = protocol.Version; const token = protocol.token; /// The end of a head, and the only thing that ends one. pub const terminator = "\r\n\r\n"; pub const ReadError = error{ /// The connection failed. ReadFailed, /// The connection ended cleanly with no request on it at all, which is /// what an idle kept-alive connection being closed looks like and is not /// an error worth reporting. EndOfStream, /// The connection ended part way through a head. IncompleteHead, /// The head did not end within the buffer it was being read into, which /// is `431 Request Header Fields Too Large`. HeadTooLong, }; /// Reads a head into `buf`, returning the part of it that was used, /// terminator included. A request head on the server, and a response head on /// the client: this looks only for the terminator, and `parse` or /// `parseResponse` decides what the head says. /// /// Copies out of the connection's buffer whatever has arrived rather than /// reading a line at a time, so that the longest line a request may carry is /// bounded by `buf` and not by the connection's read buffer. A server that /// wants to accept a 16 KiB cookie should not need a 16 KiB buffer per idle /// connection to do it. Nothing past the terminator is consumed. /// /// Up to two leading empty lines are skipped. RFC 9112 §2.2 requires a server /// to ignore at least one, because an HTTP/1.0 client that ended its last /// request with a stray CRLF is otherwise never heard from again. pub fn read(in: *Io.Reader, buf: []u8) ReadError![]u8 { var empty_lines: usize = 0; while (empty_lines < 2) : (empty_lines += 1) { const peeked = in.peek(2) catch |err| switch (err) { error.EndOfStream => return error.EndOfStream, error.ReadFailed => return error.ReadFailed, }; if (!std.mem.eql(u8, peeked, "\r\n")) break; in.toss(2); } var len: usize = 0; while (true) { const available = in.peekGreedy(1) catch |err| switch (err) { error.EndOfStream => return if (len == 0) error.EndOfStream else error.IncompleteHead, error.ReadFailed => return error.ReadFailed, }; const room = buf.len - len; if (room == 0) return error.HeadTooLong; const n = @min(available.len, room); @memcpy(buf[len..][0..n], available[0..n]); // The terminator may straddle the join, so the scan starts three // octets back from where the new data begins. const from = len -| (terminator.len - 1); if (std.mem.indexOfPos(u8, buf[0 .. len + n], from, terminator)) |i| { const end = i + terminator.len; in.toss(end - len); return buf[0..end]; } in.toss(n); len += n; } } pub const ParseError = error{ /// The request line is not three parts separated by single spaces. MalformedRequestLine, /// The status line is not a version, a space and three digits, with an /// optional space and reason phrase after them. MalformedStatusLine, /// The status code is not three digits, or is below 100 and so names no /// class of response. InvalidStatus, /// The method is not a token. InvalidMethod, /// The target is empty, carries an octet it may not, or is none of the /// four forms. InvalidTarget, /// The version is not `HTTP/` followed by a digit, a dot and a digit. InvalidVersion, /// A well-formed version this cannot speak: `505`. UnsupportedVersion, /// A field line folded onto the next, which is refused rather than /// unfolded. ObsoleteLineFolding, /// A field line with no colon, a name that is not a token, whitespace /// before the colon, or a value carrying an octet it may not. MalformedFieldLine, /// More fields than the configured limit: `431`. TooManyFields, OutOfMemory, }; pub const Parsed = struct { method: Method, target: Target, version: Version, }; /// Takes a request head apart, appending its fields to `fields`, which is /// grown with `gpa` and refused with `error.TooManyFields` once it would hold /// more than `max_fields` -- counting any it held already. Up to two leading /// empty lines are skipped, as `read` skips them. /// /// Every slice in the result and in the fields points into `head`, which must /// outlive them. pub fn parse( head: []const u8, gpa: Allocator, fields: *std.ArrayList(Field), max_fields: usize, ) ParseError!Parsed { var rest = head; var empty_lines: usize = 0; while (empty_lines < 2 and std.mem.startsWith(u8, rest, "\r\n")) : (empty_lines += 1) { rest = rest[2..]; } var lines = std.mem.splitSequence(u8, rest, "\r\n"); const request_line = lines.next() orelse return error.MalformedRequestLine; const parsed = try parseRequestLine(request_line); try parseFields(&lines, gpa, fields, max_fields); return parsed; } test parse { const gpa = std.testing.allocator; var fields: std.ArrayList(Field) = .empty; defer fields.deinit(gpa); const parsed = try parse("POST /submit?draft=1 HTTP/1.1\r\nHost: a.example\r\n\r\n", gpa, &fields, 100); try std.testing.expectEqualStrings("POST", parsed.method.name); try std.testing.expectEqualStrings("/submit", parsed.target.path); try std.testing.expectEqualStrings("draft=1", parsed.target.query.?); try std.testing.expectEqual(Version.http_1_1, parsed.version); try std.testing.expectEqualStrings("Host", fields.items[0].name); try std.testing.expectEqualStrings("a.example", fields.items[0].value); } /// The field lines of a head, which are the same on a request and a response /// -- §5 of RFC 9112 defines them once and neither direction varies them. fn parseFields( lines: *std.mem.SplitIterator(u8, .sequence), gpa: Allocator, fields: *std.ArrayList(Field), max_fields: usize, ) ParseError!void { while (lines.next()) |line| { // The empty line that ends the head. Anything after it is the body, // which is not this function's business. if (line.len == 0) break; if (token.isOws(line[0])) return error.ObsoleteLineFolding; const colon = std.mem.indexOfScalar(u8, line, ':') orelse return error.MalformedFieldLine; const name = line[0..colon]; // A token cannot hold a space or a tab, so this is also the check // that refuses whitespace before the colon. if (!token.isToken(name)) return error.MalformedFieldLine; const value = token.trimOws(line[colon + 1 ..]); if (!token.isFieldValue(value)) return error.MalformedFieldLine; if (fields.items.len >= max_fields) return error.TooManyFields; try fields.append(gpa, .{ .name = name, .value = value }); } } /// A response head, which is a status line and the same fields. pub const ParsedResponse = struct { version: Version, status: u16, /// §4 of RFC 9112: the reason phrase "is not a reliable source of /// information" and may be empty, so it is carried and never acted on. reason: []const u8, }; /// Takes a response head apart, appending its fields to `fields` under the /// same rules and the same limit as `parse`. Unlike `parse` it skips no /// leading empty lines; `read` has already done that. /// /// Every slice in the result and in the fields points into `head`, which must /// outlive them. pub fn parseResponse( head: []const u8, gpa: Allocator, fields: *std.ArrayList(Field), max_fields: usize, ) ParseError!ParsedResponse { var lines = std.mem.splitSequence(u8, head, "\r\n"); const status_line = lines.next() orelse return error.MalformedStatusLine; const parsed = try parseStatusLine(status_line); try parseFields(&lines, gpa, fields, max_fields); return parsed; } test parseResponse { const gpa = std.testing.allocator; var fields: std.ArrayList(Field) = .empty; defer fields.deinit(gpa); const parsed = try parseResponse("HTTP/1.1 404 Not Found\r\nContent-Length: 0\r\n\r\n", gpa, &fields, 100); try std.testing.expectEqual(Version.http_1_1, parsed.version); try std.testing.expectEqual(@as(u16, 404), parsed.status); // Carried, and never acted on. try std.testing.expectEqualStrings("Not Found", parsed.reason); try std.testing.expectEqualStrings("0", fields.items[0].value); } /// §4 of RFC 9112: `HTTP-version SP status-code SP [ reason-phrase ]`. fn parseStatusLine(line: []const u8) ParseError!ParsedResponse { const first_space = std.mem.indexOfScalar(u8, line, ' ') orelse return error.MalformedStatusLine; const version = try Version.parseHttp1(line[0..first_space]); const after_version = line[first_space + 1 ..]; // §4: "the status-code element is a 3-digit integer code". Exactly three, // so `20` and `2000` are both refused rather than read as something. if (after_version.len < 3) return error.MalformedStatusLine; const digits = after_version[0..3]; var status: u16 = 0; for (digits) |c| { if (c < '0' or c > '9') return error.InvalidStatus; status = status * 10 + (c - '0'); } // §15: "the status-code element is a three-digit integer code... The // first digit of the status-code defines the class of response." A code // below 100 has no class and is not a status. if (status < 100) return error.InvalidStatus; // §4: the space and the reason phrase are both optional in practice -- // a sender "SHOULD" send the space, and the phrase may be empty. Being // strict here would refuse real servers over text nothing reads. const reason = if (after_version.len == 3) "" else if (after_version[3] == ' ') after_version[4..] else return error.MalformedStatusLine; if (!token.isFieldValue(reason)) return error.MalformedStatusLine; return .{ .version = version, .status = status, .reason = reason }; } fn parseRequestLine(line: []const u8) ParseError!Parsed { const first_space = std.mem.indexOfScalar(u8, line, ' ') orelse return error.MalformedRequestLine; const method = Method.parse(line[0..first_space]) catch return error.InvalidMethod; const after_method = line[first_space + 1 ..]; const second_space = std.mem.indexOfScalar(u8, after_method, ' ') orelse return error.MalformedRequestLine; const target = Target.parse(after_method[0..second_space]) catch return error.InvalidTarget; // Anything but exactly one space here leaves the version the wrong // length, which `parseHttp1` refuses -- so `GET / HTTP/1.1` and // `GET / HTTP/1.1 junk` are both rejected without a check of their own. const version = try Version.parseHttp1(after_method[second_space + 1 ..]); return .{ .method = method, .target = target, .version = version }; } const testing = std.testing; fn expectParse(input: []const u8) !struct { Parsed, std.ArrayList(Field) } { var fields: std.ArrayList(Field) = .empty; errdefer fields.deinit(testing.allocator); const parsed = try parse(input, testing.allocator, &fields, 100); return .{ parsed, fields }; } test "an ordinary request" { const parsed, var fields = try expectParse( "GET /index.html?q=1 HTTP/1.1\r\n" ++ "Host: example.com\r\n" ++ "Accept: text/html \r\n" ++ "\r\n", ); defer fields.deinit(testing.allocator); try testing.expectEqualStrings("GET", parsed.method.name); try testing.expectEqualStrings("/index.html", parsed.target.path); try testing.expectEqualStrings("q=1", parsed.target.query.?); try testing.expectEqual(Version.http_1_1, parsed.version); try testing.expectEqual(@as(usize, 2), fields.items.len); try testing.expectEqualStrings("Host", fields.items[0].name); try testing.expectEqualStrings("example.com", fields.items[0].value); // The optional whitespace around a value is not part of it. try testing.expectEqualStrings("text/html", fields.items[1].value); } test "a request line with no fields at all" { const parsed, var fields = try expectParse("GET / HTTP/1.0\r\n\r\n"); defer fields.deinit(testing.allocator); try testing.expectEqual(Version.http_1_0, parsed.version); try testing.expectEqual(@as(usize, 0), fields.items.len); } test "leading empty lines are ignored" { const parsed, var fields = try expectParse("\r\nGET / HTTP/1.1\r\n\r\n"); defer fields.deinit(testing.allocator); try testing.expectEqualStrings("GET", parsed.method.name); } fn expectParseError(expected: anyerror, input: []const u8) !void { var fields: std.ArrayList(Field) = .empty; defer fields.deinit(testing.allocator); try testing.expectError(expected, parse(input, testing.allocator, &fields, 100)); } test "heads that are refused" { try expectParseError(error.MalformedRequestLine, "GET\r\n\r\n"); try expectParseError(error.MalformedRequestLine, "GET /\r\n\r\n"); try expectParseError(error.InvalidMethod, "GE\x00T / HTTP/1.1\r\n\r\n"); try expectParseError(error.InvalidTarget, "GET HTTP/1.1\r\n\r\n"); try expectParseError(error.InvalidVersion, "GET / HTTP/1.1 junk\r\n\r\n"); // Two spaces between the target and the version. try expectParseError(error.InvalidVersion, "GET / HTTP/1.1\r\n\r\n"); try expectParseError(error.UnsupportedVersion, "GET / HTTP/2.0\r\n\r\n"); try expectParseError(error.UnsupportedVersion, "GET / HTTP/0.9\r\n\r\n"); } test "field lines that are refused" { // A folded continuation line. try expectParseError( error.ObsoleteLineFolding, "GET / HTTP/1.1\r\nX: a\r\n b\r\n\r\n", ); // Whitespace before the colon. try expectParseError( error.MalformedFieldLine, "GET / HTTP/1.1\r\nContent-Length : 5\r\n\r\n", ); try expectParseError( error.MalformedFieldLine, "GET / HTTP/1.1\r\nno-colon\r\n\r\n", ); // A bare LF inside a field value, which would end the line early for a // recipient that accepts one. try expectParseError( error.MalformedFieldLine, "GET / HTTP/1.1\r\nX: a\nContent-Length: 5\r\n\r\n", ); } test "too many fields" { var fields: std.ArrayList(Field) = .empty; defer fields.deinit(testing.allocator); try testing.expectError(error.TooManyFields, parse( "GET / HTTP/1.1\r\nA: 1\r\nB: 2\r\nC: 3\r\n\r\n", testing.allocator, &fields, 2, )); } const memory = @import("../transport/memory.zig"); fn expectRead(expected: []const u8, source: []const u8, chunk: usize) !void { var c: memory.Connection = try .init(testing.allocator, source, .{ .chunk = chunk }); defer c.deinit(); const conn = c.connection(); var buf: [1024]u8 = undefined; try testing.expectEqualStrings(expected, try read(conn.input, &buf)); } test read { const request = "GET / HTTP/1.1\r\nHost: a\r\n\r\n"; // Whole, and then one octet at a time, which is what puts the terminator // across the join between two reads. try expectRead(request, request ++ "body", 0); try expectRead(request, request ++ "body", 1); try expectRead(request, request ++ "body", 3); // Leading empty lines are skipped before anything is copied. try expectRead(request, "\r\n" ++ request, 1); } test "read stops at the end of one request and leaves the next" { var c: memory.Connection = try .init( testing.allocator, "GET /a HTTP/1.1\r\n\r\nGET /b HTTP/1.1\r\n\r\n", .{}, ); defer c.deinit(); const conn = c.connection(); var buf: [1024]u8 = undefined; try testing.expectEqualStrings("GET /a HTTP/1.1\r\n\r\n", try read(conn.input, &buf)); try testing.expectEqualStrings("GET /b HTTP/1.1\r\n\r\n", try read(conn.input, &buf)); try testing.expectError(error.EndOfStream, read(conn.input, &buf)); } test "reads that are refused" { var c: memory.Connection = try .init(testing.allocator, "GET / HTTP/1.1\r\nHost: a\r\n", .{}); defer c.deinit(); const conn = c.connection(); var buf: [1024]u8 = undefined; try testing.expectError(error.IncompleteHead, read(conn.input, &buf)); var long: memory.Connection = try .init(testing.allocator, "GET / HTTP/1.1\r\nX: aaaaaaaaaa\r\n\r\n", .{}); defer long.deinit(); const long_conn = long.connection(); var small: [16]u8 = undefined; try testing.expectError(error.HeadTooLong, read(long_conn.input, &small)); } fn expectResponse(input: []const u8) !struct { ParsedResponse, std.ArrayList(Field) } { var fields: std.ArrayList(Field) = .empty; errdefer fields.deinit(testing.allocator); const parsed = try parseResponse(input, testing.allocator, &fields, 100); return .{ parsed, fields }; } test "an ordinary response" { const parsed, var fields = try expectResponse( "HTTP/1.1 200 OK\r\n" ++ "Content-Type: text/plain\r\n" ++ "Content-Length: 5 \r\n" ++ "\r\n", ); defer fields.deinit(testing.allocator); try testing.expectEqual(Version.http_1_1, parsed.version); try testing.expectEqual(@as(u16, 200), parsed.status); try testing.expectEqualStrings("OK", parsed.reason); try testing.expectEqual(@as(usize, 2), fields.items.len); try testing.expectEqualStrings("5", fields.items[1].value); } test "RFC 9112 4: the reason phrase is optional and never acted on" { // "The reason-phrase element exists for the sole purpose of providing a // textual description associated with the numeric status code, mostly out // of deference to earlier Internet application protocols... A client // SHOULD ignore the reason-phrase content." Servers send it empty, and a // parser that insisted on one would refuse them. { const parsed, var fields = try expectResponse("HTTP/1.1 204 \r\n\r\n"); defer fields.deinit(testing.allocator); try testing.expectEqual(@as(u16, 204), parsed.status); try testing.expectEqualStrings("", parsed.reason); } { // And with no space at all, which is what some servers send. const parsed, var fields = try expectResponse("HTTP/1.1 204\r\n\r\n"); defer fields.deinit(testing.allocator); try testing.expectEqual(@as(u16, 204), parsed.status); try testing.expectEqualStrings("", parsed.reason); } { // A phrase with spaces in it is one phrase, not the start of a third // field. const parsed, var fields = try expectResponse("HTTP/1.1 404 Not Found\r\n\r\n"); defer fields.deinit(testing.allocator); try testing.expectEqualStrings("Not Found", parsed.reason); } } test "RFC 9112 4: a status code is exactly three digits" { // Two digits and a space: the three octets where a code belongs are not // three digits, which is what `InvalidStatus` says. try testing.expectError(error.InvalidStatus, expectResponse("HTTP/1.1 20 OK\r\n\r\n")); try testing.expectError(error.InvalidStatus, expectResponse("HTTP/1.1 2x0 OK\r\n\r\n")); try testing.expectError(error.InvalidStatus, expectResponse("HTTP/1.1 099 OK\r\n\r\n")); // Four digits is three digits followed by something that is not a space, // which is a malformed line rather than a status of 200. try testing.expectError(error.MalformedStatusLine, expectResponse("HTTP/1.1 2000 OK\r\n\r\n")); try testing.expectError(error.MalformedStatusLine, expectResponse("HTTP/1.1\r\n\r\n")); } test "a response head carries the same field rules as a request head" { // The field lines are parsed by the same function, so the rules that make // a request head safe make a response head safe: no obsolete folding, no // whitespace before the colon, no control characters in a value. try testing.expectError( error.ObsoleteLineFolding, expectResponse("HTTP/1.1 200 OK\r\nX: a\r\n b\r\n\r\n"), ); try testing.expectError( error.MalformedFieldLine, expectResponse("HTTP/1.1 200 OK\r\nX : a\r\n\r\n"), ); } test "an HTTP/1.0 response is understood" { const parsed, var fields = try expectResponse("HTTP/1.0 200 OK\r\n\r\n"); defer fields.deinit(testing.allocator); try testing.expectEqual(Version.http_1_0, parsed.version); }