# zig-http as a server What serving HTTP with zig-http involves beyond the smallest server in the [README](../README.md#a-server): what each version of HTTP asks of a handler, what the drivers refuse and why, switching protocols, and TLS. The API documentation at is generated from the doc comments, which argue the framing rules out where they are implemented; this is the account of how the pieces behave together. The client side is [client.md](client.md). ## HTTP/2 On by default. `server.Server` picks it per connection: by ALPN where the transport negotiated one, and otherwise by the first four octets, which is enough to recognise a client using prior knowledge — RFC 9113 §3.4 chose the `PRI` method for its connection preface precisely so that test would work. So HTTP/2 arrives one of three ways: over TLS terminated by `http_io.tls`, which offers `h2` in its ALPN list and fills in `transport.Connection.Info.alpn`; from a cleartext prior-knowledge client (`curl --http2-prior-knowledge`, `h2load`, `nghttp`); or from a TLS terminator in front that sets the same field. **h2c `Upgrade` is deliberately not implemented**, because RFC 9113 removed it. A client that asks gets an ordinary HTTP/1.1 response rather than a `101`; answering would mean speaking a mechanism no current standard defines, and there is a test in `tests/nixos/curl.nix` that pins the behaviour. **RFC 8441 extended CONNECT is implemented**, which is what makes `Response.upgrade` work over HTTP/2 — see [Switching 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) 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. `/trailers` on the demonstration server is the shape of a handler that wants one: five lines of a body nobody declared the length of, then two fields saying how many octets went out and what their checksum was. Neither value exists before the last octet is written, which is the whole reason a trailer section exists, and it is what makes the route worth having in the virtual machine tests — curl reads the same two fields over all three framings and gets the same checksum each time, so the claim that one handler serves three protocols is checked by something that shares no code with this. 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 This is the one thing HTTP/2 asks of a handler that HTTP/1.1 did not, and it is easy to miss because the types did not change. HTTP/2 multiplexes, so up to `max_concurrent_streams` requests can be inside the same handler, on the same connection, at the same moment. Any state reached through a handler's context is shared across tasks. `src/main.zig` uses `std.atomic.Value` for its request counter for exactly this reason, and the load test asserts the count comes out *exactly* right — which a lost increment would break. ### A client that stops talking still gets its answers When the peer's sending half ends, the connection stops being read — but the requests already in flight arrived whole and their responses still have somewhere to go, so the reader waits for those stream tasks before the GOAWAY goes out. What it does not wait for is waiting itself: a handler blocked on a request body that will never arrive sees the end of that body, and one blocked on a send window that will never open is told the connection is gone, since a WINDOW_UPDATE can only arrive on a connection still being read. Credit already granted is still spendable. A connection *error* is the other case, and it is not graceful. Nothing further can be understood, so a handler still running is producing octets nobody will ever read, and the streams are stopped rather than waited for. ### What a task costs is the caller's choice Each stream gets a task. Under `std.Io.Threaded` that is an operating system thread, so `max_concurrent_streams` is a per-connection thread bound; under a fibre-based `Io` it is nearly free. The default is the conventional 100 and the right number depends on which `Io` you supply. ### The one thing that is wire-visible `/stream` in the demonstration server is a handler that does not know how long its body will be. Over HTTP/1.1 that costs a chunked transfer coding, over HTTP/1.0 a closed connection, and over HTTP/2 an ordinary run of DATA frames with no `transfer-encoding` at all — which HTTP/2 makes a malformed message. One handler, three framings, and it never finds out which. ## HTTP/3 Implemented, and it needed more than a driver: a QUIC connection is many independent streams where a `transport.Connection` is one, so HTTP/3 arrives with a listener of its own rather than being handed a connection by `server.Server`. `protocol` did not change, which is the whole reason `protocol` is where it is — and this is the first time that claim has been tested against a transport that is not a byte stream at all. ```console $ zig-http --port 8080 --h3-port 8443 --cert cert.pem --key key.pem $ curl --http3-only --cacert cert.pem https://localhost:8443/ $ nix build .#checks.x86_64-linux.h3 # the same, in a virtual machine $ nix build .#checks.x86_64-linux.aioquic # and again, from a second stack ``` The last of those is where the claim is actually tested. `tests/h3.zig` drives a request through the driver over a loopback socket, and every assertion in it is this library reading what this library wrote — a QUIC handshake, a QPACK field section and HTTP/3 framing all written against the same understanding as the code they check, so a disagreement that is self-consistent passes. The virtual machine test points a curl built with ngtcp2, nghttp3 and OpenSSL at it instead, over a real network, with a certificate it verifies properly. That found four things the in-process test could not, one of which — a ClientHello too large for one packet — aioquic's QUIC suite could not have found either, because aioquic's fits. A second one points aioquic at it, which is a different reading of the same RFCs in a different language with a different QPACK, and which can be told to send what curl will not. It found that a malformed field section was being answered with a status code where §4.1.2 requires the stream to be reset, and then something worse: this server advertised a per-stream flow control window sixty-four times the one its transport can hold. `quic.Connection` keeps one fixed buffer per stream per direction and says in as many words that "a caller advertising more than this in its transport parameters is promising room it does not have" — and this was that caller. A peer taking the advertisement at its word filled the buffer, the connection had nowhere to put the rest, and it closed with INTERNAL_ERROR. Every HTTP/3 test in the repository passed throughout, because every body any of them sent fit in one window. QUIC itself is [zig-quic](https://git.jcollie.dev/jeff/zig-quic), which is a dependency rather than part of this: two modules of it, `quic` for the protocol and `quic_io` for the loop that owns a UDP socket and routes datagrams to connections. **What it costs, and how to measure it.** Every figure here is from a `--release=safe` build, which is what `nix build` produces and what the virtual machine tests run. It is worth saying because a plain `zig build` produces a Debug binary and the first round of these numbers was measured on one: the handshake came out ten times slower and the transfer three, which was enough to point at entirely the wrong thing. Against a `curl` on the same machine, a megabyte from `/bulk` moves at about 40 MB/s and is steady within a few percent; the same handler over HTTP/1.1 moves at about 1.2 GB/s. An upload to `/echo` runs at about 20 MB/s, which is two megabytes crossing the connection for every one uploaded. A full handshake costs about 2 ms with a P-256 certificate, 6 ms with RSA-2048 and 15 ms with RSA-3072 — so on a short connection the certificate is still most of the cost, and choosing an elliptic curve key is still worth more than anything else on this page. Those RSA figures were 31 ms and 59 ms two days ago, and the five-fold difference is two bugs and an omission, none of them here: * Every private-key operation went through `std.crypto.ff`'s `Modulus.pow`, which sizes the exponent buffer by the *type's* maximum width rather than the modulus's. Supporting 4096-bit keys means instantiating `Modulus(4096)` for all of them, so a 2048-bit key had a 256-byte exponent written into a 512-byte buffer and the ladder walked all 512, spending four squarings on every nibble whether it was significant or not. Half of every signature. * The Chinese remainder theorem was not used, though every PKCS#1 and PKCS#8 key carries what it needs. Two exponentiations modulo numbers half the width of `n` are a quarter of the work of one modulo `n`. * And when that was fixed, nothing changed — because `PrivateKey.parseDer` walks PKCS#8 by hand and had never read the five integers it needed. All three are fixed in `tls.zig`. The first is also fixed in `std.crypto.ff` itself, carried as a patch in [zig-std-crypto-ext](https://git.jcollie.dev/jeff/zig-std-crypto-ext) along with a second one — a precedence slip that sends a *secret* three-byte exponent down a path that branches on its bits — and meant for upstream. Signing with the CRT is only safe with the check that comes with it, and `tls.zig` now makes it: every private operation recomputes `out^e mod n` and compares it against its own input before returning. A signer that gets one of its two halves wrong emits a result from which `gcd(out^e - m, n)` is one of the primes, which is the whole private key from a single bad signature. That 35 MB/s was six times worse until the body writer stopped sending each write as its own datagram — the story is in the doc comment on `BodyWriter` in `src/http3/Connection.zig`, and the short version is that a handler writing sixty-six octet lines was spending a whole packet on each one. **What makes it faster, and what that costs.** The per-stream buffers, and the *sending* one of the two. A download is this server *sending*, so what bounds it is how much unacknowledged data one stream may hold — §13.3 has a retransmission carry the contents of a lost frame, so an octet stays held until the peer says it arrived. Enlarging the receive buffer alone changes it by nothing measurable. `http3.Config.sizes` is where that is chosen, and `--h3-window` on the demonstration server turns it. Five runs a setting, a megabyte from `/bulk` against curl on the loopback interface: ```console $ zig-http --h3-port 8443 --h3-window 4 # 41 MB/s (the default) $ zig-http --h3-port 8443 --h3-window 64 # 54 MB/s $ zig-http --h3-port 8443 --h3-window 256 # 65 MB/s ``` **Those numbers understate it by an order of magnitude, because the loopback interface cannot ask the question.** What a send window buys is `window / round-trip`: it bounds what one stream may have unacknowledged, so the rate at which that bound is lifted is the rate acknowledgements come back. Loopback's round trip is a few hundred microseconds, which puts the bandwidth-delay product at a couple of kilobytes — below the *default* window, so every setting above it is already past the point of mattering and the whole spread above is the little that is left. `tests/nixos/window.nix` asks it properly, over a path given ten milliseconds of delay with `netem`, which is an ordinary round trip and the regime every deployment is actually in: | `--h3-window` | 4 (the default) | 64 | 256 | 4, growing to 64 | | --- | --- | --- | --- | --- | | 10 ms round trip | 304 kB/s | 4747 kB/s | 6784 kB/s | **4473 kB/s** | Four kilobytes over a ten millisecond round trip is 400 kB/s and no faster, whatever the path underneath can do, and 307 kB/s is that arithmetic. Sixteen times the window is **fifteen point seven times** the throughput, against a predicted sixteen. The same 4 KB window with the delay taken away does 6874 kB/s — twenty-two times better with no change to the setting — which is the clearest statement of why nothing measured on loopback should be used to choose this number. **The last column is the one that matters, and it is the default.** No single window is right for every peer, so the server does not choose one: every connection starts at `--h3-window` and one that fills its buffer *while the path and the peer would both have taken more* has it doubled, up to `--h3-max-window`. That last condition is the whole of it — a stream held back by the path, or by what its peer has granted, is not one a larger buffer would help, and growing for it would spend memory on a connection that is waiting for somebody else. Told nothing about the path, starting from the window that manages 304 kB/s, it arrives within six percent of the number an operator would have had to know the round trip to pick. What it costs is nothing until it is wanted. Buffers are furnished per connection alive rather than per connection permitted, and a connection that never shows the signal never grows, so a server answering short requests across a datacentre pays the default and one answering a long download across an ocean pays for what it used. Set `--h3-max-window` equal to `--h3-window` to pin it. Only the sending half is tuned. §4.1 makes an advertised receive window a promise that may grow but never shrink, so raising that means telling the peer; the sending window is local and may be chosen again at any time, and it is the half a server mostly uses. It is a check rather than a report because the ordering is a claim worth defending, and because the measurement is easy to take wrongly. Two earlier versions of that file put the `netem` qdisc on an interface the traffic never crossed, reported it configured, and measured an undelayed path; it now confirms the round trip with `ping` before measuring anything with it. A third compared four servers that had quietly all become the same one, because they were pinned by nothing and the tuner grew them all — which the numbers said plainly, all four being equally fast. Two things are worth knowing before turning it up. The first is that the window and the loss-tracking table are one decision, not two: the table has to hold the packets the window puts in the air, and a table that cannot is not a connection that slows down but one that stops. `quic.Connection.init` asserts the floor, `Config.sizes` derives the table from the window, and neither can be got wrong quietly any more. The second is memory, which is charged per connection *alive at once* rather than per connection permitted: `quic_io.Endpoint` furnishes a slot when a connection claims it, so raising the window costs nothing until somebody connects. Resident memory for this server, measured with nothing connected and then with one transfer in flight: | `--h3-window` | idle | one connection | | --- | --- | --- | | 4 | 10 MB | 12 MB | | 256 | 10 MB | 21 MB | | 1024 | 10 MB | 47 MB | So the number to reason about is the peak concurrency rather than `max_connections`: sixteen streams' worth of buffer per connection, times how many are actually being served. A megabyte-per-stream window costs 37 MB a connection, which is affordable for a handful and not for a thousand. Chasing it turned up four faults in zig-quic, all fixed there, and all reached by going *faster* rather than by anything going wrong. `recovery.Space` remembers a bounded number of unacknowledged packets and drops the oldest to make room; a dropped packet used to take its bytes out of the table and leave them counted in flight for ever, so the congestion window closed and never reopened. And its *data* was never marked to be sent again, so the octets stayed held in the stream's send buffer, where `compact` frees only the acknowledged prefix — one such hole near the front pins the whole buffer, the stream fills, and the writer waits for room that cannot come. A third did the same thing by a different route: an acknowledgement arriving above the contiguous prefix was discarded, on the argument that the range would be declared lost and sent again, which is false precisely because the peer acknowledged it. The fourth is the one that was actually holding concurrent downloads, and it is a livelock rather than a deadlock — which is why it survived three fixes aimed at sleeping threads. Once the table was full, every packet sent forgot the oldest one, whose data was re-queued as lost, which gave the sender something to send, which forgot another. Nothing in that cycle waits: the server sat at a full core emitting hundreds of thousands of retransmissions of data that was still in flight, holding the session mutex throughout, so its own pump managed one loop iteration in eighteen seconds. The table is a send window in its own right now, and a full one blocks the sender exactly as a closed congestion window does. Two concurrent megabytes, five runs a setting, before and after that last fix: | `--h3-window` | 8 | 16 | 32 | 48 | 64 | 80 | 96 | 128 | 192 | 256 | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | before | 5/5 | 5/5 | 1/5 | 0/5 | 0/5 | 0/5 | 2/5 | 3/5 | 4/5 | 5/5 | | after | 5/5 | 5/5 | 5/5 | 5/5 | 5/5 | 5/5 | 5/5 | 5/5 | 5/5 | 5/5 | The dip is the shape a size threshold cannot make, and it is what identified the fault: the band is where the derived table is about what two streams put in the air, and it recovers above the band because the table outgrows what the congestion window ever lets accumulate. Throughput is unchanged — the same figures either side of the fix — because blocking a sender that was spinning costs nothing that was being accomplished. None of this is reachable with `curl`, which reuses a connection but waits for each answer before asking again. It takes a client that asks for two things before reading either, which is what a browser does. **The driver is smaller than the HTTP/2 one, and what is absent is the point.** No connection preface, because QUIC's handshake is one. No flow control, no WINDOW_UPDATE, no stream table, no `MAX_CONCURRENT_STREAMS` — §4.6 of RFC 9114 hands all of it to QUIC. No RST_STREAM, because QUIC has one. And no writer lock, which was the largest single piece of the HTTP/2 driver: there is no shared byte stream to serialise onto, so the `Serializer` with its mutex, its control outbox and the deadlock that outbox exists to prevent has no counterpart here. What is left is three unidirectional streams carrying the connection's own business — §6.2's control stream and the two QPACK streams, in each direction — and a task per request. **QPACK is the static table and the literal representations, with a dynamic table capacity of zero.** §3.2.2 of RFC 9204 forbids a peer inserting when the advertised capacity is zero, so no field section can ever depend on an insertion, and the Required Insert Count arithmetic, the eviction, the Known Received Count and the blocked streams are absent rather than approximate. It costs compression and not correctness, which is the same trade the HPACK encoder here already makes. The Huffman code is shared with HPACK rather than transcribed twice, because §5 of RFC 9204 defines none — it points at RFC 7541 Appendix B and stops. So it lives in `field`, along with the rules for turning a field section into a `Request`: RFC 9114 §4.3 restates RFC 9113 §8.3 almost word for word, and the version is the only parameter that differs between the two callers. **A graceful shutdown is §5.2's GOAWAY**, and it is the frame that makes restarting a server safe. The identifier it names is the request this endpoint has not started, so everything already in flight is answered and everything after it is refused with `H3_REQUEST_REJECTED` — a code the client can act on, because it means the request did not happen. A server that simply closed its socket would leave every client with a request outstanding unable to tell whether it took effect, and guessing wrong means either losing a request or making it twice. 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. **Extended CONNECT is RFC 9220**, which is three pages and most of them are about what it does not change from RFC 8441: the same setting identifier, the same `:protocol` in the request, the same `2xx` rather than a `101`. So `res.upgrade` works here as it does over HTTP/2, and a WebSocket can be bootstrapped over HTTP/3. What differs is what a tunnel is made of, and it is simpler each time. Over HTTP/1.1 an upgrade must refuse when the request body has not been read, because those octets sit in the byte stream in front of the new protocol's first one. Over HTTP/2 that check is unnecessary because DATA frames are framed separately. Here it is unnecessary for a stronger reason: the request body and the tunnel are the same QUIC stream, delivered in order by the transport, so there is nothing to be in front of anything. **One trap, which cost an afternoon and is not in the library.** A tunnel is read with one `stream` call and not with `readSliceShort`. The latter keeps asking until the destination is full or the stream ends, which is right for a message of known length and wrong here: the first ask returns everything that has arrived, the second blocks on a peer that has not ended its half and is not going to, and the connection dies of its idle timeout with the data long since delivered. It looks exactly like a transport that will not carry a tunnel, and it is a reader asking for more than a tunnel promises. Not implemented: a dynamic QPACK table, server push, and plain `CONNECT`, which answers `501`. ## HTTP/1.1 framing, and what is refused Almost everything in the HTTP/1.1 driver is about where a message ends, because that is where HTTP/1.1 is dangerous. Two participants that disagree about it see two different sequences of requests in the same bytes, and the one in front — a cache, a load balancer — can be made to hand the one behind a request the client never sent. RFC 9112 §11.2 calls it request smuggling. Where the standard offers a choice between rejecting a message and guessing at it, this rejects it: | Input | Answer | | --- | --- | | `Content-Length` and `Transfer-Encoding` together | `400`, connection closed | | Two `Content-Length` lines that disagree | `400` | | A `Content-Length` that is not a plain string of digits | `400` | | `Transfer-Encoding` whose last coding is not `chunked` | `400` | | A coding under the chunking that we cannot decode | `501` | | `Transfer-Encoding` in an HTTP/1.0 request | `400` | | A field line folded onto the next (`obs-fold`) | `400` | | Whitespace between a field name and its colon | `400` | | A bare CR or LF anywhere in the head | `400` | | Anything but one space between the parts of the request line | `400` | | HTTP/1.1 with no `Host`, or two that disagree | `400` | | `HTTP/0.9`, or a major version above 1 | `505` | | A head, or a field count, past the configured limit | `431` | | An `Expect` nobody understands | `417` | | A `CONNECT` | `501` — see below | ### HTTP/2: what is a stream error and what takes the connection The distinction matters more here than anywhere else in the library: escalating a stream error kills requests that were fine, and demoting a connection error leaves the two ends disagreeing about a compression context they both have to keep in step. | Input | Answer | | --- | --- | | A preface that is not the preface | GOAWAY, PROTOCOL_ERROR | | DATA, HEADERS or RST_STREAM on stream 0 | GOAWAY, PROTOCOL_ERROR | | SETTINGS, PING or GOAWAY on a non-zero stream | GOAWAY, PROTOCOL_ERROR | | Anything but CONTINUATION between HEADERS and CONTINUATION | GOAWAY, PROTOCOL_ERROR | | A field block that does not decode | GOAWAY, COMPRESSION_ERROR | | A frame longer than the size we advertised | GOAWAY, FRAME_SIZE_ERROR | | An even client stream id, or one that goes backwards | GOAWAY, PROTOCOL_ERROR | | A frame for a stream the peer itself ended | GOAWAY, STREAM_CLOSED | | A PUSH_PROMISE from a client | GOAWAY, PROTOCOL_ERROR | | A CONTINUATION flood, or too many cancelled streams | GOAWAY, ENHANCE_YOUR_CALM | | A missing, duplicated or misplaced pseudo-header | RST_STREAM, PROTOCOL_ERROR | | An uppercase field name | RST_STREAM, PROTOCOL_ERROR | | `Connection`, `Keep-Alive`, `Transfer-Encoding`, `Upgrade` | RST_STREAM, PROTOCOL_ERROR | | `TE` other than `trailers` | RST_STREAM, PROTOCOL_ERROR | | `content-length` disagreeing with the DATA sent | RST_STREAM, PROTOCOL_ERROR | | More streams at once than we advertised | RST_STREAM, REFUSED_STREAM | | A field section over `SETTINGS_MAX_HEADER_LIST_SIZE` | `431`, on that stream | | `:protocol` without `SETTINGS_ENABLE_CONNECT_PROTOCOL` | RST_STREAM, PROTOCOL_ERROR | | A `CONNECT` with no `:protocol` | `501`, on that stream | | A PRIORITY frame | Ignored (RFC 9113 deprecated it) | | An unknown frame type outside a field block | Ignored (§5.5) | The `431` in that table is the one row that is not an error code, and it is deliberate. RFC 9113 §10.5.1 allows a status there, and the easy alternative — RST_STREAM with REFUSED_STREAM — would be a lie: that code means "nothing happened here, try another connection", so a client believing it sends the same oversized request again and gets the same answer forever. The field block is decoded to the end whatever is done with it, because the peer's dynamic table has already moved and ours has to move with it. Two attacks get named defences, because neither is caught by the rules above. **CONTINUATION flooding** (CVE-2024-27316) is not "a big field block" but "a field block that never ends", so the limits are enforced inside the reassembly loop and each frame's own nine-octet header is charged against the byte budget — which is what stops a flood of *empty* CONTINUATION frames. **Rapid reset** (CVE-2023-44487) works because a cancelled stream closes at once and so never counts against `max_concurrent_streams`; a token budget charges every RST_STREAM the peer sends and refunds every stream that runs to completion. On the way out, a field value carrying a CR or an LF is refused by `Response.setHeader` rather than written, and a handler that writes more than the length it declared is refused at the write rather than at the flush — so not one octet past the declared length reaches the wire. `Expect: 100-continue` is answered when the handler asks for the first octet of the body and not before, which is the whole point of the expectation: a handler that is going to answer `401` or `413` does it without the client ever sending the gigabyte it was offering. A handler that answers without reading the body closes the connection, because the client is still holding one. The HTTP/2 and HTTP/3 drivers follow the same rule: the `100` goes out as an interim HEADERS frame the first time the handler reads the body, none goes out if the response head is already on its way, and any other expectation is a `417`. Neither has a connection to close afterwards — a client that is still holding its content ends its own half of the stream instead. Nor does either ask a client that has already finished its half: over HTTP/2 that is END_STREAM on the HEADERS frame, and over HTTP/3 it is the stream's FIN, which `transport.Session.received` reports without reading — asked at the first read of the body rather than when the request arrived, since a client that stopped waiting may have sent the rest in between. A handler that sends a `100` of its own with `Response.sendInterim` has answered the expectation, and the driver sends no second one. Each of the three servers takes a `max_body_len`, the most request body it will read for one request. It is null by default, which leaves the limit to whatever the handler chooses to read. With one set, a request that declares a longer body is answered `413` before the handler runs, and so before any `100 Continue` asks for it. A body that runs past the limit without saying so has its read fail at the limit, and is answered `413` if the handler has not begun a response. Afterwards, HTTP/1.1 closes the connection, because the rest of the body is still on it. HTTP/2 and HTTP/3 ask the client to stop sending on that one stream, with RST_STREAM or STOP_SENDING carrying no error. ## Switching protocols `Response.upgrade` stops speaking HTTP on a connection and hands the reader and the writer to the handler. That is RFC 9110 §7.8's `Upgrade` mechanism, and it is what a WebSocket server needs: ```zig fn chat(req: *http.server.Request, res: *http.server.Response) anyerror!void { if (!req.offersUpgrade("websocket")) return res.sendStatus(.upgrade_required); try res.setHeader("Sec-WebSocket-Accept", accept_token); const stream = try res.upgrade("websocket"); // No HTTP left. `stream.input` and `stream.output` are yours until you // return, and then the connection closes. } ``` Three things make it safe to use: * **Nothing is lost behind the handshake.** The stream comes back positioned exactly where the request head ended, so a client that pipelined its first frames without waiting for the `101` still has them read. That is the classic way a protocol switch goes wrong and there is a test for it that delivers the request one octet at a time. * **It refuses what RFC 9110 §7.8 says to refuse.** A protocol the client did not list in `Upgrade` (with `Connection: upgrade` alongside it), an HTTP/1.0 client, or a request whose body the handler has not read — that last one because the unread octets sit in front of the new protocol's first octet. * **A refusal changes nothing.** `upgrade` returns an error with the response untouched, so the handler goes on to send `426 Upgrade Required` or whatever else it likes. It is a method rather than a callback registered with the server, and the reason is lifetime. A callback invoked after the handler returned would be handed a connection whose owner had already moved on, so the server would have to keep it alive on the callback's behalf and the two would have to agree about when it was finished. Returning the stream to the handler that is already running keeps the whole thing in one stack frame. ### The same handler over HTTP/2 Over HTTP/2 there is no `Upgrade` — §8.2.2 forbids the fields outright — so the mechanism is RFC 8441's extended CONNECT: a `CONNECT` request carrying a `:protocol` pseudo-header, which a client may only send after the server has advertised `SETTINGS_ENABLE_CONNECT_PROTOCOL`. **The handler above does not change.** `req.offersUpgrade("websocket")` answers from `Upgrade` over HTTP/1.1 and from `:protocol` over HTTP/2, and `res.upgrade("websocket")` sends `101 Switching Protocols` on one and `200` on the other. That is the whole argument for a `Request` that is not a wire format, and it is the first place in this library where the argument pays for something a handler could not reasonably have written itself. Three differences are real and worth knowing: * **A tunnel is one stream, not the connection.** Over HTTP/1.1 an upgraded connection is spent: every request that would have been multiplexed with it has to find another socket. Over HTTP/2 the other streams carry on, and there is a test that runs a tunnel and an ordinary request side by side on one connection. * **There is no `Sec-WebSocket-Key` handshake.** RFC 8441 §5 says so explicitly — the pseudo-header replaces it, because a pseudo-header is something no `XMLHttpRequest`-style client can forge in the first place, which is what the `Sec-` prefix was for. * **The request body is the tunnel**, so `upgrade` does not refuse an unread one. Over HTTP/1.1 an unread body sits in the byte stream in front of the new protocol's first octet; here the DATA frames *are* the new protocol. Setting `http2.Config.enable_connect_protocol` to false switches the whole thing off, and then a client that sends `:protocol` anyway gets a stream error — which is exactly what RFC 8441 §3 says a non-supporting peer does. WebSocket framing itself is not here and is not going to be: it is a different wire format that shares nothing with HTTP, and it lives in [zig-websocket](https://git.jcollie.dev/jeff/zig-websocket), which depends on this library and speaks RFC 6455 through the seam described above. ## `CONNECT` is out of scope It is answered `501 Not Implemented`, and that is a decision rather than an omission. `CONNECT` asks a server to open a TCP connection to somewhere else and relay octets between it and the client (RFC 9110 §9.3.6). Almost none of that is HTTP. What it needs is a dialling policy, a name resolver, a relay loop, and answers to the questions that make a proxy a proxy: which hosts and ports may be reached, by whom, and what is logged. A library that shipped it without those answers would be shipping an open relay; one that shipped them would be a proxy rather than a server. The mechanical half is already here for whoever wants to build that — the same `Response.upgrade` that hands a WebSocket handler its stream would hand a `CONNECT` handler the same one. What is missing is the proxy, not the seam. ## HTTPS, and why HTTP/2 needed it `http_io.tls.Listener` is the TCP listener with a TLS handshake on the front of it. Nothing above it knows: `transport.Connection` already said whether a channel was confidential and what was negotiated over it, so the drivers read and write exactly as they do over a plain socket, and `Info.secure` and `Info.alpn` had been sitting there with nothing to fill them in. That last field is the whole of how HTTP/2 gets selected in practice. §3.1 of RFC 9113 gives it the ALPN identifier `h2` and there is no other way in — the `PRI ` preface works only on a cleartext port, and §3.2's `Upgrade` was removed by that same RFC. So until there was TLS here, HTTP/2 was reachable only by prior knowledge or from behind a terminator, which is to say: not by any browser. `server.Server` has always dispatched on `Info.alpn`, so turning it on took no change to a driver at all. One certificate, however the client can reach it — `--cert` and `--key` are the certificate, `--tls` makes the byte-stream port HTTPS, and `--h3-port` answers the same name over QUIC: ```console $ zig-http --port 8443 --tls --h3-port 8443 --cert cert.pem --key key.pem listening on https://127.0.0.1:8443/ listening on https://127.0.0.1:8443/ (HTTP/3) ``` `--tls` is a switch rather than "a certificate was given", because HTTP/3 needs one too and turning the TCP port into HTTPS as a side effect of asking for HTTP/3 would be a surprise. The two listeners share the certificate outright: both modules reach the same tls.zig through the same dependency, so `quic.tls_handshake.CertKeyPair` and `http_io.tls.CertKeyPair` are one type rather than two that look alike, which `tests/typecheck.zig` asserts. `tests/nixos/tls.nix` is the guest that proves it, against a real curl and a certificate generated inside the machine so the chain is verified rather than skipped: `h2` negotiated and taken, `openssl s_client` asked separately what the handshake actually agreed, a client that offers only `http/1.1` served HTTP/1.1 over the same port and certificate, `h3` answered over QUIC from that same certificate, a POST so the body path is covered, and cleartext to the TLS port refused without disturbing the next request. Three protocols selected by negotiation from one file on disk.