socketduct 0.1.30 → 0.1.32

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

@@ -0,0 +1,5 @@
+## 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

@@ -0,0 +1 @@
+`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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "socketduct",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "description": "Resilient authenticated tunnel/proxy for keeping socket streams alive across flaky links.",
   "type": "module",
   "main": "./src/index.js",
@@ -16,7 +16,7 @@
     "./relay": "./src/relay.js"
   },
   "engines": {
-    "node": ">=24.0.0"
+    "node": "^24.0.0"
   },
   "scripts": {
     "gateway:deploy": "node scripts/deploy-gateway.js",

package/src/reverse/client.js

@@ -144,6 +144,9 @@ export class ReverseGatewayConnection extends EventEmitter {
   /** @type {number} */ #generation
   /** @type {string | undefined} */ #codec
   /** @type {boolean} */ #closing = false
+  /** @type {boolean} */ #draining = false
+  /** @type {Promise<void> | undefined} */ #closePromise
+  /** @type {Array<() => void>} */ #drainWaiters = []
   /** @type {boolean} */ #detached = false
   /** @type {boolean} */ #preserveSpools = false
   /** @type {boolean} */ #fatal = false
@@ -247,6 +250,7 @@ export class ReverseGatewayConnection extends EventEmitter {
   /** Creates a fresh or synchronously recovered reverse stream. */
   #createConnection(/** @type {import('../client/multiplexed-connection.js').VirtualConnectionOptions} */ options, /** @type {((error: Error | null, socket: VirtualSocket) => void) | undefined} */ callback, /** @type {boolean} */ recovering) {
     if (this.#closing) throw closedError()
+    if (this.#draining) throw Object.assign(new Error("Reverse gateway member is draining"), {code: "SOCKETDUCT_TRANSPORT_SET_DRAINING"})
     if (options?.manualReceiveAck !== undefined && typeof options.manualReceiveAck !== "boolean") throw new TypeError("manualReceiveAck must be a boolean")
     if (!recovering && this.#state !== "ready") throw Object.assign(new Error("Reverse gateway member is not ready"), {code: "SOCKETDUCT_TRANSPORT_SET_NOT_READY"})
     if (this.#streams.size >= (this.#options.maxStreams ?? DEFAULT_MAX_STREAMS)) throw new Error("Maximum reverse virtual stream count exceeded")
@@ -487,8 +491,44 @@ export class ReverseGatewayConnection extends EventEmitter {
   ref() { this.#referenced = true; this.#physical?.ref(); this.#reconnectTimer?.ref?.(); return this }
   unref() { this.#referenced = false; this.#physical?.unref(); this.#reconnectTimer?.unref?.(); return this }
 
+  /**
+   * Graceful counterpart of `close()`: refuses new virtual streams, lets the open
+   * ones finish on their own, then releases the shared transport. Transport sets
+   * that are torn down while they carry work must use this instead of `close()`,
+   * otherwise live streams are reset at the relay mid-transfer.
+   * @returns {Promise<void>}
+   */
+  async drain() {
+    if (this.#closePromise !== undefined) return this.#closePromise
+    this.#draining = true
+    this.#closePromise = (async () => {
+      logDiagnostic(this.#options.logger, "reverse_client.draining", {virtualStreams: this.#streams.size})
+      await this.#waitForStreamsToDrain()
+      await this.close()
+    })()
+
+    return this.#closePromise
+  }
+
+  /** @returns {Promise<void>} */
+  #waitForStreamsToDrain() {
+    if (this.#streams.size === 0) return Promise.resolve()
+
+    return new Promise((resolve) => { this.#drainWaiters.push(resolve) })
+  }
+
+  /** @returns {void} */
+  #releaseDrainWaiters() {
+    if (this.#drainWaiters.length === 0) return
+    const waiters = this.#drainWaiters.splice(0)
+    for (const resolve of waiters) resolve()
+  }
+
   async close() {
     if (this.#closing) return
+    if (this.#streams.size > 0 && !this.#draining) {
+      logDiagnostic(this.#options.logger, "reverse_client.closed_with_live_streams", {streamsKilled: this.#streams.size})
+    }
     this.#closing = true
     if (this.#reconnectTimer !== undefined) clearTimeout(this.#reconnectTimer)
     this.#reconnectTimer = undefined
@@ -496,6 +536,7 @@ export class ReverseGatewayConnection extends EventEmitter {
     this.#gatewayProbeTimer = undefined
     this.#setState("closed")
     for (const stream of [...this.#streams.values()]) stream.socket.destroy()
+    this.#releaseDrainWaiters()
     const physical = this.#physical
     this.#physical = undefined
     if (physical !== undefined && !physical.destroyed) {
@@ -1203,6 +1244,7 @@ export class ReverseGatewayConnection extends EventEmitter {
     while (stream.pendingWrites.length > 0) this.#finishWrite(stream, pendingWriteError)
     if (!this.#preserveSpools) this.#trackSpoolCleanup(stream)
     this.#progressPendingWrites()
+    if (this.#streams.size === 0) this.#releaseDrainWaiters()
   }
 
   /** @param {ReverseClientStream} stream - Stream. @param {number} sequence - ACK. */

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

@@ -0,0 +1,138 @@
+/* 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")
+  }))
+})