socketduct 0.1.26 → 0.1.28

package/changelog.d/20261025070000-reclaim-unreadable-retention-lock.md

@@ -0,0 +1,14 @@
+# Reclaim unreadable retention locks
+
+Retention now reclaims a `.socketduct-retention.lock` whose owner record this
+process cannot read instead of failing the whole run. A lock written by a
+privileged one-off process (a root repair or cleanup) is mode 0600 and owned by
+another uid, so every later retention attempt raised `EACCES` from
+`readOwnerFile`. That error propagated out of the durable log sink at startup and
+took down the server process that owns the sink.
+
+The lock directory is private and peer writers share this process's uid, so an
+unreadable record cannot belong to a live peer of the runtime. Retention now
+unlinks such a file and retries the atomic link. If the file cannot be removed,
+retention fails with `LOG_RETENTION_LOCK_UNREADABLE`, which names the lock path
+and the owning uid instead of surfacing a bare `EACCES`.

package/changelog.d/20261025162000-gateway-unavailability-report-is-not-a-timer.md

@@ -0,0 +1 @@
+A hub route-class unavailability report now lasts for the life of the connection instead of five seconds, so a transport set stops re-selecting a route class the hub already declared unserviceable and no longer fails the caller's first open on it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "socketduct",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "description": "Resilient authenticated tunnel/proxy for keeping socket streams alive across flaky links.",
   "type": "module",
   "main": "./src/index.js",

package/src/client/multiplexed-transport-set.js

@@ -44,7 +44,7 @@ const GATEWAY_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{1,63}$/
  * @property {import('../logging/structured-logger.js').DiagnosticLogger} [logger] - Optional privacy-safe structured logger shared by the set and its members.
  * @typedef {object} MemberConnectionStatus
  * @property {string} physicalState - Member lifecycle.
- * @property {boolean} [gatewayUnavailable] - Hub recently reported no selectable gateway for this member's route class.
+ * @property {boolean} [gatewayUnavailable] - Hub reported no selectable gateway for this member's route class on the current connection.
  * @property {number} connectionGeneration - Current authenticated generation.
  * @property {number} physicalConnects - Authenticated physical generations.
  * @property {number} reconnectAttempts - Physical reconnect attempts.

package/src/logging/log-retention.js

@@ -94,7 +94,20 @@ async function acquireRetentionLock(directory, lockPath) {
   for (let attempt = 0; attempt < 3; attempt += 1) {
     const created = await createOwnerFile(directory, lockPath, owner)
     if (created !== undefined) return created
-    const existing = await readOwnerFile(lockPath)
+    let existing
+    try {
+      existing = await readOwnerFile(lockPath)
+    } catch (error) {
+      // A lock this process cannot read cannot belong to a live peer: peers write
+      // their owner record mode 0600 under their own uid into this private
+      // directory. Such a file is left behind by a privileged one-off process
+      // (a root-run repair or cleanup), and because its record is unreadable here
+      // it would block retention for every later run - failing the durable log
+      // sink and, with it, the server process that owns the sink.
+      if (!isCode(error, "EACCES") && !isCode(error, "EPERM")) throw error
+      await reclaimUnreadableLock(directory, lockPath)
+      continue
+    }
     if (existing === undefined) continue
     if (await ownerIsLive(existing.owner)) return undefined
     const current = await lstat(lockPath).catch((error) => { if (isCode(error, "ENOENT")) return undefined; throw error })
@@ -106,6 +119,28 @@ async function acquireRetentionLock(directory, lockPath) {
   return undefined
 }
 
+/**
+ * Removes a retention lock that this process cannot read, so the caller can retry
+ * the atomic link. Unlink is attempted rather than deferred: the directory is
+ * private, and a lock whose owner record is unreadable here cannot be held by a
+ * peer of this runtime.
+ * @param {string} directory - Private log directory.
+ * @param {string} lockPath - Unreadable lock path.
+ */
+async function reclaimUnreadableLock(directory, lockPath) {
+  const stats = await lstat(lockPath).catch((error) => { if (isCode(error, "ENOENT")) return undefined; throw error })
+  if (stats === undefined) return
+  if (!stats.isFile()) throw Object.assign(new Error("Unsafe retention lock"), {code: "LOG_RETENTION_LOCK_INVALID"})
+  await unlink(lockPath).catch((error) => {
+    if (isCode(error, "ENOENT")) return
+    throw Object.assign(
+      new Error(`Retention lock ${lockPath} is owned by uid ${stats.uid} and cannot be reclaimed by uid ${process.getuid?.()}: ${error instanceof Error ? error.message : String(error)}`),
+      {cause: error, code: "LOG_RETENTION_LOCK_UNREADABLE"}
+    )
+  })
+  await syncDirectory(directory)
+}
+
 /**
  * @param {string} directory - Directory.
  * @param {string} lockPath - Destination.

package/src/reverse/client.js

@@ -32,7 +32,6 @@ import {attachDisconnectAttribution, createDisconnectAttribution, parseDisconnec
 const DEFAULT_STREAM_BUFFER_BYTES = 4 * 1024 * 1024
 const DEFAULT_CONNECTION_BUFFER_BYTES = 32 * 1024 * 1024
 const MANIFEST_PAGE_STREAMS = 64
-const GATEWAY_UNAVAILABLE_TTL_MS = 5_000
 
 /**
  * @typedef {object} ReverseGatewayConnectionOptions
@@ -373,13 +372,18 @@ export class ReverseGatewayConnection extends EventEmitter {
   }
 
   /**
-   * Whether the last hub-reported gateway state for this member was unavailable
-   * and the report is still fresh. A stale report never pins the member out.
-   * @returns {boolean} True while a fresh hub unavailability report is active.
+   * Whether the hub last reported this member's route class as having no selectable
+   * gateway. The report is a property of the live connection, not a short-lived cache:
+   * it arrives once per connection at selection time and only changes when the hub says
+   * otherwise or an open succeeds. Expiring it on a timer made the transport set pick a
+   * route class the hub had already declared unserviceable, and the reset that followed
+   * failed the caller's operation — a build lost its first transport open this way.
+   * The transport set still falls back to marked members when every member is marked, so
+   * a mark can never wedge the set.
+   * @returns {boolean} True while the hub reports no selectable gateway for this member.
    */
   #gatewayUnavailable() {
     return this.#gatewayUnavailableSince !== undefined
-      && Date.now() - this.#gatewayUnavailableSince < GATEWAY_UNAVAILABLE_TTL_MS
   }
 
   status() {

package/test/integration/reverse-route-class.test.js

@@ -436,6 +436,12 @@ describe("reverse gateway route-class", () => {
     expect(client.status().physicalState).toBe("ready")
     expect(client.status().gatewayUnavailable).toBe(true)
 
+    // The report belongs to the live connection: it must survive any short window a caller
+    // might wait between the announce and its first open. A timer-bound mark made the transport
+    // set pick this route class again and the resulting reset failed the caller's operation.
+    await new Promise((resolve) => setTimeout(resolve, 5200))
+    expect({value: client.status().gatewayUnavailable, context: "a hub unavailability report must not expire on a timer"}).toMatchObject({value: true})
+
     // Once the gateway registers, a replacement selection announces selectable=true and clears the mark.
     const gatewayA = new OutboundReverseGateway({
       gatewayId: "server-a-starlink",

package/test/unit/logging/log-retention.test.js

@@ -1,6 +1,6 @@
 /* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-param-type, jsdoc/require-returns */
 import {describe, expect, it, withTestCleanup} from "@velocious/testing"
-import {readlinkSync} from "node:fs"
+import {chmodSync, chownSync, readlinkSync} from "node:fs"
 import {mkdtemp, readFile, readdir, rm, utimes, writeFile} from "node:fs/promises"
 import {tmpdir} from "node:os"
 import {join} from "node:path"
@@ -63,6 +63,24 @@ describe("log retention", () => {
     await writeFile(lockPath, `${JSON.stringify({version: 1, pid: process.pid, processStart, tid, threadStart})}\n`, {mode: 0o600})
     expect((await enforceLogRetention({directory, maxAgeMs: 60_000, maxBytes: 1024})).skipped).toBe(true)
   }))
+
+  it("retention reclaims a lock left behind by a privileged process it cannot read", async () => withTestCleanup(async (after) => {
+    const directory = await mkdtemp(join(tmpdir(), "socketduct-retention-foreign-"))
+    after(() => rm(directory, {recursive: true, force: true}))
+    const lockPath = join(directory, ".socketduct-retention.lock")
+    const uid = typeof process.getuid === "function" ? process.getuid() : undefined
+
+    await writeFile(lockPath, `${JSON.stringify({version: 1, pid: 1, processStart: "1", tid: 1, threadStart: "1"})}\n`, {mode: 0o600})
+
+    if (uid === 0) chownSync(lockPath, 65_534, 65_534)
+    else if (uid !== undefined) chmodSync(lockPath, 0o000)
+
+    // The lock owner record is unreadable for this process, so retention cannot
+    // wait for it: it must reclaim the file and complete instead of failing the
+    // durable log sink for the whole server process.
+    expect((await enforceLogRetention({directory, maxAgeMs: 60_000, maxBytes: 1024})).skipped).toBe(false)
+    expect((await readdir(directory)).includes(".socketduct-retention.lock")).toBe(false)
+  }))
 })
 
 /**