diff --git a/README.md b/README.md index b48e6b5..32aded4 100644 --- a/README.md +++ b/README.md @@ -181,10 +181,34 @@ protocols](#switching-protocols). Also not implemented, and each for a reason: **server push** (deprecated; a client PUSH_PROMISE is a connection error and `SETTINGS_ENABLE_PUSH` is -advertised as 0), **response trailers**, and **RFC 7540 prioritisation** (PRIORITY -frames are parsed, checked for the one rule that still bites — a stream may -not depend on itself — and then discarded; RFC 9113 deprecated the scheme and -RFC 9218 is the replacement this does not implement). +advertised as 0) and **RFC 7540 prioritisation** (PRIORITY frames are parsed, +checked for the one rule that still bites — a stream may not depend on itself — +and then discarded; RFC 9113 deprecated the scheme and RFC 9218 is the +replacement this does not implement). + +### Response trailers + +`res.trailers` is a `Headers` a handler fills any time before the response +ends, for what is not knowable until the content has been produced: a +checksum, a signature, why a stream stopped early. Each version sends it in +the shape it has, and the three are a fair summary of the three protocols. + +HTTP/1.1 needs the chunked coding and RFC 9112 §7.1.2's trailer section, which +splits the terminator in two: the last chunk, the fields, then the empty line. +A response whose length was declared has nowhere to put them, and §6.6.2 of +RFC 9110 says so — "a trailer section is only possible when the message +framing allows it" — so they are dropped. Dropping is the specified behaviour +rather than a shortcut, which is also why §6.5.1 forbids putting anything the +recipient *needs* in one. + +HTTP/2 needs RFC 9113 §8.1: a second field block with END_STREAM. HTTP/3 needs +RFC 9114 §4.1: a second HEADERS frame, with no flag at all, because the stream +ends when QUIC says it does. One layer fewer each time. + +The fields §6.5.1 forbids are refused on the way out rather than trusted to a +handler that read the section — anything that would change how a message is +framed, routed, cached or authenticated arrives too late to be obeyed, and is +a way to tell a cache one thing and whatever is behind it another. ### A handler is now called concurrently @@ -298,8 +322,7 @@ The check on an incoming one is §7.2.6's: a second GOAWAY may only name something lower, because an increasing one would be a peer taking back a promise the frame exists to make reliable. -Not implemented: a dynamic QPACK table, server push, response trailers, and -`CONNECT`. +Not implemented: a dynamic QPACK table, server push, and `CONNECT`. ## HTTP/1.1 framing, and what is refused @@ -494,8 +517,8 @@ a `CONNECT` handler the same one. What is missing is the proxy, not the seam. * **No client.** * **No dynamic QPACK table, and no `CONNECT` over HTTP/3.** Both argued in the HTTP/3 section. -* **No server push, no response trailers, no RFC 9218 prioritisation.** Each - is argued in the HTTP/2 section. +* **No server push and no RFC 9218 prioritisation.** Each is argued in the + HTTP/2 section. * **No WebSocket framing.** The handshake is here, over both versions; RFC 6455 itself is [zig-websocket](https://git.jcollie.dev/jeff/zig-websocket). * **No content codings.** A request arriving `Content-Encoding: gzip` reaches diff --git a/src/http1/Connection.zig b/src/http1/Connection.zig index 2509efd..309ed0e 100644 --- a/src/http1/Connection.zig +++ b/src/http1/Connection.zig @@ -664,7 +664,7 @@ const Session = struct { fn endBody(res: *Response) Response.Error!void { const s: *Session = @ptrCast(@alignCast(res.context.?)); - try s.body_writer.finish(); + try s.body_writer.finishWithTrailers(&res.trailers); s.conn.output.flush() catch return error.WriteFailed; // A body that ended because the connection did has to actually end // it, or the client cannot tell a complete response from a truncated @@ -961,6 +961,21 @@ const BodyWriter = struct { } fn finish(b: *BodyWriter) Response.Error!void { + const none: Headers = .empty; + return b.finishWithTrailers(&none); + } + + /// RFC 9112 §7.1.2: the trailer section, which only the chunked coding + /// has anywhere to put. + /// + /// "A trailer section is only possible when the message framing allows + /// it" (§6.6.2 of RFC 9110), and the other three modes here do not: a + /// declared length ends where it said it would, and a body that ends by + /// closing the connection has nothing after it by definition. So the + /// fields are dropped, which is what a trailer field is for -- §6.5.1 + /// forbids putting anything the recipient needs in one precisely because + /// it may not arrive. + fn finishWithTrailers(b: *BodyWriter, trailers: *const Headers) Response.Error!void { b.interface.flush() catch return error.WriteFailed; switch (b.mode) { .discard, .until_close => {}, @@ -969,7 +984,18 @@ const BodyWriter = struct { // how long the body would be and it is not that long. if (b.remaining != 0) return error.LengthMismatch; }, - .chunked => b.out.writeAll("0\r\n\r\n") catch return error.WriteFailed, + .chunked => { + // §7.1: the last chunk, then the trailer section, then the + // empty line that ends it -- so the terminator is split in + // two rather than written as one literal. + b.out.writeAll("0\r\n") catch return error.WriteFailed; + for (trailers.fields.items) |f| { + if (Response.isForbiddenTrailer(f.name)) continue; + b.out.print("{s}: {s}\r\n", .{ f.name, f.value }) catch + return error.WriteFailed; + } + b.out.writeAll("\r\n") catch return error.WriteFailed; + }, } } }; diff --git a/src/http2/Connection.zig b/src/http2/Connection.zig index 359adcd..aad742a 100644 --- a/src/http2/Connection.zig +++ b/src/http2/Connection.zig @@ -1340,6 +1340,39 @@ const Stream = struct { return stream.write_buf[0..limit]; } + /// RFC 9113 §8.1: the trailer section, which is a second field block with + /// END_STREAM on it. + /// + /// "An HTTP request or response... can optionally include a trailer + /// section... sent as a HEADERS frame with the END_STREAM flag set", and + /// that is the whole of it -- no chunked coding to arrange, no terminator + /// to split in two, because a field section is already the shape HTTP/2 + /// sends everything in. What HTTP/1.1 needs §7.1.2 for costs nothing + /// here. + /// + /// Sent before the body writer finishes, because the writer's last act is + /// to put END_STREAM on an empty DATA frame -- and a trailer section + /// after the end of the stream is on a stream that has closed. + fn sendTrailers(stream: *Stream, res: *Response) Response.Error!void { + if (res.trailers.fields.items.len == 0) return; + if (stream.end_stream_sent) return; + + var fields: std.ArrayList(Field) = .empty; + for (res.trailers.fields.items) |f| { + // §6.5.1 of RFC 9110, and §8.1's own rule that a trailer section + // carries no pseudo-headers -- it is not a message head and has + // no status to give. + if (Response.isForbiddenTrailer(f.name)) continue; + if (f.name.len > 0 and f.name[0] == ':') continue; + fields.append(res.arena, .{ .name = f.name, .value = f.value }) catch + return error.OutOfMemory; + } + if (fields.items.len == 0) return; + + try stream.sendFieldBlock(fields.items, true); + stream.end_stream_sent = true; + } + /// A field block as HEADERS plus however many CONTINUATION frames the /// peer's maximum frame size requires, all under one hold of the /// serializer: §6.2 forbids any other frame between them, and a block @@ -1611,6 +1644,13 @@ fn beginBody(res: *Response, length: Length) Response.Error!*Io.Writer { fn endBody(res: *Response) Response.Error!void { const stream: *Stream = @ptrCast(@alignCast(res.context.?)); + // Flushed before the trailers, not after. What the handler wrote is + // still in the writer's buffer until this call, so sending the trailer + // section first would put it *in front of* the last of the body -- which + // is a stream whose field section arrives before the content it + // describes, and which a peer reads as a second response head. + stream.body_writer.interface.flush() catch return error.WriteFailed; + try stream.sendTrailers(res); try stream.body_writer.finish(); stream.local = .closed; } diff --git a/src/http3/Connection.zig b/src/http3/Connection.zig index 178fd3a..22baccb 100644 --- a/src/http3/Connection.zig +++ b/src/http3/Connection.zig @@ -505,9 +505,45 @@ fn beginBody(res: *Response, length: protocol.Length) Response.Error!*Io.Writer fn endBody(res: *Response) Response.Error!void { const state: *ResponseState = @ptrCast(@alignCast(res.context.?)); + try sendTrailers(state, res); state.writer.finish() catch return error.WriteFailed; } +/// RFC 9114 §4.1: the trailer section, which is a second HEADERS frame after +/// the DATA frames. +/// +/// Simpler again than HTTP/2's, which needs END_STREAM on the frame: here the +/// end of the trailer section is the end of the QUIC stream, and the stream +/// ends because the writer finishes it. One framing layer fewer, which is the +/// pattern the whole driver has. +fn sendTrailers(state: *ResponseState, res: *Response) Response.Error!void { + if (res.trailers.fields.items.len == 0) return; + + var fields: [64]qpack.Field = undefined; + var count: usize = 0; + for (res.trailers.fields.items) |f| { + if (count == fields.len) break; + // §6.5.1 of RFC 9110, and §4.1's own rule that a trailer section has + // no pseudo-headers in it. + if (Response.isForbiddenTrailer(f.name)) continue; + if (f.name.len > 0 and f.name[0] == ':') continue; + fields[count] = .{ .name = f.name, .value = f.value }; + count += 1; + } + if (count == 0) return; + + var section: [4096]u8 = undefined; + var sw: Io.Writer = .fixed(§ion); + qpack.encode(&sw, fields[0..count]) catch return error.WriteFailed; + const body = sw.buffered(); + + var header: [16]u8 = undefined; + const n = frame.write(&header, .headers, body.len) catch return error.WriteFailed; + state.writer.interface.writeAll(header[0..n]) catch return error.WriteFailed; + state.writer.interface.writeAll(body) catch return error.WriteFailed; + state.writer.interface.flush() catch return error.WriteFailed; +} + fn sendInterim(res: *Response, status: protocol.Status, headers: *const Headers) Response.Error!void { const state: *ResponseState = @ptrCast(@alignCast(res.context.?)); // §4.1: an informational response is a HEADERS frame like any other, and diff --git a/src/server/Response.zig b/src/server/Response.zig index 95855f1..72e614a 100644 --- a/src/server/Response.zig +++ b/src/server/Response.zig @@ -43,6 +43,25 @@ status: Status = .ok, /// must outlive `end`; `printHeader` is the way to add one that has to be /// computed. headers: Headers, +/// RFC 9110 §6.5: fields sent *after* the content, for things that are not +/// known until it has been produced — a checksum, a signature, how long the +/// work took, why a stream stopped early. +/// +/// Filled in any time before the response ends; the driver writes them when +/// it finishes the body. Which driver is running decides whether they can be +/// sent at all, and §6.6.2 is explicit that "a trailer section is only +/// possible when the message framing allows it": over HTTP/1.1 that means a +/// chunked coding, so a response whose length was declared has nowhere to put +/// them and they are dropped. Over HTTP/2 and HTTP/3 they are a second field +/// section and always possible. +/// +/// Dropping rather than failing is the specified behaviour rather than a +/// shortcut — a trailer field is by construction something the recipient may +/// not receive, which is also why §6.5.1 forbids putting anything the +/// recipient *needs* in one. `isForbiddenTrailer` is that list, and the +/// drivers refuse those names on the way out rather than trusting a handler +/// to have read the section. +trailers: Headers = .empty, /// Scratch for the length of this exchange. The same arena as /// `Request.arena`. arena: Allocator, @@ -215,6 +234,36 @@ pub fn beginBody(res: *Response, length: Length) Error!*Io.Writer { return w; } +/// RFC 9110 §6.5.1: whether a field may not be sent in a trailer section. +/// +/// The list is not arbitrary. A trailer arrives after the recipient has +/// already acted on the head and, for a proxy, after it has already forwarded +/// it — so anything that would change how the message is *framed*, *routed*, +/// *cached* or *authenticated* arrives too late to be obeyed and is a way to +/// say one thing to a cache and another to whatever is behind it. §6.5.1 +/// names the classes; these are the fields in them that this library can +/// meet. +pub fn isForbiddenTrailer(name: []const u8) bool { + const forbidden = [_][]const u8{ + // Framing: the recipient has already decided where the body ends. + "transfer-encoding", "content-length", "host", + // Routing and request modifiers. + "te", "expect", "max-forwards", + "cache-control", "expires", "pragma", + "age", "vary", "warning", + // Authentication, which a recipient acted on before the body. + "authorization", "proxy-authorization", "www-authenticate", + "proxy-authenticate", "set-cookie", "cookie", + // How to interpret the content, which is needed to read it at all. + "content-encoding", "content-type", "content-range", + "trailer", + }; + for (forbidden) |f| { + if (std.ascii.eqlIgnoreCase(name, f)) return true; + } + return false; +} + /// Finishes the response. pub fn end(res: *Response) Error!void { assert(res.state == .body); diff --git a/tests/e2e.zig b/tests/e2e.zig index 19f8879..3b15000 100644 --- a/tests/e2e.zig +++ b/tests/e2e.zig @@ -877,3 +877,59 @@ test "the WebSocket opening handshake" { .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), + ); +} diff --git a/tests/h2.zig b/tests/h2.zig index 7c2b7f0..224c5a6 100644 --- a/tests/h2.zig +++ b/tests/h2.zig @@ -92,12 +92,27 @@ const Conversation = struct { ended: bool = false, reset: ?u32 = null, - /// The last head sent, which is the response proper. Empty when the - /// server never sent one, which is what a stream that was reset - /// before its response looks like. + /// The response proper: the last field section carrying `:status`. + /// + /// Not simply the last section. A stream can carry several, and two + /// of the reasons are different: §15.2 of RFC 9110 lets any number of + /// interim `1xx` responses precede the real one, so the *last* with a + /// status is the one that counts -- and §8.1 of RFC 9113 lets a + /// trailer section follow it, which has no status at all because it + /// is not a message head. Taking the last section outright read the + /// trailer as the response and reported one with no `:status`. + /// + /// Empty when the server never sent one, which is what a stream that + /// was reset before its response looks like. fn head(s: *const Stream) []const Field { - if (s.heads.items.len == 0) return &.{}; - return s.heads.items[s.heads.items.len - 1]; + var i = s.heads.items.len; + while (i > 0) { + i -= 1; + for (s.heads.items[i]) |f| { + if (std.mem.eql(u8, f.name, ":status")) return s.heads.items[i]; + } + } + return &.{}; } fn get(s: *const Stream, name: []const u8) ?[]const u8 { @@ -1223,3 +1238,59 @@ fn silentTunnel(req: *Request, res: *Response) anyerror!void { test { std.testing.refAllDecls(@This()); } + +/// A response whose trailer is only knowable once the body has been produced. +fn trailered(_: *Request, res: *Response) anyerror!void { + const w = try res.beginBody(.unknown); + try w.writeAll("abcde"); + try res.trailers.append(res.arena, "x-length", "5"); + // §6.5.1 of RFC 9110: refused on the way out, wherever a handler puts it. + try res.trailers.append(res.arena, "content-length", "99"); + // §8.1 also forbids a pseudo-header in a trailer section, and that one + // cannot be tested from here: `Headers.append` validates a name with + // `token.isToken`, which excludes `:`, so a handler cannot construct the + // field at all. The guard in the driver is belt and braces over an API + // that already refuses -- which is worth knowing rather than discovering, + // because the attempt fails as a handler error and shows up as an + // RST_STREAM with no hint of why. + return res.end(); +} + +test "RFC 9113 8.1: a trailer section is a second field block with END_STREAM" { + // "An HTTP request or response... can optionally include a trailer + // section... sent as a HEADERS frame with the END_STREAM flag set." So + // the stream carries two field sections rather than one, and what HTTP/1.1 + // needs a special terminator for costs nothing here -- a field section is + // already the shape HTTP/2 sends everything in. + var b: frames.Builder = .init(gpa); + defer b.deinit(); + try b.begin(); + try b.headers(1, Flags.end_stream, &frames.get("/")); + + var c = try converse(b.written(), .initStateless(trailered), .{}); + defer c.deinit(); + + try c.expectWellFormed(); + try c.expectStatus(1, "200"); + try c.expectBody(1, "abcde"); + + const s = try c.on(1); + try testing.expectEqual(@as(usize, 2), s.heads.items.len); + + const trailer = s.heads.items[1]; + var saw_length = false; + for (trailer) |f| { + // The framing field did not travel. + try testing.expect(!std.mem.eql(u8, f.name, "content-length")); + try testing.expect(f.name.len == 0 or f.name[0] != ':'); + if (std.mem.eql(u8, f.name, "x-length")) { + try testing.expectEqualStrings("5", f.value); + saw_length = true; + } + } + try testing.expect(saw_length); + + // And the stream ended on the trailer section rather than on a DATA + // frame, which is what END_STREAM on a HEADERS frame means. + try testing.expect(s.ended); +} diff --git a/tests/h3.zig b/tests/h3.zig index 44ac946..c0f2be4 100644 --- a/tests/h3.zig +++ b/tests/h3.zig @@ -78,17 +78,92 @@ test "RFC 9114: a request over QUIC becomes the same Request a handler has alway try testing.expectEqualStrings("GET /hello HTTP/3", got); } +/// A response whose trailer is only knowable once the body has been produced. +fn trailered(_: ?*anyopaque, _: *http.server.Request, res: *http.server.Response) anyerror!void { + const w = try res.beginBody(.unknown); + try w.writeAll("abcde"); + try res.trailers.append(res.arena, "x-length", "5"); + // §6.5.1 of RFC 9110: refused on the way out, wherever a handler puts it. + try res.trailers.append(res.arena, "content-length", "99"); + return res.end(); +} + +test "RFC 9114 4.1: a trailer section is a second HEADERS frame" { + // The same semantics as HTTP/1.1's chunked trailer section and HTTP/2's + // second field block, in the framing HTTP/3 already has: a HEADERS frame + // after the DATA frames, ending where the stream does. One layer fewer + // than either -- there is no chunked coding to arrange and no END_STREAM + // flag to set, because QUIC says where the stream stops. + const io = testing.io; + const gpa = testing.allocator; + + var rng_impl = std.Random.DefaultPrng.init(0x0401); + const rng = rng_impl.random(); + + const bind: net.IpAddress = try .parse("127.0.0.1", 0); + var socket = try bind.bind(io, .{ .mode = .dgram }); + defer socket.close(io); + const address = socket.address; + + var listener: h3.Listener = undefined; + try listener.init(io, gpa, &socket, .{ + .context = null, + .serveFn = trailered, + }, .{ + .rng = rng, + .reset_key = @splat(0x77), + .token_key = @splat(0x88), + .max_connections = 2, + }); + defer listener.deinit(); + + var group: Io.Group = .init; + defer group.cancel(io); + try group.concurrent(io, run, .{&listener}); + defer listener.stop(); + + var answer: [256]u8 = undefined; + var trailer_value: [64]u8 = undefined; + const trailer = try askForTrailers(io, gpa, address, rng, &answer, &trailer_value); + + try testing.expectEqualStrings("x-length", trailer.name); + try testing.expectEqualStrings("5", trailer.value); + // The forbidden one did not travel. + try testing.expect(!trailer.saw_content_length); +} + +const Trailer = struct { + name: []const u8, + value: []const u8, + saw_content_length: bool, +}; + fn run(listener: *h3.Listener) void { listener.run() catch {}; } /// A hand-written HTTP/3 client: handshake, control stream, one request. +/// +/// Returns the body, which is what most callers want. `askRaw` returns the +/// whole response stream for the one that wants the second field section. fn ask( io: Io, gpa: std.mem.Allocator, to: net.IpAddress, rng: std.Random, answer: []u8, +) ![]const u8 { + var raw: [8192]u8 = undefined; + const stream = try askRaw(io, gpa, to, rng, &raw); + return readResponse(stream, answer); +} + +fn askRaw( + io: Io, + gpa: std.mem.Allocator, + to: net.IpAddress, + rng: std.Random, + answer: []u8, ) ![]const u8 { var local_id: [8]u8 = undefined; rng.bytes(&local_id); @@ -196,7 +271,9 @@ fn ask( if (sent) { const available = connection.readable(request_stream); if (available.len > 0 and connection.streamReceived(request_stream)) { - return readResponse(available, answer); + const n = @min(available.len, answer.len); + @memcpy(answer[0..n], available[0..n]); + return answer[0..n]; } } @@ -217,6 +294,61 @@ fn ask( /// Reads the HEADERS frame and whatever DATA frames follow, and returns the /// body -- which is the part the handler wrote. +/// The same exchange, keeping the *second* field section rather than the +/// body -- which is what a trailer section is. +fn askForTrailers( + io: Io, + gpa: std.mem.Allocator, + to: net.IpAddress, + rng: std.Random, + answer: []u8, + value_out: []u8, +) !Trailer { + const bytes = try askRaw(io, gpa, to, rng, answer); + + var at: usize = 0; + var sections: usize = 0; + var found: ?Trailer = null; + var saw_content_length = false; + var name_out: [64]u8 = undefined; + + while (at < bytes.len) { + const kind = try quic.varint.parse(bytes[at..]); + at += kind.len; + const length = try quic.varint.parse(bytes[at..]); + at += length.len; + const end = at + @as(usize, @intCast(length.value)); + if (end > bytes.len) return error.Truncated; + + if (kind.value == 0x01) { + sections += 1; + // §4.1: the first field section is the response head; a second + // one, after the DATA frames, is the trailer section. + if (sections == 2) { + var fields: [16]h3.qpack.Field = undefined; + var scratch: [1024]u8 = undefined; + const n = try h3.qpack.decode(bytes[at..end], &fields, &scratch); + for (fields[0..n]) |f| { + if (std.mem.eql(u8, f.name, "content-length")) saw_content_length = true; + if (found != null) continue; + @memcpy(name_out[0..f.name.len], f.name); + @memcpy(value_out[0..f.value.len], f.value); + found = .{ + .name = name_out[0..f.name.len], + .value = value_out[0..f.value.len], + .saw_content_length = false, + }; + } + } + } + at = end; + } + + var trailer = found orelse return error.NoTrailerSection; + trailer.saw_content_length = saw_content_length; + return trailer; +} + fn readResponse(bytes: []const u8, answer: []u8) ![]const u8 { var at: usize = 0; var used: usize = 0;