socketduct 0.1.23 → 0.1.24

package/changelog.d/20260929181645-reverse-gateway-stream-high-water-reset.md

@@ -0,0 +1 @@
+Reverse gateways now reset their stream high-water mark when a fresh (non-resumed) hub registration completes, so a hub restart or expired resume window no longer wedges the gateway in a protocol-violation reconnect loop that surfaces as `SocketductSessionLostError` on clients.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "socketduct",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "description": "Resilient authenticated tunnel/proxy for keeping socket streams alive across flaky links.",
   "type": "module",
   "main": "./src/index.js",
@@ -39,6 +39,7 @@
     "@eslint/js": "^10.0.1",
     "@types/node": "^24.0.0",
     "@velocious/testing": "0.0.10",
+    "awaitery": "^1.0.21",
     "eslint": "^10.0.3",
     "eslint-plugin-jsdoc": "^62.7.1",
     "globals": "^17.2.0",

package/src/reverse/gateway.js

@@ -294,6 +294,20 @@ export class OutboundReverseGateway extends EventEmitter {
             if (detail.gatewayId !== this.#options.gatewayId || detail.generation !== generation) throw fatalError("GATEWAY_REGISTRATION_FAILED")
             if (typeof detail.resumed !== "boolean") throw fatalError("GATEWAY_REGISTRATION_FAILED")
             registered = true
+            // The hub's reverse stream-ID allocation restarts on every fresh
+            // physical: it begins at the retained-stream high-water + 2 (or 2
+            // when nothing is retained). #lastStreamId otherwise persists for
+            // the gateway process lifetime, so a gateway that reconnects would
+            // reject the new physical's valid low-numbered OPENs as "Invalid
+            // reverse gateway stream ID", disconnect with protocol_violation,
+            // and wedge in a reconnect loop that surfaces on clients as
+            // SocketductSessionLostError. Reset the watermark to this
+            // physical's allocation base on every (re)registration, resumed or
+            // not; retained bridges re-attach via RESUMED (which does not flow
+            // through #openStream) and the hub allocates new OPENs strictly
+            // above the retained high-water, so the within-physical monotonic
+            // guard still holds.
+            this.#lastStreamId = 0
             if (detail.resumed) {
               // A replacement gateway intentionally owns no inherited target
               // sockets. Its empty manifest makes the hub reset every omitted

package/test/helpers/test-async.js

@@ -0,0 +1,29 @@
+import assert from "node:assert/strict"
+
+/**
+ * Listen on an ephemeral port and resolve with the assigned port.
+ * @param {import('node:net').Server} server - Server to listen on.
+ * @returns {Promise<number>} The assigned TCP port.
+ */
+export 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
+}
+
+/**
+ * Resolve the first time an event is emitted; reject on an "error" event.
+ * @param {import('node:events').EventEmitter} emitter - Emitter to watch.
+ * @param {string} event - Event name to wait for.
+ * @returns {Promise<void>}
+ */
+export async function onceEvent(emitter, event) {
+  await new Promise((resolve, reject) => {
+    emitter.once("error", reject)
+    emitter.once(event, () => { emitter.off("error", reject); resolve(undefined) })
+  })
+}

package/test/integration/reverse-gateway-stream-id-reset.test.js

@@ -0,0 +1,109 @@
+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 {withTimeout, waitUntil} from "awaitery"
+import {OutboundReverseGateway, ReverseGatewayConnection, startReverseGatewayHub} from "../../src/reverse/index.js"
+import {generateTestCertificates} from "../helpers/tls-certificates.js"
+import {listen, onceEvent} from "../helpers/test-async.js"
+
+test("gateway resets its reverse stream high-water on fresh registration after a hub restart", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-streamid-"))
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const certificates = generateTestCertificates(root)
+
+  let targetAccepts = 0
+  const targetSockets = new Set()
+  const target = createServer((socket) => {
+    targetAccepts += 1
+    targetSockets.add(socket)
+    socket.once("close", () => targetSockets.delete(socket))
+    socket.on("data", (chunk) => socket.write(chunk))
+  })
+  const targetPort = await listen(target)
+  t.after(() => {
+    for (const socket of targetSockets) socket.destroy()
+    return new Promise((resolve) => target.close(() => resolve(undefined)))
+  })
+
+  const tokens = new StaticTokenStore([
+    {username: "home-o2", token: "gateway-token"},
+    {username: "tensorbuzz", token: "client-token"}
+  ])
+  const hubOptions = {
+    tokens,
+    tls: {certFile: certificates.serverCertFile, keyFile: certificates.serverKeyFile},
+    knownGatewayIds: ["o2"],
+    authorizeGateway: (/** @type {{principal: {username: string}, gatewayId: string}} */ {principal, gatewayId}) => principal.username === "home-o2" && gatewayId === "o2",
+    authorizeClientGateway: (/** @type {{principal: {username: string}, gatewayId: string}} */ {principal, gatewayId}) => principal.username === "tensorbuzz" && gatewayId === "o2",
+    authorizeOpen: (/** @type {{principal: {username: string}, gatewayId: string, target: {host: string, port: number}}} */ {principal, gatewayId, target: requested}) => principal.username === "tensorbuzz" && gatewayId === "o2" && requested.host === "127.0.0.1" && requested.port === targetPort
+  }
+  let hub = await startReverseGatewayHub(hubOptions)
+  t.after(() => hub.close())
+
+  const gateway = new OutboundReverseGateway({
+    gatewayId: "o2",
+    connectionId: "streamid_gateway",
+    hub: {host: "127.0.0.1", port: hub.port, token: "gateway-token"},
+    tls: {caFile: certificates.caCertFile, servername: "localhost"},
+    authorizeTarget: (requested) => requested.host === "127.0.0.1" && requested.port === targetPort,
+    reconnectDelayMs: 10,
+    maxReconnectDelayMs: 20
+  })
+  t.after(() => gateway.close())
+  await withTimeout(gateway.start(), "gateway registration")
+
+  const client = new ReverseGatewayConnection({
+    gatewayId: "o2",
+    connectionId: "streamid_client",
+    hub: {host: "127.0.0.1", port: hub.port, token: "client-token"},
+    tls: {caFile: certificates.caCertFile, servername: "localhost"},
+    reconnectDelayMs: 10,
+    maxReconnectDelayMs: 20
+  })
+  t.after(() => client.close())
+  await withTimeout(client.connect(), "client authentication")
+
+  // Open the first stream: this raises the gateway's process-lifetime
+  // #lastStreamId high-water mark above the fresh registration's start.
+  const first = client.createConnection({host: "127.0.0.1", port: targetPort, sessionName: "before-restart"})
+  await withTimeout(onceEvent(first, "connect"), "first reverse stream opens")
+  first.write("first")
+  await new Promise((resolve, reject) => {
+    first.once("data", (/** @type {Buffer} */ chunk) => { assert.equal(chunk.toString(), "first"); resolve(undefined) })
+    first.once("error", reject)
+  })
+  const firstClosed = onceEvent(first, "close")
+  first.end()
+  await withTimeout(firstClosed, "first stream close")
+  // Fully retire the first stream on every peer before the hub restarts so
+  // the only effect of the restart is the fresh (non-resumed) registration.
+  await waitUntil(() => client.status().virtualStreams === 0 && gateway.status().virtualStreams === 0 && hub.status().virtualStreams === 0, "first stream retired")
+
+  // Restart the hub so the gateway reconnects with a fresh (non-resumed)
+  // registration whose stream ids restart from the low end.
+  const port = hub.port
+  await withTimeout(hub.close(), "hub close")
+  hub = await startReverseGatewayHub({...hubOptions, port})
+  t.after(() => hub.close())
+  await waitUntil(() => gateway.status().physicalState === "ready" && client.status().physicalState === "ready" && gateway.status().physicalConnects >= 2 && client.status().physicalConnects >= 2, "peers after hub restart")
+
+  // Without the high-water reset, this OPEN is rejected as
+  // "Invalid reverse gateway stream ID" and the gateway wedges.
+  const second = client.createConnection({host: "127.0.0.1", port: targetPort, sessionName: "after-restart"})
+  await withTimeout(onceEvent(second, "connect"), "second reverse stream opens after hub restart")
+  second.write("second")
+  await new Promise((resolve, reject) => {
+    second.once("data", (/** @type {Buffer} */ chunk) => { assert.equal(chunk.toString(), "second"); resolve(undefined) })
+    second.once("error", reject)
+  })
+  const secondClosed = onceEvent(second, "close")
+  second.end()
+  await withTimeout(secondClosed, "second stream close")
+
+  assert.ok(targetAccepts >= 2, `expected at least two target connections, got ${targetAccepts}`)
+})