socketduct 0.1.32 → 0.1.34

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

@@ -72,6 +72,7 @@ class FakeMember extends EventEmitter {
     this.generation = 0
     this.physicalConnects = 0
     this.gatewayUnavailable = false
+    /** @type {Set<string>} */ this.unavailableTargets = new Set()
     /** @type {Promise<void>} */
     this.connectPromise = new Promise((resolve, reject) => {
       this.resolveConnect = resolve
@@ -133,6 +134,11 @@ class FakeMember extends EventEmitter {
     return this.recoveryDescriptors.get(identifier)
   }
 
+  /** @param {{host: string, port: number}} target - Logical target. */
+  isTargetUnavailable(target) {
+    return this.unavailableTargets.has(`${target.host}:${target.port}`)
+  }
+
   status() {
     return {
       physicalState: this.state,
@@ -558,30 +564,31 @@ describe("multiplexed transport set", () => {
     await set.close()
   })
 
-  it("a member the hub registered down is never selected, even when every member is down", async () => {
+  it("a member marked down for one target keeps serving every other target", async () => {
+    const {set, members} = fixture()
+    const started = set.start()
+    members.forEach((member) => member.ready())
+    await started
+    at(members, 0).unavailableTargets.add("broken.internal:443")
+    for (let offset = 0; offset < 6; offset += 1) {
+      const socket = set.createConnection({host: "broken.internal", port: 443})
+      expect(gatewayOf(socket) === "starlink").toBe(false)
+    }
+    const healthy = set.createConnection({host: "healthy.internal", port: 443})
+    expect(gatewayOf(healthy)).toBe("starlink")
+    await set.close()
+  })
+
+  it("a stale gateway-unavailable mark cannot wedge the set when every ready member is marked", async () => {
     const {set, members} = fixture()
     const started = set.start()
     members.forEach((member) => member.ready())
     await started
     members.forEach((member) => { member.gatewayUnavailable = true })
-    let callbacks = 0
     const socket = set.createConnection({host: "target.internal", port: 443}, (error) => {
       expect(error).toBe(null)
-      callbacks += 1
     })
-    await new Promise((resolve) => setImmediate(resolve))
-    expect(callbacks).toBe(0)
-    expect(socket.gatewayId).toBe(undefined)
-    expect(set.status().pendingOpens).toBe(1)
-    expect(members.map((member) => member.opens)).toEqual([0, 0, 0])
-    expect(set.status().members.map((member) => member.gatewayUnavailable)).toEqual([true, true, true])
-
-    at(members, 2).gatewayUnavailable = false
-    at(members, 2).setState("ready")
-    await new Promise((resolve) => setImmediate(resolve))
-    expect(callbacks).toBe(1)
     expect(socket.gatewayId !== undefined).toBe(true)
-    expect(members.map((member) => member.opens)).toEqual([0, 0, 1])
     expect(set.status().pendingOpens).toBe(0)
     await set.close()
   })
@@ -1136,4 +1143,27 @@ describe("multiplexed transport set", () => {
     expect(set.status().state).toBe("closed")
     expect(() => set.createConnection({host: "target.internal", port: 443})).toThrow(/closed/i)
   })
+
+  it("drain() drains every member instead of closing them", async () => {
+    const {set, members} = fixture()
+    const started = set.start()
+    const draining = set.drain()
+
+    /** @type {unknown} */
+    let startError
+
+    try {
+      await started
+    } catch (error) {
+      startError = error
+    }
+    await draining
+
+    expect(/** @type {{code?: string}} */ (startError).code).toBe("SOCKETDUCT_TRANSPORT_SET_CLOSED")
+    expect(members.length).toBe(3)
+    expect(members.map((member) => member.drainCalls)).toEqual([1, 1, 1])
+    expect(members.map((member) => member.closeCalls)).toEqual([0, 0, 0])
+    expect(set.status().state).toBe("closed")
+    expect(() => set.createConnection({host: "target.internal", port: 443})).toThrow(/closed/i)
+  })
 })

package/changelog.d/20261025123000-route-class-down-registration.md

@@ -1 +0,0 @@
-A route class the hub reports down is never selected while it stays down: the member keeps re-reaching the hub on a bounded backoff and returns to service automatically once a gateway registers again, and `status()` now exposes the down state and the probe attempts.

package/changelog.d/20261025203000-node-24-lts.md

@@ -1,5 +0,0 @@
-## Node.js 24 LTS
-
-The package, its test suite and the reverse-gateway integration tests are validated on Node.js 24 (current LTS). `engines.node` is now pinned to `^24.0.0`.
-
-Why: on this development host the suite is also run under Node.js 26, where the compressed reverse-gateway round-trip tests fail with corrupted payloads (16 failures, `Buffer wasn't equal to Buffer`). The same suite passes 42/42 under Node.js 24, so the corruption tracks the runtime, not the wire format. Pinning to LTS keeps the validated runtime and the declared support range identical.

package/changelog.d/20261026100000-reverse-client-drain.md

@@ -1 +0,0 @@
-`ReverseGatewayConnection` gains `drain()`, matching the multiplexed connection: it refuses new virtual streams with `SOCKETDUCT_TRANSPORT_SET_DRAINING`, waits for the open ones to finish, and only then releases the hub transport, so tearing down a reverse-mode transport set no longer resets work that is still in flight; `close()` keeps its immediate-termination behaviour and now logs how many live streams it terminated.

package/test/integration/multiplexed-drain.test.js

@@ -1,179 +0,0 @@
-/* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-returns */
-import {describe, expect, it, withTestCleanup} from "@velocious/testing"
-import {createServer} from "node:net"
-
-import {StaticTokenStore} from "../../src/auth/static-token-store.js"
-import {MultiplexedSocketductConnection} from "../../src/client/multiplexed-connection.js"
-import {startMultiplexedTcpRelay} from "../../src/proxy/multiplexed-relay.js"
-
-/**
- * `close()` terminates live virtual streams, which the relay answers with a
- * stream reset — that is how in-flight work on the other side of a transport
- * set died when the owning process shut down. `drain()` is the graceful verb:
- * it refuses new streams, waits for the open ones, then releases the transport.
- */
-
-/** @param {import('node:net').Server} server - Server. @returns {Promise<number>} */
-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()
-
-  if (address === null || typeof address === "string") throw new Error("Expected a TCP address")
-
-  return address.port
-}
-
-/**
- * @param {import('node:events').EventEmitter} emitter - Emitter.
- * @param {string} event - Event.
- * @returns {Promise<void>}
- */
-async function onceEvent(emitter, event) {
-  await new Promise((resolve, reject) => {
-    emitter.once("error", reject)
-    emitter.once(event, () => {
-      emitter.off("error", reject)
-      resolve(undefined)
-    })
-  })
-}
-
-/**
- * @param {Array<import("../../src/client/virtual-socket.js").VirtualSocket>} streams - Open streams.
- * @param {number} index - Index.
- * @returns {import("../../src/client/virtual-socket.js").VirtualSocket} - The stream.
- */
-function streamAt(streams, index) {
-  const stream = streams[index]
-
-  if (stream === undefined) throw new Error(`Expected stream ${index} to be open`)
-
-  return stream
-}
-
-/** @returns {Promise<void>} */
-async function settleTurns() {
-  for (let index = 0; index < 10; index += 1) await new Promise((resolve) => setImmediate(resolve))
-}
-
-/**
- * Relay plus one client connection with `streamCount` echoed streams open.
- * @param {(cleanup: () => void | Promise<void>) => void} after - Cleanup registrar.
- * @param {number} streamCount - Streams to open.
- */
-async function openStreams(after, streamCount) {
-  /** @type {Set<import('node:net').Socket>} */
-  const targetSockets = new Set()
-  const target = createServer((socket) => {
-    targetSockets.add(socket)
-    socket.on("close", () => targetSockets.delete(socket))
-    socket.on("data", (chunk) => socket.write(chunk))
-  })
-  const targetPort = await listen(target)
-
-  after(() => {
-    for (const socket of targetSockets) socket.destroy()
-
-    return new Promise((resolve) => target.close(() => resolve(undefined)))
-  })
-
-  const relay = await startMultiplexedTcpRelay({
-    tokens: new StaticTokenStore([{username: "edge", token: "valid-token"}]),
-    authorizeTarget: ({target: requested}) => requested.host === "127.0.0.1" && requested.port === targetPort
-  })
-
-  after(() => relay.close())
-
-  const connection = new MultiplexedSocketductConnection({
-    relay: {host: "127.0.0.1", port: relay.port, token: "valid-token"}
-  })
-
-  after(() => connection.close())
-
-  /** @type {Array<import("../../src/client/virtual-socket.js").VirtualSocket>} */
-  const streams = []
-
-  for (let index = 0; index < streamCount; index += 1) {
-    streams.push(connection.createConnection({host: "127.0.0.1", port: targetPort, sessionName: `drain-${index}`}))
-  }
-
-  await Promise.all(streams.map((stream) => onceEvent(stream, "connect")))
-  expect(connection.status().virtualStreams).toBe(streamCount)
-
-  return {connection, relay, streams, targetPort}
-}
-
-describe("multiplexed connection drain", () => {
-  it("drain() keeps in-flight virtual streams alive until they finish", async () => withTestCleanup(async (after) => {
-    const {connection, relay, streams} = await openStreams(after, 2)
-    const draining = connection.drain()
-
-    await settleTurns()
-
-    expect(connection.status().virtualStreams).toBe(2)
-    expect(streamAt(streams, 0).destroyed).toBeFalse()
-    expect(streamAt(streams, 1).destroyed).toBeFalse()
-    expect(relay.status().authenticatedConnections).toBe(1)
-
-    for (const stream of streams) stream.destroy()
-    await draining
-
-    expect(connection.status().virtualStreams).toBe(0)
-    expect(relay.status().authenticatedConnections).toBe(0)
-  }))
-
-  it("drain() keeps working streams usable instead of resetting them", async () => withTestCleanup(async (after) => {
-    const {connection, streams} = await openStreams(after, 1)
-    const draining = connection.drain()
-
-    await settleTurns()
-
-    streamAt(streams, 0).write("still-works")
-
-    /** @type {string} */
-    let echoed = ""
-
-    await new Promise((resolve, reject) => {
-      streamAt(streams, 0).once("error", reject)
-      streamAt(streams, 0).on("data", (chunk) => {
-        echoed += chunk.toString()
-        if (echoed.length >= 11) resolve(undefined)
-      })
-    })
-
-    expect(echoed).toBe("still-works")
-
-    streamAt(streams, 0).destroy()
-    await draining
-  }))
-
-  it("drain() rejects new virtual streams while draining", async () => withTestCleanup(async (after) => {
-    const {connection, streams, targetPort} = await openStreams(after, 1)
-    const draining = connection.drain()
-
-    await settleTurns()
-
-    expect(() => connection.createConnection({host: "127.0.0.1", port: targetPort, sessionName: "late"})).toThrow(/connection is closed/i)
-    expect(connection.status().virtualStreams).toBe(1)
-
-    streamAt(streams, 0).destroy()
-    await draining
-  }))
-
-  it("close() still terminates in-flight virtual streams immediately", async () => withTestCleanup(async (after) => {
-    const {connection, relay, streams} = await openStreams(after, 2)
-
-    await connection.close()
-
-    expect(connection.status().virtualStreams).toBe(0)
-    expect(streamAt(streams, 0).destroyed).toBeTrue()
-    expect(streamAt(streams, 1).destroyed).toBeTrue()
-    expect(relay.status().authenticatedConnections).toBe(0)
-  }))
-})

package/test/integration/reverse-drain.test.js

@@ -1,138 +0,0 @@
-/* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-param, jsdoc/require-returns */
-import {describe, expect, it, withTestCleanup} from "@velocious/testing"
-import {mkdtemp, rm} from "node:fs/promises"
-import {createServer} from "node:net"
-import {tmpdir} from "node:os"
-import {join} from "node:path"
-
-import {StaticTokenStore} from "../../src/auth/static-token-store.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()
-  if (address === null || typeof address === "string") throw new Error("Server did not bind to a TCP port")
-  return address.port
-}
-
-/** @param {string} prefix - Echo prefix. */
-async function createEchoTarget(prefix) {
-  const server = createServer((socket) => {
-    socket.on("data", (chunk) => socket.write(`${prefix}${chunk.toString("utf8")}`))
-  })
-  const port = await listen(server)
-  return {host: "127.0.0.1", port, close: () => new Promise((resolve) => server.close(resolve))}
-}
-
-/** @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. @param {string} message - Payload. */
-async function exchange(socket, message) {
-  return await new Promise((resolve) => {
-    socket.once("data", (chunk) => resolve(chunk.toString("utf8")))
-    socket.write(message)
-  })
-}
-
-/** @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))
-  }
-}
-
-describe("reverse gateway drain", () => {
-  it("refuses new streams, lets open streams finish, then releases the transport", async () => withTestCleanup(async (after) => {
-    const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-drain-"))
-    after(() => rm(root, {recursive: true, force: true}))
-    const certificates = generateTestCertificates(root)
-    const target = await createEchoTarget("t:")
-    after(() => target.close())
-
-    const tokens = new StaticTokenStore([
-      {username: "home-a", token: "gateway-a-token"},
-      {username: "tensorbuzz", token: "client-token"}
-    ])
-    const hub = await startReverseGatewayHub({
-      tokens,
-      tls: {certFile: certificates.serverCertFile, keyFile: certificates.serverKeyFile},
-      knownGatewayIds: ["server-a-starlink"],
-      knownRouteClasses: ["starlink"],
-      authorizeGateway: ({gatewayId}) => gatewayId === "server-a-starlink",
-      authorizeClientGateway: ({gatewayId}) => gatewayId === "server-a-starlink",
-      authorizeClientRouteClass: () => true,
-      resolveOpenGateways: ({routeClass, target: requestedTarget}) => (
-        routeClass === "starlink" && requestedTarget.port === target.port ? ["server-a-starlink"] : []
-      ),
-      authorizeOpen: ({target: requestedTarget}) => requestedTarget.host === target.host && requestedTarget.port === target.port
-    })
-    after(() => hub.close())
-    const tls = {caFile: certificates.caCertFile, servername: "localhost"}
-    const gateway = new OutboundReverseGateway({
-      gatewayId: "server-a-starlink",
-      connectionId: "drain_gateway_a",
-      hub: {host: "127.0.0.1", port: hub.port, token: "gateway-a-token"},
-      tls,
-      authorizeTarget: (requestedTarget) => requestedTarget.host === target.host && requestedTarget.port === target.port,
-      reconnectDelayMs: 10,
-      maxReconnectDelayMs: 20
-    })
-    after(() => gateway.close())
-    await gateway.start()
-
-    const client = new ReverseGatewayConnection({
-      routeClass: "starlink",
-      connectionId: "drain_client",
-      hub: {host: "127.0.0.1", port: hub.port, token: "client-token"},
-      tls
-    })
-    await client.connect()
-    expect(hub.status().clientPhysicalConnections).toBe(1)
-
-    const stream = client.createConnection({host: target.host, port: target.port})
-    await onceEvent(stream, "connect")
-    expect(await exchange(stream, "before")).toBe("t:before")
-    expect(client.status().virtualStreams).toBe(1)
-
-    expect(typeof client.drain).toBe("function")
-
-    let drained = false
-    const drainPromise = client.drain().then(() => { drained = true })
-
-    // New work is refused while the set drains.
-    /** @type {Error & {code?: string} | undefined} */
-    let refused
-    try {
-      client.createConnection({host: target.host, port: target.port})
-    } catch (caught) {
-      refused = /** @type {Error & {code?: string}} */ (caught)
-    }
-    expect(refused?.code).toBe("SOCKETDUCT_TRANSPORT_SET_DRAINING")
-
-    // The transport stays up while the open stream is still usable.
-    await new Promise((resolve) => setTimeout(resolve, 50))
-    expect(drained).toBe(false)
-    expect(await exchange(stream, "during")).toBe("t:during")
-    expect(hub.status().clientPhysicalConnections).toBe(1)
-
-    // Finishing the last stream lets the drain complete and release the transport.
-    stream.destroy()
-    await drainPromise
-    expect(drained).toBe(true)
-    await waitUntil(() => hub.status().clientPhysicalConnections === 0, "hub releases the drained member")
-    expect(client.status().physicalState).toBe("closed")
-  }))
-})