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.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
const std = @import("std");
pub fn build(b: *std.Build) void { const target = b.standardTargetOptions(.{}); const optimize = b.standardOptimizeOption(.{});
const quic_dep = b.dependency("quic", .{ .target = target, .optimize = optimize }); // Addresses as values: `std.Io.net.IpAddress` would do, and naming the // networking namespace in a module that owns no socket would undo the // claim the module is built on. const z46_dep = b.dependency("z46", .{ .target = target, .optimize = optimize }); // HTTP dates: reading the three forms RFC 9110 §5.6.7 has a recipient // accept, and writing the one it has a sender use. Calendar arithmetic is // zig-datetime's business, and an HTTP library that kept its own copy // would be keeping its own bugs. const datetime_dep = b.dependency("datetime", .{ .target = target, .optimize = optimize });
// The protocol, and nothing that owns a file descriptor. `quic` is here // because HTTP/3 is defined in terms of QUIC's stream identifiers and // error codes, and `quic` is itself sans-I/O; `quic_io` is deliberately // absent, which is what keeps every byte reaching this module through a // `transport.Connection` or a `transport.Session` it cannot see behind. const mod = b.addModule("http", .{ .root_source_file = b.path("src/root.zig"), .target = target, .imports = &.{ .{ .name = "datetime", .module = datetime_dep.module("datetime") }, .{ .name = "quic", .module = quic_dep.module("quic") }, .{ .name = "z46", .module = z46_dep.module("z46") }, }, });
// HTTP with the I/O put back: the TCP listener, the QUIC-backed session // that HTTP/3 runs on, and the HTTP/3 listener that owns a UDP socket. // No options, which is how zig-quic instantiates it too: the dependency // cache is keyed on them, so matching means one module and one set of // types rather than two that merely look alike. const tls_dep = b.dependency("tls", .{}); // URLs, for `http_io.Client`: the protocol module takes a request target // and an authority as the wire has them and never needs a whole URL, so // only the half that dials does. const uri_dep = b.dependency("uri", .{ .target = target, .optimize = optimize });
const io_mod = b.addModule("http_io", .{ .root_source_file = b.path("src/io/root.zig"), .target = target, .imports = &.{ .{ .name = "http", .module = mod }, .{ .name = "quic", .module = quic_dep.module("quic") }, .{ .name = "quic_io", .module = quic_dep.module("quic_io") }, .{ .name = "tls", .module = tls_dep.module("tls") }, .{ .name = "uri", .module = uri_dep.module("uri") }, .{ .name = "z46", .module = z46_dep.module("z46") }, }, });
// z46 and zig-uri for the host, instantiated with the same options. The // dependency cache is keyed on them, and zig-uri instantiates z46 with // the ones it is handed, so this way the z46 zig-uri brings and the one // named here are one module. Mixing the target's z46 with the host's // zig-uri puts the same files in two modules whenever the target is not // the host -- which a Nix build's `-Dcpu=baseline` is enough to make it. const host_options = .{ .target = b.graph.host, .optimize = std.lang.Optimize.debug }; const host_z46_dep = b.dependency("z46", host_options); const host_uri_dep = b.dependency("uri", host_options); const host_datetime_dep = b.dependency("datetime", host_options);
// The same source built for the machine running the build, for the tools // in `tools/` -- which are build-time programs and must not be built for // whatever `-Dtarget` the library is being cross-compiled to. const host_mod = b.createModule(.{ .root_source_file = b.path("src/root.zig"), .target = b.graph.host, .imports = &.{ .{ .name = "datetime", .module = host_datetime_dep.module("datetime") }, .{ .name = "quic", .module = quic_dep.module("quic") }, .{ .name = "z46", .module = host_z46_dep.module("z46") }, }, });
// And the I/O half of it, for the same reason: a tool that serves // something needs a socket, and a file belongs to one module, so the // host build needs its own pair rather than borrowing the target's. const host_io_mod = b.createModule(.{ .root_source_file = b.path("src/io/root.zig"), .target = b.graph.host, .imports = &.{ .{ .name = "http", .module = host_mod }, .{ .name = "quic", .module = quic_dep.module("quic") }, .{ .name = "quic_io", .module = quic_dep.module("quic_io") }, .{ .name = "tls", .module = b.dependency("tls", .{}).module("tls") }, .{ .name = "uri", .module = host_uri_dep.module("uri") }, .{ .name = "z46", .module = host_z46_dep.module("z46") }, }, });
const exe = b.addExecutable(.{ .name = "zig-http", .root_module = b.createModule(.{ .root_source_file = b.path("src/main.zig"), .target = target, .optimize = optimize, // All three, because this is a server rather than a library: // `http` for the protocol, `http_io` for the sockets, and `quic` // because the HTTP/3 listener needs a certificate and a source of // randomness handed to it and those are QUIC's types -- there is // no way to describe a stateless reset key without describing // QUIC. .imports = &.{ .{ .name = "http", .module = mod }, .{ .name = "http_io", .module = io_mod }, .{ .name = "quic", .module = quic_dep.module("quic") }, }, }), }); b.installArtifact(exe);
const run_cmd = b.addRunArtifact(exe); run_cmd.step.dependOn(b.getInstallStep()); run_cmd.stdio = .inherit; run_cmd.addPassthruArgs(); const run_step = b.step("run", "Run the demonstration server"); run_step.dependOn(&run_cmd.step);
// Narrows every test executable below to the tests whose name contains // this. `-Dfuzz-filter` is separate and narrows the fuzz module only, // because the fuzzer takes one test at a time and naming a target is what // you want when a finding is being chased. const test_filter = b.option( []const u8, "test-filter", "Run only the tests whose name contains this", ); const filters: []const []const u8 = if (test_filter) |f| &.{f} else &.{};
// A test executable covers one module, so each needs its own. Missing one // out would not fail: its tests would simply never run. // // Every one is compiled with LLVM rather than the self-hosted backend // Debug uses by default, which emits no coverage instrumentation: without // it `zig build fuzz --fuzz` has an empty table of program counters and // cannot steer, and kcov has nothing to report. const test_step = b.step("test", "Run tests"); for ([_]*std.Build.Module{ mod, exe.root_module }) |m| { test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .use_llvm = true, .root_module = m, .filters = filters, })).step); }
const e2e_mod = b.createModule(.{ .root_source_file = b.path("tests/e2e.zig"), .target = target, .optimize = optimize, .imports = &.{.{ .name = "http", .module = mod }}, }); test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .use_llvm = true, .root_module = e2e_mod, .filters = filters, })).step);
// The HTTP/2 driver end to end. A module of its own rather than more // tests in `e2e.zig`, because it needs a real `Io` -- a driver that gives // each stream a task cannot be run on one that has no tasks. const h2_mod = b.createModule(.{ .root_source_file = b.path("tests/h2.zig"), .target = target, .optimize = optimize, .imports = &.{.{ .name = "http", .module = mod }}, }); test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .use_llvm = true, .root_module = h2_mod, .filters = filters, })).step);
// The HTTP/3 driver end to end, over a real UDP socket. It needs the two // QUIC modules as well as this one, because the client in it is written // by hand -- which is the point: nothing it does comes from the code it // is checking. const h3_mod = b.createModule(.{ .root_source_file = b.path("tests/h3.zig"), .target = target, .optimize = optimize, .imports = &.{ .{ .name = "http", .module = mod }, .{ .name = "http_io", .module = io_mod }, .{ .name = "quic", .module = quic_dep.module("quic") }, .{ .name = "quic_io", .module = quic_dep.module("quic_io") }, }, }); test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .use_llvm = true, .root_module = h3_mod, .filters = filters, })).step);
const client_mod = b.createModule(.{ .root_source_file = b.path("tests/client.zig"), .target = target, .optimize = optimize, .imports = &.{.{ .name = "http", .module = mod }}, }); test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .use_llvm = true, .root_module = client_mod, .filters = filters, })).step);
const tcp_mod = b.createModule(.{ .root_source_file = b.path("tests/tcp.zig"), .target = target, .optimize = optimize, .imports = &.{ .{ .name = "http", .module = mod }, .{ .name = "http_io", .module = io_mod }, }, }); test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .use_llvm = true, .root_module = tcp_mod, .filters = filters, })).step);
// `http_io.Client` against the server, over loopback sockets with and // without TLS: the URL, the name lookup, the ALPN negotiation and the // redirects, which are the parts the drivers leave to it. const fetch_mod = b.createModule(.{ .root_source_file = b.path("tests/fetch.zig"), .target = target, .optimize = optimize, .imports = &.{ .{ .name = "http", .module = mod }, .{ .name = "http_io", .module = io_mod }, }, }); test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .use_llvm = true, .root_module = fetch_mod, .filters = filters, })).step);
// The fuzz targets: what the head parser, the path resolver, the date // parser and the driver as a whole must do with input nobody wrote. They // are ordinary tests as well as fuzz targets, so `zig build test` // exercises the same properties on the seeds checked in beside them. const fuzz_mod = b.createModule(.{ .root_source_file = b.path("tests/fuzz.zig"), .target = target, .optimize = optimize, .imports = &.{.{ .name = "http", .module = mod }}, }); // Zig's fuzzer takes one test at a time and keeps a coverage file per // test, so naming a target is what you want when a finding is being // chased: `zig build fuzz --fuzz -Dfuzz-filter=paths`. const fuzz_filter = b.option( []const u8, "fuzz-filter", "Fuzz or test only the targets whose name contains this", ); const fuzz_tests = b.addTest(.{ .use_llvm = true, .root_module = fuzz_mod, .filters = if (fuzz_filter) |f| &.{f} else &.{}, }); test_step.dependOn(&b.addRunArtifact(fuzz_tests).step);
// A step of its own for `zig build fuzz --fuzz`, which needs a run step // holding nothing else: the fuzzer takes over the terminal and runs until // it is stopped, so it must not be reached by `zig build test`. const fuzz_step = b.step("fuzz", "The fuzz targets: add --fuzz to fuzz them"); fuzz_step.dependOn(&b.addRunArtifact(fuzz_tests).step);
// A loop of our own that drives those same targets from a corpus of // their seeds, bounded and reproducible, for CI and for replaying a // finding; `tools/fuzz.zig` says what it costs and what it buys. Optimised, // because a fuzzer's whole job is how many inputs it gets through, and // ReleaseSafe keeps every check that makes a failure a failure. const fuzz_run = b.addExecutable(.{ .name = "zig-http-fuzz", .root_module = b.createModule(.{ .root_source_file = b.path("tools/fuzz.zig"), .target = b.graph.host, .optimize = .safe, .imports = &.{.{ .name = "fuzz_targets", .module = fuzz_mod }}, }), }); const run_fuzz = b.addRunArtifact(fuzz_run); run_fuzz.stdio = .inherit; run_fuzz.addPassthruArgs(); const fuzz_run_step = b.step("fuzz-run", "Fuzz the targets with a loop of our own"); fuzz_run_step.dependOn(&run_fuzz.step);
// Nothing else builds it, so without this it could stop compiling and // `zig build test` would not notice. const check_step = b.step("check", "Compile everything without running it"); check_step.dependOn(&fuzz_run.step); // And the program itself, which has no test in it and so was reached by // nothing this step ran. It said "compile everything" and did not: a // shadowed capture in `src/main.zig` went through a green `check` and was // caught by `zig build`, which is the wrong order for the cheaper command // to fail in. check_step.dependOn(&exe.step);
// -- documentation ------------------------------------------------------- // // Zig emits the API documentation as a side effect of compiling, so the // module is built as a library purely to get at it. What comes out is not // a page but a program: a WebAssembly viewer, its javascript, and a tar of // the sources it reads from. test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .use_llvm = true, .root_module = io_mod, .filters = filters, })).step);
const typecheck_mod = b.createModule(.{ .root_source_file = b.path("tests/typecheck.zig"), .target = target, .optimize = optimize, .imports = &.{ .{ .name = "quic", .module = quic_dep.module("quic") }, .{ .name = "http", .module = mod }, .{ .name = "http_io", .module = io_mod }, .{ .name = "z46", .module = z46_dep.module("z46") }, }, }); test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .use_llvm = true, .root_module = typecheck_mod, .filters = filters, })).step);
const library = b.addLibrary(.{ .name = "http", .root_module = mod }); const install_docs = b.addInstallDirectory(.{ .source_dir = library.getEmittedDocs(), .install_dir = .prefix, .install_subdir = "docs", }); const docs_step = b.step("docs", "Build the API documentation into zig-out/docs"); docs_step.dependOn(&install_docs.step);
// That viewer fetches `sources.tar` and `main.wasm` at runtime, which a // browser refuses to do from a `file://` page, so reading the docs // locally means serving them. It is the same reason `zig std` runs a // server rather than opening a file. const docs_port = b.option(u16, "docs-port", "Port for `zig build docs-serve` (default 8000)") orelse 8000;
const docs_server = b.addExecutable(.{ .name = "docs-server", .root_module = b.createModule(.{ .root_source_file = b.path("tools/docs_server.zig"), // Always built for the machine running the build, never for // whatever -Dtarget the library is being built for. .target = b.graph.host, .optimize = .debug, // It serves the documentation with this repository's own server, // which is both the honest thing to do and a second real consumer // of the API. .imports = &.{ .{ .name = "http", .module = host_mod }, .{ .name = "http_io", .module = host_io_mod }, }, }), });
const run_docs_server = b.addRunArtifact(docs_server); run_docs_server.addDirectoryArg(library.getEmittedDocs()); run_docs_server.addArg(b.fmt("{d}", .{docs_port})); // The server runs until interrupted, so its output has to reach the // terminal rather than being captured by the build runner. run_docs_server.stdio = .inherit;
const docs_serve_step = b.step("docs-serve", "Serve the API documentation over HTTP"); docs_serve_step.dependOn(&run_docs_server.step);
// The server has tests of its own; without this they would never run. test_step.dependOn(&b.addRunArtifact( b.addTest(.{ .root_module = docs_server.root_module, .use_llvm = true }), ).step); check_step.dependOn(&docs_server.step);}