socketduct 0.1.24 → 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.24",
+  "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/client/multiplexed-transport-set.js

@@ -44,6 +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 {number} connectionGeneration - Current authenticated generation.
  * @property {number} physicalConnects - Authenticated physical generations.
  * @property {number} reconnectAttempts - Physical reconnect attempts.
@@ -569,17 +570,34 @@ export class MultiplexedSocketductTransportSet extends EventEmitter {
     return this.#closePromise
   }
 
-  /** @returns {{member: TransportMember, previousCursor: number} | undefined} */
+  /**
+   * Selects the next ready member, preferring members whose gateway the hub has
+   * not recently reported unavailable. When every ready member carries a
+   * gateway-unavailable mark, any ready member may still be selected so a stale
+   * mark can never wedge the set.
+   * @returns {{member: TransportMember, previousCursor: number} | undefined}
+   */
   #selectReadyMember() {
     if (this.#closed) throw closedError()
     const previousCursor = this.#cursor
+    /** @type {{member: TransportMember, index: number} | undefined} */
+    let fallback
     for (let offset = 0; offset < this.#members.length; offset += 1) {
       const index = (this.#cursor + offset) % this.#members.length
       const member = /** @type {TransportMember} */ (this.#members[index])
-      if (member.connection.status().physicalState !== "ready") continue
+      const status = member.connection.status()
+      if (status.physicalState !== "ready") continue
+      if (status.gatewayUnavailable === true) {
+        fallback ??= {member, index}
+        continue
+      }
       this.#cursor = (index + 1) % this.#members.length
       return {member, previousCursor}
     }
+    if (fallback !== undefined) {
+      this.#cursor = (fallback.index + 1) % this.#members.length
+      return {member: fallback.member, previousCursor}
+    }
     return undefined
   }
 

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/src/reverse/client.js

@@ -32,6 +32,7 @@ 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
@@ -168,6 +169,7 @@ export class ReverseGatewayConnection extends EventEmitter {
   /** @type {number} */ #spoolBytes = 0
   /** @type {number} */ #spoolCleanupFailures = 0
   /** @type {Set<Promise<void>>} */ #spoolCleanupTasks = new Set()
+  /** @type {number | undefined} - Wall-clock time of the last hub-reported gateway unavailability. */ #gatewayUnavailableSince
   /** @type {import('./disconnect-attribution.js').DisconnectAttribution | undefined} */ #disconnectAttribution
 
   /** @param {ReverseGatewayConnectionOptions} options - Hub route and safety policy. */
@@ -352,12 +354,41 @@ export class ReverseGatewayConnection extends EventEmitter {
     return socket
   }
 
+  /**
+   * Records that the hub just reported no selectable gateway for this member's
+   * route class, so the transport set can prefer members that can actually open.
+   * @param {string} code - Hub reset code.
+   * @returns {void}
+   */
+  #markGatewayUnavailable(code) {
+    const firstMark = this.#gatewayUnavailableSince === undefined
+    this.#gatewayUnavailableSince = Date.now()
+    if (firstMark) {
+      logDiagnostic(this.#options.logger, "reverse_client.gateway_unavailable", {
+        code,
+        generation: this.#generation,
+        ...this.#routeIdentityFields()
+      })
+    }
+  }
+
+  /**
+   * 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.
+   */
+  #gatewayUnavailable() {
+    return this.#gatewayUnavailableSince !== undefined
+      && Date.now() - this.#gatewayUnavailableSince < GATEWAY_UNAVAILABLE_TTL_MS
+  }
+
   status() {
     /** @type {Record<string, number>} */
     const streamStates = {}
     for (const stream of this.#streams.values()) streamStates[stream.state] = (streamStates[stream.state] ?? 0) + 1
     return {
       physicalState: this.#state,
+      gatewayUnavailable: this.#gatewayUnavailable(),
       connectionGeneration: this.#generation,
       virtualStreams: this.#streams.size,
       streamStates,
@@ -623,6 +654,8 @@ export class ReverseGatewayConnection extends EventEmitter {
             const selection = this.#routeIdentityFields()
             if (detail.generation !== generation || ("gatewayId" in selection ? detail.gatewayId !== selection.gatewayId || Object.hasOwn(detail, "routeClass") : detail.routeClass !== selection.routeClass || Object.hasOwn(detail, "gatewayId"))) throw fatalError("GATEWAY_SELECTION_FAILED")
             if (typeof detail.resumed !== "boolean") throw fatalError("GATEWAY_SELECTION_FAILED")
+            if (detail.selectable === true) this.#gatewayUnavailableSince = undefined
+            else if (detail.selectable === false) this.#markGatewayUnavailable("GATEWAY_SELECT_UNAVAILABLE")
             selected = true
             if (detail.resumed) {
               clearTimeout(timer)
@@ -745,9 +778,16 @@ export class ReverseGatewayConnection extends EventEmitter {
       const detail = decodeV3Control(frame.payload)
       if (stream.state !== "opening" || frame.sequence !== 0 || detail.identifier !== stream.identifier || !validPeerWindow(detail.initialWindow)) throw new Error("Invalid reverse OPENED response")
       stream.sendWindowLimit = Math.min(stream.sendWindowLimit, detail.initialWindow)
-      stream.sendWindow = Math.min(stream.sendWindow, stream.sendWindowLimit)
+      stream.sendWindow = Math.min(stream.sendWindow, detail.initialWindow)
       stream.state = stream.localEnded ? "half-closed" : "open"
       stream.opened = true
+      if (this.#gatewayUnavailableSince !== undefined) {
+        this.#gatewayUnavailableSince = undefined
+        logDiagnostic(this.#options.logger, "reverse_client.gateway_available", {
+          generation: this.#generation,
+          ...this.#routeIdentityFields()
+        })
+      }
       logDiagnostic(this.#options.logger, "virtual_stream.opened", {
         streamId: stream.id,
         generation: this.#generation,
@@ -801,6 +841,9 @@ export class ReverseGatewayConnection extends EventEmitter {
       const detail = decodeV3Control(frame.payload)
       const code = typeof detail.code === "string" ? detail.code : "STREAM_RESET"
       stream.state = "reset"
+      if (code === "GATEWAY_UNAVAILABLE" || code === "GATEWAY_DISCONNECTED" || code === "GATEWAY_REPLACED") {
+        this.#markGatewayUnavailable(code)
+      }
       const error = attachDisconnectAttribution(new SocketductStreamError("Reverse gateway stream was reset", code), validHubAttribution(detail) ?? (code === "GATEWAY_DISCONNECTED" ? this.#disconnectAttribution : undefined))
       stream.socket._receiveError(error)
       return

package/src/reverse/hub.js

@@ -49,6 +49,7 @@ const MANIFEST_PAGE_STREAMS = 64
  * @property {(input: {principal: Principal, gatewayId: string}) => boolean} authorizeGateway - Stable gateway identity binding.
  * @property {(input: {principal: Principal, gatewayId: string}) => boolean} authorizeClientGateway - Client-to-gateway selection policy.
  * @property {(input: {principal: Principal, routeClass: string}) => boolean} [authorizeClientRouteClass] - Client-to-route-class selection policy.
+ * @property {(input: {principal: Principal, routeClass: string}) => string[]} [resolveRouteClassGateways] - All configured gateways for a client route class, used to announce route-class availability at selection time.
  * @property {(input: {principal: Principal, gatewayId: string, target: Target}) => boolean} authorizeOpen - Hub-side route policy.
  * @property {(input: {principal: Principal, routeClass: string, target: Target}) => string[]} [resolveOpenGateways] - Eligible exact gateways for a route-class OPEN.
  * @property {string[]} [knownGatewayIds] - Configured IDs that may be temporarily unavailable.
@@ -480,7 +481,15 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
     if (clientOwner.gatewayId !== undefined || (clientOwner.routeClass !== undefined && clientOwner.routeClass !== request.routeClass)) throw protocolError("GATEWAY_SELECTION_MISMATCH")
     physical.routeClass = request.routeClass
     clientOwner.routeClass = request.routeClass
-    await sendControl(physical, V3FrameType.GATEWAY_SELECTED, 0, physical.generation, {routeClass: request.routeClass, generation: physical.generation, resumed: physical.resumeRequired})
+    const configuredGatewayIds = options.resolveRouteClassGateways?.({principal: physical.principal, routeClass: request.routeClass})
+    let selectable
+    if (Array.isArray(configuredGatewayIds) && configuredGatewayIds.length > 0) {
+      selectable = configuredGatewayIds.some((gatewayId) => {
+        const owner = gateways.get(gatewayId)
+        return owner !== undefined && owner.physical !== undefined && !owner.physical.socket.destroyed && !owner.physical.closing && !owner.physical.resumeRequired
+      })
+    }
+    await sendControl(physical, V3FrameType.GATEWAY_SELECTED, 0, physical.generation, {routeClass: request.routeClass, generation: physical.generation, resumed: physical.resumeRequired, ...(selectable === undefined ? {} : {selectable})})
     armResumeTimeout(physical)
   }
 

package/src/reverse/runtime.js

@@ -27,7 +27,15 @@ export async function startReverseHubRuntime(config, logger) {
     gatewayIds.push(route.gatewayId)
     routeClassGateways.set(key, gatewayIds)
   }
-  const routeClassRows = new Set(routeClassRoutes.map((route) => `${formatRouteClassRoute(route.username, route.routeClass, {host: route.host, port: route.port})}\0${route.gatewayId}`))
+  const routeClassRows = new Set(routeClassRoutes.map((route) => `${formatRouteClassRoute(route.username, route.routeClass, {host: route.host, port: route.port})}\\0${route.gatewayId}`))
+  /** @type {Map<string, string[]>} - Every configured gateway for a (username, routeClass) pair, independent of target. */
+  const routeClassGatewayUnions = new Map()
+  for (const route of routeClassRoutes) {
+    const key = `${route.username}\\0${route.routeClass}`
+    const gatewayIds = routeClassGatewayUnions.get(key) ?? []
+    if (!gatewayIds.includes(route.gatewayId)) gatewayIds.push(route.gatewayId)
+    routeClassGatewayUnions.set(key, gatewayIds)
+  }
   if (bindings.size !== config.reverseGatewayBindings.length) throw new Error("SOCKETDUCT_REVERSE_GATEWAY_BINDINGS contains a duplicate gateway ID")
   if (exactRouteKeys.size !== exactRoutes.length) throw new Error("SOCKETDUCT_REVERSE_ROUTES contains a duplicate route")
   if (routeClassRows.size !== routeClassRoutes.length) throw new Error("SOCKETDUCT_REVERSE_ROUTE_CLASS_ROUTES contains a duplicate route")
@@ -47,7 +55,8 @@ export async function startReverseHubRuntime(config, logger) {
     authorizeGateway: ({principal, gatewayId}) => bindings.get(gatewayId) === principal.username,
     authorizeClientGateway: ({principal, gatewayId}) => exactSelections.has(`${principal.username}\0${gatewayId}`),
     ...(knownRouteClasses.length === 0 ? {} : {
-      authorizeClientRouteClass: ({principal, routeClass}) => routeClassSelections.has(`${principal.username}\0${routeClass}`),
+      authorizeClientRouteClass: ({principal, routeClass}) => routeClassSelections.has(`${principal.username}\u0000${routeClass}`),
+      resolveRouteClassGateways: ({principal, routeClass}) => routeClassGatewayUnions.get(`${principal.username}\u0000${routeClass}`) ?? [],
       resolveOpenGateways: ({principal, routeClass, target}) => [...(routeClassGateways.get(formatRouteClassRoute(principal.username, routeClass, target)) ?? [])]
     }),
     authorizeOpen: ({principal, gatewayId, target}) => authorizedRoutes.has(formatRoute(principal.username, gatewayId, target)),

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
 }