socketduct 0.1.29 → 0.1.30

package/changelog.d/20261025193000-drain-transport-without-resetting-streams.md

@@ -0,0 +1 @@
+Multiplexed connections gain `drain()`, which refuses new virtual streams, waits for the open ones to finish, and only then releases the physical transport, so a shutdown 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.29",
+  "version": "0.1.30",
   "description": "Resilient authenticated tunnel/proxy for keeping socket streams alive across flaky links.",
   "type": "module",
   "main": "./src/index.js",

package/src/client/multiplexed-connection.js

@@ -138,6 +138,11 @@ export class MultiplexedSocketductConnection extends EventEmitter {
 
   /** @type {boolean} */
   #closing = false
+  #draining = false
+  /** @type {Promise<void> | undefined} */
+  #closePromise = undefined
+  /** @type {Array<() => void>} */
+  #drainWaiters = []
 
   /** @type {boolean} */
   #warm = false
@@ -247,7 +252,7 @@ export class MultiplexedSocketductConnection extends EventEmitter {
    * @returns {Promise<void>} Resolves when the member becomes ready.
    */
   connect() {
-    if (this.#closing) return Promise.reject(Object.assign(new Error("Multiplexed Socketduct connection is closed"), {code: "SOCKETDUCT_CONNECTION_CLOSED"}))
+    if (this.#closing || this.#draining) return Promise.reject(Object.assign(new Error("Multiplexed Socketduct connection is closed"), {code: "SOCKETDUCT_CONNECTION_CLOSED"}))
     if (this.#warmPromise !== undefined) return this.#warmPromise
     this.#warm = true
     this.#warmPromise = Promise.all([...this.#streams.values()].map((stream) => stream.spoolReady)).then(() => this.#ensureConnected())
@@ -297,7 +302,7 @@ export class MultiplexedSocketductConnection extends EventEmitter {
    * @returns {VirtualSocket} Socket-shaped Duplex.
    */
   #createConnection(options, callback, connectOnReady) {
-    if (this.#closing) throw new Error("Multiplexed Socketduct connection is closed")
+    if (this.#closing || this.#draining) throw new Error("Multiplexed Socketduct connection is closed")
     if (options.manualReceiveAck !== undefined) throw new TypeError("manualReceiveAck is supported only by reverse gateway connections")
     if (this.#streams.size >= (this.#options.maxStreams ?? DEFAULT_MAX_STREAMS)) throw new Error("Maximum virtual stream count exceeded")
     const target = normalizeTarget(options)
@@ -446,10 +451,52 @@ export class MultiplexedSocketductConnection extends EventEmitter {
     return this
   }
 
-  /** Gracefully closes all virtual streams and the shared transport. @returns {Promise<void>} */
+  /**
+   * Terminates every virtual stream and releases the shared transport. Streams
+   * still in flight are reset at the relay by design, so the number of them is
+   * logged (`multiplexed_connection.shutdown_with_live_streams`) instead of
+   * disappearing. Use `drain()` when in-flight work must survive.
+   * @returns {Promise<void>}
+   */
   async close() {
+    if (this.#closePromise !== undefined) return this.#closePromise
+    this.#closePromise = this.#shutdownTransport()
+
+    return this.#closePromise
+  }
+
+  /**
+   * Graceful counterpart of `close()`: refuses new virtual streams, lets the
+   * open ones finish, and only then releases the shared transport. Use this
+   * wherever a transport must not reset work that is still in flight.
+   * @returns {Promise<void>}
+   */
+  async drain() {
+    if (this.#closePromise !== undefined) return this.#closePromise
+    this.#draining = true
+    this.#closePromise = (async () => {
+      await this.#waitForStreamsToDrain()
+      await this.#shutdownTransport()
+    })()
+
+    return this.#closePromise
+  }
+
+  /** @returns {Promise<void>} */
+  #waitForStreamsToDrain() {
+    if (this.#streams.size === 0) return Promise.resolve()
+
+    return new Promise((resolve) => { this.#drainWaiters.push(resolve) })
+  }
+
+  /** @returns {Promise<void>} */
+  async #shutdownTransport() {
     if (this.#closing) return
     this.#closing = true
+
+    if (this.#streams.size > 0) {
+      logDiagnostic(this.#options.logger, "multiplexed_connection.shutdown_with_live_streams", {streamsKilled: this.#streams.size})
+    }
     this.#setPhysicalState("closed")
     if (this.#reconnectTimer !== undefined) clearTimeout(this.#reconnectTimer)
     this.#reconnectTimer = undefined
@@ -618,6 +665,8 @@ export class MultiplexedSocketductConnection extends EventEmitter {
       this.#trackSpoolCleanup(stream)
     }
     if (this.#streams.size === 0 && !this.#authenticated && this.#physical !== undefined) this.#physical.destroy()
+
+    if (this.#streams.size === 0) for (const resolve of this.#drainWaiters.splice(0)) resolve()
   }
 
   /** @param {number} streamId - Stream. @returns {void} */

package/src/client/multiplexed-transport-set.js

@@ -61,6 +61,7 @@ const GATEWAY_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{1,63}$/
  * @property {() => MemberConnectionStatus} status - Privacy-safe status.
  * @property {() => Promise<void>} close - Close the member.
  * @property {() => Promise<void>} detach - Preserve durable streams for process-replacement recovery.
+ * @property {() => Promise<void>} drain - Let live streams finish before releasing the member.
  * @property {(eventName: string, listener: (...args: unknown[]) => void) => unknown} on - Subscribe to lifecycle changes.
  * @property {() => unknown} [ref] - Reference resources.
  * @property {() => unknown} [unref] - Unreference resources.
@@ -550,7 +551,12 @@ export class MultiplexedSocketductTransportSet extends EventEmitter {
     return this.#shutdown("detach")
   }
 
-  /** @param {"close" | "detach"} method - Member shutdown operation. @returns {Promise<void>} */
+  /** Drains live virtual streams on every member before releasing them once. @returns {Promise<void>} */
+  drain() {
+    return this.#shutdown("drain")
+  }
+
+  /** @param {"close" | "detach" | "drain"} method - Member shutdown operation. @returns {Promise<void>} */
   #shutdown(method) {
     if (this.#closePromise !== undefined) return this.#closePromise
     this.#closed = true

package/src/reverse/client.js

@@ -1288,6 +1288,11 @@ export class ReverseGatewayConnection extends EventEmitter {
     this.#reconnectDelay = Math.min(this.#reconnectDelay * 2, this.#options.maxReconnectDelayMs ?? 30_000)
     this.#reconnectTimer = setTimeout(() => {
       this.#reconnectTimer = undefined
+      // clearTimeout() cannot stop a callback that is already queued, so a
+      // detach()/close() that lands in that window used to reconnect anyway:
+      // it reopened a physical transport after the caller had deliberately
+      // detached (observed as ENOENT reading a deleted recovery CA file).
+      if (this.#closing || this.#fatal) return
       if (this.#connectPromise === undefined) {
         this.#connectPromise = new Promise((resolve, reject) => { this.#resolveConnect = resolve; this.#rejectConnect = reject })
         this.#connectPromise.catch(() => {})

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

@@ -0,0 +1,179 @@
+/* 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/unit/client/multiplexed-transport-set.test.js

@@ -58,6 +58,7 @@ class FakeMember extends EventEmitter {
     this.closeError = closeError
     this.connectCalls = 0
     this.closeCalls = 0
+    this.drainCalls = 0
     this.opens = 0
     /** @type {FakeSocket[]} */
     this.sockets = []
@@ -161,6 +162,11 @@ class FakeMember extends EventEmitter {
     this.setState("closed")
   }
 
+  async drain() {
+    this.drainCalls += 1
+    this.setState("closed")
+  }
+
   /** @param {string} state - Physical state. @param {Error} [error] - Terminal error. */
   setState(state, error) {
     this.state = state