Something went wrong. Try again.
An HTTP library for Zig 0.17, server and client, HTTP/1.0 through HTTP/3, with the protocol in a module that owns no socket.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// 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");