531b8767

feat: webhub Hub — runtime wall, stable tile ids, checkout/release

a73x 2026-08-18 17:58

Commit message

feat: webhub Hub — runtime wall, stable tile ids, checkout/release

build.zig

Old		New
@@ -239,7 +239,7 @@ const mod_table = [_]ModSpec{
239	// The muxweb hub's HTTP/WebSocket decisions: Origin gate, route	239	// The muxweb hub's HTTP/WebSocket decisions: Origin gate, route
240	// table, WS endpoint naming. Assets are injected (the exe root	240	// table, WS endpoint naming. Assets are injected (the exe root
241	// @embedFiles them), so its tests build no artifacts.	241	// @embedFiles them), so its tests build no artifacts.
242	.{ .name = "webhub", .path = "src/webhub.zig", .layer = 3, .imports = &.{ "protocol", "client" }, .quic_tests = true },	242	.{ .name = "webhub", .path = "src/webhub.zig", .layer = 3, .imports = &.{ "protocol", "client", "wall", "handoff", "xdg" }, .quic_tests = true },
243	// sockpath is the sun_path bound only; the client binds no socket itself.	243	// sockpath is the sun_path bound only; the client binds no socket itself.
244	// protocol is the session-name validator alone (validSessionName): a bad	244	// protocol is the session-name validator alone (validSessionName): a bad
245	// --session has to be a usage error here, at parse, not bytes some	245	// --session has to be a usage error here, at parse, not bytes some

src/webhub.zig

@@ @@ -12,6 +12,9 @@ @@
+const std = @import("std");
+const proto = @import("protocol");
+const client = @import("client");
+const wall = @import("wall");
+const handoff = @import("handoff");
+const xdg = @import("xdg");
+pub const default_port: u16 = 7681;
+    return false;
+/// `/ws/<id>` → the tile id, or null when the path is not ours or the id
+/// does not parse. Deliberately no range opinion: ids are hub-assigned and
+/// go sparse the moment a tile is removed, so "is this id live" is a
+/// question only the Hub's map can answer, under its mutex.
+pub fn wsTileId(path: []const u8) ?u32 {
+    const prefix = "/ws/";
+    if (!std.mem.startsWith(u8, path, prefix)) return null;
+    return std.fmt.parseInt(u32, path[prefix.len..], 10) catch null;
+/// One runtime tile. Owns an arena holding its resolved target and label
+/// strings; the arena dies with the tile, which is why pumps must
+/// checkout a COPY rather than borrow.
+const HubTile = struct {
+    id: u32,
+    arena: std.heap.ArenaAllocator,
+    target: client.Target,
+    label: []const u8,
+    session: []const u8,
+    /// Registered while a pump owns a WS for this tile. removeTile uses
+    /// it to shutdown(2) the socket, which unblocks the pump's reads;
+    /// the pump unregisters (under the hub mutex) BEFORE serveConn
+    /// closes the fd, so a shutdown can never hit a recycled fd.
+    ws_fd: ?std.posix.fd_t = null,
+};
+/// What a spelling can fail to become. `MissingKey` is a `quic://` entry
+/// with no key to prove itself with; `PersistFailed` is a mutation the
+/// wall file did not accept.
+pub const AddError = wall.ParseError || error{ MissingKey, OutOfMemory, PersistFailed };
+/// Spelling → client.Target. The same resolution argv gets at startup,
+/// so a tile added at runtime means exactly what one typed on the command
+/// line means. Allocates into `arena` (the tile's own).
+fn resolveTile(
+    arena: std.mem.Allocator,
+    spelling: []const u8,
+    key: ?[]const u8,
+    idle_ms: u32,
+) (wall.ParseError || error{ MissingKey, OutOfMemory })!struct {
+    target: client.Target,
+    label: []const u8,
+    session: []const u8,
+} {
+    const p = try wall.parseSpelling(spelling);
+    // The label is the user's spelling verbatim, `#NAME` included — the
+    // page shows what was typed, not a rebuilt approximation of it.
+    const label = try arena.dupe(u8, spelling);
+    const session = try arena.dupe(u8, p.session);
+    const target: client.Target = switch (p.spec) {
+        .sock => |path| .{ .sock = try arena.dupe(u8, path) },
+        .host => |h| blk: {
+            const hd = try arena.dupe(u8, h);
+            const r = try handoff.recipeFor(arena, hd);
+            break :blk .{ .hand = .{
+                .host = hd,
+                .ssh_cmd = r.ssh_cmd,
+                .cache_path = r.cache_path,
+                .idle_ms = idle_ms,
+            } };
+        },
+        .quic => |hp| blk: {
+            const key_path = switch (xdg.resolveKeyPath(arena, key) catch |err| switch (err) {
+                // No HOME is no default key path, which is the same
+                // outcome for this caller as a default that isn't there:
+                // nothing to authenticate the dial with.
+                error.NoHome => return error.MissingKey,
+                else => |e| return e,
+            }) {
+                // `.given` borrows from argv/env, which outlives nothing
+                // in particular from the tile's point of view.
+                .given => |kp| try arena.dupe(u8, kp),
+                .default => |kp| kp,
+                .missing => return error.MissingKey,
+            };
+            break :blk .{ .quic = .{
+                .host_port = try arena.dupe(u8, hp),
+                .key_path = key_path,
+                .idle_ms = idle_ms,
+            } };
+        },
+    };
+    return .{ .target = target, .label = label, .session = session };
+}
+/// Every string field copied into `arena`, every scalar by value: what a
+/// pump holds must outlive the tile it came from, and a field left out
+/// would arrive as its default — a handshake budget quietly shortened by
+/// a copy nobody suspected.
+///
+/// Field by field, with the shapes pinned below, because most of these
+/// fields HAVE defaults: a new one added to client.zig would compile here
+/// in silence and be wrong at runtime. The counts make that a build error.
+fn copyTarget(arena: std.mem.Allocator, t: client.Target) !client.Target {
+    comptime {
+        std.debug.assert(@typeInfo(client.Target).@"union".fields.len == 4);
+        std.debug.assert(@typeInfo(client.QuicTarget).@"struct".fields.len == 4);
+        std.debug.assert(@typeInfo(client.HandoffTarget).@"struct".fields.len == 6);
+    }
+    return switch (t) {
+        .sock => |s| .{ .sock = try arena.dupe(u8, s) },
+        .via => |s| .{ .via = try arena.dupe(u8, s) },
+        .quic => |q| .{ .quic = .{
+            .host_port = try arena.dupe(u8, q.host_port),
+            .key_path = try arena.dupe(u8, q.key_path),
+            .idle_ms = q.idle_ms,
+            .deadline_ms = q.deadline_ms,
+        } },
+        .hand => |h| .{ .hand = .{
+            .host = try arena.dupe(u8, h.host),
+            .ssh_cmd = try arena.dupe(u8, h.ssh_cmd),
+            .cache_path = if (h.cache_path) |c| try arena.dupe(u8, c) else null,
+            .deadline_ms = h.deadline_ms,
+            .idle_ms = h.idle_ms,
+            .report_fallback = h.report_fallback,
+        } },
+    };
+}
+/// The wall at runtime: the persisted spellings, their resolved targets,
+/// and the ids the browser names them by.
+///
+/// Ids are handed out once and never reused, because the browser holds
+/// them across a mutation it did not make: an index would silently
+/// re-point a `/ws/<n>` at a different machine the moment another device
+/// removed a tile. The wall file stays index-ordered — order is the whole
+/// content of a wall — so `tiles` is kept parallel to `wall_state.targets`
+/// and the id lives only here.
+pub const Hub = struct {
+    alloc: std.mem.Allocator,
+    /// One lock for the whole hub. Mutations are rare (a human clicking)
+    /// and every one of them touches wall, tiles and the file together;
+    /// finer locking would buy nothing and cost an invariant.
+    mutex: std.Thread.Mutex = .{},
+    tiles: std.ArrayList(HubTile) = .empty,
+    wall_state: wall.Wall,
+    next_id: u32 = 0,
+    /// null = don't persist (tests). Persist failures on a mutation are
+    /// PersistFailed, not silence: a wall the user thinks is saved and
+    /// isn't would be the worst kind of quiet.
+    state_path: ?[]const u8,
+    key: ?[]const u8,
+    idle_ms: u32,
+    /// Takes ownership of `w` — resolved or not, `deinit` frees it.
+    pub fn init(
+        alloc: std.mem.Allocator,
+        w: wall.Wall,
+        state_path: ?[]const u8,
+        key: ?[]const u8,
+        idle_ms: u32,
+    ) !Hub {
+        var self = Hub{
+            .alloc = alloc,
+            .wall_state = w,
+            .state_path = state_path,
+            .key = key,
+            .idle_ms = idle_ms,
+        };
+        errdefer self.deinit();
+        for (self.wall_state.targets.items) |spelling| {
+            const tile = try self.makeTile(spelling);
+            errdefer {
+                var a = tile.arena;
+                a.deinit();
+            }
+            try self.tiles.append(alloc, tile);
+        }
+        return self;
+    }
+    pub fn deinit(self: *Hub) void {
+        for (self.tiles.items) |*t| t.arena.deinit();
+        self.tiles.deinit(self.alloc);
+        self.wall_state.deinit(self.alloc);
+    }
+    /// Resolve one spelling into a tile with its own arena. Takes no lock
+    /// itself: mutating callers hold the mutex, and init runs before the
+    /// Hub is reachable from any other thread.
+    fn makeTile(self: *Hub, spelling: []const u8) !HubTile {
+        var arena = std.heap.ArenaAllocator.init(self.alloc);
+        errdefer arena.deinit();
+        const r = try resolveTile(arena.allocator(), spelling, self.key, self.idle_ms);
+        const id = self.next_id;
+        self.next_id += 1;
+        return .{
+            .id = id,
+            .arena = arena,
+            .target = r.target,
+            .label = r.label,
+            .session = r.session,
+        };
+    }
+    /// Caller holds the mutex.
+    fn indexOf(self: *Hub, id: u32) ?usize {
+        for (self.tiles.items, 0..) |t, i| if (t.id == id) return i;
+        return null;
+    }
+    /// Caller holds the mutex. A wall we cannot write is a mutation the
+    /// user must be told did not stick.
+    fn persist(self: *Hub) error{PersistFailed}!void {
+        const path = self.state_path orelse return;
+        wall.save(&self.wall_state, path) catch return error.PersistFailed;
+    }
+    pub fn addTile(self: *Hub, spelling: []const u8) AddError!u32 {
+        self.mutex.lock();
+        defer self.mutex.unlock();
+        const idx = try self.wall_state.add(self.alloc, spelling);
+        errdefer self.wall_state.remove(self.alloc, idx);
+        var tile = try self.makeTile(spelling);
+        errdefer tile.arena.deinit();
+        try self.tiles.append(self.alloc, tile);
+        errdefer _ = self.tiles.pop();
+        try self.persist();
+        return tile.id;
+    }
+    /// False for an id that is already gone — a second device removing
+    /// the same tile is a race, not an error.
+    pub fn removeTile(self: *Hub, id: u32) bool {
+        self.mutex.lock();
+        defer self.mutex.unlock();
+        const idx = self.indexOf(id) orelse return false;
+        var tile = self.tiles.orderedRemove(idx);
+        // Wake the pump before freeing anything it might still be reading
+        // for: shutdown unblocks its recv, and it unregisters the fd
+        // itself. Its target is a copy in its own arena, so the arena
+        // dying here cannot pull the ground from under it.
+        // The raw syscall, ignoring errno: std.posix.shutdown calls BADF
+        // and NOTSOCK unreachable, and neither is a reason to abort a
+        // removal — a registered fd whose pump is already unwinding is
+        // exactly the race this wakes up, and it has nothing left to say.
+        if (tile.ws_fd) |fd| _ = std.os.linux.shutdown(fd, std.os.linux.SHUT.RDWR);
+        tile.arena.deinit();
+        // Same index, by construction: tiles is parallel to the wall.
+        self.wall_state.remove(self.alloc, idx);
+        // A bool cannot carry PersistFailed. Say it on stderr rather than
+        // swallow it — the tile IS gone from this hub either way, and a
+        // wall file that disagrees is exactly what the user needs told.
+        self.persist() catch std.debug.print(
+            "muxweb: wall not saved after removing tile {d}\n",
+            .{id},
+        );
+        return true;
+    }
+    /// `ids` must name every live tile exactly once — a browser working
+    /// from a view that has since changed gets Stale and refetches rather
+    /// than imposing an order built around a tile that no longer exists.
+    pub fn reorderTiles(self: *Hub, ids: []const u32) error{ Stale, OutOfMemory, PersistFailed }!void {
+        self.mutex.lock();
+        defer self.mutex.unlock();
+        const n = self.tiles.items.len;
+        if (ids.len != n) return error.Stale;
+        const order = try self.alloc.alloc(usize, n);
+        defer self.alloc.free(order);
+        var seen = try self.alloc.alloc(bool, n);
+        defer self.alloc.free(seen);
+        @memset(seen, false);
+        for (ids, 0..) |id, dst| {
+            const src = self.indexOf(id) orelse return error.Stale;
+            if (seen[src]) return error.Stale;
+            seen[src] = true;
+            order[dst] = src;
+        }
+        const old = try self.alloc.dupe(HubTile, self.tiles.items);
+        defer self.alloc.free(old);
+        // The wall goes first: it is the one that can refuse, and it
+        // refuses only on a permutation we have already proven good.
+        self.wall_state.reorder(self.alloc, order) catch |err| switch (err) {
+            error.BadOrder => return error.Stale,
+            error.OutOfMemory => return error.OutOfMemory,
+        };
+        for (order, 0..) |src, dst| self.tiles.items[dst] = old[src];
+        // A failed save leaves the new order live and the file behind it:
+        // the hub is the running truth, and the next successful mutation
+        // writes the whole wall anyway. The caller is told, which is the
+        // part that matters. (addTile differs — there the rollback costs
+        // nothing and a POST that errors is cleaner having changed
+        // nothing at all.)
+        try self.persist();
+    }
+    /// The pump's copy of the target, in the pump's own arena, plus the
+    /// fd registration that lets removeTile reach it. Null when the id is
+    /// gone — a browser can always dial a tile another device just removed.
+    pub fn checkoutTarget(
+        self: *Hub,
+        id: u32,
+        ws_fd: std.posix.fd_t,
+        arena: std.mem.Allocator,
+    ) ?client.Target {
+        self.mutex.lock();
+        defer self.mutex.unlock();
+        const idx = self.indexOf(id) orelse return null;
+        // Copy first: a failed copy must not leave an fd registered for a
+        // pump that never starts.
+        const copy = copyTarget(arena, self.tiles.items[idx].target) catch return null;
+        // FIRST registration wins: two browsers on one wall run two pumps
+        // per tile, and overwriting would leave removeTile able to wake
+        // only the last one — worse, the untracked pump's release would
+        // then clear the tracked one's fd and removeTile would wake
+        // nobody. The second pump still runs and still serves its browser;
+        // it is simply not the shutdown-tracked one, and its own WS read
+        // ends it when the browser goes away. Best-effort single-fd
+        // tracking — a full fd list per tile is deliberately deferred
+        // until two-browser removal latency is shown to matter.
+        if (self.tiles.items[idx].ws_fd == null) self.tiles.items[idx].ws_fd = ws_fd;
+        return copy;
+    }
+    /// Unregister, but only the fd this caller registered: a second pump
+    /// releasing must not clear the tracked pump's registration. Must run
+    /// BEFORE the caller closes the fd, or a concurrent removeTile could
+    /// shutdown a number the kernel has already handed to somebody else.
+    pub fn releaseTile(self: *Hub, id: u32, ws_fd: std.posix.fd_t) void {
+        self.mutex.lock();
+        defer self.mutex.unlock();
+        const idx = self.indexOf(id) orelse return;
+        if (self.tiles.items[idx].ws_fd) |fd| {
+            if (fd == ws_fd) self.tiles.items[idx].ws_fd = null;
+        }
+    }
+    /// The tile list the page renders and attaches by, in wall order.
+    pub fn json(self: *Hub, alloc: std.mem.Allocator) ![]u8 {
+        self.mutex.lock();
+        defer self.mutex.unlock();
+        var out: std.ArrayList(u8) = .empty;
+        errdefer out.deinit(alloc);
+        try out.append(alloc, '[');
+        for (self.tiles.items, 0..) |t, i| {
+            if (i > 0) try out.append(alloc, ',');
+            try out.print(alloc, "{{\"id\":{d},\"label\":", .{t.id});
+            // The same escape road tilesJson uses: a label is the user's
+            // spelling, which is theirs to make unparseable.
+            try appendJsonString(alloc, &out, t.label);
+            try out.appendSlice(alloc, ",\"session\":");
+            try appendJsonString(alloc, &out, t.session);
+            try out.append(alloc, '}');
+        }
+        try out.append(alloc, ']');
+        return out.toOwnedSlice(alloc);
+    }
+};
+/// The embedded page, injected by the exe root (webhub_main @embedFiles
+/// them; tests inject fakes).
+pub const Assets = struct {
@@ @@ -575,7 +922,14 @@ pub fn serveConn( @@
+        var req = server.receiveHead() catch return;
+        const path = req.head.target;
+        // The argv-driven flow still names tiles by index, and here id ==
+        // index because nothing removes a tile; the range check that used
+        // to live in the path parser lives here until the Hub owns this.
+        const wanted: ?usize = if (wsTileId(path)) |id|
+            (if (id < targets.len) @as(usize, id) else null)
+        else
+            null;
+        if (wanted) |idx| {
+            // Origin BEFORE upgrade, always: the refusal must happen while
+            // this is still HTTP, so a hostile page gets a 403 and never a
+            // socket. std's upgradeRequested does not look at Origin.
+test "ws path by id: parses, no range opinion" {
+    try std.testing.expectEqual(@as(?u32, 0), wsTileId("/ws/0"));
+    try std.testing.expectEqual(@as(?u32, 41), wsTileId("/ws/41"));
+    try std.testing.expectEqual(@as(?u32, null), wsTileId("/ws/"));
+    try std.testing.expectEqual(@as(?u32, null), wsTileId("/ws/x"));
+    try std.testing.expectEqual(@as(?u32, null), wsTileId("/ws/-1"));
+    try std.testing.expectEqual(@as(?u32, null), wsTileId("/wsx/0"));
+}
+test "hub: ids are stable across remove and reorder; json is wall order" {
+    const alloc = std.testing.allocator;
+    var w = wall.Wall{};
+    _ = try w.add(alloc, "--sock /tmp/a");
+    _ = try w.add(alloc, "--sock /tmp/b#s");
+    var hub = try Hub.init(alloc, w, null, null, client.quic_idle_ms_default);
+    defer hub.deinit();
+    const j0 = try hub.json(alloc);
+    defer alloc.free(j0);
+    try std.testing.expectEqualStrings(
+        \\[{"id":0,"label":"--sock /tmp/a","session":""},{"id":1,"label":"--sock /tmp/b#s","session":"s"}]
+    , j0);
+    const id2 = try hub.addTile("--sock /tmp/c");
+    try std.testing.expectEqual(@as(u32, 2), id2);
+    try std.testing.expect(hub.removeTile(1));
+    try std.testing.expect(!hub.removeTile(1)); // already gone
+    try hub.reorderTiles(&.{ 2, 0 });
+    try std.testing.expectError(error.Stale, hub.reorderTiles(&.{ 0, 1 })); // 1 is gone: stale view
+    const j1 = try hub.json(alloc);
+    defer alloc.free(j1);
+    try std.testing.expectEqualStrings(
+        \\[{"id":2,"label":"--sock /tmp/c","session":""},{"id":0,"label":"--sock /tmp/a","session":""}]
+    , j1);
+}
+test "hub: checkout copies the target into the caller's arena; release unregisters" {
+    const alloc = std.testing.allocator;
+    var w = wall.Wall{};
+    _ = try w.add(alloc, "--sock /tmp/a");
+    var hub = try Hub.init(alloc, w, null, null, client.quic_idle_ms_default);
+    defer hub.deinit();
+    var arena = std.heap.ArenaAllocator.init(alloc);
+    defer arena.deinit();
+    const t = hub.checkoutTarget(0, 7, arena.allocator()).?;
+    // The copy must survive the tile's death: remove frees the tile's own
+    // arena, and the pump's strings must not be in it.
+    try std.testing.expect(hub.removeTile(0));
+    try std.testing.expectEqualStrings("/tmp/a", t.sock);
+    hub.releaseTile(0, 7); // gone id: a no-op, not a crash
+    try std.testing.expectEqual(@as(?client.Target, null), hub.checkoutTarget(0, 7, arena.allocator()));
+}
+test "hub: two pumps on one tile — the first fd stays tracked, the second's release spares it" {
+    const alloc = std.testing.allocator;
+    var w = wall.Wall{};
+    _ = try w.add(alloc, "--sock /tmp/a");
+    var hub = try Hub.init(alloc, w, null, null, client.quic_idle_ms_default);
+    defer hub.deinit();
+    var arena = std.heap.ArenaAllocator.init(alloc);
+    defer arena.deinit();
+    // Two browsers on one wall: both pumps get a target and both serve.
+    const first = hub.checkoutTarget(0, 7, arena.allocator()).?;
+    const second = hub.checkoutTarget(0, 8, arena.allocator()).?;
+    try std.testing.expectEqualStrings("/tmp/a", first.sock);
+    try std.testing.expectEqualStrings("/tmp/a", second.sock);
+    // The first registration is the tracked one, and the untracked pump's
+    // release must leave it alone — clearing it would leave removeTile
+    // with nobody to wake.
+    try std.testing.expectEqual(@as(?std.posix.fd_t, 7), hub.tiles.items[0].ws_fd);
+    hub.releaseTile(0, 8);
+    try std.testing.expectEqual(@as(?std.posix.fd_t, 7), hub.tiles.items[0].ws_fd);
+    hub.releaseTile(0, 7);
+    try std.testing.expectEqual(@as(?std.posix.fd_t, null), hub.tiles.items[0].ws_fd);
+}
+test "hub: addTile persists; a reloaded wall matches" {
+    const alloc = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const dir_path = try tmp.dir.realpathAlloc(alloc, ".");
+    defer alloc.free(dir_path);
+    const path = try std.fmt.allocPrint(alloc, "{s}/wall", .{dir_path});
+    defer alloc.free(path);
+    {
+        var hub = try Hub.init(alloc, wall.Wall{}, path, null, client.quic_idle_ms_default);
+        defer hub.deinit();
+        _ = try hub.addTile("--sock /tmp/a");
+        _ = try hub.addTile("--sock /tmp/b");
+        _ = try hub.addTile("--sock /tmp/c");
+        try std.testing.expect(hub.removeTile(1));
+        try hub.reorderTiles(&.{ 2, 0 });
+    }
+    var r = try wall.load(alloc, path);
+    defer r.deinit(alloc);
+    try std.testing.expectEqual(@as(usize, 2), r.targets.items.len);
+    try std.testing.expectEqualStrings("--sock /tmp/c", r.targets.items[0]);
+    try std.testing.expectEqualStrings("--sock /tmp/a", r.targets.items[1]);
+test "routes: the three assets with their content types, 404 for the rest" {