From 1fdfae302f8621c22afe96bb731dfa95e1d7bfcf Mon Sep 17 00:00:00 2001 From: "Jeffrey C. Ollie" Date: Thu, 27 Aug 2026 23:08:33 -0500 Subject: [PATCH] serve the api documentation from a build step Reading the generated documentation locally required a web server, and the README told the reader to find one: the viewer fetches sources.tar and main.wasm at runtime, and a browser refuses both from a file:// page, so opening index.html gives an empty page. `zig build docs-serve` now builds the pages and serves them at http://127.0.0.1:8000/, with -Ddocs-port=N for another port. This is the same reason `zig std` runs a server rather than opening a file. The server is tools/docs_server.zig, copied from z46, which has the same problem and solved it first. It serves one directory to one person on the loopback interface: a thread per connection, because a browser opens several at once and holds some open without sending anything, so a server that reads them one at a time blocks on a speculative connection and never answers the real requests. Requests containing .. or an absolute path are refused, and the MIME table covers what autodoc emits, which is what makes main.wasm load at all. It is built for b.graph.host rather than the -Dtarget the library is built for, since it runs on the machine doing the build. Its own test is attached to the test step, so `zig build test` now runs 8 tests over two binaries rather than 7 over one. tools was added to the package paths so the file ships with the package, as it does in z46. Checked by serving on port 8123 and requesting through it: / and /index.html return the page as text/html, main.wasm as application/wasm, sources.tar as application/x-tar, a missing file gives 404, a query string is stripped, and /../build.zig does not escape the documentation directory. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_011JRTRSt3F4KkHY7ip2MgEk --- README.md | 8 +- build.zig | 44 +++++++++++ build.zig.zon | 1 + tools/docs_server.zig | 165 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 215 insertions(+), 3 deletions(-) create mode 100644 tools/docs_server.zig diff --git a/README.md b/README.md index 4e33119..648fa9c 100644 --- a/README.md +++ b/README.md @@ -261,13 +261,15 @@ Build and test: ```sh zig build zig build test -zig build docs # API reference into zig-out/docs +zig build docs # API reference into zig-out/docs +zig build docs-serve # ...and serve it at http://127.0.0.1:8000/ ``` The documentation is a WebAssembly viewer that fetches `sources.tar`, so it has to be served over HTTP; opening `zig-out/docs/index.html` from the filesystem -shows an empty page. `python3 -m http.server -d zig-out/docs` is enough to read -it locally. CI publishes the same output to [the address above][docs]. +shows an empty page, which is why there is a step that serves it and why `zig +std` works the same way. `-Ddocs-port=N` chooses another port. CI publishes the +same output to [the address above][docs]. The `enumerate` test opens real devices on the host, so its results depend on what hardware is attached and on the permissions described above. diff --git a/build.zig b/build.zig index 07834eb..33e9e6a 100644 --- a/build.zig +++ b/build.zig @@ -41,4 +41,48 @@ pub fn build(b: *std.Build) void { const docs_step = b.step("docs", "Generate API documentation"); docs_step.dependOn(&install_docs.step); + + // The generated 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. This is the same reason `zig std` runs a + // server rather than just 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, + }, + ), + }, + ); + + const run_docs_server = b.addRunArtifact(docs_server); + run_docs_server.step.dependOn(&install_docs.step); + run_docs_server.addArg(b.getInstallPath(.prefix, "docs")); + 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. + const docs_server_tests = b.addTest( + .{ + .root_module = docs_server.root_module, + }, + ); + test_step.dependOn(&b.addRunArtifact(docs_server_tests).step); } diff --git a/build.zig.zon b/build.zig.zon index e45d330..b041e68 100644 --- a/build.zig.zon +++ b/build.zig.zon @@ -11,6 +11,7 @@ "build.zig", "build.zig.zon", "src", + "tools", "LICENSES", "README.md", }, diff --git a/tools/docs_server.zig b/tools/docs_server.zig new file mode 100644 index 0000000..b53d0d5 --- /dev/null +++ b/tools/docs_server.zig @@ -0,0 +1,165 @@ +// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie +// SPDX-License-Identifier: MIT + +//! Serves the generated API documentation over HTTP, the way `zig std` serves +//! the standard library's. +//! +//! A server is needed rather than just opening `index.html`, because the +//! viewer fetches `sources.tar` and `main.wasm` at runtime and a browser +//! refuses those requests from a `file://` page. +//! +//! Run through the build system: `zig build docs-serve`. It is deliberately +//! minimal, serving one directory to one person on the loopback interface. +//! +//! Every connection gets its own thread, which is not a throughput concern but +//! a correctness one: a browser opens several connections at once and holds +//! some of them open without sending anything, so a server that reads them one +//! at a time blocks on a speculative connection and never answers the real +//! requests. +//! +//! A thread each, rather than a pool: a connection handler blocks until its +//! client goes away, which can be minutes, and a pool sized for short tasks +//! wedges once every worker is parked on an idle socket. A browser opens a +//! handful of connections, so the thread count stays small in practice. + +const std = @import("std"); +const Io = std.Io; + +/// Nothing in a documentation bundle comes close to this; it exists so that a +/// stray huge file cannot exhaust memory. +const max_file_size = 64 * 1024 * 1024; + +pub fn main(init: std.process.Init) !void { + const gpa = init.gpa; + const io = init.io; + const args = try init.minimal.args.toSlice(init.arena.allocator()); + + var stderr_buffer: [512]u8 = undefined; + var stderr_writer: Io.File.Writer = .init(.stderr(), io, &stderr_buffer); + const stderr = &stderr_writer.interface; + + if (args.len != 3) { + try stderr.writeAll("usage: docs-server \n"); + try stderr.flush(); + std.process.exit(2); + } + const docs_path = args[1]; + const port = try std.fmt.parseInt(u16, args[2], 10); + + var docs_dir = Io.Dir.cwd().openDir(io, docs_path, .{}) catch |err| { + try stderr.print("cannot open {s}: {s}\n", .{ docs_path, @errorName(err) }); + try stderr.flush(); + std.process.exit(1); + }; + defer docs_dir.close(io); + + const address: Io.net.IpAddress = .{ .ip4 = .{ .bytes = .{ 127, 0, 0, 1 }, .port = port } }; + var server = address.listen(io, .{ .reuse_address = true }) catch |err| { + try stderr.print("cannot listen on 127.0.0.1:{d}: {s}\n", .{ port, @errorName(err) }); + if (err == error.AddressInUse) { + try stderr.writeAll("another port can be chosen with -Ddocs-port=N\n"); + } + try stderr.flush(); + std.process.exit(1); + }; + defer server.deinit(io); + + try stderr.print("serving {s} at http://127.0.0.1:{d}/\npress ctrl-c to stop\n", .{ docs_path, port }); + try stderr.flush(); + + while (true) { + const stream = server.accept(io) catch |err| switch (err) { + // One client giving up is not a reason to stop serving. + error.ConnectionAborted, error.WouldBlock, error.ProtocolFailure => continue, + else => return err, + }; + + const thread = std.Thread.spawn(.{}, handleConnection, .{ io, gpa, docs_dir, stream }) catch { + // Out of threads. Serving it here blocks the ones behind it, but + // dropping it silently would look like the same hang from the + // browser's side with none of the progress. + handleConnection(io, gpa, docs_dir, stream); + continue; + }; + // Nothing joins these: each ends when its client disconnects, and the + // process runs until interrupted. + thread.detach(); + } +} + +/// Serves one connection until the client goes away, then closes it. +fn handleConnection(io: Io, gpa: std.mem.Allocator, docs_dir: Io.Dir, stream: Io.net.Stream) void { + defer stream.close(io); + + var recv_buffer: [16 * 1024]u8 = undefined; + var send_buffer: [64 * 1024]u8 = undefined; + var stream_reader = stream.reader(io, &recv_buffer); + var stream_writer = stream.writer(io, &send_buffer); + var http_server: std.http.Server = .init(&stream_reader.interface, &stream_writer.interface); + + // Keep answering on the same connection, so that one page load does not + // need a connection per file. + while (true) { + var request = http_server.receiveHead() catch return; + serve(&request, io, gpa, docs_dir) catch return; + // A client that asked to close is waiting for exactly that; waiting + // for another request it will never send would hang it until it times + // out. + if (!request.head.keep_alive) return; + } +} + +fn serve( + request: *std.http.Server.Request, + io: Io, + gpa: std.mem.Allocator, + docs_dir: Io.Dir, +) !void { + const target = request.head.target; + const path_end = std.mem.indexOfAny(u8, target, "?#") orelse target.len; + var path = target[0..path_end]; + if (std.mem.startsWith(u8, path, "/")) path = path[1..]; + if (path.len == 0) path = "index.html"; + + // The documentation directory is the whole world this server knows about. + if (std.mem.indexOf(u8, path, "..") != null or std.fs.path.isAbsolute(path)) { + return request.respond("bad request\n", .{ .status = .bad_request }); + } + + const content = docs_dir.readFileAlloc(io, path, gpa, .limited(max_file_size)) catch { + return request.respond("not found\n", .{ .status = .not_found }); + }; + defer gpa.free(content); + + try request.respond(content, .{ + .extra_headers = &.{.{ .name = "content-type", .value = mimeType(path) }}, + }); +} + +/// Enough of a MIME table for what `zig build docs` emits. +fn mimeType(path: []const u8) []const u8 { + const extension = std.fs.path.extension(path); + const table = [_]struct { []const u8, []const u8 }{ + .{ ".html", "text/html; charset=utf-8" }, + .{ ".js", "text/javascript; charset=utf-8" }, + .{ ".css", "text/css; charset=utf-8" }, + .{ ".wasm", "application/wasm" }, + .{ ".tar", "application/x-tar" }, + .{ ".json", "application/json" }, + .{ ".svg", "image/svg+xml" }, + }; + for (table) |entry| { + if (std.mem.eql(u8, extension, entry[0])) return entry[1]; + } + return "application/octet-stream"; +} + +const testing = std.testing; + +test mimeType { + try testing.expectEqualStrings("text/html; charset=utf-8", mimeType("index.html")); + try testing.expectEqualStrings("application/wasm", mimeType("main.wasm")); + try testing.expectEqualStrings("application/x-tar", mimeType("sources.tar")); + try testing.expectEqualStrings("text/javascript; charset=utf-8", mimeType("main.js")); + try testing.expectEqualStrings("application/octet-stream", mimeType("noextension")); +} -- knotmirror 0.0.1