socketduct 0.1.24 → 0.1.26

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

@@ -1,11 +1,10 @@
 /* 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, readFile, readdir, 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 {connect as connectTls} from "node:tls"
 
 import {ReverseGatewayConnection} from "../../src/reverse/client.js"
@@ -46,7 +45,9 @@ async function listen(server) {
     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")
+  }
   return address.port
 }
 
@@ -164,335 +165,344 @@ async function onceEvent(emitter, event) {
   })
 }
 
-test("reserved reverse-hub startup retries a pre-start listen EADDRINUSE without leaking attempts", async (t) => {
-  const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-port-retry-"))
-  t.after(() => rm(root, {recursive: true, force: true}))
-  const certificates = generateTestCertificates(root)
-  const occupiedListener = createServer()
-  const occupiedPort = await listen(occupiedListener)
-  t.after(() => new Promise((resolve) => occupiedListener.close(() => resolve(undefined))))
-  let reservations = 0
-  const {child, port, attempts} = 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:process-gateway-token,tensorbuzz:process-client-token",
-    SOCKETDUCT_REVERSE_GATEWAY_BINDINGS: "o2:home-o2",
-    SOCKETDUCT_REVERSE_ROUTES: "tensorbuzz:o2:127.0.0.1:1",
-    SOCKETDUCT_STATUS_INTERVAL_MS: "0"
-  }, "reverse-hub.started", {
-    reservePort: async () => {
-      reservations += 1
-      return reservations === 1 ? occupiedPort : reservePort()
-    }
-  })
-  t.after(() => stopProcess(child))
+describe("reverse gateway process", () => {
+  it("reserved reverse-hub startup retries a pre-start listen EADDRINUSE without leaking attempts", async () => withTestCleanup(async (after) => {
+    const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-port-retry-"))
+    after(() => rm(root, {recursive: true, force: true}))
+    const certificates = generateTestCertificates(root)
+    const occupiedListener = createServer()
+    const occupiedPort = await listen(occupiedListener)
+    after(() => new Promise((resolve) => occupiedListener.close(() => resolve(undefined))))
+    let reservations = 0
+    const {child, port, attempts} = 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:process-gateway-token,tensorbuzz:process-client-token",
+      SOCKETDUCT_REVERSE_GATEWAY_BINDINGS: "o2:home-o2",
+      SOCKETDUCT_REVERSE_ROUTES: "tensorbuzz:o2:127.0.0.1:1",
+      SOCKETDUCT_STATUS_INTERVAL_MS: "0"
+    }, "reverse-hub.started", {
+      reservePort: async () => {
+        reservations += 1
+        return reservations === 1 ? occupiedPort : reservePort()
+      }
+    })
+    after(() => stopProcess(child))
 
-  assert.equal(reservations, 2)
-  assert.notEqual(port, occupiedPort)
-  assert.equal(attempts.length, 2)
-  const [failedAttempt, successfulAttempt] = attempts
-  assert(failedAttempt !== undefined)
-  assert(successfulAttempt !== undefined)
-  assert(failedAttempt.exitCode !== null || failedAttempt.signalCode !== null)
-  assert.equal(successfulAttempt, child)
-  assert.equal(child.exitCode, null)
-  assert.equal(child.signalCode, null)
-  assert.equal(occupiedListener.listening, true)
+    expect(reservations).toBe(2)
+    expect(port).not.toBe(occupiedPort)
+    expect(attempts.length).toBe(2)
+    const [failedAttempt, successfulAttempt] = attempts
+    if (failedAttempt === undefined || successfulAttempt === undefined) throw new Error("Expected two startup attempts")
+    expect(failedAttempt.exitCode !== null || failedAttempt.signalCode !== null).toBeTruthy()
+    expect(successfulAttempt).toBe(child)
+    expect(child.exitCode).toBe(null)
+    expect(child.signalCode).toBe(null)
+    expect(occupiedListener.listening).toBe(true)
 
-  await stopProcess(child)
-  assert(child.exitCode !== null || child.signalCode !== null)
-  const releasedPortProbe = createServer()
-  t.after(() => {
-    if (!releasedPortProbe.listening) return undefined
-    return new Promise((resolve) => releasedPortProbe.close(() => resolve(undefined)))
-  })
-  await new Promise((resolve, reject) => {
-    releasedPortProbe.once("error", reject)
-    releasedPortProbe.listen(port, "127.0.0.1", () => {
-      releasedPortProbe.off("error", reject)
-      resolve(undefined)
+    await stopProcess(child)
+    expect(child.exitCode !== null || child.signalCode !== null).toBeTruthy()
+    const releasedPortProbe = createServer()
+    after(() => {
+      if (!releasedPortProbe.listening) return undefined
+      return new Promise((resolve) => releasedPortProbe.close(() => resolve(undefined)))
     })
-  })
-})
+    await new Promise((resolve, reject) => {
+      releasedPortProbe.once("error", reject)
+      releasedPortProbe.listen(port, "127.0.0.1", () => {
+        releasedPortProbe.off("error", reject)
+        resolve(undefined)
+      })
+    })
+  }))
 
-test("reserved process startup does not retry an unclassified EADDRINUSE failure", async () => {
-  const failure = new Error("untrusted EADDRINUSE text is not a listener-bind classification")
-  let reservations = 0
-  let starts = 0
-  await assert.rejects(startProcessOnReservedPort({}, "reverse-hub.started", {
-    reservePort: async () => {
-      reservations += 1
-      return 31_337
-    },
-    startProcess: async () => {
-      starts += 1
-      throw failure
+  it("reserved process startup does not retry an unclassified EADDRINUSE failure", async () => {
+    const failure = new Error("untrusted EADDRINUSE text is not a listener-bind classification")
+    let reservations = 0
+    let starts = 0
+    let error
+    try {
+      await startProcessOnReservedPort({}, "reverse-hub.started", {
+        reservePort: async () => {
+          reservations += 1
+          return 31_337
+        },
+        startProcess: async () => {
+          starts += 1
+          throw failure
+        }
+      })
+    } catch (caught) {
+      error = caught
     }
-  }), (error) => error === failure)
-  assert.equal(reservations, 1)
-  assert.equal(starts, 1)
-})
-
-test("spawned reverse hub and outbound gateway expose an allowlisted Docker stream over verified TLS", async (t) => {
-  const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-process-"))
-  t.after(() => rm(root, {recursive: true, force: true}))
-  const certificates = generateTestCertificates(root)
-  const logDirectory = join(root, "logs")
-  const targetSockets = new Set()
-  const target = createServer((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)))
+    expect(error).toBeDefined()
+    expect(error === failure).toBeTruthy()
+    expect(reservations).toBe(1)
+    expect(starts).toBe(1)
   })
-  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:process-gateway-token,tensorbuzz:process-client-token",
-    SOCKETDUCT_REVERSE_GATEWAY_BINDINGS: "o2:home-o2",
-    SOCKETDUCT_REVERSE_ROUTES: `tensorbuzz:o2:127.0.0.1:${targetPort}`,
-    SOCKETDUCT_STATUS_INTERVAL_MS: "0",
-    SOCKETDUCT_LOG_DIRECTORY: logDirectory,
-    SOCKETDUCT_LOG_SEGMENT_MAX_BYTES: "4096",
-    SOCKETDUCT_CONNECTION_FINGERPRINT_KEY: TEST_FINGERPRINT_KEY,
-    SOCKETDUCT_CONNECTION_FINGERPRINT_KEY_EPOCH: "process-test"
-  }, "reverse-hub.started")
-  t.after(() => stopProcess(hub))
-  const gateway = await startProcess({
-    SOCKETDUCT_MODE: "reverse-gateway",
-    SOCKETDUCT_REVERSE_GATEWAY_ID: "o2",
-    SOCKETDUCT_REVERSE_CONNECTION_ID: "process_home_o2_gateway",
-    SOCKETDUCT_REVERSE_HUB_HOST: "127.0.0.1",
-    SOCKETDUCT_REVERSE_HUB_PORT: String(hubPort),
-    SOCKETDUCT_REVERSE_TOKEN: "process-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_LOG_DIRECTORY: logDirectory,
-    SOCKETDUCT_LOG_SEGMENT_MAX_BYTES: "4096"
-  }, "reverse-gateway.started")
-  t.after(() => stopProcess(gateway))
 
-  const client = new ReverseGatewayConnection({
-    gatewayId: "o2",
-    connectionId: "process_tensorbuzz_client",
-    hub: {host: "127.0.0.1", port: hubPort, token: "process-client-token"},
-    tls: {caFile: certificates.caCertFile, servername: "localhost"}
-  })
-  t.after(() => client.close())
-  await withTimeout(client.connect(), "process client connect")
-  const socket = client.createConnection({host: "127.0.0.1", port: targetPort, sessionName: "docker-version-process"})
-  await withTimeout(onceEvent(socket, "connect"), "process stream open")
-  const response = new Promise((resolve, reject) => { socket.once("error", reject); socket.once("data", resolve) })
-  socket.write("GET /version")
-  assert.equal(Buffer.from(/** @type {Uint8Array} */ (await withTimeout(response, "process response"))).toString(), "docker:GET /version")
-  assert.equal(client.status().compression, "zstd")
-  socket.destroy()
-  client.close()
-  await stopProcess(gateway)
-  await stopProcess(hub)
+  it("spawned reverse hub and outbound gateway expose an allowlisted Docker stream over verified TLS", async () => withTestCleanup(async (after) => {
+    const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-process-"))
+    after(() => rm(root, {recursive: true, force: true}))
+    const certificates = generateTestCertificates(root)
+    const logDirectory = join(root, "logs")
+    const targetSockets = new Set()
+    const target = createServer((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)
+    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:process-gateway-token,tensorbuzz:process-client-token",
+      SOCKETDUCT_REVERSE_GATEWAY_BINDINGS: "o2:home-o2",
+      SOCKETDUCT_REVERSE_ROUTES: `tensorbuzz:o2:127.0.0.1:${targetPort}`,
+      SOCKETDUCT_STATUS_INTERVAL_MS: "0",
+      SOCKETDUCT_LOG_DIRECTORY: logDirectory,
+      SOCKETDUCT_LOG_SEGMENT_MAX_BYTES: "4096",
+      SOCKETDUCT_CONNECTION_FINGERPRINT_KEY: TEST_FINGERPRINT_KEY,
+      SOCKETDUCT_CONNECTION_FINGERPRINT_KEY_EPOCH: "process-test"
+    }, "reverse-hub.started")
+    after(() => stopProcess(hub))
+    const gateway = await startProcess({
+      SOCKETDUCT_MODE: "reverse-gateway",
+      SOCKETDUCT_REVERSE_GATEWAY_ID: "o2",
+      SOCKETDUCT_REVERSE_CONNECTION_ID: "process_home_o2_gateway",
+      SOCKETDUCT_REVERSE_HUB_HOST: "127.0.0.1",
+      SOCKETDUCT_REVERSE_HUB_PORT: String(hubPort),
+      SOCKETDUCT_REVERSE_TOKEN: "process-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_LOG_DIRECTORY: logDirectory,
+      SOCKETDUCT_LOG_SEGMENT_MAX_BYTES: "4096"
+    }, "reverse-gateway.started")
+    after(() => stopProcess(gateway))
 
-  const logs = await readCompressedLogDirectory(logDirectory)
-  assert.equal(logs.incomplete, false)
-  const hubEntries = logs.records.filter(({role}) => role === "reverse-hub")
-  const gatewayEntries = logs.records.filter(({role}) => role === "reverse-gateway")
-  assert(hubEntries.some(({event}) => event === "process.started"))
-  assert(gatewayEntries.some(({event}) => event === "process.started"))
-  assert(gatewayEntries.some(({event}) => event === "transport.connected"))
-  assert.doesNotMatch(JSON.stringify(logs.records), /process-gateway-token|127\.0\.0\.1|docker-server|process_home_o2_gateway/)
-})
+    const client = new ReverseGatewayConnection({
+      gatewayId: "o2",
+      connectionId: "process_tensorbuzz_client",
+      hub: {host: "127.0.0.1", port: hubPort, token: "process-client-token"},
+      tls: {caFile: certificates.caCertFile, servername: "localhost"}
+    })
+    after(() => client.close())
+    await withTimeout(client.connect(), "process client connect")
+    const socket = client.createConnection({host: "127.0.0.1", port: targetPort, sessionName: "docker-version-process"})
+    await withTimeout(onceEvent(socket, "connect"), "process stream open")
+    const response = new Promise((resolve, reject) => { socket.once("error", reject); socket.once("data", resolve) })
+    socket.write("GET /version")
+    expect(Buffer.from(/** @type {Uint8Array} */ (await withTimeout(response, "process response"))).toString()).toBe("docker:GET /version")
+    expect(client.status().compression).toBe("zstd")
+    socket.destroy()
+    client.close()
+    await stopProcess(gateway)
+    await stopProcess(hub)
 
-test("one route-class client physical connection interleaves streams through different gateway processes", async (t) => {
-  const root = await mkdtemp(join(tmpdir(), "socketduct-route-class-process-"))
-  t.after(() => rm(root, {recursive: true, force: true}))
-  const certificates = generateTestCertificates(root)
-  const targetSockets = new Set()
-  const targetA = createServer((socket) => {
-    targetSockets.add(socket)
-    socket.once("close", () => targetSockets.delete(socket))
-    socket.on("data", (chunk) => socket.write(Buffer.concat([Buffer.from("a:"), chunk])))
-  })
-  const targetB = createServer((socket) => {
-    targetSockets.add(socket)
-    socket.once("close", () => targetSockets.delete(socket))
-    socket.on("data", (chunk) => socket.write(Buffer.concat([Buffer.from("b:"), chunk])))
-  })
-  const targetAPort = await listen(targetA)
-  const targetBPort = await listen(targetB)
-  t.after(() => {
-    for (const socket of targetSockets) socket.destroy()
-    return Promise.all([
-      new Promise((resolve) => targetA.close(() => resolve(undefined))),
-      new Promise((resolve) => targetB.close(() => resolve(undefined)))
-    ])
-  })
+    const logs = await readCompressedLogDirectory(logDirectory)
+    expect(logs.incomplete).toBe(false)
+    const hubEntries = logs.records.filter(({role}) => role === "reverse-hub")
+    const gatewayEntries = logs.records.filter(({role}) => role === "reverse-gateway")
+    expect(hubEntries.some(({event}) => event === "process.started")).toBeTruthy()
+    expect(gatewayEntries.some(({event}) => event === "process.started")).toBeTruthy()
+    expect(gatewayEntries.some(({event}) => event === "transport.connected")).toBeTruthy()
+    expect(JSON.stringify(logs.records)).not.toMatch(/process-gateway-token|127\.0\.0\.1|docker-server|process_home_o2_gateway/)
+  }))
 
-  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-a:gateway-a-token,home-b:gateway-b-token,tensorbuzz:client-token",
-    SOCKETDUCT_REVERSE_GATEWAY_BINDINGS: "server-a-starlink:home-a,server-b-starlink:home-b",
-    SOCKETDUCT_REVERSE_ROUTE_CLASS_ROUTES: `tensorbuzz:starlink:server-a-starlink:127.0.0.1:${targetAPort},tensorbuzz:starlink:server-b-starlink:127.0.0.1:${targetBPort}`,
-    SOCKETDUCT_STATUS_INTERVAL_MS: "0"
-  }, "reverse-hub.started")
-  t.after(() => stopProcess(hub))
+  it("one route-class client physical connection interleaves streams through different gateway processes", async () => withTestCleanup(async (after) => {
+    const root = await mkdtemp(join(tmpdir(), "socketduct-route-class-process-"))
+    after(() => rm(root, {recursive: true, force: true}))
+    const certificates = generateTestCertificates(root)
+    const targetSockets = new Set()
+    const targetA = createServer((socket) => {
+      targetSockets.add(socket)
+      socket.once("close", () => targetSockets.delete(socket))
+      socket.on("data", (chunk) => socket.write(Buffer.concat([Buffer.from("a:"), chunk])))
+    })
+    const targetB = createServer((socket) => {
+      targetSockets.add(socket)
+      socket.once("close", () => targetSockets.delete(socket))
+      socket.on("data", (chunk) => socket.write(Buffer.concat([Buffer.from("b:"), chunk])))
+    })
+    const targetAPort = await listen(targetA)
+    const targetBPort = await listen(targetB)
+    after(() => {
+      for (const socket of targetSockets) socket.destroy()
+      return Promise.all([
+        new Promise((resolve) => targetA.close(() => resolve(undefined))),
+        new Promise((resolve) => targetB.close(() => resolve(undefined)))
+      ]).then(() => undefined)
+    })
 
-  const gatewayA = await startProcess({
-    SOCKETDUCT_MODE: "reverse-gateway",
-    SOCKETDUCT_REVERSE_GATEWAY_ID: "server-a-starlink",
-    SOCKETDUCT_REVERSE_CONNECTION_ID: "route_class_process_gateway_a",
-    SOCKETDUCT_REVERSE_HUB_HOST: "127.0.0.1",
-    SOCKETDUCT_REVERSE_HUB_PORT: String(hubPort),
-    SOCKETDUCT_REVERSE_TOKEN: "gateway-a-token",
-    SOCKETDUCT_REVERSE_HUB_CA_FILE: certificates.caCertFile,
-    SOCKETDUCT_REVERSE_HUB_SERVERNAME: "localhost",
-    SOCKETDUCT_TARGET_ALLOWLIST: `127.0.0.1:${targetAPort}`,
-    SOCKETDUCT_STATUS_INTERVAL_MS: "0"
-  }, "reverse-gateway.started")
-  t.after(() => stopProcess(gatewayA))
-  const gatewayB = await startProcess({
-    SOCKETDUCT_MODE: "reverse-gateway",
-    SOCKETDUCT_REVERSE_GATEWAY_ID: "server-b-starlink",
-    SOCKETDUCT_REVERSE_CONNECTION_ID: "route_class_process_gateway_b",
-    SOCKETDUCT_REVERSE_HUB_HOST: "127.0.0.1",
-    SOCKETDUCT_REVERSE_HUB_PORT: String(hubPort),
-    SOCKETDUCT_REVERSE_TOKEN: "gateway-b-token",
-    SOCKETDUCT_REVERSE_HUB_CA_FILE: certificates.caCertFile,
-    SOCKETDUCT_REVERSE_HUB_SERVERNAME: "localhost",
-    SOCKETDUCT_TARGET_ALLOWLIST: `127.0.0.1:${targetBPort}`,
-    SOCKETDUCT_STATUS_INTERVAL_MS: "0"
-  }, "reverse-gateway.started")
-  t.after(() => stopProcess(gatewayB))
+    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-a:gateway-a-token,home-b:gateway-b-token,tensorbuzz:client-token",
+      SOCKETDUCT_REVERSE_GATEWAY_BINDINGS: "server-a-starlink:home-a,server-b-starlink:home-b",
+      SOCKETDUCT_REVERSE_ROUTE_CLASS_ROUTES: `tensorbuzz:starlink:server-a-starlink:127.0.0.1:${targetAPort},tensorbuzz:starlink:server-b-starlink:127.0.0.1:${targetBPort}`,
+      SOCKETDUCT_STATUS_INTERVAL_MS: "0"
+    }, "reverse-hub.started")
+    after(() => stopProcess(hub))
 
-  let clientPhysicalConnections = 0
-  const client = new ReverseGatewayConnection({
-    routeClass: "starlink",
-    connectionId: "route_class_process_client",
-    hub: {host: "127.0.0.1", port: hubPort, token: "client-token"},
-    tls: {caFile: certificates.caCertFile, servername: "localhost"},
-    createPhysicalSocket: ({host, port, tls}) => {
-      clientPhysicalConnections += 1
-      return connectTls({host, port, ...tls})
-    }
-  })
-  t.after(() => client.close())
-  await withTimeout(client.connect(), "route-class process client connect")
-  const streamA = client.createConnection({host: "127.0.0.1", port: targetAPort, sessionName: "route-class-a"})
-  const streamB = client.createConnection({host: "127.0.0.1", port: targetBPort, sessionName: "route-class-b"})
-  await withTimeout(Promise.all([onceEvent(streamA, "connect"), onceEvent(streamB, "connect")]), "route-class process streams")
-  const responseA = new Promise((resolve, reject) => { streamA.once("error", reject); streamA.once("data", resolve) })
-  const responseB = new Promise((resolve, reject) => { streamB.once("error", reject); streamB.once("data", resolve) })
-  streamA.write("one")
-  streamB.write("two")
-  assert.equal(Buffer.from(/** @type {Uint8Array} */ (await withTimeout(responseA, "route-class response A"))).toString(), "a:one")
-  assert.equal(Buffer.from(/** @type {Uint8Array} */ (await withTimeout(responseB, "route-class response B"))).toString(), "b:two")
-  assert.equal(clientPhysicalConnections, 1)
-  assert.equal(client.status().physicalConnects, 1)
-  streamA.destroy()
-  streamB.destroy()
-})
+    const gatewayA = await startProcess({
+      SOCKETDUCT_MODE: "reverse-gateway",
+      SOCKETDUCT_REVERSE_GATEWAY_ID: "server-a-starlink",
+      SOCKETDUCT_REVERSE_CONNECTION_ID: "route_class_process_gateway_a",
+      SOCKETDUCT_REVERSE_HUB_HOST: "127.0.0.1",
+      SOCKETDUCT_REVERSE_HUB_PORT: String(hubPort),
+      SOCKETDUCT_REVERSE_TOKEN: "gateway-a-token",
+      SOCKETDUCT_REVERSE_HUB_CA_FILE: certificates.caCertFile,
+      SOCKETDUCT_REVERSE_HUB_SERVERNAME: "localhost",
+      SOCKETDUCT_TARGET_ALLOWLIST: `127.0.0.1:${targetAPort}`,
+      SOCKETDUCT_STATUS_INTERVAL_MS: "0"
+    }, "reverse-gateway.started")
+    after(() => stopProcess(gatewayA))
+    const gatewayB = await startProcess({
+      SOCKETDUCT_MODE: "reverse-gateway",
+      SOCKETDUCT_REVERSE_GATEWAY_ID: "server-b-starlink",
+      SOCKETDUCT_REVERSE_CONNECTION_ID: "route_class_process_gateway_b",
+      SOCKETDUCT_REVERSE_HUB_HOST: "127.0.0.1",
+      SOCKETDUCT_REVERSE_HUB_PORT: String(hubPort),
+      SOCKETDUCT_REVERSE_TOKEN: "gateway-b-token",
+      SOCKETDUCT_REVERSE_HUB_CA_FILE: certificates.caCertFile,
+      SOCKETDUCT_REVERSE_HUB_SERVERNAME: "localhost",
+      SOCKETDUCT_TARGET_ALLOWLIST: `127.0.0.1:${targetBPort}`,
+      SOCKETDUCT_STATUS_INTERVAL_MS: "0"
+    }, "reverse-gateway.started")
+    after(() => stopProcess(gatewayB))
 
-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")
+    let clientPhysicalConnections = 0
+    const client = new ReverseGatewayConnection({
+      routeClass: "starlink",
+      connectionId: "route_class_process_client",
+      hub: {host: "127.0.0.1", port: hubPort, token: "client-token"},
+      tls: {caFile: certificates.caCertFile, servername: "localhost"},
+      createPhysicalSocket: ({host, port, tls}) => {
+        clientPhysicalConnections += 1
+        return connectTls({host, port, ...tls})
+      }
+    })
+    after(() => client.close())
+    await withTimeout(client.connect(), "route-class process client connect")
+    const streamA = client.createConnection({host: "127.0.0.1", port: targetAPort, sessionName: "route-class-a"})
+    const streamB = client.createConnection({host: "127.0.0.1", port: targetBPort, sessionName: "route-class-b"})
+    await withTimeout(Promise.all([onceEvent(streamA, "connect"), onceEvent(streamB, "connect")]), "route-class process streams")
+    const responseA = new Promise((resolve, reject) => { streamA.once("error", reject); streamA.once("data", resolve) })
+    const responseB = new Promise((resolve, reject) => { streamB.once("error", reject); streamB.once("data", resolve) })
+    streamA.write("one")
+    streamB.write("two")
+    expect(Buffer.from(/** @type {Uint8Array} */ (await withTimeout(responseA, "route-class response A"))).toString()).toBe("a:one")
+    expect(Buffer.from(/** @type {Uint8Array} */ (await withTimeout(responseB, "route-class response B"))).toString()).toBe("b:two")
+    expect(clientPhysicalConnections).toBe(1)
+    expect(client.status().physicalConnects).toBe(1)
+    streamA.destroy()
+    streamB.destroy()
+  }))
 
-  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
+  it("outbound gateway process spools durably under SOCKETDUCT_SPOOL_DIRECTORY when the hub link is lost", async () => withTestCleanup(async (after) => {
+    const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-spool-process-"))
+    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)
+    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")
+    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
+    })
+    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")
+    expect(Buffer.from(/** @type {Uint8Array} */ (await withTimeout(initialResponse, "spool initial response"))).toString()).toBe("docker:GET /version")
+
+    hub.kill("SIGKILL")
+    await withTimeout(new Promise((resolve) => hub.once("exit", () => resolve(undefined))), "hub exit")
+    if (targetSocket === undefined) throw new Error("Expected a live target socket")
+    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
     }
-    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")
+    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"))
+    // Spool must not fall back to the ephemeral default root.
+    expect(defaultSpooled).toBe(false)
 
-  socket.destroy()
-  client.close()
-  await stopProcess(gateway)
+    socket.destroy()
+    client.close()
+    await stopProcess(gateway)
+  }))
 })