fix: make UDS mirror cleanup ownership-aware, not path-based

[kriszyp]

What / why

An overlapping in-process worker restart (component reload, deploy, or a config change)
silently loses all of a node's per-worker Unix-domain-socket mirrors, downgrading it from
the UDS + proxy-terminated-TLS architecture back to TCP passthrough and its ~64k
per-tuple ephemeral-port ceiling — with no warning until a full process restart happens to
recreate the files.

Root cause: on Linux, restartWorkers() deliberately pre-starts and binds the replacement
worker before telling the outgoing worker to shut down (that overlap is intentional and is
not changed here). The replacement's listenOnDomainSocket() unlinks the outgoing
worker's socket file and binds a brand-new inode at the same path. When the outgoing worker
then exits and calls cleanupUdsFiles(), it unlinks purely by path — deleting the live
replacement's .sock and .yaml, since the path is byte-identical (same worker index +
port). The replacement is left listening on an unlinked inode: functional, but unreachable
through its filesystem path, and no longer advertised to the fronting proxy.

Fix: make socket-file cleanup ownership-aware instead of path-based.

• recordUdsBindSuccess() captures the (dev, ino) (as bigint, to avoid precision loss on
  filesystems like XFS with inode64) a mirror's bind actually confirmed, at all four bind
  sites: the Node HTTP/TLS mirror, its h2 sibling, the raw-socket/MQTT securePort mirror,
  the uWS path, and the Bun path.
• cleanupUdsFiles() unlinks a path only when the identity currently on disk still matches
  what this worker recorded. A mismatched or never-recorded identity means a replacement (or
  nothing) owns it, so the entry is skipped — both the socket and its .yaml, since a
  replacement that rebound the socket owns the pair. It also consumes the recorded
  identity after its first pass (this function runs twice per worker — SHUTDOWN, then
  process.on('exit') — and inode numbers get reused once freed, so a stale second-pass
  comparison could otherwise coincidentally re-match an unrelated later generation).
• markUdsBindFailed() carries an intentionally asymmetric version of the same guard: it
  also retracts stale metadata when nothing is currently on disk (absent), not just when it
  owns the socket — its only caller runs synchronously before any bind is attempted, so it can
  never itself be in the "owned" state, and there's no concurrency window for that call
  specifically. cleanupUdsFiles() deliberately does not extend the same "absent is safe"
  treatment to itself, because its second call can land seconds after the first, during which
  a concurrently-booting replacement (on non-overlapping-restart platforms) can have written
  its own fresh yaml without having bound its socket yet.
• Wired up the already-written cleanupSocketsDirectory() crash-path sweep on main-thread
  startup (before any worker can bind, one-shot per process), so a hard crash that skips a
  worker's own exit-time cleanup can't leave stale files behind either. This is a separate
  defense from the inode guard above (crash-path vs. rolling-restart) and is now unconditional
  on the current config (a crash-then-reconfigure-then-reboot must still sweep).

restartWorkers()'s overlapping-restart sequencing and listenOnDomainSocket()'s
unlink-before-bind are both left exactly as they were — this is purely about who is allowed
to delete a socket file, not about restart ordering.

Deliberately not fixed here (see the PR's self-review for the full reasoning): the yaml's
publish lifecycle (SNICallback.ready/cert-reload) is independent of the socket's bind, so
socket-inode ownership doesn't fully protect it in two narrow windows — a non-path-too-long
bind failure, and a cert reload racing an outgoing worker's shutdown drain on non-overlapping
platforms. Both are real but narrow, and the clean fix (yaml-own-identity via its embedded
pid/tid, or an atomic write) is a larger change than "who owns a socket file." Flagging for
discussion rather than expanding scope unilaterally.

Out of scope (separate, pre-existing issue, left alone): the same overlap also permanently
kills the per-worker Node inspector port on a rolling restart, because the inspector port
isn't SO_REUSEPORT and nothing retries the bind after the outgoing worker exits.

Test plan

Extended unitTests/server/udsMirror.test.js (46 tests in the file, all passing):

• normal shutdown still removes the socket + yaml this worker bound
• the regression: after the socket file is replaced by a different inode at the same
  path (simulating the replacement rebinding), cleanupUdsFiles() leaves both files in place
• double-cleanup idempotency: forces the exact recorded inode to reappear (via a pinned
  hard link, deterministic rather than allocator-dependent) between the two real-world
  cleanupUdsFiles() calls a worker makes, and asserts the second call is a no-op
• a bind that never succeeded doesn't unlink anything; ENOENT is handled quietly
• markUdsBindFailed()'s asymmetric guard: removes when this worker owns the pair or nothing
  is on disk, leaves it when a live foreign socket is present
• cleanupSocketsDirectory()'s unconditional sweep

Also: npm run build clean; full server unit suite 702 passing; test:unit:main 4138
passing with 11 pre-existing failures verified unrelated (reproduced identically on
unmodified main via git stash).

---

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces ownership-aware lifecycle management for Unix Domain Socket (UDS) mirror files to prevent outgoing workers from deleting replacement workers' files during overlapping restarts. It captures the device and inode of bound sockets and verifies ownership before unlinking. Additionally, it ensures that the startup crash-path sweep of the sockets directory runs unconditionally and only once. The reviewer suggested a robustness improvement in ownershipOf to specifically check for ENOENT errors when stating the socket path, preventing other filesystem errors from falsely indicating that the socket is absent.

[cb1kenobi]

Reviewed 05d679ef — no issues found. This PR looks good, nice job!

Traced the ownership model against the real code paths: recordUdsBindSuccess captures (dev, ino) as bigint at all bind sites (Node/h2 mirrors via listenOnDomainSocket's onListening, the raw-socket/MQTT securePort mirror through the same, Bun after Bun.serve(), uWS after createUwsServer() resolves), and cleanupUdsFiles/markUdsBindFailed only unlink when the on-disk inode still matches. The two failure directions both hold up: a false-positive delete of a live replacement's socket is prevented by the inode check (with the residual stat→unlink TOCTOU correctly narrowed to microseconds and disclosed), and a false-negative leak that would block rebind with EADDRINUSE can't strand a path because every bind site does unlink-before-bind and the newly-wired, now-unconditional cleanupSocketsDirectory() sweeps stale files on main-thread startup before any worker binds. The sweptSocketsDirectory guard is load-bearing and correct — it stops a later in-process startHTTPThreads from nuking live mirrors. Identity consumption across the two per-worker cleanup passes (SHUTDOWN then process.on('exit')) correctly defeats inode reuse, and the deliberate owned-only vs absent-safe asymmetry between cleanupUdsFiles and markUdsBindFailed matches each caller's concurrency window. Tests are thorough (regression, double-cleanup idempotency via pinned hard link, unconfirmed bind, ENOTDIR, foreign inode) and DESIGN.md is updated accurately.

—
Generated by Barber AI