socketduct 0.1.32 → 0.1.34

package/src/reverse/client.js

@@ -32,8 +32,16 @@ import {attachDisconnectAttribution, createDisconnectAttribution, parseDisconnec
 const DEFAULT_STREAM_BUFFER_BYTES = 4 * 1024 * 1024
 const DEFAULT_CONNECTION_BUFFER_BYTES = 32 * 1024 * 1024
 const MANIFEST_PAGE_STREAMS = 64
-const DEFAULT_GATEWAY_PROBE_DELAY_MS = 1_000
-const DEFAULT_MAX_GATEWAY_PROBE_DELAY_MS = 30_000
+const MAX_TARGET_UNAVAILABLE_ENTRIES = 64
+
+/**
+ * Builds the per-target availability key for one logical target.
+ * @param {{host: string, port: number}} target - Logical target.
+ * @returns {string} Stable key.
+ */
+function targetKey(target) {
+  return `${target.host}:${target.port}`
+}
 
 /**
  * @typedef {object} ReverseGatewayConnectionOptions
@@ -52,8 +60,6 @@ const DEFAULT_MAX_GATEWAY_PROBE_DELAY_MS = 30_000
  * @property {number} [connectTimeoutMs] - TLS/auth deadline.
  * @property {number} [reconnectDelayMs] - Initial reconnect delay.
  * @property {number} [maxReconnectDelayMs] - Maximum reconnect delay.
- * @property {number} [gatewayProbeDelayMs] - Initial re-reach delay while the hub reports no selectable gateway.
- * @property {number} [maxGatewayProbeDelayMs] - Maximum re-reach delay while the hub reports no selectable gateway.
  * @property {number} [initialGeneration] - Monotonic seed for controlled replacement; defaults to wall-clock microseconds.
  * @property {boolean} [continuousReconnect] - Keep the member warm after loss, default true.
  * @property {import('../protocol/compression.js').CompressionLimits} [compressionLimits] - zstd safety bounds.
@@ -144,9 +150,6 @@ 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
@@ -175,10 +178,15 @@ export class ReverseGatewayConnection extends EventEmitter {
   /** @type {number} */ #spoolBytes = 0
   /** @type {number} */ #spoolCleanupFailures = 0
   /** @type {Set<Promise<void>>} */ #spoolCleanupTasks = new Set()
-  /** @type {number | undefined} - Wall-clock time the hub first reported this member's route class unselectable; undefined means registered available. */ #gatewayDownSince
-  /** @type {ReturnType<typeof setTimeout> | undefined} */ #gatewayProbeTimer
-  /** @type {number} */ #gatewayProbeDelay
-  /** @type {number} */ #gatewayProbeAttempts = 0
+  /** @type {number | undefined} - Wall-clock time of the last hub-reported gateway unavailability. */ #gatewayUnavailableSince
+  /**
+   * Targets this member most recently answered with "the hub has no gateway for
+   * that target". Scoped to the exact target so one unreachable machine cannot
+   * take this route class out of rotation for every other target, and cleared by
+   * the next OPENED for the same target instead of expiring on a timer.
+   * @type {Map<string, number>}
+   */
+  #targetUnavailableSince = new Map()
   /** @type {import('./disconnect-attribution.js').DisconnectAttribution | undefined} */ #disconnectAttribution
 
   /** @param {ReverseGatewayConnectionOptions} options - Hub route and safety policy. */
@@ -194,7 +202,6 @@ export class ReverseGatewayConnection extends EventEmitter {
     })
     this.#generation = options.initialGeneration ?? Date.now() * 1000
     this.#reconnectDelay = options.reconnectDelayMs ?? 250
-    this.#gatewayProbeDelay = options.gatewayProbeDelayMs ?? DEFAULT_GATEWAY_PROBE_DELAY_MS
     this.#sendWindowLimit = this.#initialWindow()
     this.createConnection = this.createConnection.bind(this)
   }
@@ -250,7 +257,6 @@ 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")
@@ -372,92 +378,58 @@ export class ReverseGatewayConnection extends EventEmitter {
    * @returns {void}
    */
   #markGatewayUnavailable(code) {
-    const firstMark = this.#gatewayDownSince === undefined
-    this.#gatewayDownSince ??= Date.now()
+    const firstMark = this.#gatewayUnavailableSince === undefined
+    this.#gatewayUnavailableSince = Date.now()
     if (firstMark) {
       logDiagnostic(this.#options.logger, "reverse_client.gateway_unavailable", {
         code,
         generation: this.#generation,
         ...this.#routeIdentityFields()
       })
-      this.#emitStateChange()
     }
-    this.#scheduleGatewayProbe()
   }
 
   /**
-   * Registers this member's route class as available again, which is the only
-   * transition back into service.
-   * @returns {void}
+   * Whether the hub last reported this member's route class as having no selectable
+   * gateway. The report is a property of the live connection, not a short-lived cache:
+   * it arrives once per connection at selection time and only changes when the hub says
+   * otherwise or an open succeeds. Expiring it on a timer made the transport set pick a
+   * route class the hub had already declared unserviceable, and the reset that followed
+   * failed the caller's operation — a build lost its first transport open this way.
+   * The transport set still falls back to marked members when every member is marked, so
+   * a mark can never wedge the set.
+   * @returns {boolean} True while the hub reports no selectable gateway for this member.
    */
-  #markGatewayAvailable() {
-    if (this.#gatewayDownSince === undefined) return
-    const downMs = Date.now() - this.#gatewayDownSince
-    this.#gatewayDownSince = undefined
-    this.#gatewayProbeDelay = this.#options.gatewayProbeDelayMs ?? DEFAULT_GATEWAY_PROBE_DELAY_MS
-    this.#gatewayProbeAttempts = 0
-    if (this.#gatewayProbeTimer !== undefined) clearTimeout(this.#gatewayProbeTimer)
-    this.#gatewayProbeTimer = undefined
-    logDiagnostic(this.#options.logger, "reverse_client.gateway_available", {
-      downMs,
-      generation: this.#generation,
-      ...this.#routeIdentityFields()
-    })
-    this.#emitStateChange()
+  #gatewayUnavailable() {
+    return this.#gatewayUnavailableSince !== undefined
   }
 
   /**
-   * Keeps reaching the hub while this member is down, so a returning gateway is
-   * detected and taken into service again without operator action. Only a fresh
-   * hub selection can report a route class available, so the probe re-selects.
-   * @returns {void}
+   * Whether this member most recently reported the exact target unserviceable.
+   * Scoped per target: one unreachable machine must not remove this route class
+   * from rotation for every other machine.
+   * @param {{host: string, port: number}} target - Logical target a caller wants to open.
+   * @returns {boolean} True while this member is marked down for that target.
    */
-  #scheduleGatewayProbe() {
-    if (this.#closing || this.#fatal || this.#gatewayDownSince === undefined || this.#gatewayProbeTimer !== undefined) return
-    const delay = this.#gatewayProbeDelay
-    this.#gatewayProbeDelay = Math.min(this.#gatewayProbeDelay * 2, this.#options.maxGatewayProbeDelayMs ?? DEFAULT_MAX_GATEWAY_PROBE_DELAY_MS)
-    this.#gatewayProbeTimer = setTimeout(() => {
-      this.#gatewayProbeTimer = undefined
-      this.#probeGateway()
-    }, delay)
-    if (!this.#referenced) this.#gatewayProbeTimer.unref?.()
+  isTargetUnavailable(target) {
+    return this.#targetUnavailableSince.has(targetKey(target))
   }
 
-  /** Re-runs hub selection for a down route class and re-reads its availability. @returns {void} */
-  #probeGateway() {
-    if (this.#closing || this.#fatal || this.#gatewayDownSince === undefined) return
-    this.#gatewayProbeAttempts += 1
-    logDiagnostic(this.#options.logger, "reverse_client.gateway_probe", {
-      attempt: this.#gatewayProbeAttempts,
-      generation: this.#generation,
-      physicalState: this.#state,
-      ...this.#routeIdentityFields()
-    })
-    const physical = this.#physical
-    if (physical !== undefined && !physical.destroyed) {
-      physical.destroy()
-      return
-    }
-    if (this.#connectPromise === undefined) {
-      this.#connectPromise = new Promise((resolve, reject) => { this.#resolveConnect = resolve; this.#rejectConnect = reject })
-      this.#connectPromise.catch(() => {})
+  /** Records that this member could not serve a target, bounded so long-lived sets stay small. */
+  #markTargetUnavailable(/** @type {{host: string, port: number}} */ target) {
+    const key = targetKey(target)
+    this.#targetUnavailableSince.delete(key)
+    this.#targetUnavailableSince.set(key, Date.now())
+    while (this.#targetUnavailableSince.size > MAX_TARGET_UNAVAILABLE_ENTRIES) {
+      const oldest = this.#targetUnavailableSince.keys().next()
+      if (oldest.done === true) break
+      this.#targetUnavailableSince.delete(oldest.value)
     }
-    this.#connectPhysical()
-  }
-
-  /** Notifies owners that availability changed without changing the physical state. @returns {void} */
-  #emitStateChange() {
-    this.emit("stateChange", this.#state, undefined)
   }
 
-  /**
-   * Whether the hub currently has this member's route class registered down. The
-   * state never expires on its own: a down member stays out of service until the
-   * hub reports a selectable gateway again.
-   * @returns {boolean} True while the route class is registered down.
-   */
-  #gatewayUnavailable() {
-    return this.#gatewayDownSince !== undefined
+  /** Clears a target mark; a successful open is the only thing that proves it recovered. */
+  #clearTargetUnavailable(/** @type {{host: string, port: number}} */ target) {
+    this.#targetUnavailableSince.delete(targetKey(target))
   }
 
   status() {
@@ -467,7 +439,6 @@ export class ReverseGatewayConnection extends EventEmitter {
     return {
       physicalState: this.#state,
       gatewayUnavailable: this.#gatewayUnavailable(),
-      gatewayProbeAttempts: this.#gatewayProbeAttempts,
       connectionGeneration: this.#generation,
       virtualStreams: this.#streams.size,
       streamStates,
@@ -491,52 +462,13 @@ 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
-    if (this.#gatewayProbeTimer !== undefined) clearTimeout(this.#gatewayProbeTimer)
-    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) {
@@ -560,8 +492,6 @@ export class ReverseGatewayConnection extends EventEmitter {
     this.#closing = true
     if (this.#reconnectTimer !== undefined) clearTimeout(this.#reconnectTimer)
     this.#reconnectTimer = undefined
-    if (this.#gatewayProbeTimer !== undefined) clearTimeout(this.#gatewayProbeTimer)
-    this.#gatewayProbeTimer = undefined
     this.#setState("closed")
     const physical = this.#physical
     physical?.pause()
@@ -774,7 +704,7 @@ export class ReverseGatewayConnection extends EventEmitter {
             const selection = this.#routeIdentityFields()
             if (detail.generation !== generation || ("gatewayId" in selection ? detail.gatewayId !== selection.gatewayId || Object.hasOwn(detail, "routeClass") : detail.routeClass !== selection.routeClass || Object.hasOwn(detail, "gatewayId"))) throw fatalError("GATEWAY_SELECTION_FAILED")
             if (typeof detail.resumed !== "boolean") throw fatalError("GATEWAY_SELECTION_FAILED")
-            if (detail.selectable === true) this.#markGatewayAvailable()
+            if (detail.selectable === true) this.#gatewayUnavailableSince = undefined
             else if (detail.selectable === false) this.#markGatewayUnavailable("GATEWAY_SELECT_UNAVAILABLE")
             selected = true
             if (detail.resumed) {
@@ -901,7 +831,14 @@ export class ReverseGatewayConnection extends EventEmitter {
       stream.sendWindow = Math.min(stream.sendWindow, detail.initialWindow)
       stream.state = stream.localEnded ? "half-closed" : "open"
       stream.opened = true
-      this.#markGatewayAvailable()
+      this.#clearTargetUnavailable(stream.target)
+      if (this.#gatewayUnavailableSince !== undefined) {
+        this.#gatewayUnavailableSince = undefined
+        logDiagnostic(this.#options.logger, "reverse_client.gateway_available", {
+          generation: this.#generation,
+          ...this.#routeIdentityFields()
+        })
+      }
       logDiagnostic(this.#options.logger, "virtual_stream.opened", {
         streamId: stream.id,
         generation: this.#generation,
@@ -955,9 +892,21 @@ export class ReverseGatewayConnection extends EventEmitter {
       const detail = decodeV3Control(frame.payload)
       const code = typeof detail.code === "string" ? detail.code : "STREAM_RESET"
       stream.state = "reset"
-      if (code === "GATEWAY_UNAVAILABLE" || code === "GATEWAY_DISCONNECTED" || code === "GATEWAY_REPLACED") {
-        this.#markGatewayUnavailable(code)
-      }
+      // A stream reset describes this stream's target, not the health of the
+      // member's whole route class. The hub resolves gateways per (route class,
+      // target) and the transport set retries a failed open across members, so a
+      // single unreachable target would otherwise mark every route class down.
+      // Such a mark never expires on its own, which deadlocks the set: nothing is
+      // selected, so no open can succeed, so no mark can ever be cleared.
+      // Route-class availability is owned by the hub's GATEWAY_SELECTED response,
+      // which is class-scoped and re-read on every probe.
+      //
+      // What the reset does own is this target: the transport set must stop
+      // handing this member opens for a target it just reported unserviceable,
+      // while every other target keeps using it. The mark is keyed by target and
+      // cleared by the next OPENED for that target, so it never expires on a
+      // timer and can never wedge the set.
+      if (code === "GATEWAY_UNAVAILABLE" || code === "GATEWAY_DISCONNECTED") this.#markTargetUnavailable(stream.target)
       const error = attachDisconnectAttribution(new SocketductStreamError("Reverse gateway stream was reset", code), validHubAttribution(detail) ?? (code === "GATEWAY_DISCONNECTED" ? this.#disconnectAttribution : undefined))
       stream.socket._receiveError(error)
       return
@@ -1244,7 +1193,6 @@ 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. */
@@ -1330,11 +1278,6 @@ 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(() => {})
@@ -1452,9 +1395,6 @@ function validateOptions(options) {
   positiveInteger(options.maxConnectionBufferBytes, "maxConnectionBufferBytes", DEFAULT_CONNECTION_BUFFER_BYTES)
   if (options.spoolDirectory !== undefined && (typeof options.spoolDirectory !== "string" || options.spoolDirectory.length === 0)) throw new TypeError("spoolDirectory must be a non-empty string")
   positiveInteger(options.maxAgeMs, "maxAgeMs", 24 * 60 * 60 * 1000)
-  const gatewayProbeDelay = positiveInteger(options.gatewayProbeDelayMs, "gatewayProbeDelayMs", DEFAULT_GATEWAY_PROBE_DELAY_MS)
-  const maxGatewayProbeDelay = positiveInteger(options.maxGatewayProbeDelayMs, "maxGatewayProbeDelayMs", DEFAULT_MAX_GATEWAY_PROBE_DELAY_MS)
-  if (maxGatewayProbeDelay < gatewayProbeDelay) throw new RangeError("maxGatewayProbeDelayMs must not be smaller than gatewayProbeDelayMs")
   if (options.initialGeneration !== undefined && (!Number.isSafeInteger(options.initialGeneration) || options.initialGeneration < 0)) throw new RangeError("initialGeneration must be a non-negative safe integer")
 }
 

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

@@ -207,3 +207,163 @@ describe("multiplexed transport", () => {
     sockets.forEach((socket) => socket.destroy())
   }))
 })
+
+/**
+ * `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, and only then releases the
+ * transport.
+ */
+
+/** @returns {Promise<void>} */
+async function settleTurns() {
+  for (let index = 0; index < 10; index += 1) await new Promise((resolve) => setImmediate(resolve))
+}
+
+/**
+ * @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 opened stream.
+ */
+function streamAt(streams, index) {
+  const stream = streams[index]
+
+  if (stream === undefined) throw new Error(`Expected stream ${index} to be open`)
+
+  return stream
+}
+
+/**
+ * @param {(callback: () => Promise<void> | void) => void} after - Cleanup registrar.
+ * @param {number} streamCount - Streams to open.
+ */
+async function openDrainStreams(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(async () => {
+    for (const socket of targetSockets) socket.destroy()
+    await 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 transport drain", () => {
+  it("drain() keeps in-flight virtual streams alive until they finish", async () => withTestCleanup(async (after) => {
+    const {connection, relay, streams} = await openDrainStreams(after, 2)
+
+    const draining = connection.drain()
+
+    await settleTurns()
+
+    // drain() must not tear down streams that are still open.
+    expect(connection.status().virtualStreams).toBe(2)
+    expect(streamAt(streams, 0).destroyed).toBe(false)
+    expect(streamAt(streams, 1).destroyed).toBe(false)
+    // The physical transport must not be dropped while streams are live.
+    expect(relay.status().authenticatedConnections).toBe(1)
+
+    for (const stream of streams) stream.destroy()
+    await draining
+
+    expect(connection.status().virtualStreams).toBe(0)
+    // The physical transport is released once the last stream ends.
+    expect(relay.status().authenticatedConnections).toBe(0)
+  }))
+
+  it("drain() keeps working streams usable instead of resetting them", async () => withTestCleanup(async (after) => {
+    const {connection, streams} = await openDrainStreams(after, 1)
+    const draining = connection.drain()
+
+    await settleTurns()
+
+    streamAt(streams, 0).write("still-works")
+    /** @type {string} */
+    let echoed = ""
+
+    await new Promise((resolve, reject) => {
+      /** @param {Buffer} chunk - Echoed data. */
+      const onData = (chunk) => {
+        echoed += chunk.toString()
+        if (echoed.length < 11) return
+        streamAt(streams, 0).off("error", reject)
+        resolve(undefined)
+      }
+      streamAt(streams, 0).on("error", reject)
+      streamAt(streams, 0).on("data", onData)
+    })
+
+    // Data written during the drain must still reach the target and come back.
+    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 openDrainStreams(after, 1)
+    const draining = connection.drain()
+
+    await settleTurns()
+
+    // A draining connection must refuse new virtual streams instead of opening
+    // them on a doomed transport.
+    /** @type {unknown} */
+    let caughtError
+
+    try {
+      connection.createConnection({host: "127.0.0.1", port: targetPort, sessionName: "late"})
+    } catch (error) {
+      caughtError = error
+    }
+
+    expect(caughtError).toBeInstanceOf(Error)
+    expect(String(/** @type {Error} */ (caughtError).message)).toMatch(/connection is closed/i)
+    // The stream that was already open must survive.
+    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 openDrainStreams(after, 2)
+
+    await connection.close()
+
+    expect(connection.status().virtualStreams).toBe(0)
+    expect(streamAt(streams, 0).destroyed).toBe(true)
+    expect(streamAt(streams, 1).destroyed).toBe(true)
+    expect(relay.status().authenticatedConnections).toBe(0)
+  }))
+})

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

@@ -56,15 +56,6 @@ async function waitUntil(predicate, label) {
   }
 }
 
-/** @param {() => boolean} predicate - Completion predicate. @param {string} label - Failure label. @param {number} timeoutMs - Deadline. */
-async function waitUntilWithin(predicate, label, timeoutMs) {
-  const deadline = Date.now() + timeoutMs
-  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()
@@ -480,58 +471,42 @@ describe("reverse gateway route-class", () => {
     stream.destroy()
   }))
 
-  it("a route class registered down stays down, keeps being reached, and rejoins automatically", async () => withTestCleanup(async (after) => {
-    const root = await mkdtemp(join(tmpdir(), "socketduct-route-class-down-"))
+  it("a reset for one target without a gateway does not mark the whole route class unavailable", async () => withTestCleanup(async (after) => {
+    const root = await mkdtemp(join(tmpdir(), "socketduct-route-class-target-scope-"))
     after(() => rm(root, {recursive: true, force: true}))
     const certificates = generateTestCertificates(root)
     const targetA = await createEchoTarget("a:")
     after(() => targetA.close())
+    const targetB = await createEchoTarget("b:")
+    after(() => targetB.close())
 
+    // The route class is serviceable, but only target A has a configured gateway.
+    // Target B has none, so the hub resets opens for it with GATEWAY_UNAVAILABLE.
+    // That statement is about target B, not about the route class as a whole.
     const hub = await startReverseGatewayHub({
       tokens: new StaticTokenStore([
         {username: "home-a", token: "gateway-a-token"},
         {username: "tensorbuzz", token: "client-token"}
       ]),
       tls: {certFile: certificates.serverCertFile, keyFile: certificates.serverKeyFile},
-      knownGatewayIds: ["server-a-starlink"],
+      knownGatewayIds: ["server-a-starlink", "server-b-starlink"],
       knownRouteClasses: ["starlink"],
-      authorizeGateway: ({principal, gatewayId}) => principal.username === "home-a" && gatewayId === "server-a-starlink",
+      authorizeGateway: ({principal, gatewayId}) => principal.username === "home-a" && (gatewayId === "server-a-starlink" || gatewayId === "server-b-starlink"),
       authorizeClientGateway: () => false,
       authorizeClientRouteClass: ({principal, routeClass}) => principal.username === "tensorbuzz" && routeClass === "starlink",
-      resolveRouteClassGateways: () => ["server-a-starlink"],
-      resolveOpenGateways: ({routeClass, target}) => (routeClass === "starlink" && target.host === targetA.host ? ["server-a-starlink"] : []),
-      authorizeOpen: ({gatewayId, target}) => gatewayId === "server-a-starlink" && target.port === targetA.port
+      resolveRouteClassGateways: () => ["server-a-starlink", "server-b-starlink"],
+      resolveOpenGateways: ({routeClass, target}) => {
+        if (routeClass !== "starlink") return []
+        return target.port === targetA.port ? ["server-a-starlink"] : ["server-b-starlink"]
+      },
+      authorizeOpen: ({gatewayId, target}) => (gatewayId === "server-a-starlink" && target.port === targetA.port) || (gatewayId === "server-b-starlink" && target.port === targetB.port)
     })
     after(() => hub.close())
     const tls = {caFile: certificates.caCertFile, servername: "localhost"}
 
-    const client = new ReverseGatewayConnection({
-      routeClass: "starlink",
-      connectionId: "route_class_down_client",
-      hub: {host: "127.0.0.1", port: hub.port, token: "client-token"},
-      tls,
-      gatewayProbeDelayMs: 20,
-      maxGatewayProbeDelayMs: 40,
-      reconnectDelayMs: 10,
-      maxReconnectDelayMs: 20
-    })
-    after(() => client.close())
-
-    await client.connect()
-    expect(client.status().gatewayUnavailable).toBe(true)
-
-    // The member keeps reaching the hub while its route class is down.
-    await waitUntilWithin(() => client.status().gatewayProbeAttempts >= 3, "gateway re-reaching", 4_000)
-
-    // A down registration never expires on its own: the previous five-second
-    // mark would have silently returned this member to service with no gateway.
-    await new Promise((resolve) => setTimeout(resolve, 5_100))
-    expect(client.status().gatewayUnavailable).toBe(true)
-    expect(client.status().gatewayProbeAttempts >= 3).toBe(true)
-
     const gatewayA = new OutboundReverseGateway({
       gatewayId: "server-a-starlink",
-      connectionId: "down_gateway_a",
+      connectionId: "target_scope_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,
@@ -542,11 +517,39 @@ describe("reverse gateway route-class", () => {
     await gatewayA.start()
     await waitUntil(() => hub.status().healthyGateways === 1, "gateway A registration")
 
-    // The same member registers the class up again and is taken back into use.
-    await waitUntilWithin(() => client.status().gatewayUnavailable === false, "automatic re-registration", 4_000)
-    const stream = client.createConnection({host: targetA.host, port: targetA.port})
-    await onceEvent(stream, "connect")
-    expect(await exchange(stream, "probe")).toBe("a:probe")
-    stream.destroy()
+    const client = new ReverseGatewayConnection({
+      routeClass: "starlink",
+      connectionId: "target_scope_client",
+      hub: {host: "127.0.0.1", port: hub.port, token: "client-token"},
+      tls
+    })
+    after(() => client.close())
+    await client.connect()
+    expect(client.status().gatewayUnavailable).toBe(false)
+
+    // Target B's gateway is configured in the route table but is not registered
+    // (the maintenance/offline case), so the hub resets its opens as unavailable.
+    const unavailableStream = client.createConnection({host: targetB.host, port: targetB.port})
+    const reset = await nextError(unavailableStream)
+    expect(reset.code).toBe("GATEWAY_UNAVAILABLE")
+    unavailableStream.destroy()
+
+    // The route class is healthy, so the reset must not take it out of service.
+    // A member marked unavailable this way is never selected again, which would
+    // stall every later open in the set until the caller's own deadline.
+    expect({value: client.status().gatewayUnavailable, context: "a target-scoped reset must not mark the route class unavailable"}).toMatchObject({value: false})
+
+    // The member must still be skipped for the target the hub could not serve,
+    // otherwise every later open for it keeps paying a full round trip, while
+    // every other target on this member stays in rotation.
+    expect({value: client.isTargetUnavailable({host: targetB.host, port: targetB.port}), context: "the unserviceable target is marked on this member"}).toMatchObject({value: true})
+    expect({value: client.isTargetUnavailable({host: targetA.host, port: targetA.port}), context: "a different target stays available on the same member"}).toMatchObject({value: false})
+
+    // A healthy target on the same route class still opens and exchanges data.
+    const healthyStream = client.createConnection({host: targetA.host, port: targetA.port})
+    await onceEvent(healthyStream, "connect")
+    expect(await exchange(healthyStream, "probe")).toBe("a:probe")
+    healthyStream.destroy()
   }))
+
 })