zig-http as a server #
What serving HTTP with zig-http involves beyond the smallest server in the README: what each version of HTTP asks of a handler, what the drivers refuse and why, switching protocols, and TLS. The API documentation at https://jeff.jcollie.page/zig-http/ 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.
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.
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.
$ 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, 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'sModulus.pow, which sizes the exponent buffer by the type's maximum width rather than the modulus's. Supporting 4096-bit keys means instantiatingModulus(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
nare a quarter of the work of one modulon. - And when that was fixed, nothing changed — because
PrivateKey.parseDerwalks 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 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:
$ 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.
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:
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
101still 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(withConnection: upgradealongside 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.
upgradereturns an error with the response untouched, so the handler goes on to send426 Upgrade Requiredor 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-Keyhandshake. RFC 8441 §5 says so explicitly — the pseudo-header replaces it, because a pseudo-header is something noXMLHttpRequest-style client can forge in the first place, which is what theSec-prefix was for. - The request body is the tunnel, so
upgradedoes 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, 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:
$ 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.