// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! RFC 9114: HTTP/3, which is the same semantics again over a transport that //! finally matches them. //! //! HTTP/2 multiplexed requests onto one TCP connection, and paid for it: a //! lost segment stalls every stream, because TCP will not deliver what comes //! after a hole. HTTP/3 puts each request on a QUIC stream, where a loss //! stalls only the stream it happened to, and hands back most of the framing //! layer while it is there -- flow control, stream creation, resets and the //! connection preface are all QUIC's now. //! //! What is left is smaller than HTTP/2's driver rather than larger: frames //! with a varint type and a varint length (`frame`), a field section //! compressed with QPACK, and three unidirectional streams that carry the //! connection's own business. //! //! ## What it needs that the other two did not //! //! A listener of its own. `transport.Connection` is a reader and a writer, //! which is exactly a TCP connection and exactly not a QUIC one, so there is //! nothing for `server.Server` to hand an HTTP/3 driver -- which is why //! `server.Protocol.h3` has always been in that enumeration with a comment //! saying so rather than a driver behind it. //! //! Nothing in `protocol` changes, which is the third time that claim has been //! made and the first time it has been made against a transport that is not a //! byte stream at all. const std = @import("std"); pub const frame = @import("http3/frame.zig"); /// The client side: RFC 9114 from the end that asks. pub const client = @import("http3/client.zig"); pub const qpack = @import("http3/qpack.zig"); pub const Connection = @import("http3/Connection.zig"); test { std.testing.refAllDecls(@This()); } const Io = std.Io; const Allocator = std.mem.Allocator; const quic = @import("quic"); const Handler = @import("server/Handler.zig"); /// What a listener does, beyond what `Connection.Config` decides. pub const Config = struct { connection: Connection.Config = .{}, /// The certificate and key this server authenticates itself with. Null /// completes a handshake that authenticates nobody, which is no use on a /// network and is what a test wants. auth: ?*quic.tls_handshake.CertKeyPair = null, /// Randomness for connection IDs, reset tokens and the handshake. rng: std.Random, /// §10.3.2 of RFC 9000: the static key stateless reset tokens come from. reset_key: quic.stateless_reset.Key, /// §8.1.4: the key Retry tokens are sealed with. token_key: quic.retry.Token.Key, /// §4.6.1 of RFC 8446: the key session tickets are sealed with, or null /// to issue none. ticket_key: ?quic.tls_handshake.TicketKey = null, /// §4.6 of RFC 9001: whether to accept 0-RTT. Off by default, because /// §9.2 makes replay the application's problem to reason about and a /// server library cannot reason about it for somebody else's handler. early_data: bool = false, /// §8.1: whether to make every client prove its address with a Retry. require_retry: bool = false, /// How many connections to hold at once. max_connections: usize = 64, /// What this endpoint advertises in its transport parameters. /// /// The unidirectional limit is the one HTTP/3 forces: §6.2 has each end /// open a control stream and two QPACK streams before anything else, so /// an endpoint that granted fewer than three would deadlock a conforming /// peer at the start of every connection. Three is the minimum and the /// default is more, because a peer that opens an extension stream is /// entitled to. /// The four flow control limits are **not** taken from here. They are a /// promise about memory, `sizes` is where that memory is chosen, and /// setting them in two places is a way of disagreeing with yourself -- /// which is exactly what went wrong when they were separate: this /// advertised sixty-four times what the buffers held, and any request /// body or field section larger than one buffer left the connection with /// nowhere to put what it had already said it would accept. It closed /// with INTERNAL_ERROR, which is the honest answer to a promise this end /// could not keep and a mystery to whoever was on the other end. /// /// So `init` fills them in from `sizes` and whatever is set for them here /// is replaced. transport: quic.parameters.Parameters = .{ // The stream table holds sixteen, shared by both ends, and every // stream promised to the client here is a slot this server keeps // free for it. What is left over has to fit the server's own three // unidirectional streams (§6.2), so the two together leave it three: // the client's own three plus one spare, and nine requests at once. .initial_max_streams_bidi = 9, .initial_max_streams_uni = 4, .max_idle_timeout = 30_000, .active_connection_id_limit = 4, }, /// How much memory each connection starts with, and therefore how much /// this server can promise. /// /// The defaults are modest on purpose, and what they cost is the /// per-stream sizes times sixteen streams times the connections *alive /// at once* rather than the connections permitted -- a slot is furnished /// when a connection claims it, so raising these costs nothing until /// somebody connects. sizes: quic.Connection.Sizes = .{}, /// The largest send window a connection may be grown to. /// /// What a send window buys is `window / round-trip`, so no single number /// is right for every peer: four kilobytes is already past the /// bandwidth-delay product of a path across a building and a small /// fraction of one across an ocean. Rather than make a server choose, /// every connection starts at `sizes.send_window` and one that fills its /// buffer while the path and the peer would both have taken more has it /// doubled, up to this. A connection that never does never costs more /// than the default. /// /// Sixty-four kilobytes by default, which is sixteen times the starting /// window and a megabyte per connection if every stream reaches it at /// once. `tests/nixos/window.nix` measures what that is worth over a ten /// millisecond round trip: 307 kB/s at four kilobytes against 4816 at /// sixty-four, which is the arithmetic above rather than a surprise. /// Null leaves every connection at `sizes.send_window`. max_send_window: ?usize = 64 << 10, };