Add an HTTP/2 server engine on nghttp2

CHANGELOG.md

@@ -4,8 +4,33 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+- An HTTP/2 server engine on nghttp2, with the `use_http2` build option. A TLS
+  listener serves HTTP/2 when `tls.alpn_protocols` offers "h2" and the client
+  picks it; a cleartext listener with `http2_prior_knowledge` serves HTTP/2 to
+  a client that opens with the connection preface, and HTTP/1.x to the rest.
+  Streams reach the same router, middleware and handlers as HTTP/1.x, through
+  `Server.dispatch` and a sink-backed `Response`. Request and response bodies
+  stream with flow control in both directions, responses can carry trailers,
+  and a request body the handler leaves unread ends the stream with
+  RST_STREAM(NO_ERROR) after the response. Limits are in
+  `ServerConfig.http2`. A draining server refuses new streams and sends
+  GOAWAY.
+- An HTTP/1.0 request that asks to keep the connection now gets
+  `Connection: keep-alive` on its response when the server keeps it. Without
+  it an HTTP/1.0 client (ApacheBench with `-k`, for one) waits for the server
+  to close, while the server waits for the next request.
+- Added a protocol-neutral seam for engines other than the HTTP/1.x loop
+  (HTTP/2 first): `Response.initSink` writes the head, body and end of a
+  response to a `Sink` instead of formatting HTTP/1.x; `Response.trailer`
+  adds trailer fields, which a sink carries; `Request.body_source` delivers a
+  body that arrives unframed, decoded as usual; `Request.applyEntityHeaders`
+  fills the entity fields from the headers; and `Server.dispatch` routes a
+  request through the middleware to its handler. HTTP/1.x is unchanged.
 - Added the `use_bundled_tls` build option. Applications can keep TLS enabled
   while replacing Dusty's pinned tls.zig dependency with a compatible module.
+- Added `ServerConfig.Tls.alpn_protocols`, the protocols a TLS listener
+  offers through ALPN in preference order, and the server
+  `Connection.negotiatedProtocol()` that reports the agreed one.
 - `Listener.kernel_backlog` now defaults to the system's limit, `net.core.somaxconn`
   on Linux, instead of 1024. A full accept queue makes Linux drop new connections,
   which then wait a second or more to retry.

README.md

@@ -63,6 +63,44 @@ The application declares `custom_tls` in its own `build.zig.zon`, so it can
 point to another commit, fork, or local path. Omitting the injected module is a
 compile error. Use `.use_tls = false` instead when TLS should be compiled out.
 
+### HTTP/2
+
+Built with `.use_http2 = true`, a server speaks HTTP/2 (through nghttp2) to
+clients that ask for it, on the same router and handlers:
+
+```zig
+.listeners = &.{
+    // TLS: negotiated through ALPN.
+    .{ .address = addr443, .tls = .{ .cert_path = "server.pem", .key_path = "server.key", .alpn_protocols = &.{ "h2", "http/1.1" } } },
+    // Cleartext: HTTP/2 for a client that starts with the preface, HTTP/1.x otherwise.
+    .{ .address = addr80, .http2_prior_knowledge = true },
+},
+.http2 = .{ .max_concurrent_streams = 250 },
+```
+
+A handler can add trailer fields with `res.trailer(name, value)`; they are
+sent over HTTP/2 and dropped over HTTP/1.x.
+
+### Using your own nghttp2
+
+With `.use_http2 = true` Dusty compiles its vendored nghttp2. An application
+that already builds nghttp2 (a newer release, or one shared with other code)
+can inject its own bindings instead, so only one copy is linked:
+
+```zig
+const dusty_dep = b.dependency("dusty", .{
+    .target = target,
+    .optimize = optimize,
+    .use_http2 = true,
+    .use_bundled_nghttp2 = false,
+});
+const dusty_mod = dusty_dep.module("dusty");
+// A translate-c module of nghttp2.h that also links the nghttp2 library.
+dusty_mod.addImport("nghttp2", my_nghttp2_mod);
+```
+
+Omitting the injected module is a compile error.
+
 ## Usage
 
 ### Server Example
@@ -100,6 +138,9 @@ can serve HTTPS on 443 and plain HTTP on 80 with the same router:
 },
 ```
 
+A TLS listener offers protocols through ALPN when given a list in preference
+order, for example `.tls = .{ ..., .alpn_protocols = &.{"http/1.1"} }`.
+
 When `listeners` is omitted or empty, the server listens on `127.0.0.1:8080`.
 
 A handler can tell them apart through `req.listener` and `req.secure`, and

src/client_test.zig

@@ -716,6 +716,57 @@ test "Client: HTTPS with a custom CA file" {
     try client_future.await(io);
 }
 
+test "Server: tls.alpn_protocols is offered to the client through ALPN" {
+    if (!build_options.use_tls) return error.SkipZigTest;
+    const tls = @import("tls");
+    const io = std.testing.io;
+
+    var server = dusty.Server(void).init(std.testing.allocator, io, .{
+        .listeners = &.{.{ .address = loopback_addr, .tls = .{
+            .cert_path = test_cert_path,
+            .key_path = test_key_path,
+            .alpn_protocols = &.{"http/1.1"},
+        } }},
+    }, {});
+    defer server.deinit();
+
+    var server_future = try io.concurrent(struct {
+        fn run(s: *dusty.Server(void)) !void {
+            try s.run();
+        }
+    }.run, .{&server});
+    defer server_future.cancel(io) catch {};
+
+    var client_future = try io.concurrent(struct {
+        fn run(s: *dusty.Server(void), _io: std.Io) !void {
+            try s.ready.wait(_io);
+            const ca: dusty.TlsCa = .{ .file = .{ .path = test_cert_path } };
+            var bundle = try ca.load(std.testing.allocator, _io);
+            defer bundle.deinit(std.testing.allocator);
+
+            const stream = try s.address.ip.connect(_io, .{ .mode = .stream });
+            defer stream.close(_io);
+            var read_buf: [tls.input_buffer_len]u8 = undefined;
+            var write_buf: [tls.output_buffer_len]u8 = undefined;
+            var tcp_reader = stream.reader(_io, &read_buf);
+            var tcp_writer = stream.writer(_io, &write_buf);
+            var rng: std.Random.IoSource = .{ .io = _io };
+
+            // The client prefers h2; the server only lists http/1.1.
+            const conn = try tls.client(&tcp_reader.interface, &tcp_writer.interface, .{
+                .host = "localhost",
+                .root_ca = bundle,
+                .now = std.Io.Clock.real.now(_io),
+                .rng = rng.interface(),
+                .alpn_protocols = &.{ "h2", "http/1.1" },
+            });
+            try std.testing.expectEqualStrings("http/1.1", conn.alpn_protocol orelse return error.NoAlpn);
+        }
+    }.run, .{ &server, io });
+
+    try client_future.await(io);
+}
+
 test "Client: presents a client certificate for mutual TLS" {
     if (!build_options.use_tls) return error.SkipZigTest;
     const io = std.testing.io;

src/config.zig

@@ -87,6 +87,13 @@ pub const Listener = struct {
     kernel_backlog: ?u31 = null,
     /// Sets SO_REUSEADDR (and SO_REUSEPORT on POSIX) on an IP listener.
     reuse_address: bool = true,
+    /// Serve cleartext HTTP/2 to a client that opens with the HTTP/2
+    /// connection preface ("prior knowledge", RFC 9113 §3.3), alongside
+    /// HTTP/1.x on the same port. Needs the `use_http2` build option, and
+    /// is ignored on a TLS listener, which negotiates "h2" through
+    /// `Tls.alpn_protocols` instead. The deprecated `Upgrade: h2c` is not
+    /// supported.
+    http2_prior_knowledge: bool = false,
     /// How many accept loops share the socket. With io_uring, an accept
     /// completes at most once per trip through the event loop, so a single
     /// loop takes one connection per trip however many are queued, which
@@ -132,6 +139,9 @@ pub const ServerConfig = struct {
     timeout: Timeout = .{},
     request: Request = .{},
     response: Response = .{},
+    /// HTTP/2 connections (with the `use_http2` build option): reached
+    /// through ALPN "h2" on a TLS listener or `Listener.http2_prior_knowledge`.
+    http2: Http2 = .{},
     /// Where the server accepts connections. `Server.run` serves all of
     /// them. An empty list uses the default, 127.0.0.1:8080. Borrowed for
     /// the server's life, and requests point back into it through
@@ -170,6 +180,11 @@ pub const ServerConfig = struct {
         /// Ask connecting clients to authenticate with a certificate (mutual
         /// TLS). Null means client certificates are never requested.
         client_auth: ?ClientAuth = null,
+        /// Protocols offered through ALPN, in server preference order, for
+        /// example `&.{ "h2", "http/1.1" }`. Empty means no ALPN; a client
+        /// whose offer shares nothing with a non-empty list is handled by the
+        /// TLS module (tls.zig refuses it).
+        alpn_protocols: []const []const u8 = &.{},
 
         pub const ClientAuth = struct {
             /// Certificate authorities used to verify client certificates.
@@ -183,6 +198,29 @@ pub const ServerConfig = struct {
         };
     };
 
+    pub const Http2 = struct {
+        /// SETTINGS_MAX_CONCURRENT_STREAMS: streams a client may have open
+        /// at once. Each costs a task and, once it sends a body, a buffer
+        /// of `stream_window` bytes.
+        max_concurrent_streams: u32 = 100,
+        /// SETTINGS_INITIAL_WINDOW_SIZE: request body bytes a client may
+        /// send on a stream before the handler reads them, which is also
+        /// the stream's body buffer.
+        stream_window: u31 = 64 * 1024,
+        /// Request body bytes in flight across all streams of a connection.
+        connection_window: u31 = 1024 * 1024,
+        /// SETTINGS_MAX_HEADER_LIST_SIZE: the decoded size of a request's
+        /// header block (names, values and 32 bytes each, RFC 9113 §6.5.2).
+        max_header_list_size: u32 = 64 * 1024,
+        /// RST_STREAM a client may send in a burst, refilled at
+        /// `stream_reset_rate` per second, before the connection is closed
+        /// (CVE-2023-44487, "rapid reset").
+        stream_reset_burst: u64 = 1000,
+        stream_reset_rate: u64 = 33,
+        /// CONTINUATION frames allowed after one HEADERS (CVE-2024-28182).
+        max_continuations: usize = 8,
+    };
+
     pub const Timeout = struct {
         /// Maximum time to complete a request, including handler work and the
         /// response. TLS handshakes use the same timeout as a separate phase.

src/middleware.zig

@@ -89,7 +89,7 @@ pub fn Executor(comptime Ctx: type) type {
                     // fault, so it is neither a 500 nor worth an error log.
                     // The connection is asked, not the error: a handler
                     // can return an `EndOfStream` of its own.
-                    if (self.res.conn.peerGone()) return err;
+                    if (self.res.peerGone()) return err;
                     if (self.res.headers_written) {
                         // The response already started (e.g. streaming/chunked
                         // body or a WebSocket upgrade), so headers were sent

src/parser.zig

@@ -246,17 +246,7 @@ pub const RequestParser = struct {
     fn onHeadersComplete(parser: ?*c.llhttp_t) callconv(.c) c_int {
         const self: *RequestParser = @fieldParentPtr("parser", parser.?);
 
-        if (self.request.headers.get("Content-Type")) |content_type| {
-            self.request.content_type = ContentType.fromContentType(content_type);
-        }
-
-        if (self.request.headers.get("Content-Encoding")) |content_encoding| {
-            self.request.content_encoding = ContentEncoding.fromString(content_encoding);
-        }
-
-        if (self.request.headers.get("Content-Length")) |content_length| {
-            self.request.content_length = std.fmt.parseInt(usize, content_length, 10) catch null;
-        }
+        self.request.applyEntityHeaders();
 
         self.state.headers_complete = true;
         return c.HPE_PAUSED; // Always pause so we can track consumed bytes
@@ -565,11 +555,25 @@ pub const ResponseParser = struct {
 /// `std.Io.Reader` and so needs one underneath it handing over raw framed
 /// bytes. That one is another `BodyReader` -- same type, lower role -- and
 /// `startDecoding` puts it and the decoder in one allocation.
+/// A request body that arrives already unframed, from a protocol engine
+/// rather than through the HTTP/1.x parser: an HTTP/2 stream's DATA frames.
+pub const BodySource = struct {
+    reader: *std.Io.Reader,
+    /// What an `error.ReadFailed` from `reader` actually was; null when
+    /// nothing was recorded. A peer that reset the stream is
+    /// `ConnectionResetByPeer`.
+    err: *const fn (reader: *std.Io.Reader) ?Transport.ReadError,
+};
+
 pub fn BodyReader(comptime Parser: type) type {
     return struct {
         parser: *Parser,
         transport: Transport,
         request: ?*Request = null,
+        /// The body as a plain reader, already unframed, in place of the
+        /// parser and transport: an HTTP/2 stream's DATA. See
+        /// `Request.body_source`.
+        raw: ?BodySource = null,
         /// Set when the headers called for a content coding. Null both when
         /// nothing is coded and on the lower reader that feeds the decoder.
         decode: ?*Decode = null,
@@ -726,9 +730,6 @@ pub fn BodyReader(comptime Parser: type) type {
         }
 
         fn streamFramed(self: *Self, w: *std.Io.Writer, limit: std.Io.Limit) std.Io.Reader.StreamError!usize {
-            const parser = self.parser;
-            const conn = self.transport.reader;
-
             // Send 100 Continue on first body read if client expects it
             if (self.request) |req| {
                 if (req.expects_continue) {
@@ -740,13 +741,28 @@ pub fn BodyReader(comptime Parser: type) type {
                             req.expects_continue = false;
                             // A write, on a read: the caller asked for the body
                             // and this is what unblocks the peer from sending it.
-                            sendContinue(res.conn.writer) catch
-                                return self.fail(self.transport.getWriteError() orelse error.Unexpected);
+                            if (res.sink) |sink| {
+                                sink.interim(.@"continue") catch
+                                    return self.fail(sink.writeError() orelse error.Unexpected);
+                            } else {
+                                sendContinue(res.conn.writer) catch
+                                    return self.fail(self.transport.getWriteError() orelse error.Unexpected);
+                            }
                         }
                     }
                 }
             }
 
+            if (self.raw) |src| {
+                return src.reader.stream(w, limit) catch |err| switch (err) {
+                    error.ReadFailed => return self.fail(src.err(src.reader) orelse error.Unexpected),
+                    else => |e| return e,
+                };
+            }
+
+            const parser = self.parser;
+            const conn = self.transport.reader;
+
             const dest = limit.slice(try w.writableSliceGreedy(1));
             if (dest.len == 0) return 0;