Something went wrong. Try again.
The WebSocket Protocol (RFC 6455) for Zig: framing, a client, and a server handshake on zig-http
Something went wrong. Try again.
zig-websocket build.zig
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212// 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(.{});
// zig-http with this package's own target and optimize mode. Asked for // with none, it takes the machine building it -- whatever -Dcpu the // program asked for -- and every program had to ask for zig-uri, z46 and // anything else under it the same way, or have them twice. const http = b.dependency("http", .{ .target = target, .optimize = optimize });
// Two modules, split at the only place an HTTP implementation is needed. // // `websocket` is the protocol -- framing, the connection, and the client // half of the opening handshake -- and depends on nothing but the // standard library. `websocket_server` is `accept` and `refuse`, which // are written against zig-http because a server has a request in hand and // an HTTP version to worry about. // // A client should not have to take a dependency on an HTTP *server* // library in order to open a connection, and with one module it would // have to: the import has to resolve at build time whether or not the // code is reached. const mod = b.addModule("websocket", .{ .root_source_file = b.path("src/root.zig"), .target = target, });
const server_mod = b.addModule("websocket_server", .{ .root_source_file = b.path("src/server.zig"), .target = target, .imports = &.{ .{ .name = "http", .module = http.module("http") }, .{ .name = "websocket", .module = mod }, }, });
const exe = b.addExecutable(.{ .name = "zig-websocket", .root_module = b.createModule(.{ .root_source_file = b.path("src/main.zig"), .target = target, .optimize = optimize, .imports = &.{ .{ .name = "websocket", .module = mod }, .{ .name = "websocket_server", .module = server_mod }, .{ .name = "http", .module = http.module("http") }, .{ .name = "http_io", .module = http.module("http_io") }, }, }), }); 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);
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. const test_step = b.step("test", "Run tests"); for ([_]*std.Build.Module{ mod, server_mod, exe.root_module }) |m| { test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = m, .filters = filters, })).step); }
// The protocol end to end, over a transport made of a string: a scripted // client conversation in, the server's octets out. const e2e_mod = b.createModule(.{ .root_source_file = b.path("tests/e2e.zig"), .target = target, .optimize = optimize, .imports = &.{ .{ .name = "websocket", .module = mod }, .{ .name = "websocket_server", .module = server_mod }, .{ .name = "http", .module = http.module("http") }, }, }); test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = e2e_mod, .filters = filters, })).step);
// The same handler over HTTP/2, which needs a real `Io`: zig-http's // HTTP/2 driver gives every stream a task, and one that cannot run two at // once would refuse every stream. const h2_mod = b.createModule(.{ .root_source_file = b.path("tests/h2.zig"), .target = target, .optimize = optimize, .imports = &.{ .{ .name = "websocket", .module = mod }, .{ .name = "websocket_server", .module = server_mod }, .{ .name = "http", .module = http.module("http") }, }, }); test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = h2_mod, .filters = filters, })).step);
// The fuzz targets, which are ordinary tests as well: without `--fuzz` // they run 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 = "websocket", .module = mod }, .{ .name = "websocket_server", .module = server_mod }, .{ .name = "http", .module = http.module("http") }, }, }); const fuzz_filter = b.option( []const u8, "fuzz-filter", "Fuzz or test only the targets whose name contains this", ); const fuzz_tests = b.addTest(.{ .root_module = fuzz_mod, .filters = if (fuzz_filter) |f| &.{f} else &.{}, // LLVM rather than the self-hosted backend Debug uses by default, // which emits no coverage instrumentation: under it `--fuzz` has no // program counters to steer by and ends with "pcs_len was zero". .use_llvm = true, }); test_step.dependOn(&b.addRunArtifact(fuzz_tests).step);
const fuzz_step = b.step("fuzz", "The fuzz targets: add --fuzz to fuzz them"); fuzz_step.dependOn(&b.addRunArtifact(fuzz_tests).step);
// The loop that drives those same targets without Zig's fuzzer: seeded // and bounded, from an ordinary executable, which is what CI wants and // what reproduces a run exactly. const fuzz_run = b.addExecutable(.{ .name = "zig-websocket-fuzz", .root_module = b.createModule(.{ .root_source_file = b.path("tools/fuzz.zig"), .target = b.graph.host, .optimize = .ReleaseSafe, .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);
const check_step = b.step("check", "Compile everything without running it"); check_step.dependOn(&fuzz_run.step);
// -- documentation -------------------------------------------------------
const library = b.addLibrary(.{ .name = "websocket", .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);
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 the machine running the build, never whatever -Dtarget // the library is being built for. .target = b.graph.host, .optimize = .Debug, // It serves the documentation using zig-http, which is the // smallest honest test of the dependency: reading these docs // exercises the library they are about. .imports = &.{ .{ .name = "http", .module = http.module("http") }, .{ .name = "http_io", .module = http.module("http_io") }, }, }), }); const run_docs_server = b.addRunArtifact(docs_server); run_docs_server.addDirectoryArg(library.getEmittedDocs()); run_docs_server.addArg(b.fmt("{d}", .{docs_port})); // It 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);
test_step.dependOn(&b.addRunArtifact( b.addTest(.{ .root_module = docs_server.root_module }), ).step); check_step.dependOn(&docs_server.step);}