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.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// 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);}