socketduct 0.1.16 → 0.1.18

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

@@ -0,0 +1,377 @@
+/* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-param, jsdoc/require-returns */
+import assert from "node:assert/strict"
+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 {StaticTokenStore} from "../../src/auth/static-token-store.js"
+import {V3FrameType} from "../../src/protocol/v3-frame.js"
+import {OutboundReverseGateway, ReverseGatewayConnection, startReverseGatewayHub} from "../../src/reverse/index.js"
+import {generateTestCertificates} from "../helpers/tls-certificates.js"
+
+/** @param {import('node:net').Server} server - Server. */
+async function listen(server) {
+  await new Promise((resolve, reject) => {
+    server.once("error", reject)
+    server.listen(0, "127.0.0.1", () => { server.off("error", reject); resolve(undefined) })
+  })
+  const address = server.address()
+  assert(address !== null && typeof address !== "string")
+  return address.port
+}
+
+/** @param {import('node:events').EventEmitter} emitter - Source. @param {string} event - Event. */
+async function onceEvent(emitter, event) {
+  await new Promise((resolve, reject) => {
+    emitter.once("error", reject)
+    emitter.once(event, () => { emitter.off("error", reject); resolve(undefined) })
+  })
+}
+
+/** @param {import('node:stream').Duplex} socket - Stream. @returns {Promise<Error & {code?: string}>} Next stream error. */
+async function nextError(socket) {
+  return await new Promise((resolve) => socket.once("error", (error) => resolve(/** @type {Error & {code?: string}} */ (error))))
+}
+
+/** @param {Promise<unknown>} promise - Work. @param {string} label - Timeout label. */
+async function withTimeout(promise, label) {
+  let timer
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`Timed out: ${label}`)), 4_000) })
+    ])
+  } finally {
+    if (timer !== undefined) clearTimeout(timer)
+  }
+}
+
+/** @param {() => boolean} predicate - Completion predicate. @param {string} label - Failure label. */
+async function waitUntil(predicate, label) {
+  const deadline = Date.now() + 4_000
+  while (!predicate()) {
+    if (Date.now() >= deadline) throw new Error(`Timed out: ${label}`)
+    await new Promise((resolve) => setTimeout(resolve, 10))
+  }
+}
+
+/** @param {string} prefix - Echo response prefix. */
+async function createEchoTarget(prefix) {
+  const sockets = new Set()
+  const server = createServer((socket) => {
+    sockets.add(socket)
+    socket.once("close", () => sockets.delete(socket))
+    socket.on("data", (chunk) => socket.write(Buffer.concat([Buffer.from(prefix), chunk])))
+  })
+  const port = await listen(server)
+  return {
+    host: "127.0.0.1",
+    port,
+    close: async () => {
+      for (const socket of sockets) socket.destroy()
+      await new Promise((resolve) => server.close(() => resolve(undefined)))
+    }
+  }
+}
+
+/** @param {import('node:stream').Duplex} socket - Open stream. @param {string} payload - Request. */
+async function exchange(socket, payload) {
+  const response = new Promise((resolve, reject) => {
+    socket.once("error", reject)
+    socket.once("data", (chunk) => resolve(Buffer.from(chunk).toString()))
+  })
+  socket.write(payload)
+  return await withTimeout(response, `response for ${payload}`)
+}
+
+test("route-class clients fail closed per OPEN while unaffected routes and legacy exact clients remain usable", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-route-class-"))
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const certificates = generateTestCertificates(root)
+  const targetA = await createEchoTarget("a:")
+  const targetB = await createEchoTarget("b:")
+  t.after(() => targetA.close())
+  t.after(() => targetB.close())
+
+  const tokens = new StaticTokenStore([
+    {username: "home-a", token: "gateway-a-token"},
+    {username: "home-b", token: "gateway-b-token"},
+    {username: "tensorbuzz", token: "client-token"},
+    {username: "untrusted", token: "untrusted-token"}
+  ])
+  let ambiguousTargetA = false
+  const hub = await startReverseGatewayHub({
+    tokens,
+    tls: {certFile: certificates.serverCertFile, keyFile: certificates.serverKeyFile},
+    knownGatewayIds: ["server-a-starlink", "server-b-starlink"],
+    knownRouteClasses: ["starlink"],
+    authorizeGateway: ({principal, gatewayId}) => (
+      (principal.username === "home-a" && gatewayId === "server-a-starlink")
+      || (principal.username === "home-b" && gatewayId === "server-b-starlink")
+    ),
+    authorizeClientGateway: ({principal, gatewayId}) => principal.username === "tensorbuzz" && gatewayId === "server-a-starlink",
+    authorizeClientRouteClass: ({principal}) => principal.username === "tensorbuzz",
+    resolveOpenGateways: ({principal, routeClass, target}) => {
+      if (principal.username !== "tensorbuzz" || routeClass !== "starlink" || target.host !== "127.0.0.1") return []
+      if (target.port === targetA.port) return ambiguousTargetA ? ["server-a-starlink", "server-b-starlink"] : ["server-a-starlink"]
+      if (target.port === targetB.port) return ["server-b-starlink"]
+      return []
+    },
+    authorizeOpen: ({principal, gatewayId, target}) => principal.username === "tensorbuzz" && (
+      (gatewayId === "server-a-starlink" && target.host === targetA.host && target.port === targetA.port)
+      || (gatewayId === "server-b-starlink" && target.host === targetB.host && target.port === targetB.port)
+    )
+  })
+  t.after(() => hub.close())
+  const tls = {caFile: certificates.caCertFile, servername: "localhost"}
+  const gatewayA = new OutboundReverseGateway({
+    gatewayId: "server-a-starlink",
+    connectionId: "route_class_gateway_a",
+    hub: {host: "127.0.0.1", port: hub.port, token: "gateway-a-token"},
+    tls,
+    authorizeTarget: (target) => target.host === targetA.host && target.port === targetA.port,
+    reconnectDelayMs: 10,
+    maxReconnectDelayMs: 20
+  })
+  const gatewayB = new OutboundReverseGateway({
+    gatewayId: "server-b-starlink",
+    connectionId: "route_class_gateway_b",
+    hub: {host: "127.0.0.1", port: hub.port, token: "gateway-b-token"},
+    tls,
+    authorizeTarget: (target) => target.host === targetB.host && target.port === targetB.port,
+    reconnectDelayMs: 10,
+    maxReconnectDelayMs: 20
+  })
+  t.after(() => gatewayA.close())
+  t.after(() => gatewayB.close())
+  await Promise.all([gatewayA.start(), gatewayB.start()])
+
+  const unknown = new ReverseGatewayConnection({
+    routeClass: "missing",
+    connectionId: "route_class_unknown_client",
+    hub: {host: "127.0.0.1", port: hub.port, token: "client-token"},
+    tls,
+    continuousReconnect: false
+  })
+  t.after(() => unknown.close())
+  await assert.rejects(withTimeout(unknown.connect(), "unknown route class"), (error) => /** @type {{code?: string}} */ (error).code === "UNKNOWN_ROUTE_CLASS")
+
+  const unauthorized = new ReverseGatewayConnection({
+    routeClass: "starlink",
+    connectionId: "route_class_unauthorized_client",
+    hub: {host: "127.0.0.1", port: hub.port, token: "untrusted-token"},
+    tls,
+    continuousReconnect: false
+  })
+  t.after(() => unauthorized.close())
+  await assert.rejects(withTimeout(unauthorized.connect(), "unauthorized route class"), (error) => /** @type {{code?: string}} */ (error).code === "ROUTE_CLASS_UNAUTHORIZED")
+
+  const client = new ReverseGatewayConnection({
+    routeClass: "starlink",
+    connectionId: "route_class_tensorbuzz_client",
+    hub: {host: "127.0.0.1", port: hub.port, token: "client-token"},
+    tls
+  })
+  t.after(() => client.close())
+  await client.connect()
+  assert.equal(client.status().physicalConnects, 1)
+  assert.equal(hub.status().clientPhysicalConnections, 1)
+
+  const denied = client.createConnection({host: "127.0.0.1", port: 65_534})
+  assert.equal((await nextError(denied)).code, "TARGET_UNAUTHORIZED")
+
+  ambiguousTargetA = true
+  const ambiguous = client.createConnection({host: targetA.host, port: targetA.port})
+  assert.equal((await nextError(ambiguous)).code, "AMBIGUOUS_ROUTE")
+  ambiguousTargetA = false
+
+  const legacy = new ReverseGatewayConnection({
+    gatewayId: "server-a-starlink",
+    connectionId: "legacy_exact_gateway_client",
+    hub: {host: "127.0.0.1", port: hub.port, token: "client-token"},
+    tls
+  })
+  t.after(() => legacy.close())
+  await legacy.connect()
+  const legacyStream = legacy.createConnection({host: targetA.host, port: targetA.port})
+  await onceEvent(legacyStream, "connect")
+  assert.equal(await exchange(legacyStream, "legacy"), "a:legacy")
+  legacyStream.destroy()
+  await legacy.close()
+
+  const streamA = client.createConnection({host: targetA.host, port: targetA.port})
+  const streamB = client.createConnection({host: targetB.host, port: targetB.port})
+  await Promise.all([onceEvent(streamA, "connect"), onceEvent(streamB, "connect")])
+  assert.deepEqual(await Promise.all([exchange(streamA, "one"), exchange(streamB, "two")]), ["a:one", "b:two"])
+
+  const resumed = Promise.all([onceEvent(streamA, "ready"), onceEvent(streamB, "ready")])
+  await hub.closeActiveGateway("server-a-starlink")
+  await withTimeout(resumed, "route-class streams resume after gateway transport replacement")
+  await waitUntil(() => hub.status().healthyGateways === 2, "gateway A re-registration")
+  assert.equal(await exchange(streamA, "resumed"), "a:resumed")
+  assert.equal(await exchange(streamB, "still-open"), "b:still-open")
+
+  const anotherA = client.createConnection({host: targetA.host, port: targetA.port})
+  await onceEvent(anotherA, "connect")
+  assert.equal(await exchange(anotherA, "new-a"), "a:new-a")
+  const anotherB = client.createConnection({host: targetB.host, port: targetB.port})
+  await onceEvent(anotherB, "connect")
+  assert.equal(await exchange(anotherB, "new"), "b:new")
+
+  streamA.destroy()
+  anotherA.destroy()
+  await gatewayA.close()
+  const replacementA = new OutboundReverseGateway({
+    gatewayId: "server-a-starlink",
+    connectionId: "route_class_gateway_a",
+    initialGeneration: gatewayA.status().connectionGeneration,
+    hub: {host: "127.0.0.1", port: hub.port, token: "gateway-a-token"},
+    tls,
+    authorizeTarget: (target) => target.host === targetA.host && target.port === targetA.port
+  })
+  t.after(() => replacementA.close())
+  await replacementA.start()
+  const rejoinedA = client.createConnection({host: targetA.host, port: targetA.port})
+  await onceEvent(rejoinedA, "connect")
+  assert.equal(await exchange(rejoinedA, "rejoined"), "a:rejoined")
+  assert(client.status().physicalConnects >= 2)
+  assert.equal(hub.status().clientPhysicalConnections, 1)
+  streamB.destroy()
+  anotherB.destroy()
+  rejoinedA.destroy()
+})
+
+test("a backpressured gateway does not block DATA or a new OPEN for another route-class gateway", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-route-class-backpressure-"))
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const certificates = generateTestCertificates(root)
+  const targetA = await createEchoTarget("a:")
+  const targetB = await createEchoTarget("b:")
+  t.after(() => targetA.close())
+  t.after(() => targetB.close())
+
+  const hub = await startReverseGatewayHub({
+    tokens: new StaticTokenStore([
+      {username: "home-a", token: "gateway-a-token"},
+      {username: "home-b", token: "gateway-b-token"},
+      {username: "tensorbuzz", token: "client-token"}
+    ]),
+    tls: {certFile: certificates.serverCertFile, keyFile: certificates.serverKeyFile},
+    knownGatewayIds: ["server-a-starlink", "server-b-starlink"],
+    knownRouteClasses: ["starlink"],
+    authorizeGateway: ({principal, gatewayId}) => (
+      (principal.username === "home-a" && gatewayId === "server-a-starlink")
+      || (principal.username === "home-b" && gatewayId === "server-b-starlink")
+    ),
+    authorizeClientGateway: () => false,
+    authorizeClientRouteClass: ({principal, routeClass}) => principal.username === "tensorbuzz" && routeClass === "starlink",
+    resolveOpenGateways: ({routeClass, target}) => {
+      if (routeClass !== "starlink" || target.host !== "127.0.0.1") return []
+      if (target.port === targetA.port) return ["server-a-starlink"]
+      if (target.port === targetB.port) return ["server-b-starlink"]
+      return []
+    },
+    authorizeOpen: ({gatewayId, target}) => (
+      (gatewayId === "server-a-starlink" && target.port === targetA.port)
+      || (gatewayId === "server-b-starlink" && target.port === targetB.port)
+    ),
+    maxOutputBytesPerConnection: 1_024
+  })
+  t.after(() => hub.close())
+  /** @type {import('node:tls').TLSSocket[]} */
+  const accepted = []
+  hub.server.on("secureConnection", (socket) => accepted.push(socket))
+  const tls = {caFile: certificates.caCertFile, servername: "localhost"}
+  const gatewayA = new OutboundReverseGateway({
+    gatewayId: "server-a-starlink",
+    connectionId: "backpressure_gateway_a",
+    hub: {host: "127.0.0.1", port: hub.port, token: "gateway-a-token"},
+    tls,
+    authorizeTarget: (target) => target.host === targetA.host && target.port === targetA.port,
+    reconnectDelayMs: 10_000,
+    maxReconnectDelayMs: 10_000
+  })
+  const gatewayB = new OutboundReverseGateway({
+    gatewayId: "server-b-starlink",
+    connectionId: "backpressure_gateway_b",
+    hub: {host: "127.0.0.1", port: hub.port, token: "gateway-b-token"},
+    tls,
+    authorizeTarget: (target) => target.host === targetB.host && target.port === targetB.port,
+    reconnectDelayMs: 10_000,
+    maxReconnectDelayMs: 10_000
+  })
+  t.after(() => gatewayA.close())
+  t.after(() => gatewayB.close())
+  await gatewayA.start()
+  await gatewayB.start()
+  assert.equal(accepted.length, 2)
+
+  const client = new ReverseGatewayConnection({
+    routeClass: "starlink",
+    connectionId: "backpressure_route_client",
+    hub: {host: "127.0.0.1", port: hub.port, token: "client-token"},
+    tls,
+    continuousReconnect: false,
+    reconnectDelayMs: 10_000,
+    maxReconnectDelayMs: 10_000
+  })
+  t.after(() => client.close())
+  await client.connect()
+  const streamA = client.createConnection({host: targetA.host, port: targetA.port})
+  const streamB = client.createConnection({host: targetB.host, port: targetB.port})
+  await Promise.all([onceEvent(streamA, "connect"), onceEvent(streamB, "connect")])
+
+  const gatewayASocket = /** @type {import('node:tls').TLSSocket} */ (accepted[0])
+  const writable = /** @type {{write: (chunk: Buffer) => boolean}} */ (/** @type {unknown} */ (gatewayASocket))
+  const originalWrite = writable.write
+  let blocked = false
+  /** @type {() => void} */
+  let markBlocked = () => {}
+  const backpressured = new Promise((resolve) => { markBlocked = () => resolve(undefined) })
+  writable.write = (chunk) => {
+    const acceptedWrite = Reflect.apply(originalWrite, gatewayASocket, [chunk])
+    if (!blocked && chunk[5] === V3FrameType.DATA) {
+      blocked = true
+      markBlocked()
+      return false
+    }
+    return acceptedWrite
+  }
+  t.after(() => {
+    writable.write = originalWrite
+    if (blocked) gatewayASocket.emit("drain")
+  })
+
+  streamA.write("blocked")
+  await withTimeout(backpressured, "gateway A backpressure")
+  const newStreamB = client.createConnection({host: targetB.host, port: targetB.port})
+  t.after(() => newStreamB.destroy())
+  const newStreamBExchange = (async () => {
+    await onceEvent(newStreamB, "connect")
+    return await exchange(newStreamB, "new-open")
+  })()
+  assert.deepEqual(await withTimeout(Promise.all([
+    exchange(streamB, "existing"),
+    newStreamBExchange
+  ]), "healthy gateway progress while gateway A is backpressured"), ["b:existing", "b:new-open"])
+  assert.equal(client.status().physicalConnects, 1)
+  assert(hub.status().queuedOutputBytes > 0)
+  const streamAError = nextError(streamA)
+  const queuedAErrors = Array.from({length: 8}, () => {
+    const socket = client.createConnection({host: targetA.host, port: targetA.port, sessionName: "a".repeat(256)})
+    t.after(() => socket.destroy())
+    return nextError(socket)
+  })
+  assert.equal((await withTimeout(streamAError, "gateway A output limit")).code, "OUTPUT_BACKPRESSURE_LIMIT")
+  await withTimeout(Promise.all(queuedAErrors), "queued gateway A stream cleanup")
+  assert.equal(await exchange(streamB, "after-limit"), "b:after-limit")
+  assert.equal(hub.status().healthyGateways, 1)
+  assert.equal(hub.status().clientPhysicalConnections, 1)
+  assert.equal(client.status().physicalConnects, 1)
+  writable.write = originalWrite
+  assert.equal(hub.status().queuedOutputBytes, 0)
+  streamA.destroy()
+  streamB.destroy()
+})

package/test/unit/client/multiplexed-transport-set.test.js

@@ -260,6 +260,48 @@ test("validates stable gateway identities, pinned endpoints, and process limits"
   }
 })
 
+test("route-class members are first-class reverse transports with route-class allocation metadata", async () => {
+  /** @type {FakeMember[]} */
+  const members = []
+  const set = new MultiplexedSocketductTransportSet(/** @type {import('../../../src/client/multiplexed-transport-set.js').TransportSetOptions} */ (/** @type {unknown} */ ({
+    connectionId: "route_class_process_identity",
+    minimumReadyMembers: 1,
+    routeClasses: [
+      {routeClass: "starlink", endpoint: {reverseHub: {host: "hub.example", port: 3100, token: "starlink-token"}, tls: {servername: "hub.example"}}},
+      {routeClass: "zyxel", endpoint: {reverseHub: {host: "hub.example", port: 3100, token: "zyxel-token"}, tls: {servername: "hub.example"}}}
+    ]
+  })), {
+    createMember(memberOptions, routeClass) {
+      const member = new FakeMember(memberOptions, routeClass, undefined)
+      members.push(member)
+      return member
+    }
+  })
+
+  assert.deepEqual(members.map((member) => {
+    const memberOptions = /** @type {import('../../../src/reverse/client.js').ReverseGatewayConnectionOptions} */ (member.options)
+    return {gatewayId: memberOptions.gatewayId, routeClass: memberOptions.routeClass}
+  }), [
+    {gatewayId: undefined, routeClass: "starlink"},
+    {gatewayId: undefined, routeClass: "zyxel"}
+  ])
+  const connectionIds = members.map((member) => member.options.connectionId)
+  assert(connectionIds.every((connectionId) => typeof connectionId === "string"))
+  assert.equal(new Set(connectionIds).size, 2)
+
+  const started = set.start()
+  at(members, 0).ready()
+  await started
+  const socket = set.createConnection({host: "target.internal", port: 443})
+  assert.equal(/** @type {{gatewayId?: string}} */ (socket).gatewayId, undefined)
+  assert.equal(/** @type {{routeClass?: string}} */ (socket).routeClass, "starlink")
+  assert.deepEqual(set.status().members.map((member) => ({gatewayId: member.gatewayId, routeClass: member.routeClass})), [
+    {gatewayId: undefined, routeClass: "starlink"},
+    {gatewayId: undefined, routeClass: "zyxel"}
+  ])
+  await set.close()
+})
+
 test("logs transport-set startup, generation replacement, and terminal failure without error text", async () => {
   /** @type {Array<{event: string} & Record<string, unknown>>} */
   const entries = []

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

@@ -254,12 +254,13 @@ test("isLoopbackHost rejects non-loopback addresses", () => {
   assert.equal(isLoopbackHost("::ffff:127.0.0.1"), false)
 })
 
-test("loadEnvironmentConfig parses reverse hub identity bindings and exact routes", () => {
+test("loadEnvironmentConfig parses reverse hub identity bindings, exact routes, and route-class routes", () => {
   const config = loadEnvironmentConfig({
     SOCKETDUCT_MODE: "reverse-hub",
     SOCKETDUCT_AUTH_TOKENS: "home-o2:gateway-token,tensorbuzz:client-token",
     SOCKETDUCT_REVERSE_GATEWAY_BINDINGS: "o2:home-o2,zyxel:home-zyxel",
     SOCKETDUCT_REVERSE_ROUTES: "tensorbuzz:o2:docker-server:2375,tensorbuzz:zyxel:docker-server:2375",
+    SOCKETDUCT_REVERSE_ROUTE_CLASS_ROUTES: "tensorbuzz:starlink:o2:docker-a:2375,tensorbuzz:starlink:zyxel:docker-b:2375",
     SOCKETDUCT_TLS_CERT_FILE: "/certs/hub.crt",
     SOCKETDUCT_TLS_KEY_FILE: "/certs/hub.key"
   })
@@ -269,6 +270,10 @@ test("loadEnvironmentConfig parses reverse hub identity bindings and exact route
     {username: "tensorbuzz", gatewayId: "o2", host: "docker-server", port: 2375},
     {username: "tensorbuzz", gatewayId: "zyxel", host: "docker-server", port: 2375}
   ])
+  assert.deepEqual(config.reverseRouteClassRoutes, [
+    {username: "tensorbuzz", routeClass: "starlink", gatewayId: "o2", host: "docker-a", port: 2375},
+    {username: "tensorbuzz", routeClass: "starlink", gatewayId: "zyxel", host: "docker-b", port: 2375}
+  ])
 })
 
 test("loadEnvironmentConfig parses outbound reverse gateway verified TLS settings", () => {
@@ -296,6 +301,7 @@ test("loadEnvironmentConfig rejects malformed reverse mode policy and credential
   assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "unknown"}), /Unsupported SOCKETDUCT_MODE/)
   assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "reverse-hub", SOCKETDUCT_REVERSE_GATEWAY_BINDINGS: "missing-user"}), /gatewayId:username/)
   assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "reverse-hub", SOCKETDUCT_REVERSE_ROUTES: "too:few:fields"}), /username:gatewayId:host:port/)
+  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "reverse-hub", SOCKETDUCT_REVERSE_ROUTE_CLASS_ROUTES: "too:few:fields"}), /username:routeClass:gatewayId:host:port/)
   assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "reverse-gateway", SOCKETDUCT_REVERSE_TOKEN: "replace-me"}), /placeholder/)
   assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "reverse-gateway", SOCKETDUCT_REVERSE_HUB_CLIENT_CERT_FILE: "/certs/client.crt"}), /must both be set/)
 })