b4020e15

feat: serve gives bind and the guarded unlink one owner

a73x 2026-08-31 21:58

Commit message

feat: serve gives bind and the guarded unlink one owner

Three binders answered the same trio independently — the daemon socket,
the per-session agent sockets, askpass's prompt socket — and only the
daemon's carried the stillAt-guarded unlink that sockpath's PathId record
paid for. `serve.bind` takes the policy (refuse a live owner, or clobber a
name that embeds our own identity) and `Bound.close` carries the guard, so
the other two gain it by conversion rather than by three edits.

cloexec defaults FALSE on purpose: `mux d upgrade` execs the candidate over
the running daemon, and the listener and every agent socket must survive
that exec.

Accept loops stay with their callers: the daemon's slot table, askpass's
credential check and the hub's thread-per-conn differ for reasons.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TWxBL1HBULH1ZwTNzzKTja

build.zig

Old		New
@@ -149,6 +149,11 @@ const mod_table = [_]ModSpec{
149	// claim and the dev+ino record teardown compares against. A leaf — it	149	// claim and the dev+ino record teardown compares against. A leaf — it
150	// takes a path and nothing else, and knows no Server exists.	150	// takes a path and nothing else, and knows no Server exists.
151	.{ .name = "sockpath", .path = "src/sockpath.zig", .test_imports = &.{"testtmp"} },	151	.{ .name = "sockpath", .path = "src/sockpath.zig", .test_imports = &.{"testtmp"} },
		152	// The bind-and-unlink half of owning a socket path, above sockpath and
		153	// below every binder: the daemon socket, the per-session agent sockets
		154	// and askpass's prompt socket all take their listener from here, so the
		155	// guarded unlink is written once instead of three times.
		156	.{ .name = "serve", .path = "src/serve.zig", .imports = &.{"sockpath"}, .test_imports = &.{"testtmp"} },
152	// No imports that teach it anything, deliberately: the proxy is a byte	157	// No imports that teach it anything, deliberately: the proxy is a byte
153	// pump that knows nothing about the protocol it carries. `testtmp` is	158	// pump that knows nothing about the protocol it carries. `testtmp` is
154	// the one exception and does not weaken that — it hands its tests a	159	// the one exception and does not weaken that — it hands its tests a
@@ -723,8 +728,8 @@ fn docGate(b: std.Build, target: std.Build.ResolvedTarget, check_step: std.Bui
723	const test_order = [_][]const u8{	728	const test_order = [_][]const u8{
724	"script", "cliflags", "testtmp", "spawn", "dial", "link",	729	"script", "cliflags", "testtmp", "spawn", "dial", "link",
725	"quic", "webhub", "agent", "term", "rawmode", "delaypipe",	730	"quic", "webhub", "agent", "term", "rawmode", "delaypipe",
726	"render", "wsclient", "ptyclient", "pty", "sockpath", "xdg",	731	"render", "wsclient", "ptyclient", "pty", "sockpath", "serve",
727	"proxy", "wall", "client", "daemon", "mux",	732	"xdg", "proxy", "wall", "client", "daemon", "mux",
728	};	733	};
729		734
730	comptime {	735	comptime {

src/serve.zig

@@ @@ -0,0 +1,197 @@ @@
+//! The server side of a unix socket path: the right to bind it and the duty
+//! to unlink it, written once. Three binders used to answer this trio
+//! independently — the daemon socket, the per-session agent sockets, the
+//! askpass socket — and only the first carried the guarded unlink that
+//! sockpath's incident record paid for. Accept loops are NOT here: the
+//! daemon's slot-table accept, askpass's credential check and the hub's
+//! thread-per-conn differ for reasons, and a shared loop would be a shape
+//! they do not fit.
+const std = @import("std");
+const sockpath = @import("sockpath");
+pub const Policy = enum {
+    /// Never steal a path that answers: sockpath.claim's refusal, the
+    /// daemon-socket rule.
+    refuse_live,
+    /// The name embeds our identity (a pid, a session name in our own
+    /// directory), so a leftover file there is ours — a previous us that
+    /// died without unlinking — and is deleted before the bind.
+    clobber_own,
+};
+pub const BindOpts = struct {
+    policy: Policy,
+    backlog: u31 = 128,
+    /// TRUE by default, which is what `std.net.Address.listen` did for every
+    /// binder before this module existed, and the flag is load-bearing for
+    /// the reason it always was: the daemon forks a shell per session, and a
+    /// listener leaked into one is a socket that shell could serve.
+    ///
+    /// It does NOT conflict with `mux d upgrade` execing the candidate over
+    /// the running daemon. That path clears the flag explicitly on the
+    /// listener, every pty master and every agent socket right before the
+    /// exec (`Server.execUpgrade`) and `sealAdoptedFds` puts it back on the
+    /// far side — so the fds that must cross say so at the exec, one by one,
+    /// rather than by standing permanently open to every forked shell.
+    cloexec: bool = true,
+};
+pub const Bound = struct {
+    fd: std.posix.fd_t,
+    path_id: sockpath.PathId,
+    /// Close, then unlink only if the path still names OUR socket: a newer
+    /// owner may have replaced the file, and deleting that one would steal
+    /// its clients. The stat comes after the close because a successor only
+    /// claims once nothing is listening — that narrows the race to the
+    /// stat→unlink gap, the floor Linux gives for deleting by name.
+    pub fn close(self: *Bound, path: []const u8) void {
+        if (self.fd == -1) return;
+        std.posix.close(self.fd);
+        self.fd = -1;
+        self.unlinkIfOurs(path);
+    }
+    /// The guard without the close, for the one caller that must not close:
+    /// askpass's `retire` runs on a process about to `std.posix.exit` with
+    /// detached pumps still live, one of which may be inside `declined` on
+    /// that Listener. The name has to leave the filesystem there; the
+    /// descriptor may not.
+    pub fn unlinkIfOurs(self: *const Bound, path: []const u8) void {
+        if (self.path_id.stillAt(path)) {
+            std.fs.cwd().deleteFile(path) catch {};
+        }
+    }
+};
+/// Bind, listen, and remember which inode is ours. Overlong paths are
+/// initUnix's refusal (kernel truth, not a re-stated bound) — `mux d`'s
+/// parse-time `sockpath.tooLong` with its own stderr wording remains the
+/// one binder-side pre-check, and it lives with `mux d`.
+pub fn bind(path: []const u8, opts: BindOpts) !Bound {
+    switch (opts.policy) {
+        .refuse_live => try sockpath.claim(path),
+        .clobber_own => std.fs.cwd().deleteFile(path) catch {},
+    }
+    const addr = try std.net.Address.initUnix(path);
+    const sock_flags: u32 = std.posix.SOCK.STREAM |
+        (if (opts.cloexec) @as(u32, std.posix.SOCK.CLOEXEC) else 0);
+    const fd = try std.posix.socket(std.posix.AF.UNIX, sock_flags, 0);
+    errdefer std.posix.close(fd);
+    try std.posix.bind(fd, &addr.any, addr.getOsSockLen());
+    try std.posix.listen(fd, opts.backlog);
+    return .{ .fd = fd, .path_id = try sockpath.PathId.of(path) };
+}
+/// A listener that already exists — the upgrade manifest's adopted fd. The
+/// PathId is re-stamped from the file as found, which is the manifest rule:
+/// a watermark belongs to the space that minted it.
+pub fn adopt(fd: std.posix.fd_t, path: []const u8) !Bound {
+    return .{ .fd = fd, .path_id = try sockpath.PathId.of(path) };
+}
+const TmpDir = @import("testtmp").TmpDir;
+const testing = std.testing;
+test "refuse_live refuses a path a live listener owns; clobber_own takes its own leftover" {
+    var tmp = try TmpDir.make();
+    defer tmp.cleanup();
+    var buf: [280]u8 = undefined;
+    const path = try std.fmt.bufPrint(&buf, "{s}/serve.sock", .{tmp.path()});
+    var first = try bind(path, .{ .policy = .refuse_live });
+    // sockpath.claim's own word for "something answers here": the refusal is
+    // the daemon-socket rule, so the error stays claim's rather than being
+    // re-spelled as a socket error this module invented.
+    try testing.expectError(error.DaemonAlreadyRunning, bind(path, .{ .policy = .refuse_live }));
+    // Kill the listener but leave the file: the dead-us case.
+    std.posix.close(first.fd);
+    first.fd = -1;
+    var second = try bind(path, .{ .policy = .clobber_own });
+    second.close(path);
+}
+test "close unlinks our socket but never a successor's" {
+    var tmp = try TmpDir.make();
+    defer tmp.cleanup();
+    var buf: [280]u8 = undefined;
+    const path = try std.fmt.bufPrint(&buf, "{s}/succ.sock", .{tmp.path()});
+    var old = try bind(path, .{ .policy = .clobber_own });
+    // A successor replaces the FILE while old's listener lives on — deleting
+    // a unix socket's path does not touch the listening fd, which is the
+    // incident shape sockpath.zig's PathId records: two owners, one name, and
+    // the displaced one's teardown must not delete by that name.
+    var succ = try bind(path, .{ .policy = .clobber_own });
+    old.close(path); // guard fires: the inode at path is succ's — no unlink
+    _ = try std.fs.cwd().statFile(path); // successor's file survived
+    succ.close(path); // ours: unlinked
+    try testing.expectError(error.FileNotFound, std.fs.cwd().statFile(path));
+}
+test "unlinkIfOurs takes the name without the descriptor, and spares a successor's" {
+    var tmp = try TmpDir.make();
+    defer tmp.cleanup();
+    var buf: [280]u8 = undefined;
+    const path = try std.fmt.bufPrint(&buf, "{s}/retire.sock", .{tmp.path()});
+    // askpass's retire shape: the name goes, the fd stays open for the
+    // detached pumps that may still be reading this object.
+    var one = try bind(path, .{ .policy = .clobber_own });
+    one.unlinkIfOurs(path);
+    try testing.expectError(error.FileNotFound, std.fs.cwd().statFile(path));
+    try testing.expect(one.fd != -1);
+    std.posix.close(one.fd);
+    var old = try bind(path, .{ .policy = .clobber_own });
+    var succ = try bind(path, .{ .policy = .clobber_own });
+    old.unlinkIfOurs(path);
+    _ = try std.fs.cwd().statFile(path);
+    std.posix.close(old.fd);
+    succ.close(path);
+}
+test "adopt re-stamps the id of the file as found, and close then unlinks it" {
+    var tmp = try TmpDir.make();
+    defer tmp.cleanup();
+    var buf: [280]u8 = undefined;
+    const path = try std.fmt.bufPrint(&buf, "{s}/adopt.sock", .{tmp.path()});
+    // The upgrade shape: a listener fd crosses the exec, and nothing
+    // re-claims or re-binds — claim's probe would find our own listener
+    // answering and refuse the daemon its own socket.
+    const first = try bind(path, .{ .policy = .refuse_live });
+    var after = try adopt(first.fd, path);
+    try testing.expectEqual(first.path_id, after.path_id);
+    after.close(path);
+    try testing.expectError(error.FileNotFound, std.fs.cwd().statFile(path));
+}
+test "cloexec is on by default and off only when asked" {
+    var tmp = try TmpDir.make();
+    defer tmp.cleanup();
+    var buf: [280]u8 = undefined;
+    const path = try std.fmt.bufPrint(&buf, "{s}/flag.sock", .{tmp.path()});
+    // Asked of the descriptor, not read off the call that made it: every
+    // binder here is in a process that forks shells, and the default going
+    // quietly false would hand each of them a listening socket. That is
+    // exactly how it broke once — `std.net.Address.listen` set the flag
+    // unconditionally, so a bind() written without it was a silent leak.
+    var on = try bind(path, .{ .policy = .clobber_own });
+    try testing.expect(try std.posix.fcntl(on.fd, std.posix.F.GETFD, 0) & std.posix.FD_CLOEXEC != 0);
+    on.close(path);
+    var off = try bind(path, .{ .policy = .clobber_own, .cloexec = false });
+    try testing.expect(try std.posix.fcntl(off.fd, std.posix.F.GETFD, 0) & std.posix.FD_CLOEXEC == 0);
+    off.close(path);
+}
+// 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());
+}