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.
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! The HTTP/1.x driver, end to end, over a transport made of a string.//!//! Every test here is a request written out as it would go on the wire and an//! assertion about the response that comes back, which is the only way to//! check the thing that actually matters about an HTTP server: what the//! octets are. A test that called the parser and then the framing logic//! separately would pass while the two disagreed.//!//! There is no socket, no port and no scheduling — `Io.failing` is the `Io`,//! because a memory transport needs no I/O at all and a driver that reached//! for some would fail loudly here rather than quietly in production.
const std = @import("std");const http = @import("http");const testing = std.testing;
const Request = http.server.Request;const Response = http.server.Response;const Handler = http.server.Handler;
/// Runs one connection's worth of requests and hands back everything the/// server wrote.fn exchange( gpa: std.mem.Allocator, request: []const u8, handler: Handler, options: Options,) ![]u8 { var c: http.transport.memory.Connection = try .init(gpa, request, .{ .chunk = options.chunk, .read_buffer_len = options.read_buffer_len, .info = options.info, }); defer c.deinit();
var conn = c.connection(); try http.http1.serve(std.Io.failing, gpa, &conn, handler, options.config); return gpa.dupe(u8, c.written());}
const Options = struct { /// Deliver the request this many octets at a time, or all of it at once. chunk: usize = 0, read_buffer_len: usize = 8192, info: http.transport.Connection.Info = .{}, config: http.http1.Config = .{ .send_date = false, .server_name = null },};
/// The handler most of these use: it says what it was asked for, so that a/// test can tell a request that was parsed right from one that merely did not/// crash.fn echo(req: *Request, res: *Response) anyerror!void { try res.setHeader("Content-Type", "text/plain"); const body = try req.body.readAlloc(req.arena, 1 << 20); try res.sendPrint("{s} {s} {s}|{s}|{s}", .{ req.method.name, req.target.path, req.target.query orelse "", req.authority() orelse "", body, });}
const echo_handler: Handler = .initStateless(echo);
fn expectResponse(expected: []const u8, request: []const u8, handler: Handler) !void { const gpa = testing.allocator; // Whole, then one octet at a time, then three: a parser that only works // when its input arrives all at once is not a parser. for ([_]usize{ 0, 1, 3 }) |chunk| { const got = try exchange(gpa, request, handler, .{ .chunk = chunk }); defer gpa.free(got); testing.expectEqualStrings(expected, got) catch |err| { std.debug.print("(delivered {d} octets at a time)\n", .{chunk}); return err; }; }}
test "the simplest request there is" { try expectResponse( "HTTP/1.1 200 OK\r\n" ++ "Content-Length: 17\r\n" ++ "Content-Type: text/plain\r\n" ++ "\r\n" ++ "GET / |a.example|", "GET / HTTP/1.1\r\nHost: a.example\r\n\r\n", echo_handler, );}
test "a query and a percent-encoded path survive" { try expectResponse( "HTTP/1.1 200 OK\r\n" ++ "Content-Length: 29\r\n" ++ "Content-Type: text/plain\r\n" ++ "\r\n" ++ "GET /a%20b x=1&y=2|a.example|", "GET /a%20b?x=1&y=2 HTTP/1.1\r\nHost: a.example\r\n\r\n", echo_handler, );}
test "an absolute-form target beats the Host field" { // RFC 9112 §3.2.2. The two disagree here on purpose: a server that // believed the field is one half of a cache poisoning. try expectResponse( "HTTP/1.1 200 OK\r\n" ++ "Content-Length: 21\r\n" ++ "Content-Type: text/plain\r\n" ++ "\r\n" ++ "GET /p |real.example|", "GET http://real.example/p HTTP/1.1\r\nHost: lying.example\r\n\r\n", echo_handler, );}
// -- persistence ------------------------------------------------------------
fn tiny(req: *Request, res: *Response) anyerror!void { _ = req; try res.send("hi");}
const tiny_handler: Handler = .initStateless(tiny);
test "HTTP/1.1 keeps the connection and serves both requests" { try expectResponse( "HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nhi" ++ "HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nhi", "GET /a HTTP/1.1\r\nHost: h\r\n\r\nGET /b HTTP/1.1\r\nHost: h\r\n\r\n", tiny_handler, );}
test "HTTP/1.1 closes when asked to, and does not read what follows" { try expectResponse( "HTTP/1.1 200 OK\r\nContent-Length: 2\r\nConnection: close\r\n\r\nhi", "GET /a HTTP/1.1\r\nHost: h\r\nConnection: close\r\n\r\nGET /b HTTP/1.1\r\nHost: h\r\n\r\n", tiny_handler, );}
test "HTTP/1.0 closes unless it asked not to" { try expectResponse( "HTTP/1.0 200 OK\r\nContent-Length: 2\r\nConnection: close\r\n\r\nhi", "GET /a HTTP/1.0\r\n\r\nGET /b HTTP/1.0\r\n\r\n", tiny_handler, );
try expectResponse( "HTTP/1.0 200 OK\r\nContent-Length: 2\r\nConnection: keep-alive\r\n\r\nhi" ++ "HTTP/1.0 200 OK\r\nContent-Length: 2\r\nConnection: close\r\n\r\nhi", "GET /a HTTP/1.0\r\nConnection: keep-alive\r\n\r\nGET /b HTTP/1.0\r\n\r\n", tiny_handler, );}
test "the request limit closes the connection rather than serving forever" { const gpa = testing.allocator; const got = try exchange( gpa, "GET / HTTP/1.1\r\nHost: h\r\n\r\n" ** 3, tiny_handler, .{ .config = .{ .send_date = false, .server_name = null, .max_requests = 2 } }, ); defer gpa.free(got); try testing.expectEqualStrings( "HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nhi" ++ "HTTP/1.1 200 OK\r\nContent-Length: 2\r\nConnection: close\r\n\r\nhi", got, );}
// -- response framing -------------------------------------------------------
fn streaming(req: *Request, res: *Response) anyerror!void { _ = req; try res.setHeader("Content-Type", "text/plain"); const w = try res.beginBody(.unknown); try w.writeAll("one"); try w.flush(); try w.writeAll("two"); try res.end();}
const streaming_handler: Handler = .initStateless(streaming);
test "a body of unknown length is chunked over HTTP/1.1" { try expectResponse( "HTTP/1.1 200 OK\r\n" ++ "Transfer-Encoding: chunked\r\n" ++ "Content-Type: text/plain\r\n" ++ "\r\n" ++ "3\r\none\r\n" ++ "3\r\ntwo\r\n" ++ "0\r\n\r\n", "GET / HTTP/1.1\r\nHost: h\r\n\r\n", streaming_handler, );}
test "a close-delimited body really does end the stream" { // The framing *is* the end of the stream, so the write half has to be // shut down: without it the client cannot tell a complete response from // one that was cut off part way through. const gpa = testing.allocator; var c: http.transport.memory.Connection = try .init( gpa, "GET / HTTP/1.0\r\n\r\n", .{}, ); defer c.deinit();
var conn = c.connection(); try http.http1.serve(std.Io.failing, gpa, &conn, streaming_handler, .{ .send_date = false, .server_name = null, }); try testing.expect(c.write_shutdown);}
test "a body of unknown length ends the connection over HTTP/1.0" { // HTTP/1.0 has no chunked coding, so the only framing left is the end of // the connection -- which means the connection cannot be kept. try expectResponse( "HTTP/1.0 200 OK\r\n" ++ "Connection: close\r\n" ++ "Content-Type: text/plain\r\n" ++ "\r\n" ++ "onetwo", "GET / HTTP/1.0\r\nConnection: keep-alive\r\n\r\n", streaming_handler, );}
fn head_style(req: *Request, res: *Response) anyerror!void { _ = req; try res.setHeader("Content-Type", "text/plain"); // The handler writes the body it would have written for a GET, and does // not have to know which it is answering. try res.send("the whole document");}
test "HEAD gets the length and none of the octets" { try expectResponse( "HTTP/1.1 200 OK\r\n" ++ "Content-Length: 18\r\n" ++ "Content-Type: text/plain\r\n" ++ "\r\n", "HEAD / HTTP/1.1\r\nHost: h\r\n\r\n", .initStateless(head_style), );}
fn no_content(req: *Request, res: *Response) anyerror!void { _ = req; try res.sendStatus(.no_content);}
test "204 carries neither a body nor a Content-Length" { try expectResponse( "HTTP/1.1 204 No Content\r\n\r\n", "GET / HTTP/1.1\r\nHost: h\r\n\r\n", .initStateless(no_content), );}
fn silent(req: *Request, res: *Response) anyerror!void { _ = .{ req, res };}
test "a handler that says nothing means 200 with an empty body" { try expectResponse( "HTTP/1.1 200 OK\r\nContent-Length: 0\r\n\r\n", "GET / HTTP/1.1\r\nHost: h\r\n\r\n", .initStateless(silent), );}
fn redirecting(req: *Request, res: *Response) anyerror!void { _ = req; try res.redirect(.found, "/elsewhere");}
test "a redirect carries its Location" { try expectResponse( "HTTP/1.1 302 Found\r\n" ++ "Content-Length: 10\r\n" ++ "Location: /elsewhere\r\n" ++ "Content-Type: text/plain; charset=utf-8\r\n" ++ "\r\n" ++ "302 Found\n", "GET / HTTP/1.1\r\nHost: h\r\n\r\n", .initStateless(redirecting), );}
fn framing_meddler(req: *Request, res: *Response) anyerror!void { _ = req; // Every one of these is the driver's to decide, and setting them by hand // is how a handler would otherwise be able to desynchronise the stream. try res.setHeader("Content-Length", "99"); try res.setHeader("Transfer-Encoding", "chunked"); try res.setHeader("Connection", "close"); try res.setHeader("X-Kept", "yes"); try res.send("ok");}
test "framing fields set by a handler are ignored" { try expectResponse( "HTTP/1.1 200 OK\r\nContent-Length: 2\r\nX-Kept: yes\r\n\r\nok", "GET / HTTP/1.1\r\nHost: h\r\n\r\n", .initStateless(framing_meddler), );}
fn splitter(req: *Request, res: *Response) anyerror!void { _ = req; const injected = res.setHeader("X-Evil", "a\r\nSet-Cookie: stolen=1"); try testing.expectError(error.InvalidField, injected); try res.send("safe");}
test "a field value that would split the response is refused" { try expectResponse( "HTTP/1.1 200 OK\r\nContent-Length: 4\r\n\r\nsafe", "GET / HTTP/1.1\r\nHost: h\r\n\r\n", .initStateless(splitter), );}
// -- request bodies ---------------------------------------------------------
test "a body with a Content-Length" { try expectResponse( "HTTP/1.1 200 OK\r\n" ++ "Content-Length: 22\r\n" ++ "Content-Type: text/plain\r\n" ++ "\r\n" ++ "POST /p |h|hello there", "POST /p HTTP/1.1\r\nHost: h\r\nContent-Length: 11\r\n\r\nhello there", echo_handler, );}
test "a chunked body, its extensions and its trailers" { try expectResponse( "HTTP/1.1 200 OK\r\n" ++ "Content-Length: 22\r\n" ++ "Content-Type: text/plain\r\n" ++ "\r\n" ++ "POST /p |h|hello there", "POST /p HTTP/1.1\r\nHost: h\r\nTransfer-Encoding: chunked\r\n\r\n" ++ "5;ext=1\r\nhello\r\n" ++ "6\r\n there\r\n" ++ "0\r\n" ++ "X-Checksum: abc\r\n" ++ "\r\n", echo_handler, );}
test "a chunked request is followed by the next request on the connection" { try expectResponse( "HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nhi" ++ "HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nhi", "POST /a HTTP/1.1\r\nHost: h\r\nTransfer-Encoding: chunked\r\n\r\n" ++ "3\r\nabc\r\n0\r\n\r\n" ++ "GET /b HTTP/1.1\r\nHost: h\r\n\r\n", tiny_handler, );}
test "an unread request body is drained so the next request is found" { // `tiny` never reads the body. The connection is only reusable because // the driver throws the rest away. try expectResponse( "HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nhi" ++ "HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nhi", "POST /a HTTP/1.1\r\nHost: h\r\nContent-Length: 5\r\n\r\nabcde" ++ "GET /b HTTP/1.1\r\nHost: h\r\n\r\n", tiny_handler, );}
test "a body too large to drain closes the connection instead" { const gpa = testing.allocator; const got = try exchange( gpa, "POST /a HTTP/1.1\r\nHost: h\r\nContent-Length: 100\r\n\r\n" ++ ("x" ** 100) ++ "GET /b HTTP/1.1\r\nHost: h\r\n\r\n", tiny_handler, .{ .config = .{ .send_date = false, .server_name = null, .max_drain_len = 10 } }, ); defer gpa.free(got); try testing.expectEqualStrings( "HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nhi", got, );}
// -- requests that are refused ----------------------------------------------
fn expectStatus(expected_status: []const u8, request: []const u8) !void { const gpa = testing.allocator; const got = try exchange(gpa, request, echo_handler, .{}); defer gpa.free(got); try testing.expect(std.mem.startsWith(u8, got, expected_status)); // Every refusal closes the connection: the stream cannot be trusted to // be at a message boundary once a message has been refused. try testing.expect(std.mem.indexOf(u8, got, "Connection: close\r\n") != null);}
test "a request carrying both framing fields is refused" { // The shape of every request smuggling attack there is: one recipient // reads the length and the next reads the chunks. try expectStatus("HTTP/1.1 400 Bad Request\r\n", "POST / HTTP/1.1\r\nHost: h\r\n" ++ "Content-Length: 6\r\nTransfer-Encoding: chunked\r\n\r\n0\r\n\r\nGET /x HTTP/1.1\r\n\r\n");}
test "two Content-Lengths that disagree are refused" { try expectStatus("HTTP/1.1 400 Bad Request\r\n", "POST / HTTP/1.1\r\nHost: h\r\n" ++ "Content-Length: 6\r\nContent-Length: 0\r\n\r\nabcdef");}
test "a Content-Length that is not a plain number is refused" { try expectStatus("HTTP/1.1 400 Bad Request\r\n", "POST / HTTP/1.1\r\nHost: h\r\nContent-Length: +6\r\n\r\nabcdef"); try expectStatus("HTTP/1.1 400 Bad Request\r\n", "POST / HTTP/1.1\r\nHost: h\r\nContent-Length: 0x6\r\n\r\nabcdef");}
test "a transfer coding that is not the final chunked is refused" { try expectStatus("HTTP/1.1 400 Bad Request\r\n", "POST / HTTP/1.1\r\nHost: h\r\n" ++ "Transfer-Encoding: chunked, gzip\r\n\r\n"); // Chunked is final, but there is a coding underneath that this cannot // decode -- which is `501` and not `400`. try expectStatus("HTTP/1.1 501 Not Implemented\r\n", "POST / HTTP/1.1\r\nHost: h\r\n" ++ "Transfer-Encoding: gzip, chunked\r\n\r\n");}
test "an HTTP/1.1 request with no Host is refused" { try expectStatus("HTTP/1.1 400 Bad Request\r\n", "GET / HTTP/1.1\r\n\r\n");}
test "two Host fields that disagree are refused" { try expectStatus("HTTP/1.1 400 Bad Request\r\n", "GET / HTTP/1.1\r\nHost: a\r\nHost: b\r\n\r\n");}
test "a folded field line is refused" { try expectStatus("HTTP/1.1 400 Bad Request\r\n", "GET / HTTP/1.1\r\nHost: h\r\nX: a\r\n b\r\n\r\n");}
test "whitespace before a colon is refused" { try expectStatus("HTTP/1.1 400 Bad Request\r\n", "GET / HTTP/1.1\r\nHost: h\r\nContent-Length : 5\r\n\r\n");}
test "a version this server does not speak is 505" { try expectStatus("HTTP/1.1 505 HTTP Version Not Supported\r\n", "GET / HTTP/2.0\r\n\r\n"); try expectStatus("HTTP/1.1 505 HTTP Version Not Supported\r\n", "GET / HTTP/0.9\r\n\r\n");}
test "CONNECT is 501, because there is nowhere to hand the connection" { try expectStatus("HTTP/1.1 501 Not Implemented\r\n", "CONNECT example.com:443 HTTP/1.1\r\nHost: example.com:443\r\n\r\n");}
test "an asterisk target outside OPTIONS is refused" { try expectStatus("HTTP/1.1 400 Bad Request\r\n", "GET * HTTP/1.1\r\nHost: h\r\n\r\n");}
test "a head that does not fit is 431" { const gpa = testing.allocator; const got = try exchange( gpa, "GET / HTTP/1.1\r\nHost: h\r\nX-Big: " ++ ("a" ** 200) ++ "\r\n\r\n", echo_handler, .{ .config = .{ .send_date = false, .server_name = null, .max_head_len = 64 } }, ); defer gpa.free(got); try testing.expect(std.mem.startsWith(u8, got, "HTTP/1.1 431 Request Header Fields Too Large\r\n"));}
test "more fields than the limit is 431" { const gpa = testing.allocator; const got = try exchange( gpa, "GET / HTTP/1.1\r\nHost: h\r\nA: 1\r\nB: 2\r\nC: 3\r\n\r\n", echo_handler, .{ .config = .{ .send_date = false, .server_name = null, .max_header_count = 2 } }, ); defer gpa.free(got); try testing.expect(std.mem.startsWith(u8, got, "HTTP/1.1 431 Request Header Fields Too Large\r\n"));}
test "a HEAD that is refused gets the length and not the body" { const gpa = testing.allocator; const got = try exchange(gpa, "HEAD / HTTP/1.1\r\n\r\n", echo_handler, .{}); defer gpa.free(got); // No `Host`, so `400` -- and still not one octet of body, because a // response to `HEAD` never carries one however badly the request went. try testing.expectEqualStrings( "HTTP/1.1 400 Bad Request\r\n" ++ "Content-Type: text/plain; charset=utf-8\r\n" ++ "Content-Length: 16\r\n" ++ "Connection: close\r\n" ++ "\r\n", got, );}
test "a refusal answers the version it was asked in" { const gpa = testing.allocator; const got = try exchange( gpa, "POST / HTTP/1.0\r\nTransfer-Encoding: chunked\r\n\r\n", echo_handler, .{}, ); defer gpa.free(got); try testing.expect(std.mem.startsWith(u8, got, "HTTP/1.0 400 Bad Request\r\n"));}
test "a truncated head gets no response at all" { const gpa = testing.allocator; const got = try exchange(gpa, "GET / HTTP/1.1\r\nHost: h\r\n", echo_handler, .{}); defer gpa.free(got); // There is nothing to answer: the client stopped mid-sentence, and a // response would be a guess about what it meant to ask. try testing.expectEqualStrings("", got);}
// -- expectations -----------------------------------------------------------
fn reads_body(req: *Request, res: *Response) anyerror!void { const body = try req.body.readAlloc(req.arena, 1 << 20); try res.send(body);}
test "100-continue is sent when the handler asks for the body" { try expectResponse( "HTTP/1.1 100 Continue\r\n\r\n" ++ "HTTP/1.1 200 OK\r\nContent-Length: 5\r\n\r\nhello", "POST / HTTP/1.1\r\nHost: h\r\nContent-Length: 5\r\nExpect: 100-continue\r\n\r\nhello", .initStateless(reads_body), );}
fn refuses_body(req: *Request, res: *Response) anyerror!void { _ = req; try res.sendStatus(.payload_too_large);}
test "100-continue is not sent when the handler answers without the body" { // The whole point of the expectation: the client offered a body, the // server said no, and the body was never sent. The connection cannot be // kept, because the client is still holding one. try expectResponse( "HTTP/1.1 413 Payload Too Large\r\n" ++ "Content-Length: 22\r\n" ++ "Connection: close\r\n" ++ "Content-Type: text/plain; charset=utf-8\r\n" ++ "\r\n" ++ "413 Payload Too Large\n", "POST / HTTP/1.1\r\nHost: h\r\nContent-Length: 5\r\nExpect: 100-continue\r\n\r\nhello", .initStateless(refuses_body), );}
test "an expectation nobody understands is 417" { try expectStatus( "HTTP/1.1 417 Expectation Failed\r\n", "POST / HTTP/1.1\r\nHost: h\r\nExpect: the-moon\r\n\r\n", );}
// -- handlers that go wrong -------------------------------------------------
fn fails_immediately(req: *Request, res: *Response) anyerror!void { _ = .{ req, res }; return error.SomethingWentWrong;}
test "a handler that fails before writing gets a 500" { try expectResponse( "HTTP/1.1 500 Internal Server Error\r\n" ++ "Content-Type: text/plain; charset=utf-8\r\n" ++ "Content-Length: 26\r\n" ++ "Connection: close\r\n" ++ "\r\n" ++ "500 Internal Server Error\n", "GET / HTTP/1.1\r\nHost: h\r\n\r\n", .initStateless(fails_immediately), );}
fn fails_midway(req: *Request, res: *Response) anyerror!void { _ = req; const w = try res.beginBody(.{ .exact = 100 }); try w.writeAll("the first part"); return error.SomethingWentWrong;}
test "a handler that fails after the head closes the connection" { const gpa = testing.allocator; const got = try exchange( gpa, "GET /a HTTP/1.1\r\nHost: h\r\n\r\nGET /b HTTP/1.1\r\nHost: h\r\n\r\n", .initStateless(fails_midway), .{}, ); defer gpa.free(got); // The head promised a hundred octets and fourteen went out. There is no // way to take that back, so the connection ends and the client sees a // truncated response rather than a complete-looking one -- and the // second request is never served. try testing.expectEqualStrings( "HTTP/1.1 200 OK\r\nContent-Length: 100\r\n\r\nthe first part", got, );}
fn writes_too_much(req: *Request, res: *Response) anyerror!void { _ = req; const w = try res.beginBody(.{ .exact = 2 }); try testing.expectError(error.WriteFailed, w.writeAll("far too much")); return error.Overran;}
test "a handler cannot write more than it declared" { const gpa = testing.allocator; const got = try exchange(gpa, "GET / HTTP/1.1\r\nHost: h\r\n\r\n", .initStateless(writes_too_much), .{}); defer gpa.free(got); // Not one octet past the declared length went out: the message on the // wire is short rather than unparseable. try testing.expectEqualStrings("HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\n", got);}
// -- the fields the driver adds ---------------------------------------------
test "Date and Server are added when they are configured" { const gpa = testing.allocator; const got = try exchange(gpa, "GET / HTTP/1.1\r\nHost: h\r\n\r\n", tiny_handler, .{ .config = .{ .server_name = "test-server" }, }); defer gpa.free(got); // `Io.failing` has no clock, and says so by answering zero -- which is a // date, and a deterministic one. try testing.expectEqualStrings( "HTTP/1.1 200 OK\r\n" ++ "Content-Length: 2\r\n" ++ "Date: Thu, 01 Jan 1970 00:00:00 GMT\r\n" ++ "Server: test-server\r\n" ++ "\r\n" ++ "hi", got, );}
fn own_server_header(req: *Request, res: *Response) anyerror!void { _ = req; try res.setHeader("Server", "mine"); try res.send("hi");}
test "a handler's own Server field is left alone" { const gpa = testing.allocator; const got = try exchange(gpa, "GET / HTTP/1.1\r\nHost: h\r\n\r\n", .initStateless(own_server_header), .{ .config = .{ .send_date = false, .server_name = "test-server" }, }); defer gpa.free(got); try testing.expectEqualStrings( "HTTP/1.1 200 OK\r\nContent-Length: 2\r\nServer: mine\r\n\r\nhi", got, );}
// -- the transport is visible, and only where it should be ------------------
fn reports_scheme(req: *Request, res: *Response) anyerror!void { try res.sendPrint("{s}", .{req.scheme()});}
test "a confidential transport makes the scheme https" { try expectResponse( "HTTP/1.1 200 OK\r\nContent-Length: 4\r\n\r\nhttp", "GET / HTTP/1.1\r\nHost: h\r\n\r\n", .initStateless(reports_scheme), );
const gpa = testing.allocator; const got = try exchange(gpa, "GET / HTTP/1.1\r\nHost: h\r\n\r\n", .initStateless(reports_scheme), .{ .info = .{ .secure = true, .alpn = "http/1.1" }, }); defer gpa.free(got); try testing.expectEqualStrings("HTTP/1.1 200 OK\r\nContent-Length: 5\r\n\r\nhttps", got);}
// -- switching protocols ----------------------------------------------------
/// A handler that takes the connection over and then speaks something that is/// not HTTP: it reads a line and writes it back reversed.fn reverser(req: *Request, res: *Response) anyerror!void { if (!req.offersUpgrade("reverse")) return res.sendStatus(.upgrade_required);
try res.setHeader("X-Reverse-Version", "1"); const stream = try res.upgrade("reverse");
// From here there is no HTTP left: these are the same reader and writer // the server was using, positioned exactly where the request head ended. const line = try stream.input.takeDelimiterExclusive('\n'); var reversed: [64]u8 = undefined; for (line, 0..) |c, i| reversed[line.len - 1 - i] = c; try stream.output.writeAll(reversed[0..line.len]); try stream.output.writeAll("\n"); try stream.output.flush();}
test "an upgrade hands the byte stream to the handler" { try expectResponse( "HTTP/1.1 101 Switching Protocols\r\n" ++ "Connection: Upgrade\r\n" ++ "Upgrade: reverse\r\n" ++ "X-Reverse-Version: 1\r\n" ++ "\r\n" ++ "dlrow\n", "GET /chat HTTP/1.1\r\nHost: h\r\nConnection: Upgrade\r\nUpgrade: reverse\r\n\r\n" ++ "world\n", .initStateless(reverser), );}
test "the octets sent behind the handshake are not lost" { // The client pipelined its first message immediately after the request // head, without waiting for the `101`. Those octets were already in the // server's read buffer when the upgrade happened, and the handler has to // see them: losing them is the classic way a protocol switch goes wrong. const gpa = testing.allocator; const got = try exchange( gpa, "GET /chat HTTP/1.1\r\nHost: h\r\nConnection: Upgrade\r\nUpgrade: reverse\r\n\r\nabc\n", .initStateless(reverser), // One octet at a time, so the head and the message really do arrive // in separate reads. .{ .chunk = 1 }, ); defer gpa.free(got); try testing.expect(std.mem.endsWith(u8, got, "\r\n\r\ncba\n"));}
test "an upgraded connection serves no further requests" { const gpa = testing.allocator; const got = try exchange( gpa, "GET /chat HTTP/1.1\r\nHost: h\r\nConnection: Upgrade\r\nUpgrade: reverse\r\n\r\n" ++ "ab\n" ++ "GET /after HTTP/1.1\r\nHost: h\r\n\r\n", .initStateless(reverser), .{}, ); defer gpa.free(got); // The second request is the new protocol's data now, not a request. It // must not be answered. try testing.expect(std.mem.indexOf(u8, got, "/after") == null); try testing.expectEqual(@as(usize, 1), std.mem.count(u8, got, "HTTP/1.1 "));}
fn expectsUpgradeError(expected: anyerror, req: *Request, res: *Response) anyerror!void { _ = req; try testing.expectError(expected, res.upgrade("reverse")); // The response is still untouched, so an ordinary one can still be sent. try res.send("refused");}
fn refusedNotOffered(req: *Request, res: *Response) anyerror!void { return expectsUpgradeError(error.NotOffered, req, res);}
test "an upgrade the client did not offer is refused" { // RFC 9110 §7.8: a server must not switch to a protocol the client did // not list. Both halves of the offer are required, so each of these is a // non-offer. try expectResponse( "HTTP/1.1 200 OK\r\nContent-Length: 7\r\n\r\nrefused", "GET / HTTP/1.1\r\nHost: h\r\n\r\n", .initStateless(refusedNotOffered), ); try expectResponse( "HTTP/1.1 200 OK\r\nContent-Length: 7\r\n\r\nrefused", "GET / HTTP/1.1\r\nHost: h\r\nUpgrade: reverse\r\n\r\n", .initStateless(refusedNotOffered), ); try expectResponse( "HTTP/1.1 200 OK\r\nContent-Length: 7\r\n\r\nrefused", "GET / HTTP/1.1\r\nHost: h\r\nConnection: Upgrade\r\nUpgrade: other\r\n\r\n", .initStateless(refusedNotOffered), );}
fn refusedUnavailable(req: *Request, res: *Response) anyerror!void { return expectsUpgradeError(error.UpgradeUnavailable, req, res);}
test "HTTP/1.0 cannot switch protocols" { try expectResponse( "HTTP/1.0 200 OK\r\nContent-Length: 7\r\nConnection: close\r\n\r\nrefused", "GET / HTTP/1.0\r\nConnection: Upgrade\r\nUpgrade: reverse\r\n\r\n", .initStateless(refusedUnavailable), );}
fn refusedBodyNotConsumed(req: *Request, res: *Response) anyerror!void { return expectsUpgradeError(error.BodyNotConsumed, req, res);}
test "an unread request body blocks the upgrade" { // Those five octets are in front of the new protocol's first octet. A // switch that ignored them would hand the new protocol somebody else's // data. try expectResponse( "HTTP/1.1 200 OK\r\nContent-Length: 7\r\n\r\nrefused", "POST / HTTP/1.1\r\nHost: h\r\nContent-Length: 5\r\n" ++ "Connection: Upgrade\r\nUpgrade: reverse\r\n\r\nabcde", .initStateless(refusedBodyNotConsumed), );}
/// The RFC 6455 opening handshake, and nothing else.////// This library does not implement WebSockets and is not going to. What this/// proves is that it does not need to: the handshake is four field lines and/// a hash, and everything after it is bytes on a stream that `upgrade` has/// already handed over. If this test passes, a WebSocket framing layer can be/// written on top of this library without the library knowing.fn websocket(req: *Request, res: *Response) anyerror!void { if (!req.offersUpgrade("websocket")) return res.sendStatus(.upgrade_required); const key = req.header("sec-websocket-key") orelse return res.sendStatus(.bad_request);
// RFC 6455 §1.3: base64(SHA-1(key ++ the magic GUID)). const magic = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"; var sha1: std.crypto.hash.Sha1 = .init(.{}); sha1.update(key); sha1.update(magic); var digest: [std.crypto.hash.Sha1.digest_length]u8 = undefined; sha1.final(&digest);
var accept: [28]u8 = undefined; _ = std.base64.standard.Encoder.encode(&accept, &digest);
try res.setHeader("Sec-WebSocket-Accept", &accept); const stream = try res.upgrade("websocket");
// A real implementation would read RFC 6455 frames here. This one says // hello in the clear and stops, because the point is the handshake. try stream.output.writeAll("frames would go here"); try stream.output.flush();}
test "the WebSocket opening handshake" { // The key and the accept token are the worked example from RFC 6455 §1.3, // so this is checked against the standard rather than against itself. try expectResponse( "HTTP/1.1 101 Switching Protocols\r\n" ++ "Connection: Upgrade\r\n" ++ "Upgrade: websocket\r\n" ++ "Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=\r\n" ++ "\r\n" ++ "frames would go here", "GET /chat HTTP/1.1\r\n" ++ "Host: server.example.com\r\n" ++ "Upgrade: websocket\r\n" ++ "Connection: Upgrade\r\n" ++ "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n" ++ "Sec-WebSocket-Version: 13\r\n" ++ "\r\n", .initStateless(websocket), );}
/// A response whose trailer is only knowable once the body has been produced/// — which is the case the whole feature exists for.fn trailered(_: *Request, res: *Response) anyerror!void { const w = try res.beginBody(.unknown); try w.writeAll("abc"); try w.writeAll("de"); // Decided here, after the content, which is the point: a handler that // knew this in advance would have put it in `res.headers`. try res.trailers.append(res.arena, "x-length", "5"); // §6.5.1: refused on the way out. A handler that put a framing field in a // trailer would be telling a recipient how long the body was after it had // already read it, which is how a cache and the thing behind it come to // disagree about where one message ends. try res.trailers.append(res.arena, "content-length", "99"); return res.end();}
test "RFC 9112 7.1.2: a trailer section, and what may not be in one" { // The chunked coding is the only HTTP/1.1 framing with anywhere to put // one: the last chunk, then the fields, then the empty line. So the // terminator that is usually written as `0\r\n\r\n` is split in two, with // the trailer section between its halves. try expectResponse( // One chunk rather than two, because the writer buffers and the // handler's two writes fit in it. Which is worth seeing in the // expectation rather than hidden behind it: a chunk boundary is not a // write boundary, and a test that assumed otherwise would be pinning // the buffer's size as if it were part of the protocol. "HTTP/1.1 200 OK\r\nTransfer-Encoding: chunked\r\n\r\n" ++ "5\r\nabcde\r\n" ++ "0\r\nx-length: 5\r\n\r\n", "GET / HTTP/1.1\r\nHost: h\r\n\r\n", .initStateless(trailered), );}
fn trailerWithDeclaredLength(_: *Request, res: *Response) anyerror!void { const w = try res.beginBody(.{ .exact = 5 }); try w.writeAll("abcde"); try res.trailers.append(res.arena, "x-length", "5"); return res.end();}
test "RFC 9110 6.6.2: a framing with nowhere to put a trailer drops it" { // "A trailer section is only possible when the message framing allows // it." A declared length ends where it said it would, so there is no // after to send anything in -- and dropping is the specified behaviour // rather than a shortcut, because §6.5.1 forbids putting anything the // recipient needs in a trailer precisely because it may not arrive. try expectResponse( "HTTP/1.1 200 OK\r\nContent-Length: 5\r\n\r\nabcde", "GET / HTTP/1.1\r\nHost: h\r\n\r\n", .initStateless(trailerWithDeclaredLength), );}
// -- content codings, from the server's side --------------------------------
/// Long enough to be worth coding and repetitive enough that it plainly is.const compressible_body = "a representation worth coding, said again and again. " ** 128;
fn bigText(_: *Request, res: *Response) anyerror!void { try res.setHeader("Content-Type", "text/plain; charset=utf-8"); try res.send(compressible_body);}
fn smallText(_: *Request, res: *Response) anyerror!void { try res.setHeader("Content-Type", "text/plain"); try res.send("short");}
fn bigImage(_: *Request, res: *Response) anyerror!void { try res.setHeader("Content-Type", "image/png"); try res.send(compressible_body);}
const compressing: http.http1.Config = .{ .send_date = false, .server_name = null, .compression = .{},};
/// The head and the body, split at the empty line.fn parts(whole: []const u8) struct { head: []const u8, body: []const u8 } { const at = std.mem.indexOf(u8, whole, "\r\n\r\n").?; return .{ .head = whole[0 .. at + 4], .body = whole[at + 4 ..] };}
/// Undoes a chunked coding, which is what a compressed response is framed/// with: §8.6 counts the coded octets and nothing can count them in advance,/// so `Content-Length` is not available and §6.1 of RFC 9112 is what is left.fn dechunk(gpa: std.mem.Allocator, chunked: []const u8) ![]u8 { var out: std.ArrayList(u8) = .empty; errdefer out.deinit(gpa); var rest = chunked; while (true) { const eol = std.mem.indexOf(u8, rest, "\r\n") orelse break; const size = try std.fmt.parseInt(usize, rest[0..eol], 16); rest = rest[eol + 2 ..]; if (size == 0) break; try out.appendSlice(gpa, rest[0..size]); rest = rest[size + 2 ..]; } return out.toOwnedSlice(gpa);}
test "RFC 9110 8.4: a compressible representation is coded when the client takes it" { const gpa = testing.allocator; const got = try exchange( gpa, "GET / HTTP/1.1\r\nHost: h\r\nAccept-Encoding: gzip\r\n\r\n", .initStateless(bigText), .{ .config = compressing }, ); defer gpa.free(got);
const split = parts(got); try testing.expect(std.mem.indexOf(u8, split.head, "Content-Encoding: gzip\r\n") != null); // §12.5.4: the cache has to be told the representation depends on it. try testing.expect(std.mem.indexOf(u8, split.head, "Vary: Accept-Encoding\r\n") != null); // §8.6 counts coded octets and nobody can count them up front, so the // declared length is gone and §6.1's chunked coding carries the end. try testing.expect(std.mem.indexOf(u8, split.head, "Content-Length") == null); try testing.expect(std.mem.indexOf(u8, split.head, "Transfer-Encoding: chunked") != null);
const coded = try dechunk(gpa, split.body); defer gpa.free(coded); try testing.expect(coded.len < compressible_body.len);
var window: [http.protocol.coding.window_len]u8 = undefined; const plain = try http.protocol.coding.undo(gpa, coded, .gzip, &window, 1 << 20); defer gpa.free(plain); try testing.expectEqualStrings(compressible_body, plain);}
test "RFC 9110 12.5.3: a client that did not ask is not sent a coding" { const gpa = testing.allocator; const got = try exchange( gpa, "GET / HTTP/1.1\r\nHost: h\r\n\r\n", .initStateless(bigText), .{ .config = compressing }, ); defer gpa.free(got);
const split = parts(got); try testing.expect(std.mem.indexOf(u8, split.head, "Content-Encoding") == null); // Still negotiable, so still `Vary` -- the representation this server // sends for this resource does depend on `Accept-Encoding`, and a cache // that stored this one without being told would hand it to a client that // asked for gzip. try testing.expect(std.mem.indexOf(u8, split.head, "Vary: Accept-Encoding\r\n") != null); // And with no coding the length is knowable again. try testing.expect(std.mem.indexOf(u8, split.head, "Content-Length") != null); try testing.expectEqualStrings(compressible_body, split.body);}
test "below the floor, and the wrong media type, are left alone" { const gpa = testing.allocator;
const small = try exchange( gpa, "GET / HTTP/1.1\r\nHost: h\r\nAccept-Encoding: gzip\r\n\r\n", .initStateless(smallText), .{ .config = compressing }, ); defer gpa.free(small); try testing.expect(std.mem.indexOf(u8, small, "Content-Encoding") == null); // Negotiable even so: `text/plain` is a type this server would code, and // a cache has to know that however big this one happened to be. try testing.expect(std.mem.indexOf(u8, small, "Vary: Accept-Encoding\r\n") != null); try testing.expectEqualStrings("short", parts(small).body);
const image = try exchange( gpa, "GET / HTTP/1.1\r\nHost: h\r\nAccept-Encoding: gzip\r\n\r\n", .initStateless(bigImage), .{ .config = compressing }, ); defer gpa.free(image); try testing.expect(std.mem.indexOf(u8, image, "Content-Encoding") == null); // Not negotiable at all, so nothing to tell a cache about. try testing.expect(std.mem.indexOf(u8, image, "Vary") == null);}
test "a server with no compression configured sends none of this" { const gpa = testing.allocator; const got = try exchange( gpa, "GET / HTTP/1.1\r\nHost: h\r\nAccept-Encoding: gzip\r\n\r\n", .initStateless(bigText), .{}, ); defer gpa.free(got); try testing.expect(std.mem.indexOf(u8, got, "Content-Encoding") == null); try testing.expect(std.mem.indexOf(u8, got, "Vary") == null); try testing.expectEqualStrings(compressible_body, parts(got).body);}
// -- a coded request body ---------------------------------------------------
const decoding: http.http1.Config = .{ .send_date = false, .server_name = null, .request_decoding = .{},};
/// Says back exactly what it read, so a test can tell a decoded body from a/// coded one rather than merely from a request that did not crash.fn echoBody(req: *Request, res: *Response) anyerror!void { const body = try req.body.readAlloc(req.arena, 1 << 20); try res.setHeader("Content-Type", "application/octet-stream"); try res.send(body);}
test "RFC 9110 8.4: a coded request body is undone when the server was asked to" { const gpa = testing.allocator;
var coded_buf: [4096]u8 = undefined; var out: std.Io.Writer = .fixed(&coded_buf); var window: [http.protocol.coding.window_len]u8 = undefined; var c = try http.protocol.coding.gzipCompressor(&out, &window, .default); try c.writer.writeAll(compressible_body); try c.finish(); const coded = out.buffered();
var head_buf: [160]u8 = undefined; const head = try std.fmt.bufPrint( &head_buf, "POST / HTTP/1.1\r\nHost: h\r\nContent-Encoding: gzip\r\nContent-Length: {d}\r\n\r\n", .{coded.len}, ); var whole: [8192]u8 = undefined; @memcpy(whole[0..head.len], head); @memcpy(whole[head.len..][0..coded.len], coded); const request = whole[0 .. head.len + coded.len];
// Asked to decode: the handler reads the representation. const decoded_answer = try exchange(gpa, request, .initStateless(echoBody), .{ .config = decoding }); defer gpa.free(decoded_answer); try testing.expectEqualStrings(compressible_body, parts(decoded_answer).body);
// Not asked: the handler reads what arrived, which §8.4 makes the right // thing to hand over -- the `Content-Encoding` field is still on the // request saying what it is. const coded_answer = try exchange(gpa, request, .initStateless(echoBody), .{}); defer gpa.free(coded_answer); try testing.expectEqualStrings(coded, parts(coded_answer).body);}
test "RFC 9110 8.4: a coding the server was not asked to undo is left alone" { const gpa = testing.allocator; // `br` is named and not performed, so even a server that decodes gzip // hands this one over as it arrived rather than guessing. const request = "POST / HTTP/1.1\r\nHost: h\r\nContent-Encoding: br\r\nContent-Length: 5\r\n\r\nzzzzz"; const got = try exchange(gpa, request, .initStateless(echoBody), .{ .config = decoding }); defer gpa.free(got); try testing.expectEqualStrings("zzzzz", parts(got).body);}