75465356

feat: wall.zig — spelling grammar, wall model, atomic persistence

a73x 2026-08-18 17:58

Commit message

feat: wall.zig — spelling grammar, wall model, atomic persistence

build.zig

src/wall.zig

@@ @@ -0,0 +1,275 @@ @@
+//! The wall: an ordered list of TARGET spellings, shared by muxweb today
+//! and the mux CLI later — one owner for the spelling grammar, the
+//! session split, and the persisted file, so the wall built in a browser
+//! is the wall the CLI sees.
+//!
+//! Spelling grammar (one string; also the line format of the state file
+//! and the body of the hub's POST /tiles):
+//!   HOST[#SESSION] | quic://HOST[:PORT][#SESSION] | --sock PATH[#SESSION]
+//! The session splits at the LAST '#' because validSessionName refuses
+//! '#', so any earlier one belongs to the target's own spelling.
+//!
+//! The file is `$XDG_STATE_HOME/mux/wall`, one spelling per line, order
+//! is wall order. Every mutation rewrites it atomically (temp + rename);
+//! two concurrent writers resolve as last-rename-wins, acceptable for a
+//! single user's state file. "Atomic" is writer-vs-writer only: `save`
+//! does not fsync the file or its directory, so a crash at the wrong
+//! moment can still leave the rename torn on some filesystems — no
+//! stronger, crash-durability claim is made here.
+const std = @import("std");
+const proto = @import("protocol");
+pub const Spec = union(enum) {
+    sock: []const u8,
+    host: []const u8,
+    quic: []const u8,
+};
+pub const Parsed = struct { spec: Spec, session: []const u8 };
+pub const ParseError = error{ BadSession, EmptySpec, BadByte };
+/// Splits and classifies one spelling. Refuses here, at usage altitude,
+/// what would otherwise surface as a rejected attach far from the typo:
+/// a malformed session name, or a spelling whose target part is empty
+/// (`#b`, `quic://`, `--sock #b`).
+///
+/// The returned slices BORROW from `line` — nothing is copied, so a
+/// caller that keeps a Parsed must keep the string it parsed.
+pub fn parseSpelling(line: []const u8) ParseError!Parsed {
+    // No control byte anywhere, checked before the split so it covers the
+    // target part too (validSessionName already refuses them after '#').
+    // A '\n' is the sharp one: the file is one spelling per line, so such
+    // a spelling would be WRITTEN as one tile and LOADED as two — the
+    // writer/loader identity, and with it the one-grammar contract, gone.
+    // Reachable from argv and from the browser's POST body, so it is
+    // refused in the grammar rather than at either mouth.
+    for (line) |c| if (c < 0x20) return error.BadByte;
+    var spec_str = line;
+    var session: []const u8 = "";
+    if (std.mem.lastIndexOfScalar(u8, line, '#')) |hash| {
+        const name = line[hash + 1 ..];
+        if (!proto.validSessionName(name)) return error.BadSession;
+        spec_str = line[0..hash];
+        session = name;
+    }
+    const sock_prefix = "--sock ";
+    const quic_prefix = "quic://";
+    if (std.mem.startsWith(u8, spec_str, sock_prefix)) {
+        const path = spec_str[sock_prefix.len..];
+        if (path.len == 0) return error.EmptySpec;
+        return .{ .spec = .{ .sock = path }, .session = session };
+    }
+    if (std.mem.startsWith(u8, spec_str, quic_prefix)) {
+        const hp = spec_str[quic_prefix.len..];
+        if (hp.len == 0) return error.EmptySpec;
+        return .{ .spec = .{ .quic = hp }, .session = session };
+    }
+    if (spec_str.len == 0) return error.EmptySpec;
+    return .{ .spec = .{ .host = spec_str }, .session = session };
+}
+pub const Wall = struct {
+    /// Owned copies, wall order. The spelling IS the label downstream.
+    targets: std.ArrayList([]u8) = .empty,
+    pub fn deinit(self: *Wall, alloc: std.mem.Allocator) void {
+        for (self.targets.items) |t| alloc.free(t);
+        self.targets.deinit(alloc);
+    }
+    /// Validates, then appends. Returns the new entry's index.
+    pub fn add(self: *Wall, alloc: std.mem.Allocator, spelling: []const u8) !usize {
+        _ = try parseSpelling(spelling);
+        const copy = try alloc.dupe(u8, spelling);
+        errdefer alloc.free(copy);
+        try self.targets.append(alloc, copy);
+        return self.targets.items.len - 1;
+    }
+    pub fn remove(self: *Wall, alloc: std.mem.Allocator, idx: usize) void {
+        alloc.free(self.targets.orderedRemove(idx));
+    }
+    /// `order` must be an exact permutation of 0..len — anything else is
+    /// the caller working from a stale view, refused so it can refetch.
+    pub fn reorder(self: *Wall, alloc: std.mem.Allocator, order: []const usize) error{ BadOrder, OutOfMemory }!void {
+        const n = self.targets.items.len;
+        if (order.len != n) return error.BadOrder;
+        var seen = try alloc.alloc(bool, n);
+        defer alloc.free(seen);
+        @memset(seen, false);
+        for (order) |i| {
+            if (i >= n or seen[i]) return error.BadOrder;
+            seen[i] = true;
+        }
+        const old = try alloc.dupe([]u8, self.targets.items);
+        defer alloc.free(old);
+        for (order, 0..) |src, dst| self.targets.items[dst] = old[src];
+    }
+};
+/// Missing file is an empty wall, not an error: first run has no state.
+/// A line that no longer parses (edited by hand) is refused loudly —
+/// error, not skip — because silently dropping a tile the user wrote
+/// down is worse than making them fix the line.
+pub fn load(alloc: std.mem.Allocator, path: []const u8) !Wall {
+    var w = Wall{};
+    errdefer w.deinit(alloc);
+    const data = std.fs.cwd().readFileAlloc(alloc, path, 1024 * 1024) catch |err| switch (err) {
+        error.FileNotFound => return w,
+        else => return err,
+    };
+    defer alloc.free(data);
+    // tokenize, not split: `save` ends every line with '\n', so a split
+    // would hand the trailing empty string to `add` and make every
+    // round-trip fail EmptySpec. Blank lines are skipped for free.
+    var it = std.mem.tokenizeScalar(u8, data, '\n');
+    while (it.next()) |line| _ = try w.add(alloc, line);
+    return w;
+}
+pub fn save(w: *const Wall, path: []const u8) !void {
+    var write_buf: [4096]u8 = undefined;
+    var af = try std.fs.cwd().atomicFile(path, .{ .make_path = true, .write_buffer = &write_buf });
+    defer af.deinit();
+    for (w.targets.items) |t| {
+        try af.file_writer.interface.writeAll(t);
+        try af.file_writer.interface.writeAll("\n");
+    }
+    try af.finish();
+}
+/// `$XDG_STATE_HOME/mux/wall`, defaulting to `~/.local/state/mux/wall`.
+/// The *From split is xdg.zig's pattern for the same reason: setenv is
+/// unsafe in-process for Zig tests.
+pub fn statePath(alloc: std.mem.Allocator) ![]const u8 {
+    return statePathFrom(alloc, std.posix.getenv("XDG_STATE_HOME"), std.posix.getenv("HOME"));
+}
+pub fn statePathFrom(
+    alloc: std.mem.Allocator,
+    xdg_state_home: ?[]const u8,
+    home: ?[]const u8,
+) ![]const u8 {
+    if (xdg_state_home) |d| if (d.len > 0)
+        return std.fmt.allocPrint(alloc, "{s}/mux/wall", .{d});
+    const h = home orelse return error.NoHome;
+    return std.fmt.allocPrint(alloc, "{s}/.local/state/mux/wall", .{h});
+}
+test "parseSpelling: three spellings classify; session splits at the LAST '#'" {
+    try std.testing.expectEqualStrings("box1", (try parseSpelling("box1")).spec.host);
+    try std.testing.expectEqualStrings("", (try parseSpelling("box1")).session);
+    try std.testing.expectEqualStrings("h:4433", (try parseSpelling("quic://h:4433#b")).spec.quic);
+    try std.testing.expectEqualStrings("b", (try parseSpelling("quic://h:4433#b")).session);
+    try std.testing.expectEqualStrings("/tmp/x", (try parseSpelling("--sock /tmp/x#b")).spec.sock);
+    // The LAST '#': earlier ones belong to the target's own spelling.
+    try std.testing.expectEqualStrings("a#b", (try parseSpelling("a#b#c")).spec.host);
+    try std.testing.expectEqualStrings("c", (try parseSpelling("a#b#c")).session);
+}
+test "parseSpelling: refusals — bad session, empty spec in every spelling" {
+    try std.testing.expectError(error.BadSession, parseSpelling("host#has space"));
+    try std.testing.expectError(error.BadSession, parseSpelling("host#")); // empty name is not typeable
+    try std.testing.expectError(error.EmptySpec, parseSpelling("#b"));
+    try std.testing.expectError(error.EmptySpec, parseSpelling("quic://"));
+    try std.testing.expectError(error.EmptySpec, parseSpelling("--sock #b"));
+    try std.testing.expectError(error.EmptySpec, parseSpelling(""));
+    // Control bytes: '\n' would break the one-spelling-per-line file in
+    // two, and there is no target spelling the rest of them belong in.
+    try std.testing.expectError(error.BadByte, parseSpelling("a\nb"));
+    try std.testing.expectError(error.BadByte, parseSpelling("a\tb"));
+    try std.testing.expectError(error.BadByte, parseSpelling("a\rb"));
+    try std.testing.expectError(error.BadByte, parseSpelling("host#s\nevil"));
+}
+test "wall: add validates, remove frees, reorder is permutation-or-refused" {
+    const alloc = std.testing.allocator;
+    var w = Wall{};
+    defer w.deinit(alloc);
+    _ = try w.add(alloc, "a");
+    _ = try w.add(alloc, "b#s");
+    _ = try w.add(alloc, "quic://c:1");
+    try std.testing.expectError(error.BadSession, w.add(alloc, "d#bad name"));
+    // The add gate is why `load` can never meet a multi-line entry: a
+    // spelling holding '\n' never reaches the file to be split by it.
+    try std.testing.expectError(error.BadByte, w.add(alloc, "d\ne"));
+    try std.testing.expectEqual(@as(usize, 3), w.targets.items.len);
+    try w.reorder(alloc, &.{ 2, 0, 1 });
+    try std.testing.expectEqualStrings("quic://c:1", w.targets.items[0]);
+    try std.testing.expectEqualStrings("a", w.targets.items[1]);
+    // Stale views are refused, not guessed at: wrong length, dup, range.
+    try std.testing.expectError(error.BadOrder, w.reorder(alloc, &.{ 0, 1 }));
+    try std.testing.expectError(error.BadOrder, w.reorder(alloc, &.{ 0, 0, 1 }));
+    try std.testing.expectError(error.BadOrder, w.reorder(alloc, &.{ 0, 1, 3 }));
+    w.remove(alloc, 1);
+    try std.testing.expectEqual(@as(usize, 2), w.targets.items.len);
+    try std.testing.expectEqualStrings("b#s", w.targets.items[1]);
+}
+test "wall: save/load round-trip; missing file loads empty; bad line refuses" {
+    const testtmp = @import("testtmp");
+    const alloc = std.testing.allocator;
+    var tmp = try testtmp.TmpDir.make();
+    defer tmp.cleanup();
+    const path = try std.fmt.allocPrint(alloc, "{s}/deep/wall", .{tmp.path()});
+    defer alloc.free(path);
+    {
+        var missing = try load(alloc, path);
+        defer missing.deinit(alloc);
+        try std.testing.expectEqual(@as(usize, 0), missing.targets.items.len);
+    }
+    {
+        var w = Wall{};
+        defer w.deinit(alloc);
+        _ = try w.add(alloc, "a#s");
+        _ = try w.add(alloc, "--sock /tmp/x");
+        try save(&w, path); // .make_path: the deep/ parent did not exist
+    }
+    {
+        var r = try load(alloc, path);
+        defer r.deinit(alloc);
+        try std.testing.expectEqual(@as(usize, 2), r.targets.items.len);
+        try std.testing.expectEqualStrings("a#s", r.targets.items[0]);
+        try std.testing.expectEqualStrings("--sock /tmp/x", r.targets.items[1]);
+    }
+    // A hand-edited line that no longer parses refuses the whole load.
+    try tmp.dir.writeFile(.{ .sub_path = "deep/wall", .data = "ok\nbad name#x y\n" });
+    try std.testing.expectError(error.BadSession, load(alloc, path));
+    // The BadByte refusal is per-LINE, so it cannot change what the
+    // tokenizer means: blank lines are still skipped, not refused.
+    try tmp.dir.writeFile(.{ .sub_path = "deep/wall", .data = "a\n\n\nb#s\n" });
+    {
+        var r = try load(alloc, path);
+        defer r.deinit(alloc);
+        try std.testing.expectEqual(@as(usize, 2), r.targets.items.len);
+        try std.testing.expectEqualStrings("b#s", r.targets.items[1]);
+    }
+}
+test "statePathFrom: XDG wins when set and non-empty, HOME default otherwise" {
+    const alloc = std.testing.allocator;
+    {
+        const p = try statePathFrom(alloc, "/xs", "/home/u");
+        defer alloc.free(p);
+        try std.testing.expectEqualStrings("/xs/mux/wall", p);
+    }
+    {
+        const p = try statePathFrom(alloc, "", "/home/u");
+        defer alloc.free(p);
+        try std.testing.expectEqualStrings("/home/u/.local/state/mux/wall", p);
+    }
+    try std.testing.expectError(error.NoHome, statePathFrom(alloc, null, null));
+}
+// Forces semantic analysis of every pub decl under `zig build test`, so an
+// unreferenced decl must at least compile (the silent-module-loss hazard,
+// decisions.md).
+test {
+    std.testing.refAllDeclsRecursive(@This());
+}

Old		New
@@ -186,6 +186,11 @@ const mod_table = [_]ModSpec{
186	// Engine plus protocol and nothing else, same shape as delta — pure,	186	// Engine plus protocol and nothing else, same shape as delta — pure,
187	// socket-free, and its own tests drive it with no daemon in sight.	187	// socket-free, and its own tests drive it with no daemon in sight.
188	.{ .name = "cmd", .path = "src/cmd.zig", .layer = 1, .imports = &.{ "engine", "protocol" } },	188	.{ .name = "cmd", .path = "src/cmd.zig", .layer = 1, .imports = &.{ "engine", "protocol" } },
		189	// The wall: the TARGET spelling grammar, the ordered list, and the
		190	// state file behind them. One owner for a grammar the hub, the state
		191	// file and later the CLI all have to agree on — protocol and nothing
		192	// else, so its tests need no hub, no daemon and no socket.
		193	.{ .name = "wall", .path = "src/wall.zig", .layer = 1, .imports = &.{"protocol"}, .test_imports = &.{"testtmp"} },
189	// Shell integration: the OSC 133 mark scripts and what a spawn must add	194	// Shell integration: the OSC 133 mark scripts and what a spawn must add
190	// to hand them to a shell. Near-leaf on purpose — it writes files and	195	// to hand them to a shell. Near-leaf on purpose — it writes files and
191	// reads the environment, and knows nothing of ptys, servers or the	196	// reads the environment, and knows nothing of ptys, servers or the
@@ -393,12 +398,12 @@ fn shellGate(b: std.Build, step: std.Build.Step) void {
393	/// escape pins. mux and exe are executable roots but carry the argument	398	/// escape pins. mux and exe are executable roots but carry the argument
394	/// parsers — a test that is never built is not a test (decisions.md).	399	/// parsers — a test that is never built is not a test (decisions.md).
395	const test_order = [_][]const u8{	400	const test_order = [_][]const u8{
396	"script", "protocol", "client_core", "engine", "pty", "delta",	401	"script", "protocol", "client_core", "engine", "pty", "delta",
397	"cmd", "shellint", "replica", "keymap", "webhub", "sockpath",	402	"cmd", "wall", "shellint", "replica", "keymap", "webhub",
398	"muxa", "server", "client", "proxy", "mux", "quic",	403	"sockpath", "muxa", "server", "client", "proxy", "mux",
399	"quic_server", "exe", "testtmp", "quic_client", "predict", "rawmode",	404	"quic", "quic_server", "exe", "testtmp", "quic_client", "predict",
400	"delaypipe", "xdg", "spawn", "handoff", "paint", "render",	405	"rawmode", "delaypipe", "xdg", "spawn", "handoff", "paint",
401	"ptyclient", "webhub_main", "wsclient",	406	"render", "ptyclient", "webhub_main", "wsclient",
402	};	407	};
403		408
404	comptime {	409	comptime {