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