socketduct 0.1.21 → 0.1.22

package/changelog.d/20260928120416-reverse-gateway-spool-directory.md

@@ -0,0 +1,3 @@
+# Outbound reverse gateway spool directory environment variable
+
+The standalone outbound reverse gateway runtime now accepts `SOCKETDUCT_SPOOL_DIRECTORY`, which points the gateway's durable target-output spool at an operator-chosen persistent path. The default remains the process temporary directory, so containerized gateways can move the bounded spool behind exactly-once resume replay onto a host volume instead of the container's ephemeral, size-bounded `/tmp`. The variable is accepted only in `reverse-gateway` mode and is rejected in every other mode.

package/changelog.d/20260928124500-critical-reserve-bound-test.md

@@ -0,0 +1,3 @@
+# Bound the compressed-log critical reserve test to a coverable charge
+
+The compressed-log queue-pressure test asserted that a critical disconnect record is accepted while a 4096-byte queue holds a 1024-byte critical reserve, but the record's conservative charge (line bytes × 3 + 128) exceeds the reserve, so the writer correctly dropped it and the test failed on every run. Accepted log sequences are append-only and cannot be evicted without tearing the durable journal, so the test now reserves 2048 bytes — covering the critical record's charge — and the logging docs state the reserve sizing bound explicitly.

package/docs/logging.md

@@ -28,7 +28,11 @@ SOCKETDUCT_LOG_COMPRESSION_LEVEL=19
 Those values are the defaults. Reaching the uncompressed frame limit starts a
 flush immediately. Flush deadlines are measured from the oldest queued work and
 are never extended by later records; critical lifecycle, security, and resume
-events use the shorter deadline and may use the reserved queue capacity.
+events use the shorter deadline and may use the reserved queue capacity. A
+critical record is guaranteed acceptance only while its conservative charge
+(line bytes × 3 + 128) fits the reserve, because accepted sequences are
+append-only and can never be evicted from the durable journal; size the
+reserve for the largest critical record you must retain under queue pressure.
 Segment size, age, and directory quota are bounded independently. Invalid or mutually
 inconsistent values stop startup.
 The former `SOCKETDUCT_LOG_MAX_FILE_BYTES` and `SOCKETDUCT_LOG_MAX_FILES`

package/docs/reverse-gateway.md

@@ -298,9 +298,17 @@ SOCKETDUCT_REVERSE_TOKEN='<secret>' \
 SOCKETDUCT_REVERSE_HUB_CA_FILE=/certs/hub-ca.crt \
 SOCKETDUCT_REVERSE_HUB_SERVERNAME=server3.example.net \
 SOCKETDUCT_TARGET_ALLOWLIST=docker-a:2375 \
+SOCKETDUCT_SPOOL_DIRECTORY=/var/lib/socketduct/spool \
 node src/index.js
 ```
 
+`SOCKETDUCT_SPOOL_DIRECTORY` is reverse-gateway-only and points the gateway's
+durable target-output spool — the bounded store behind exactly-once resume
+replay — at an operator-chosen path. Without it the spool lives under the
+process temporary directory, which is ephemeral and size-bounded inside a
+container; set it to a persistent host mount so spool capacity and retention
+do not depend on container lifetime. The runtime rejects it in every other mode.
+
 The namespace/default-route configuration remains outside Socketduct. Each
 gateway registration represents one exact target server and WAN class;
 Socketduct does not aggregate away either identity. Socketduct needs no inbound

package/package.json

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

package/src/config/environment.js

@@ -54,6 +54,7 @@ const SUPPORTED_PROTOCOL_VERSIONS = new Set([2, 3])
  * @property {string} relayHost - Relay listen host.
  * @property {number} relayPort - Relay listen port.
  * @property {number} resumeWindowMs - Resume window in milliseconds.
+ * @property {string} [spoolDirectory] - Outbound gateway durable spool root; reverse-gateway mode only.
  * @property {number} maxTargetBufferBytes - Per-session byte limit for buffered target data while the tunnel is detached.
  * @property {number} maxTotalBufferBytes - Process-wide byte limit for buffered target data across all sessions.
  * @property {number} [initialTargetRetryDelayMs] - Initial delay between target acquisition attempts. Default 250.
@@ -143,6 +144,8 @@ export function loadEnvironmentConfig(env = process.env) {
     ...(reverseClientCertFile === undefined ? {} : {certFile: reverseClientCertFile, keyFile: /** @type {string} */ (reverseClientKeyFile)}),
     ...(env.SOCKETDUCT_REVERSE_HUB_SERVERNAME?.trim() ? {servername: env.SOCKETDUCT_REVERSE_HUB_SERVERNAME.trim()} : {})
   }
+  const spoolDirectory = env.SOCKETDUCT_SPOOL_DIRECTORY?.trim() || undefined
+  if (spoolDirectory !== undefined && mode !== "reverse-gateway") throw new Error("SOCKETDUCT_SPOOL_DIRECTORY is reverse-gateway-only")
   const logDirectory = env.SOCKETDUCT_LOG_DIRECTORY?.trim() || undefined
   if (env.SOCKETDUCT_LOG_MAX_FILE_BYTES !== undefined || env.SOCKETDUCT_LOG_MAX_FILES !== undefined) throw new Error("SOCKETDUCT_LOG_MAX_FILE_BYTES and SOCKETDUCT_LOG_MAX_FILES were replaced by compressed log frame, segment, and retention settings")
   let fileLogging
@@ -251,7 +254,8 @@ export function loadEnvironmentConfig(env = process.env) {
         port: parsePort(env.SOCKETDUCT_REVERSE_HUB_PORT, "SOCKETDUCT_REVERSE_HUB_PORT", DEFAULT_RELAY_PORT),
         token: reverseToken ?? ""
       },
-      reverseHubTls
+      reverseHubTls,
+      ...(spoolDirectory === undefined ? {} : {spoolDirectory})
     } : {})
   }
 }

package/src/reverse/runtime.js

@@ -80,6 +80,7 @@ export async function startOutboundReverseGatewayRuntime(config, logger) {
     maxStreamBufferBytes: config.maxTargetBufferBytes,
     maxTotalBufferBytes: config.maxTotalBufferBytes,
     compressionLimits: compressionLimits(config),
+    ...(config.spoolDirectory === undefined ? {} : {spoolDirectory: config.spoolDirectory}),
     ...(logger === undefined ? {} : {logger})
   })
   await gateway.start()

package/test/e2e/reverse-gateway-process.test.js

@@ -1,7 +1,7 @@
 /* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-param, jsdoc/require-returns */
 import assert from "node:assert/strict"
 import {spawn} from "node:child_process"
-import {mkdtemp, rm} from "node:fs/promises"
+import {mkdtemp, readFile, readdir, rm} from "node:fs/promises"
 import {createServer} from "node:net"
 import {tmpdir} from "node:os"
 import {join} from "node:path"
@@ -131,6 +131,31 @@ async function withTimeout(promise, label) {
   }
 }
 
+/** @param {string} directory - Directory. @returns {Promise<string[]>} Entries, or an empty list for a missing directory. */
+async function readDirectoryOrEmpty(directory) {
+  try {
+    return await readdir(directory)
+  } catch (error) {
+    if (error instanceof Error && /** @type {Error & {code?: string}} */ (error).code === "ENOENT") return []
+    throw error
+  }
+}
+
+/**
+ * Polls until the probe resolves truthy, bounded by the process timeout.
+ * @param {() => boolean | Promise<boolean>} probe - Condition to test.
+ * @param {string} label - Timeout label.
+ * @returns {Promise<void>}
+ */
+async function waitUntil(probe, label) {
+  const deadline = Date.now() + PROCESS_TIMEOUT_MS
+  for (;;) {
+    if (await probe()) return
+    if (Date.now() >= deadline) throw new Error(`Timed out: ${label}`)
+    await new Promise((resolve) => setTimeout(resolve, 50))
+  }
+}
+
 /** @param {import('node:events').EventEmitter} emitter - Source. @param {string} event - Event. */
 async function onceEvent(emitter, event) {
   await new Promise((resolve, reject) => {
@@ -377,3 +402,97 @@ test("one route-class client physical connection interleaves streams through dif
   streamA.destroy()
   streamB.destroy()
 })
+
+test("outbound gateway process spools durably under SOCKETDUCT_SPOOL_DIRECTORY when the hub link is lost", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-spool-process-"))
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const certificates = generateTestCertificates(root)
+  const gatewaySpoolDirectory = join(root, "gateway-spool")
+  const clientSpoolDirectory = join(root, "client-spool")
+  /** @type {import('node:net').Socket | undefined} */
+  let targetSocket
+  const targetSockets = new Set()
+  const target = createServer((socket) => {
+    targetSocket = socket
+    targetSockets.add(socket)
+    socket.once("close", () => targetSockets.delete(socket))
+    socket.on("data", (chunk) => socket.write(Buffer.concat([Buffer.from("docker:"), chunk])))
+  })
+  const targetPort = await listen(target)
+  t.after(() => {
+    for (const socket of targetSockets) socket.destroy()
+    return new Promise((resolve) => target.close(() => resolve(undefined)))
+  })
+  const {child: hub, port: hubPort} = await startProcessOnReservedPort({
+    SOCKETDUCT_MODE: "reverse-hub",
+    SOCKETDUCT_RELAY_HOST: "127.0.0.1",
+    SOCKETDUCT_TLS_CERT_FILE: certificates.serverCertFile,
+    SOCKETDUCT_TLS_KEY_FILE: certificates.serverKeyFile,
+    SOCKETDUCT_AUTH_TOKENS: "home-o2:spool-gateway-token,tensorbuzz:spool-client-token",
+    SOCKETDUCT_REVERSE_GATEWAY_BINDINGS: "o2:home-o2",
+    SOCKETDUCT_REVERSE_ROUTES: `tensorbuzz:o2:127.0.0.1:${targetPort}`,
+    SOCKETDUCT_STATUS_INTERVAL_MS: "0"
+  }, "reverse-hub.started")
+  const gateway = await startProcess({
+    SOCKETDUCT_MODE: "reverse-gateway",
+    SOCKETDUCT_REVERSE_GATEWAY_ID: "o2",
+    SOCKETDUCT_REVERSE_CONNECTION_ID: "spool_process_gateway",
+    SOCKETDUCT_REVERSE_HUB_HOST: "127.0.0.1",
+    SOCKETDUCT_REVERSE_HUB_PORT: String(hubPort),
+    SOCKETDUCT_REVERSE_TOKEN: "spool-gateway-token",
+    SOCKETDUCT_REVERSE_HUB_CA_FILE: certificates.caCertFile,
+    SOCKETDUCT_REVERSE_HUB_SERVERNAME: "localhost",
+    SOCKETDUCT_TARGET_ALLOWLIST: `127.0.0.1:${targetPort}`,
+    SOCKETDUCT_STATUS_INTERVAL_MS: "0",
+    SOCKETDUCT_SPOOL_DIRECTORY: gatewaySpoolDirectory
+  }, "reverse-gateway.started")
+  t.after(() => stopProcess(gateway))
+  const client = new ReverseGatewayConnection({
+    gatewayId: "o2",
+    connectionId: "spool_process_client",
+    hub: {host: "127.0.0.1", port: hubPort, token: "spool-client-token"},
+    tls: {caFile: certificates.caCertFile, servername: "localhost"},
+    spoolDirectory: clientSpoolDirectory,
+    reconnectDelayMs: 50,
+    maxReconnectDelayMs: 100
+  })
+  t.after(() => client.close())
+  await withTimeout(client.connect(), "spool client connect")
+  const socket = client.createConnection({host: "127.0.0.1", port: targetPort, sessionName: "docker-spool-process"})
+  await withTimeout(onceEvent(socket, "connect"), "spool stream open")
+  const initialResponse = new Promise((resolve, reject) => { socket.once("error", reject); socket.once("data", resolve) })
+  socket.write("GET /version")
+  assert.equal(Buffer.from(/** @type {Uint8Array} */ (await withTimeout(initialResponse, "spool initial response"))).toString(), "docker:GET /version")
+
+  hub.kill("SIGKILL")
+  await withTimeout(new Promise((resolve) => hub.once("exit", () => resolve(undefined))), "hub exit")
+  assert(targetSocket !== undefined)
+  const spooledMarker = Buffer.alloc(32, 0x61)
+  targetSocket.write(spooledMarker)
+  const spoolHasPayload = async () => {
+    const markerBase64 = spooledMarker.toString("base64")
+    for (const session of await readDirectoryOrEmpty(gatewaySpoolDirectory)) {
+      const files = await readDirectoryOrEmpty(join(gatewaySpoolDirectory, session))
+      if (!files.includes("chunks.jsonl")) continue
+      const lines = (await readFile(join(gatewaySpoolDirectory, session, "chunks.jsonl"), "utf8")).split("\n")
+      if (lines.some((line) => {
+        if (line === "") return false
+        try {
+          return /** @type {{dataBase64?: unknown}} */ (JSON.parse(line)).dataBase64 === markerBase64
+        } catch (error) {
+          if (error instanceof SyntaxError) return false
+          throw error
+        }
+      })) return true
+    }
+    return false
+  }
+  await waitUntil(spoolHasPayload, "durable spool chunk under SOCKETDUCT_SPOOL_DIRECTORY")
+  const defaultGatewaySpoolRoot = join(tmpdir(), `socketduct-${typeof process.getuid === "function" ? process.getuid() : "user"}`, "reverse-gateway")
+  const defaultSpooled = (await readDirectoryOrEmpty(defaultGatewaySpoolRoot)).some((entry) => entry.startsWith("o2-spool_process_gateway"))
+  assert.equal(defaultSpooled, false, "spool must not fall back to the ephemeral default root")
+
+  socket.destroy()
+  client.close()
+  await stopProcess(gateway)
+})

package/test/unit/config/environment.test.js

@@ -337,6 +337,31 @@ test("loadEnvironmentConfig parses outbound reverse gateway verified TLS setting
   assert.deepEqual(config.reverseHubTls, {caFile: "/certs/ca.crt", certFile: "/certs/client.crt", keyFile: "/certs/client.key", servername: "server3.example.test"})
 })
 
+test("loadEnvironmentConfig parses the reverse-gateway spool directory", () => {
+  const config = loadEnvironmentConfig({
+    SOCKETDUCT_MODE: "reverse-gateway",
+    SOCKETDUCT_REVERSE_GATEWAY_ID: "starlink",
+    SOCKETDUCT_REVERSE_CONNECTION_ID: "home_starlink_01",
+    SOCKETDUCT_REVERSE_HUB_HOST: "server3.example.test",
+    SOCKETDUCT_REVERSE_TOKEN: "gateway-token",
+    SOCKETDUCT_TARGET_ALLOWLIST: "docker-server:2375",
+    SOCKETDUCT_SPOOL_DIRECTORY: " /spool/reverse-gateway "
+  })
+  assert.equal(config.spoolDirectory, "/spool/reverse-gateway")
+  assert.equal("spoolDirectory" in loadEnvironmentConfig({
+    SOCKETDUCT_MODE: "reverse-gateway",
+    SOCKETDUCT_REVERSE_GATEWAY_ID: "starlink",
+    SOCKETDUCT_REVERSE_CONNECTION_ID: "home_starlink_01",
+    SOCKETDUCT_REVERSE_HUB_HOST: "server3.example.test",
+    SOCKETDUCT_REVERSE_TOKEN: "gateway-token",
+    SOCKETDUCT_TARGET_ALLOWLIST: "docker-server:2375",
+    SOCKETDUCT_SPOOL_DIRECTORY: "   "
+  }), false)
+  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "relay", SOCKETDUCT_SPOOL_DIRECTORY: "/spool"}), /reverse-gateway-only/)
+  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "reverse-hub", SOCKETDUCT_SPOOL_DIRECTORY: "/spool"}), /reverse-gateway-only/)
+  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_SPOOL_DIRECTORY: "/spool"}), /reverse-gateway-only/)
+})
+
 test("loadEnvironmentConfig rejects malformed reverse mode policy and credentials", () => {
   assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "unknown"}), /Unsupported SOCKETDUCT_MODE/)
   assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "reverse-hub", SOCKETDUCT_REVERSE_GATEWAY_BINDINGS: "missing-user"}), /gatewayId:username/)

package/test/unit/logging/compressed-log-writer.test.js

@@ -61,11 +61,13 @@ test("compressed logger durably acknowledges ordered records and closes asynchro
 test("compressed logger enforces one shared bounded queue with a critical reserve", async (t) => {
   const root = await mkdtemp(join(tmpdir(), "socketduct-compressed-pressure-"))
   const directory = join(root, "logs")
+  // The reserve must cover the critical event's conservative charge (line bytes × 3 + 128);
+  // an accepted-but-undelivered sequence can never be evicted without tearing the durable journal.
   const logger = createCompressedJsonlFileLogger({
     directory,
     role: "reverse-client",
     maxQueueBytes: 4096,
-    criticalReserveBytes: 1024,
+    criticalReserveBytes: 2048,
     frameMaxBytes: 1024,
     flushIntervalMs: 60_000,
     criticalFlushIntervalMs: 60_000