// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // 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, repeat("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" ++ @as([100]u8, @splat('x')) ++ "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: " ++ @as([200]u8, @splat('a')) ++ "\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 = repeat("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); } /// `s` said `n` times over: what `s ** n` spelled before Zig 0.17 took the /// operator away. inline fn repeat(comptime s: []const u8, comptime n: usize) *const [s.len * n]u8 { comptime { const rows: [n][s.len]u8 = @splat(s[0..s.len].*); const flat: [s.len * n]u8 = @bitCast(rows); return ♭ } }