socketduct 0.1.25 → 0.1.26

package/AGENTS.md

@@ -160,9 +160,9 @@ docs/
 ## Definition of done for implementation PRs
 
 - Add a release-note fragment for every user-visible change, bug fix, security fix, or protocol change under `changelog.d/YYYYMMDDHHMMSS-short-slug.md`. Keep it to one concise, user-facing sentence; do not edit generated release notes directly.
-- Tests added or updated.
+- Tests added or updated — test modules declare `describe`/`it`/`expect` from `@velocious/testing`; `node:test`/`node:assert` are not used in test modules.
 - Relevant docs updated.
-- `npm test` passes.
+- `npm test` passes (every `test/**/*.test.js` module runs through the `velocious-test` runner).
 - Lint/typecheck passes once configured.
 - Security-sensitive changes mention how credentials/tokens are protected.
 - No open proxy behavior introduced.

package/changelog.d/20261010130509-bound-log-frame-compression-memory.md

@@ -0,0 +1 @@
+Diagnostic log frames now default to zstd level 9 instead of 19: zstd context memory scales steeply with the level (~1-2 MB per compressed batch at 9 versus ~90 MB at 19), and per-batch contexts accumulated into a multi-GB resident/peak-RSS ratchet in long-lived processes that no JS-level accounting or GC pressure sees.

package/docs/runbooks/jsonl-integrity-rollout.md

@@ -35,12 +35,14 @@ npm run lint
 git diff --check
 ```
 
-Run the two focused modules sequentially with the published `@velocious/testing`
-runner. `npm test` is the CI entry point: it discovers untouched legacy modules
-for Node's runner and then invokes the owning runner separately for each migrated
-logger module. `npm test -- --list` prints both selections without running tests.
-Do not run the full suite or shards locally during a correction pass; CI owns
-that coverage. Test cleanup uses the package's supported FIFO `withTestCleanup`.
+Run the focused modules sequentially with the published `@velocious/testing`
+runner. `npm test` is the CI entry point: it discovers every module under
+`test/**/*.test.js` and runs each one through the `velocious-test` runner in
+sorted order. `npm test -- --list` prints the discovered modules without running
+tests, and `npm test -- <path-or-args>` forwards arguments to a focused runner
+invocation. Do not run the full suite or shards locally during a correction
+pass; CI owns that coverage. Test cleanup uses the package's supported FIFO
+`withTestCleanup`.
 
 The process tests create and remove only their own private home subdirectories;
 the canonical `/home/dev` bind persists across child-process exits. They reuse

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "socketduct",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "description": "Resilient authenticated tunnel/proxy for keeping socket streams alive across flaky links.",
   "type": "module",
   "main": "./src/index.js",
@@ -38,7 +38,7 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/node": "^24.0.0",
-    "@velocious/testing": "0.0.10",
+    "@velocious/testing": "^0.0.18",
     "awaitery": "^1.0.21",
     "eslint": "^10.0.3",
     "eslint-plugin-jsdoc": "^62.7.1",

package/scripts/test.js

@@ -1,24 +1,19 @@
 import {spawnSync} from "node:child_process"
 import {globSync} from "node:fs"
 
-const migrated = ["test/unit/logging/structured-logger.test.js", "test/integration/logging-recovery.test.js"]
+const args = process.argv.slice(2)
 const files = globSync("test/**/*.test.js").sort()
-for (const path of migrated) {
-  if (!files.includes(path)) throw new Error(`Missing migrated test module: ${path}`)
-}
-const legacy = files.filter((path) => !migrated.includes(path))
-if (legacy.length === 0) throw new Error("No legacy test modules discovered")
-const commands = [
-  {runner: process.execPath, args: ["--test", ...legacy]},
-  ...migrated.map((path) => ({runner: "velocious-test", args: [path]}))
-]
+if (files.length === 0) throw new Error("No test modules discovered")
 
-if (process.argv.length === 3 && process.argv[2] === "--list") {
-  console.log(JSON.stringify({legacy, migrated, commands}, null, 2))
+if (args.length === 1 && args[0] === "--list") {
+  console.log(JSON.stringify({files}, null, 2))
 } else {
-  if (process.argv.length !== 2) throw new Error("Only --list is supported; use the owning runner for focused tests")
+  const commands = args.length === 0
+    ? files.map((path) => ({args: [path], label: path}))
+    : [{args, label: args.join(" ")}]
   for (const command of commands) {
-    const result = spawnSync(command.runner, command.args, {stdio: "inherit"})
+    if (commands.length > 1) console.log(`\n=== ${command.label} ===`)
+    const result = spawnSync("velocious-test", command.args, {stdio: "inherit"})
     if (result.error) throw result.error
     if (result.status !== 0) {
       process.exitCode = result.status ?? 1

package/src/logging/compressed-log-writer.js

@@ -36,7 +36,7 @@ const NONCRITICAL_EVENTS = new Set(["runtime.status", "transport.connecting", "t
  * @property {number} [maxSegmentBytes] - Maximum compressed segment size.
  * @property {number} [maxQueueBytes] - Shared producer/worker allocation bound.
  * @property {number} [criticalReserveBytes] - Queue bytes reserved for critical events.
- * @property {number} [compressionLevel] - Explicit zstd level, default 19.
+ * @property {number} [compressionLevel] - Explicit zstd level, default 9. High levels (12+) allocate tens of MB of zstd context memory per compressed batch; see `DEFAULT_LOG_COMPRESSION_LEVEL`.
  * @property {number} [retentionDays] - Closed-segment maximum age, default 30 days.
  * @property {number} [retentionBytes] - Directory quota, default 4 GiB.
  * @property {{write(chunk: string): unknown}} [stderr] - Secret-free health reporting destination.

package/src/logging/zstd-frame-codec.js

@@ -2,7 +2,21 @@
 import {promisify} from "node:util"
 import {constants, zstdCompress, zstdDecompress} from "node:zlib"
 
-export const DEFAULT_LOG_COMPRESSION_LEVEL = 19
+/**
+ * Default zstd level for per-batch diagnostic log frames.
+ *
+ * Every batch is compressed as its own frame, and a fresh zstd context's
+ * memory scales steeply with the level: level 9 allocates ~1-2 MB per call,
+ * level 12 tens of MB, and level 19 roughly 90 MB. Long-lived processes flush
+ * log batches continuously, so a high level turns those per-call context
+ * allocations into a multi-GB resident/peak-RSS ratchet that no JS-level
+ * accounting sees (the memory is freed by the compressor but retained by the
+ * allocator while the producing worker's isolate never pressures GC). JSONL
+ * diagnostics already compress 50x+ at level 9, and level 19 buys only ~15%
+ * smaller frames at ~20x the CPU and ~50x the per-call memory, so the default
+ * stays in the bounded-memory range. Raise it per process only deliberately.
+ */
+export const DEFAULT_LOG_COMPRESSION_LEVEL = 9
 
 const compress = promisify(zstdCompress)
 const decompress = promisify(zstdDecompress)

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

@@ -1,10 +1,9 @@
-import assert from "node:assert/strict"
+import {describe, expect, it, withTestCleanup} from "@velocious/testing"
 import {spawn} from "node:child_process"
 import {mkdtemp, rm} from "node:fs/promises"
 import {createConnection, createServer} from "node:net"
 import {tmpdir} from "node:os"
 import {join} from "node:path"
-import test from "node:test"
 
 import {startTcpEdge} from "../../src/edge/tcp-edge.js"
 import {encodeFrame, FrameDecoder} from "../../src/protocol/frame.js"
@@ -159,104 +158,106 @@ async function stopProcess(child) {
   }), PROCESS_TIMEOUT_MS, "Timed out waiting for relay shutdown")
 }
 
-test("e2e process gateway forwards edge traffic to an allowlisted target", async () => {
-  const tempDir = await mkdtemp(join(tmpdir(), "socketduct-e2e-spool-"))
-  const targetServer = createServer((socket) => {
-    socket.on("data", (chunk) => socket.write(Buffer.concat([Buffer.from("echo:"), chunk])))
-  })
-  const targetPort = await listen(targetServer)
-  const relayPort = await reservePort()
-  const relay = await startRelayProcess({
-    SOCKETDUCT_MODE: "relay",
-    SOCKETDUCT_RELAY_HOST: "127.0.0.1",
-    SOCKETDUCT_RELAY_PORT: String(relayPort),
-    SOCKETDUCT_AUTH_TOKENS: "tensorbuzz-edge:e2e-token-not-placeholder",
-    SOCKETDUCT_TARGET_ALLOWLIST: `127.0.0.1:${targetPort}`
-  })
-
-  const edge = await startTcpEdge({
-    relayHost: "127.0.0.1",
-    relayPort,
-    token: "e2e-token-not-placeholder",
-    sessionName: "e2e process gateway",
-    target: {host: "127.0.0.1", port: targetPort},
-    spool: new SessionSpool({rootDir: tempDir}),
-    reconnectDelayMs: 10
-  })
-
-  test.after(async () => {
-    await edge.close()
-    await stopProcess(relay.process)
-    await closeServer(targetServer)
-    await rm(tempDir, {recursive: true, force: true})
-  })
-
-  const appSocket = createConnection({host: "127.0.0.1", port: edge.port})
-  await waitConnect(appSocket)
-  appSocket.write("hello-tensorbuzz")
-  assert.equal((await readOnce(appSocket)).toString("utf8"), "echo:hello-tensorbuzz")
-  appSocket.destroy()
-})
+describe("e2e process gateway", () => {
+  it("e2e process gateway forwards edge traffic to an allowlisted target", async () => withTestCleanup(async (after) => {
+    const tempDir = await mkdtemp(join(tmpdir(), "socketduct-e2e-spool-"))
+    const targetServer = createServer((socket) => {
+      socket.on("data", (chunk) => socket.write(Buffer.concat([Buffer.from("echo:"), chunk])))
+    })
+    const targetPort = await listen(targetServer)
+    const relayPort = await reservePort()
+    const relay = await startRelayProcess({
+      SOCKETDUCT_MODE: "relay",
+      SOCKETDUCT_RELAY_HOST: "127.0.0.1",
+      SOCKETDUCT_RELAY_PORT: String(relayPort),
+      SOCKETDUCT_AUTH_TOKENS: "tensorbuzz-edge:e2e-token-not-placeholder",
+      SOCKETDUCT_TARGET_ALLOWLIST: `127.0.0.1:${targetPort}`
+    })
 
-test("e2e process gateway denies non-allowlisted target requests", async () => {
-  const allowedTarget = createServer((socket) => {
-    socket.on("data", (chunk) => socket.write(chunk))
-  })
-  const allowedPort = await listen(allowedTarget)
-  const blockedPort = await reservePort()
-  const relayPort = await reservePort()
-  const relay = await startRelayProcess({
-    SOCKETDUCT_MODE: "relay",
-    SOCKETDUCT_RELAY_HOST: "127.0.0.1",
-    SOCKETDUCT_RELAY_PORT: String(relayPort),
-    SOCKETDUCT_AUTH_TOKENS: "tensorbuzz-edge:e2e-token-not-placeholder",
-    SOCKETDUCT_TARGET_ALLOWLIST: `127.0.0.1:${allowedPort}`
-  })
+    const edge = await startTcpEdge({
+      relayHost: "127.0.0.1",
+      relayPort,
+      token: "e2e-token-not-placeholder",
+      sessionName: "e2e process gateway",
+      target: {host: "127.0.0.1", port: targetPort},
+      spool: new SessionSpool({rootDir: tempDir}),
+      reconnectDelayMs: 10
+    })
 
-  test.after(async () => {
-    await stopProcess(relay.process)
-    await closeServer(allowedTarget)
-  })
+    after(async () => {
+      await edge.close()
+      await stopProcess(relay.process)
+      await closeServer(targetServer)
+      await rm(tempDir, {recursive: true, force: true})
+    })
 
-  const tunnel = createConnection({host: "127.0.0.1", port: relayPort})
-  const decoder = new FrameDecoder()
-  await waitConnect(tunnel)
-  tunnel.write(encodeFrame({
-    type: "session.create",
-    token: "e2e-token-not-placeholder",
-    name: "blocked process gateway target",
-    target: {host: "127.0.0.1", port: blockedPort},
-    framing: [2]
+    const appSocket = createConnection({host: "127.0.0.1", port: edge.port})
+    await waitConnect(appSocket)
+    appSocket.write("hello-tensorbuzz")
+    expect((await readOnce(appSocket)).toString("utf8")).toBe("echo:hello-tensorbuzz")
+    appSocket.destroy()
   }))
 
-  const [frame] = decoder.push(await readOnce(tunnel))
-  assert.equal(frame?.header.type, "error")
-  assert.equal(frame?.header.code, "TARGET_UNAUTHORIZED")
-  tunnel.destroy()
-})
-
-test("e2e process gateway rejects placeholder tokens before listening", async () => {
-  const relayPort = await reservePort()
-  const child = spawn(process.execPath, ["src/index.js"], {
-    cwd: process.cwd(),
-    env: {
-      ...process.env,
+  it("e2e process gateway denies non-allowlisted target requests", async () => withTestCleanup(async (after) => {
+    const allowedTarget = createServer((socket) => {
+      socket.on("data", (chunk) => socket.write(chunk))
+    })
+    const allowedPort = await listen(allowedTarget)
+    const blockedPort = await reservePort()
+    const relayPort = await reservePort()
+    const relay = await startRelayProcess({
       SOCKETDUCT_MODE: "relay",
       SOCKETDUCT_RELAY_HOST: "127.0.0.1",
       SOCKETDUCT_RELAY_PORT: String(relayPort),
-      SOCKETDUCT_AUTH_TOKENS: "tensorbuzz-edge:replace-with-generated-token",
-      SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:443"
-    },
-    stdio: ["ignore", "pipe", "pipe"]
-  })
-  let output = ""
-  child.stdout.on("data", (chunk) => { output += chunk.toString("utf8") })
-  child.stderr.on("data", (chunk) => { output += chunk.toString("utf8") })
+      SOCKETDUCT_AUTH_TOKENS: "tensorbuzz-edge:e2e-token-not-placeholder",
+      SOCKETDUCT_TARGET_ALLOWLIST: `127.0.0.1:${allowedPort}`
+    })
+
+    after(async () => {
+      await stopProcess(relay.process)
+      await closeServer(allowedTarget)
+    })
 
-  const exitCode = await withTimeout(new Promise((resolve) => {
-    child.once("exit", (code) => resolve(code))
-  }), PROCESS_TIMEOUT_MS, "Timed out waiting for placeholder-token process exit")
+    const tunnel = createConnection({host: "127.0.0.1", port: relayPort})
+    const decoder = new FrameDecoder()
+    await waitConnect(tunnel)
+    tunnel.write(encodeFrame({
+      type: "session.create",
+      token: "e2e-token-not-placeholder",
+      name: "blocked process gateway target",
+      target: {host: "127.0.0.1", port: blockedPort},
+      framing: [2]
+    }))
+
+    const [frame] = decoder.push(await readOnce(tunnel))
+    expect(frame?.header.type).toBe("error")
+    expect(frame?.header.code).toBe("TARGET_UNAUTHORIZED")
+    tunnel.destroy()
+  }))
 
-  assert.notEqual(exitCode, 0)
-  assert.match(output, /placeholder tokens/)
+  it("e2e process gateway rejects placeholder tokens before listening", async () => {
+    const relayPort = await reservePort()
+    const child = spawn(process.execPath, ["src/index.js"], {
+      cwd: process.cwd(),
+      env: {
+        ...process.env,
+        SOCKETDUCT_MODE: "relay",
+        SOCKETDUCT_RELAY_HOST: "127.0.0.1",
+        SOCKETDUCT_RELAY_PORT: String(relayPort),
+        SOCKETDUCT_AUTH_TOKENS: "tensorbuzz-edge:replace-with-generated-token",
+        SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:443"
+      },
+      stdio: ["ignore", "pipe", "pipe"]
+    })
+    let output = ""
+    child.stdout.on("data", (chunk) => { output += chunk.toString("utf8") })
+    child.stderr.on("data", (chunk) => { output += chunk.toString("utf8") })
+
+    const exitCode = await withTimeout(new Promise((resolve) => {
+      child.once("exit", (code) => resolve(code))
+    }), PROCESS_TIMEOUT_MS, "Timed out waiting for placeholder-token process exit")
+
+    expect(exitCode).not.toBe(0)
+    expect(output).toMatch(/placeholder tokens/)
+  })
 })

package/test/e2e/logger-shutdown-process.test.js

@@ -1,52 +1,53 @@
 /* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-param, jsdoc/require-returns */
-import assert from "node:assert/strict"
+import {describe, expect, it, withTestCleanup} from "@velocious/testing"
 import {spawn} from "node:child_process"
 import {mkdtemp, rm} from "node:fs/promises"
 import {createServer} from "node:net"
 import {tmpdir} from "node:os"
 import {join} from "node:path"
-import test from "node:test"
 
 import {readCompressedLogDirectory} from "../../src/logging/compressed-log-reader.js"
 
 const TIMEOUT_MS = 8_000
 
-test("SIGTERM durably flushes queued critical lifecycle records before exit", async (t) => {
-  const root = await mkdtemp(join(tmpdir(), "socketduct-logger-shutdown-"))
-  const directory = join(root, "logs")
-  const port = await reservePort()
-  const child = spawn(process.execPath, ["src/index.js"], {
-    cwd: process.cwd(),
-    env: {
-      ...process.env,
-      SOCKETDUCT_MODE: "relay",
-      SOCKETDUCT_RELAY_HOST: "127.0.0.1",
-      SOCKETDUCT_RELAY_PORT: String(port),
-      SOCKETDUCT_AUTH_TOKENS: "shutdown-test:shutdown-test-token",
-      SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:1",
-      SOCKETDUCT_STATUS_INTERVAL_MS: "0",
-      SOCKETDUCT_LOG_DIRECTORY: directory,
-      SOCKETDUCT_LOG_FLUSH_INTERVAL_MS: "60000",
-      SOCKETDUCT_LOG_CRITICAL_FLUSH_INTERVAL_MS: "60000"
-    },
-    stdio: ["ignore", "pipe", "pipe"]
-  })
-  let output = ""
-  child.stdout.on("data", (chunk) => { output += chunk.toString() })
-  child.stderr.on("data", (chunk) => { output += chunk.toString() })
-  t.after(async () => {
-    if (child.exitCode === null) child.kill("SIGKILL")
-    await rm(root, {recursive: true, force: true})
-  })
+describe("logger shutdown", () => {
+  it("SIGTERM durably flushes queued critical lifecycle records before exit", async () => withTestCleanup(async (after) => {
+    const root = await mkdtemp(join(tmpdir(), "socketduct-logger-shutdown-"))
+    const directory = join(root, "logs")
+    const port = await reservePort()
+    const child = spawn(process.execPath, ["src/index.js"], {
+      cwd: process.cwd(),
+      env: {
+        ...process.env,
+        SOCKETDUCT_MODE: "relay",
+        SOCKETDUCT_RELAY_HOST: "127.0.0.1",
+        SOCKETDUCT_RELAY_PORT: String(port),
+        SOCKETDUCT_AUTH_TOKENS: "shutdown-test:shutdown-test-token",
+        SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:1",
+        SOCKETDUCT_STATUS_INTERVAL_MS: "0",
+        SOCKETDUCT_LOG_DIRECTORY: directory,
+        SOCKETDUCT_LOG_FLUSH_INTERVAL_MS: "60000",
+        SOCKETDUCT_LOG_CRITICAL_FLUSH_INTERVAL_MS: "60000"
+      },
+      stdio: ["ignore", "pipe", "pipe"]
+    })
+    let output = ""
+    child.stdout.on("data", (chunk) => { output += chunk.toString() })
+    child.stderr.on("data", (chunk) => { output += chunk.toString() })
+    after(async () => {
+      if (child.exitCode === null) child.kill("SIGKILL")
+      await rm(root, {recursive: true, force: true})
+    })
 
-  await waitUntil(() => output.includes('"event":"relay.started"'), child, () => output)
-  assert.equal(child.kill("SIGTERM"), true)
-  const exit = await withTimeout(new Promise((resolve) => child.once("exit", (code, signal) => resolve({code, signal}))), "process exit")
-  assert.deepEqual(exit, {code: 0, signal: null})
+    await waitUntil(() => output.includes('"event":"relay.started"'), child, () => output)
+    expect(child.kill("SIGTERM")).toBe(true)
+    const exit = await withTimeout(new Promise((resolve) => child.once("exit", (code, signal) => resolve({code, signal}))), "process exit")
+    expect(exit).toEqual({code: 0, signal: null})
 
-  const result = await readCompressedLogDirectory(directory)
-  assert.equal(result.incomplete, false)
-  assert.deepEqual(result.records.map((record) => record.event), ["process.started", "process.stopped", "log_batch_accepted", "log_frame_committed", "log_closed"])
+    const result = await readCompressedLogDirectory(directory)
+    expect(result.incomplete).toBe(false)
+    expect(result.records.map((record) => record.event)).toEqual(["process.started", "process.stopped", "log_batch_accepted", "log_frame_committed", "log_closed"])
+  }))
 })
 
 /** @returns {Promise<number>} A released loopback port. */
@@ -57,7 +58,9 @@ async function reservePort() {
     server.listen(0, "127.0.0.1", () => { server.off("error", reject); resolve(undefined) })
   })
   const address = server.address()
-  assert(address !== null && typeof address !== "string")
+  if (address === null || typeof address === "string") {
+    throw new Error("Server did not bind to a TCP port")
+  }
   await new Promise((resolve) => server.close(() => resolve(undefined)))
   return address.port
 }