// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! An HTTP server that does not know what it is running on. //! //! Four layers, and the boundaries between them are the point of the library: //! //! * `protocol` is HTTP semantics — methods, statuses, targets, header //! fields, dates — with nothing in it about how any of them are written //! down. RFC 9110 made that separation and this follows it, because it is //! what makes everything above a version of HTTP reusable across all of //! them. //! * `transport` is where the octets come from: a reader, a writer, and the //! few facts about the channel that HTTP needs and cannot read off it. //! TCP and an in-memory implementation are provided; TLS, a Unix socket or //! a pair of pipes would each be about fifty lines and nothing above would //! know. //! * `http1` and `http2` are the wire formats — RFC 9112's request line and //! chunked coding, RFC 9113's frames and RFC 7541's header compression. //! They are the only parts that know what any of that looks like, and //! neither knows about the other. //! * `server` is the accept loop and the three types a handler is written //! against: `Request`, `Response` and `Handler`. //! //! ## HTTP/2 //! //! Implemented, and 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 //! because RFC 9113 §3.4 chose the `PRI ` method to make exactly that test //! possible. ALPN is the other way in, and something below has to negotiate //! it: `http_io.tls` does, offering `h2` and filling in //! `transport.Connection.Info.alpn`, and so does a TLS terminator in front of //! this. Neither is this module's business — it reads that field and never //! sets it. //! //! Nothing above the driver changed to make it work, which is the claim the //! four layers were arranged to support and is now a demonstration rather //! than an assertion: a handler declares how long its body is and never //! writes a `Content-Length`, never sees a chunk, and cannot set //! `Connection`, so the same handler is correct over a version where none of //! those things exist. `src/main.zig`'s `/stream` route is the short version //! — one handler, a chunked coding over HTTP/1.1, a closed connection over //! HTTP/1.0, and DATA frames over HTTP/2. //! //! **A handler is now called concurrently on one connection.** HTTP/2 //! multiplexes, so up to `http2.Config.max_concurrent_streams` tasks may be //! inside the same handler at once. See `server.Handler`. //! //! Not implemented: server push (a client PUSH_PROMISE is a connection //! error), RFC 8441 extended CONNECT, and response trailers. //! //! ## HTTP/3 //! //! In `http3`. It needs more than a driver, because a QUIC connection is //! many streams where a `transport.Connection` is one, so it arrives with a //! listener of its own rather than being handed a connection by //! `server.Server`. `protocol` does not change, which is the whole reason //! `protocol` is where it is, and this is the first time that claim is tested //! against a transport that is not a byte stream at all. //! //! `http_io.http3.Listener` owns a UDP socket and a handler, the driver opens §6.2's //! control and QPACK streams, and a HEADERS frame carrying a QPACK field //! section becomes the same `Request` a handler has been written against //! since HTTP/1.0 -- built by the same `field.request` the HTTP/2 driver //! uses, with the version as its only parameter. Response trailers, §5.2's //! GOAWAY and RFC 9220's extended CONNECT are all there, and two clients //! that share nothing with it agree: curl over ngtcp2 and nghttp3, and //! aioquic over `pylsqpack`. //! //! Not there: a dynamic QPACK table (capacity zero is advertised, so no peer //! may use one), server push, and plain `CONNECT`. //! //! ## Two modules, and which one you want //! //! This one is the protocol and nothing that owns a file descriptor. Every //! byte reaches it through a `transport.Connection` -- a reader, a writer and //! a handful of facts -- or, for HTTP/3, a `transport.Session`, which is the //! same idea for a connection carrying many streams. Neither names a socket. //! That is what lets the whole of an exchange be driven over a slice of //! memory, which is why the parsers can be fuzzed at half a million inputs a //! second and why an HTTP/3 request can be served in a test with no port and //! no QUIC handshake. //! //! `http_io` is the other half: the TCP listener, the QUIC-backed session and //! the HTTP/3 listener. A program serving HTTP wants both. Something //! embedding HTTP in a runtime that already owns its own I/O wants only this //! one, and gets to keep it. //! //! ## Getting started //! //! ```zig //! fn hello(req: *http.server.Request, res: *http.server.Response) anyerror!void { //! _ = req; //! try res.setHeader("Content-Type", "text/plain; charset=utf-8"); //! try res.send("hello\n"); //! } //! //! var listener = try http_io.tcp.Listener.listen(io, address, .{}); //! defer listener.deinit(io); //! var server = http.server.Server.init( //! io, //! gpa, //! listener.listener(), //! .initStateless(hello), //! .{}, //! ); //! try server.serve(); //! ``` //! //! ## Switching protocols //! //! `Response.upgrade` stops speaking HTTP on a connection and hands the //! reader and the writer to the handler, which is what RFC 9110 §7.8's //! `Upgrade` mechanism is for and what a WebSocket server needs. The stream //! comes back positioned exactly where the request head ended, so anything a //! client pipelined behind its handshake is still there to be read. //! //! 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 //! holding a connection whose owner had moved on. Returning the stream to the //! handler that is already running keeps it in one stack frame — the handler //! speaks the new protocol for as long as it likes, returns, and the //! connection closes where every other connection closes. //! //! ## `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, and one that shipped them would be a proxy rather than a server. //! //! The mechanical part 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. //! //! ## What is not here //! //! No content codings and no caching. //! //! No TLS in *this module*, which is a design rather than a gap: `http` is //! the protocol and nothing that owns a file descriptor, so it reads //! `transport.Connection.Info.secure` and never sets it. `http_io.tls` sets //! it, for a server. A connection that says it is not secure is exactly as //! public as it says. //! //! TLS reaches all three clients. `http3.client` has it because QUIC carries //! it; the other two get it from `http_io.tls.connect`, which is //! `Listener.accept` seen from the other end and hands back the same //! `transport.Connection` — so neither driver has a line about TLS in it, and //! `http2.client` needed no change at all to speak over one. What decides the //! version is the ALPN list the dialler offers, which is §3.1 of RFC 9113's //! answer on this side as much as on the server's: `h2` for HTTP/2, //! `http/1.1` otherwise, and a caller that offers one and is agreed the other //! has to notice rather than assume. const std = @import("std"); pub const http1 = @import("http1.zig"); pub const http2 = @import("http2.zig"); pub const protocol = @import("protocol.zig"); pub const server = @import("server.zig"); pub const client = @import("client.zig"); pub const transport = @import("transport.zig"); /// The port IANA assigns to HTTP. pub const default_port = 80; /// The port IANA assigns to HTTP over TLS. pub const default_tls_port = 443; test { std.testing.refAllDecls(@This()); } /// RFC 9114: HTTP/3, over QUIC. pub const http3 = @import("http3.zig"); /// What HPACK and QPACK share, which is the Huffman code and nothing else. pub const field = @import("field.zig");