// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! The HTTP/1.x client, driven over a slice of memory. //! //! A scripted server: the response is a string literal and what the client //! wrote is read back and asserted. No socket, no port, no scheduling -- the //! same shape `tests/e2e.zig` has for the server, and for the same reason. A //! framing bug reproduces from a literal rather than from a packet capture. const std = @import("std"); const Io = std.Io; const testing = std.testing; const http = @import("http"); const client = http.http1.client; /// Runs one exchange against a scripted response and hands the live response /// to `check`. /// /// A callback rather than a return value, because every slice in a response /// points into the connection's head buffer -- see the note at the top of /// `client/Response.zig`. Returning one would hand back a response whose /// fields had been freed, which is how this helper was first written and what /// the first run of these tests segfaulted on. fn exchange( gpa: std.mem.Allocator, response: []const u8, request: http.client.Request, config: client.Config, comptime check: fn (*client.Connection, http.client.Response, []const u8, []const u8) anyerror!void, ) !void { const io = testing.io; var memory = try http.transport.memory.Connection.init(gpa, response, .{}); defer memory.deinit(); var conn = try client.Connection.init(io, gpa, memory.connection(), config); defer conn.deinit(); const res = try conn.send(request); const body = try conn.readAll(res, 1 << 20); defer gpa.free(body); try check(&conn, res, body, memory.written()); } test "a GET, and the request that went out to get it" { try exchange( testing.allocator, "HTTP/1.1 200 OK\r\nContent-Length: 5\r\nContent-Type: text/plain\r\n\r\nhello", .{ .host = "example.com", .target = "/index.html" }, .{}, struct { fn check(conn: *client.Connection, res: http.client.Response, body: []const u8, sent: []const u8) !void { try testing.expectEqual(@as(u16, 200), res.status); try testing.expect(res.isOk()); try testing.expectEqualStrings("OK", res.reason); try testing.expectEqualStrings("text/plain", res.header("content-type").?); try testing.expectEqualStrings("hello", body); // §9.3 of RFC 9112: HTTP/1.1 is persistent unless `close` is // named. try testing.expect(conn.canReuse()); // §3.2: exactly one `Host`, written by the driver rather than // the caller, so the authority has one source. try testing.expectEqualStrings( "GET /index.html HTTP/1.1\r\nHost: example.com\r\n\r\n", sent, ); } }.check, ); } test "RFC 9112 6.3 rule 1: a HEAD response is head only, whatever it declares" { // The field says five octets and there are none, because a `HEAD` is // answered with the head a `GET` would have had. A client that believed // the field would read the next response as this one's content. try exchange( testing.allocator, "HTTP/1.1 200 OK\r\nContent-Length: 5\r\n\r\n", .{ .host = "example.com", .method = http.protocol.Method.head }, .{}, struct { fn check(_: *client.Connection, res: http.client.Response, body: []const u8, _: []const u8) !void { try testing.expectEqual(@as(u16, 200), res.status); try testing.expectEqualStrings("", body); try testing.expect(!res.body.present); // The field is still readable, because it describes what a // `GET` would have returned. try testing.expectEqualStrings("5", res.header("content-length").?); } }.check, ); } test "a chunked response is the content, with no way to ask that it was chunked" { try exchange( testing.allocator, "HTTP/1.1 200 OK\r\nTransfer-Encoding: chunked\r\n\r\n" ++ "5\r\nhello\r\n6\r\n world\r\n0\r\n\r\n", .{ .host = "example.com" }, .{}, struct { fn check(conn: *client.Connection, res: http.client.Response, body: []const u8, _: []const u8) !void { try testing.expectEqualStrings("hello world", body); try testing.expectEqual(@as(?u64, null), res.body.length); // The coding ends the body, so the connection survives it. try testing.expect(conn.canReuse()); } }.check, ); } test "RFC 9112 6.3 rule 3: a response framed two ways at once is refused" { // "Such a message might indicate an attempt to perform request smuggling // or response splitting and ought to be handled as an error." Guessing // which to believe is guessing where the next response starts. const gpa = testing.allocator; var memory = try http.transport.memory.Connection.init( gpa, "HTTP/1.1 200 OK\r\nContent-Length: 5\r\nTransfer-Encoding: chunked\r\n\r\nhello", .{}, ); defer memory.deinit(); var conn = try client.Connection.init(testing.io, gpa, memory.connection(), .{}); defer conn.deinit(); try testing.expectError(error.InvalidFraming, conn.send(.{ .host = "example.com" })); } test "RFC 9112 6.3 rule 8: a response with no framing runs to the close" { try exchange( testing.allocator, "HTTP/1.0 200 OK\r\n\r\neverything until the socket shuts", .{ .host = "example.com" }, .{}, struct { fn check(conn: *client.Connection, res: http.client.Response, body: []const u8, _: []const u8) !void { try testing.expectEqualStrings("everything until the socket shuts", body); try testing.expectEqual(http.protocol.Version.http_1_0, res.version); // The body ended because the connection did, so there is no // next message on it. try testing.expect(!conn.canReuse()); } }.check, ); } test "RFC 9112 9.3: an HTTP/1.0 response is not persistent unless it says so" { try exchange( testing.allocator, "HTTP/1.0 200 OK\r\nContent-Length: 2\r\n\r\nhi", .{ .host = "example.com" }, .{}, struct { fn check(conn: *client.Connection, _: http.client.Response, _: []const u8, _: []const u8) !void { try testing.expect(!conn.canReuse()); } }.check, ); try exchange( testing.allocator, "HTTP/1.0 200 OK\r\nContent-Length: 2\r\nConnection: keep-alive\r\n\r\nhi", .{ .host = "example.com" }, .{}, struct { fn check(conn: *client.Connection, _: http.client.Response, _: []const u8, _: []const u8) !void { try testing.expect(conn.canReuse()); } }.check, ); } test "an HTTP/1.1 response naming close ends the connection" { try exchange( testing.allocator, "HTTP/1.1 200 OK\r\nContent-Length: 2\r\nConnection: close\r\n\r\nhi", .{ .host = "example.com" }, .{}, struct { fn check(conn: *client.Connection, _: http.client.Response, _: []const u8, _: []const u8) !void { try testing.expect(!conn.canReuse()); } }.check, ); } test "a request body with a known length is sent with one" { try exchange( testing.allocator, "HTTP/1.1 204 \r\n\r\n", .{ .host = "example.com", .method = http.protocol.Method.post, .target = "/submit", .body = .{ .exact = 4 }, .content = "data", }, .{}, struct { fn check(_: *client.Connection, res: http.client.Response, _: []const u8, sent: []const u8) !void { try testing.expectEqual(@as(u16, 204), res.status); try testing.expectEqualStrings( "POST /submit HTTP/1.1\r\nHost: example.com\r\nContent-Length: 4\r\n\r\ndata", sent, ); } }.check, ); } test "a request body of unknown length is chunked, and only in HTTP/1.1" { try exchange( testing.allocator, "HTTP/1.1 204 \r\n\r\n", .{ .host = "example.com", .method = http.protocol.Method.post, .body = .unknown, .content = "data", }, .{}, struct { fn check(_: *client.Connection, _: http.client.Response, _: []const u8, sent: []const u8) !void { try testing.expectEqualStrings( "POST / HTTP/1.1\r\nHost: example.com\r\nTransfer-Encoding: chunked\r\n\r\n" ++ "4\r\ndata\r\n0\r\n\r\n", sent, ); } }.check, ); // §6.1: chunked is HTTP/1.1's. An HTTP/1.0 recipient would read the sizes // as content, so the driver refuses rather than sending it. const gpa = testing.allocator; var memory = try http.transport.memory.Connection.init(gpa, "HTTP/1.0 204 \r\n\r\n", .{}); defer memory.deinit(); var conn = try client.Connection.init(testing.io, gpa, memory.connection(), .{ .version = .http_1_0 }); defer conn.deinit(); try testing.expectError(error.InvalidRequest, conn.send(.{ .host = "example.com", .method = http.protocol.Method.post, .body = .unknown, .content = "data", })); } test "an HTTP/1.1 request without an authority is refused before it is sent" { // §3.2: "A client MUST send a Host header field in all HTTP/1.1 request // messages." Sending one without is sending a message every server must // reject, which is worth refusing here rather than discovering there. const gpa = testing.allocator; var memory = try http.transport.memory.Connection.init(gpa, "HTTP/1.1 200 OK\r\n\r\n", .{}); defer memory.deinit(); var conn = try client.Connection.init(testing.io, gpa, memory.connection(), .{}); defer conn.deinit(); try testing.expectError(error.InvalidRequest, conn.send(.{ .host = "" })); } test "a target carrying a CRLF is refused, and nothing goes out" { // §2.2 of RFC 9112: a message is a sequence of lines ended by CRLF, so a // target carrying one does not travel as a target. It ends the request // line, and everything after it is read as fields -- a field the caller // never sent, which the server has no way to tell from one it did. A // caller that builds a path out of something it was given reaches this // without doing anything unusual, which is what makes it worth refusing // here rather than trusting every caller to have checked. // // Found by fuzzing what the client writes rather than what it reads. // Before this, `send` reported success and put four lines on the wire: // // GET /a // X-Injected: yes // Junk: HTTP/1.1 // Host: example.com const gpa = testing.allocator; var memory = try http.transport.memory.Connection.init(gpa, "HTTP/1.1 200 OK\r\n\r\n", .{}); defer memory.deinit(); var conn = try client.Connection.init(testing.io, gpa, memory.connection(), .{}); defer conn.deinit(); try testing.expectError(error.InvalidRequest, conn.send(.{ .host = "example.com", .target = "/a\r\nX-Injected: yes\r\nJunk: ", })); // Refused *before* it is sent, which is the half that matters: a driver // that noticed after writing the request line would have already sent // the injected field. try testing.expectEqualStrings("", memory.written()); // The authority goes out on a line of its own and splits the same way. try testing.expectError(error.InvalidRequest, conn.send(.{ .host = "example.com\r\nX-Injected: yes", .target = "/", })); try testing.expectEqualStrings("", memory.written()); } /// The fixture, gzipped. std's codec rather than anything of this library's, /// because what these tests are about is the wiring: whether the driver asks, /// notices, and undoes — not whether deflate works, which `protocol.coding` /// has its own round trip for. fn gzipped(plain: []const u8, into: []u8) ![]u8 { var out: std.Io.Writer = .fixed(into); var window: [http.protocol.coding.window_len]u8 = undefined; var c = try http.protocol.coding.gzipCompressor(&out, &window, .default); try c.writer.writeAll(plain); try c.finish(); return out.buffered(); } /// Standing a connection up and taking it down again, for /// `checkAllAllocationFailures` to run once per allocation with that one /// failing. /// /// `init` and not a whole exchange, and the reason is worth leaving here so /// nobody spends an afternoon widening it: the memory transport writes through /// an `Io.Writer.Allocating`, and a `drain` can only report `Writer.Error`, so /// an allocation that fails while the request is going out arrives as /// `error.WriteFailed` with the `OutOfMemory` already lost. That is correct of /// the interface and fatal to this tool, which insists on seeing /// `error.OutOfMemory` from every failing run. Covering the send path needs a /// transport whose writes cannot allocate, which is a different fixture. fn initAndDeinit(gpa: std.mem.Allocator) !void { var memory = try http.transport.memory.Connection.init(gpa, "", .{}); defer memory.deinit(); var conn = try client.Connection.init(testing.io, gpa, memory.connection(), .{}); conn.deinit(); } test "an allocation that fails while standing up a connection frees what it took" { // `init` allocated its two buffers inside the returned struct literal, // where a `try` on the second has nowhere to put an `errdefer` -- so a // failure there leaked the first, and left the caller no `Connection` to // free it through. Reported from zig-weather, whose own tests make every // allocation fail in turn, which is the only way anybody sees this. // // `checkAllAllocationFailures` runs the body once to count the // allocations, then once for each with that one failing, and insists every // failing run reports `OutOfMemory` *and* gives back every octet it took. try testing.checkAllAllocationFailures(testing.allocator, initAndDeinit, .{}); } /// One whole response carrying `coded` as a gzipped body, built without an /// allocator so that a fixture cannot be what a leak check reports. fn codedResponse(coded: []const u8, into: []u8) ![]u8 { var head_buf: [128]u8 = undefined; const head_text = try std.fmt.bufPrint( &head_buf, "HTTP/1.1 200 OK\r\nContent-Encoding: gzip\r\nContent-Length: {d}\r\n\r\n", .{coded.len}, ); @memcpy(into[0..head_text.len], head_text); @memcpy(into[head_text.len..][0..coded.len], coded); return into[0 .. head_text.len + coded.len]; } /// Long enough and repetitive enough that the coded form is plainly smaller, /// so a test that accidentally compared coded with coded would not pass. const compressible = "a content coding is part of the representation. " ** 24; test "RFC 9110 12.5.3: a client that asks for gzip is answered and undoes it" { const gpa = testing.allocator; var coded_buf: [4096]u8 = undefined; const coded = try gzipped(compressible, &coded_buf); try testing.expect(coded.len < compressible.len); var whole: [8192]u8 = undefined; const response = try codedResponse(coded, &whole); var memory = try http.transport.memory.Connection.init(gpa, response, .{}); defer memory.deinit(); var conn = try client.Connection.init(testing.io, gpa, memory.connection(), .{ .accept_encodings = &.{.gzip}, }); defer conn.deinit(); const res = try conn.send(.{ .host = "example.com", .target = "/" }); // §12.5.3: it asked. Without this the server has no reason to have sent // the coding, and the rest of the test would be checking a fixture. try testing.expect(std.mem.indexOf(u8, memory.written(), "Accept-Encoding: gzip\r\n") != null); // §8.6: `Content-Length` counted the coded octets, and the caller is // about to read the decoded ones — so the length it was given must not // be the one on the wire. Saying nothing is the only honest answer. try testing.expectEqual(@as(?u64, null), res.body.length); const body = try conn.readAll(res, 1 << 20); defer gpa.free(body); try testing.expectEqualStrings(compressible, body); } test "RFC 9110 8.4: a coding nobody asked to have undone is handed over coded" { // A content coding is part of the representation, so a client that did // not ask for one gets what arrived rather than a driver's opinion of it. // This is the behaviour the README argues for, now with a second way to // reach it: the codings are configured off. const gpa = testing.allocator; var coded_buf: [4096]u8 = undefined; const coded = try gzipped(compressible, &coded_buf); var whole: [8192]u8 = undefined; const response = try codedResponse(coded, &whole); var memory = try http.transport.memory.Connection.init(gpa, response, .{}); defer memory.deinit(); var conn = try client.Connection.init(testing.io, gpa, memory.connection(), .{}); defer conn.deinit(); const res = try conn.send(.{ .host = "example.com", .target = "/" }); // Nothing was asked for, so nothing was sent to ask. try testing.expect(std.mem.indexOf(u8, memory.written(), "Accept-Encoding") == null); // And the length still describes what the caller will read, because what // the caller will read is what arrived. try testing.expectEqual(@as(?u64, coded.len), res.body.length); const body = try conn.readAll(res, 1 << 20); defer gpa.free(body); try testing.expectEqualStrings(coded, body); } test "RFC 9110 8.4: a coding this library cannot undo is not pretended about" { // `br` is a coding this library names and cannot perform. Handing the // body over coded is right; what would be wrong is decoding it as gzip, // or refusing a response whose representation is simply not this // driver's business. const gpa = testing.allocator; const response = "HTTP/1.1 200 OK\r\nContent-Encoding: br\r\nContent-Length: 5\r\n\r\nzzzzz"; var memory = try http.transport.memory.Connection.init(gpa, response, .{}); defer memory.deinit(); var conn = try client.Connection.init(testing.io, gpa, memory.connection(), .{ .accept_encodings = &.{.gzip}, }); defer conn.deinit(); const res = try conn.send(.{ .host = "example.com", .target = "/" }); try testing.expectEqual(@as(?u64, 5), res.body.length); const body = try conn.readAll(res, 1 << 20); defer gpa.free(body); try testing.expectEqualStrings("zzzzz", body); } test "the driver owns Accept-Encoding only while it is negotiating" { // Two sources for one negotiation is a client that asks for one thing and // decodes another, which is why the driver refuses a caller-set field // while it is asking for codings itself -- and why it does not refuse one // when it is not, since then the field is the caller's and so is whatever // comes back. const gpa = testing.allocator; var asking = try http.transport.memory.Connection.init(gpa, "HTTP/1.1 204 No Content\r\n\r\n", .{}); defer asking.deinit(); var with = try client.Connection.init(testing.io, gpa, asking.connection(), .{ .accept_encodings = &.{.gzip}, }); defer with.deinit(); var headers: http.protocol.Headers = .empty; defer headers.deinit(gpa); try headers.append(gpa, "Accept-Encoding", "br"); try testing.expectError(error.InvalidRequest, with.send(.{ .host = "example.com", .target = "/", .headers = headers, })); var quiet = try http.transport.memory.Connection.init(gpa, "HTTP/1.1 204 No Content\r\n\r\n", .{}); defer quiet.deinit(); var without = try client.Connection.init(testing.io, gpa, quiet.connection(), .{}); defer without.deinit(); _ = try without.send(.{ .host = "example.com", .target = "/", .headers = headers }); try testing.expect(std.mem.indexOf(u8, quiet.written(), "Accept-Encoding: br\r\n") != null); } test "two exchanges on one connection" { // What keep-alive is for, and why the driver holds state rather than // taking it per call: the second request is written into the connection // the first left behind. const gpa = testing.allocator; var memory = try http.transport.memory.Connection.init( gpa, "HTTP/1.1 200 OK\r\nContent-Length: 3\r\n\r\none" ++ "HTTP/1.1 200 OK\r\nContent-Length: 3\r\n\r\ntwo", .{}, ); defer memory.deinit(); var conn = try client.Connection.init(testing.io, gpa, memory.connection(), .{}); defer conn.deinit(); const first = try conn.send(.{ .host = "example.com", .target = "/1" }); const first_body = try conn.readAll(first, 1 << 20); defer gpa.free(first_body); try testing.expectEqualStrings("one", first_body); try testing.expect(conn.canReuse()); const second = try conn.send(.{ .host = "example.com", .target = "/2" }); const second_body = try conn.readAll(second, 1 << 20); defer gpa.free(second_body); try testing.expectEqualStrings("two", second_body); } test "a body left unread makes the connection unusable rather than corrupt" { // What is left on the wire is the rest of a message, and the next request // written into it would be answered by the remains of this one. const gpa = testing.allocator; var memory = try http.transport.memory.Connection.init( gpa, "HTTP/1.1 200 OK\r\nContent-Length: 3\r\n\r\none", .{}, ); defer memory.deinit(); var conn = try client.Connection.init(testing.io, gpa, memory.connection(), .{}); defer conn.deinit(); _ = try conn.send(.{ .host = "example.com" }); try testing.expect(!conn.canReuse()); try testing.expectError(error.InvalidRequest, conn.send(.{ .host = "example.com" })); } test "a bodiless response that declares a body ends the connection" { // §6.3 rule 1 outranks rule 3: a 204 has no body "regardless of the // header fields present in the message", so this is framed as bodiless // and that is right. What is not right is reusing the connection -- // `abcde` is still on the wire, and the next request written here would // be answered by it. That is response splitting performed on oneself. // // Found by fuzzing the client against arbitrary server bytes. try exchange( testing.allocator, "HTTP/1.1 204 OK\r\nContent-Length: 5\r\nTransfer-Encoding: chunked\r\n\r\nabcde", .{ .host = "example.com" }, .{}, struct { fn check(conn: *client.Connection, res: http.client.Response, body: []const u8, _: []const u8) !void { try testing.expectEqual(@as(u16, 204), res.status); try testing.expectEqualStrings("", body); try testing.expect(!res.body.present); try testing.expect(!conn.canReuse()); } }.check, ); } test "RFC 9110 15: a status outside every class is carried, not refused" { // "A client MUST understand the class of any status code... and treat an // unrecognized status code as being equivalent to the x00 status code of // that class." A code with no class at all is outside that rule, and // refusing it would make this library the thing that broke rather than // the server that sent it. try exchange( testing.allocator, "HTTP/1.1 804 Nonsense\r\nContent-Length: 2\r\n\r\nhi", .{ .host = "example.com" }, .{}, struct { fn check(_: *client.Connection, res: http.client.Response, body: []const u8, _: []const u8) !void { try testing.expectEqual(@as(u16, 804), res.status); try testing.expectEqual(http.client.Response.Class.unknown, res.class()); try testing.expect(!res.isOk()); try testing.expectEqualStrings("hi", body); } }.check, ); }