socketduct 0.1.16 → 0.1.17

package/src/reverse/hub.js

@@ -6,6 +6,7 @@ import {availableCodecs, negotiateCodec, zstdAvailable} from "../protocol/compre
 import {decodeV3Data, encodeV3Data, AdaptiveCompressor} from "../protocol/v3-compression.js"
 import {decodeV3Control, encodeV3Control, encodeV3Frame, V3FrameDecoder, V3FrameType} from "../protocol/v3-frame.js"
 import {
+  asError,
   DEFAULT_FRAME_BYTES,
   DEFAULT_HANDSHAKE_MS,
   DEFAULT_KEEP_ALIVE_INITIAL_DELAY_MS,
@@ -17,10 +18,13 @@ import {
   parseTarget,
   positiveInteger,
   protocolError,
+  ROUTE_CLASS,
   STABLE_IDENTIFIER,
   writeSocket
 } from "./common.js"
 
+const DEFAULT_OUTPUT_BUFFER_BYTES = 32 * 1024 * 1024
+
 /**
  * @typedef {{userId: string, username: string}} Principal
  * @typedef {{host: string, port: number}} Target
@@ -31,8 +35,11 @@ import {
  * @property {{certFile: string, keyFile: string, clientCaFile?: string}} tls - Mandatory outer TLS server configuration.
  * @property {(input: {principal: Principal, gatewayId: string}) => boolean} authorizeGateway - Stable gateway identity binding.
  * @property {(input: {principal: Principal, gatewayId: string}) => boolean} authorizeClientGateway - Client-to-gateway selection policy.
+ * @property {(input: {principal: Principal, routeClass: string}) => boolean} [authorizeClientRouteClass] - Client-to-route-class selection policy.
  * @property {(input: {principal: Principal, gatewayId: string, target: Target}) => boolean} authorizeOpen - Hub-side route policy.
+ * @property {(input: {principal: Principal, routeClass: string, target: Target}) => string[]} [resolveOpenGateways] - Eligible exact gateways for a route-class OPEN.
  * @property {string[]} [knownGatewayIds] - Configured IDs that may be temporarily unavailable.
+ * @property {string[]} [knownRouteClasses] - Configured route classes available to authorized clients.
  * @property {number} [initialWindowBytes] - Per-direction flow-control window.
  * @property {number} [maxFrameBytes] - Maximum uncompressed DATA frame.
  * @property {number} [maxStreams] - Process-wide bridge limit.
@@ -40,6 +47,7 @@ import {
  * @property {number} [maxConnectionIdentities] - Retained stale-generation identity bound.
  * @property {number} [handshakeTimeoutMs] - Authentication deadline.
  * @property {number} [maxInputBytesPerConnection] - Pre-authentication byte bound.
+ * @property {number} [maxOutputBytesPerConnection] - Per-physical queued hub output bound.
  * @property {import('../protocol/compression.js').CompressionLimits} [compressionLimits] - zstd safety bounds.
  * @typedef {object} HubPhysical
  * @property {import('node:tls').TLSSocket} socket
@@ -49,12 +57,19 @@ import {
  * @property {number} generation
  * @property {string | undefined} codec
  * @property {string | undefined} gatewayId
+ * @property {string | undefined} routeClass
  * @property {Map<number, Bridge>} streams
  * @property {number} lastClientStreamId
  * @property {number} nextGatewayStreamId
  * @property {boolean} authenticated
  * @property {boolean} closing
  * @property {(() => void) | undefined} clearHandshake
+ * @property {HubOutputItem[]} outputQueue
+ * @property {number} outputBytes
+ * @property {boolean} outputWriting
+ * @typedef {object} HubOutputItem
+ * @property {Buffer} bytes
+ * @property {(delivered: boolean) => void} resolve
  * @typedef {object} GatewayOwner
  * @property {string} gatewayId
  * @property {string} connectionId
@@ -92,6 +107,7 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
   const maxStreams = positiveInteger(options.maxStreams, "maxStreams", DEFAULT_MAX_STREAMS)
   const maxIdentities = positiveInteger(options.maxConnectionIdentities, "maxConnectionIdentities", 4096)
   const maxPhysicalConnections = positiveInteger(options.maxPhysicalConnections, "maxPhysicalConnections", 8192)
+  const maxOutputBytes = positiveInteger(options.maxOutputBytesPerConnection, "maxOutputBytesPerConnection", DEFAULT_OUTPUT_BUFFER_BYTES)
   /** @type {Map<string, GatewayOwner>} */
   const gateways = new Map()
   /** @type {Map<string, ClientOwner>} */
@@ -153,12 +169,16 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
       generation: 0,
       codec: undefined,
       gatewayId: undefined,
+      routeClass: undefined,
       streams: new Map(),
       lastClientStreamId: 0,
       nextGatewayStreamId: 2,
       authenticated: false,
       closing: false,
-      clearHandshake: undefined
+      clearHandshake: undefined,
+      outputQueue: [],
+      outputBytes: 0,
+      outputWriting: false
     }
     physicals.add(physical)
     const decoder = new V3FrameDecoder({maxFrameBytes: Math.max(MAX_CONTROL_BYTES, maxFrameBytes + 4), maxBufferedBytes: Math.max(MAX_CONTROL_BYTES, maxFrameBytes + 4) * 2})
@@ -174,10 +194,9 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
         if (!physical.authenticated && unauthenticatedBytes > (options.maxInputBytesPerConnection ?? DEFAULT_MAX_INPUT_BYTES)) throw protocolError("INPUT_LIMIT_EXCEEDED")
         const frames = decoder.push(chunk)
         for (const frame of frames) await handleFrame(physical, frame)
-      }).catch(async (error) => {
+      }).catch((error) => {
         const code = typeof /** @type {{code?: unknown}} */ (error).code === "string" ? /** @type {{code: string}} */ (error).code : "PROTOCOL_VIOLATION"
-        await sendControl(physical, V3FrameType.GOAWAY, 0, 0, {code}).catch(() => {})
-        socket.destroy()
+        terminate(physical, code)
       }).finally(() => {
         if (!socket.destroyed && !physical.closing) socket.resume()
       })
@@ -237,9 +256,9 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
       await registerGateway(physical, frame)
       return
     }
-    if (physical.role === "client" && physical.gatewayId === undefined) {
+    if (physical.role === "client" && physical.gatewayId === undefined && physical.routeClass === undefined) {
       if (frame.type !== V3FrameType.GATEWAY_SELECT) throw protocolError("GATEWAY_SELECTION_REQUIRED")
-      await selectGateway(physical, frame)
+      await selectClientRoute(physical, frame)
       return
     }
     if (frame.type === V3FrameType.GATEWAY_REGISTER || frame.type === V3FrameType.GATEWAY_REGISTERED || frame.type === V3FrameType.GATEWAY_SELECT || frame.type === V3FrameType.GATEWAY_SELECTED || frame.type === V3FrameType.AUTH || frame.type === V3FrameType.AUTH_OK || frame.type === V3FrameType.AUTH_ERROR || frame.type === V3FrameType.RESUME || frame.type === V3FrameType.RESUMED) throw protocolError("UNSUPPORTED_FRAME")
@@ -309,17 +328,28 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
   }
 
   /** @param {HubPhysical} physical - Authenticated client. @param {import('../protocol/v3-frame.js').V3Frame} frame - Selection frame. */
-  async function selectGateway(physical, frame) {
+  async function selectClientRoute(physical, frame) {
     if (frame.streamId !== 0 || frame.sequence !== physical.generation || frame.flags !== 0) throw protocolError("INVALID_GATEWAY_SELECTION")
     const request = decodeV3Control(frame.payload)
-    if (typeof request.gatewayId !== "string" || !GATEWAY_ID.test(request.gatewayId)) throw protocolError("INVALID_GATEWAY_SELECTION")
-    if (physical.principal === undefined || options.authorizeClientGateway({principal: physical.principal, gatewayId: request.gatewayId}) !== true) throw protocolError("GATEWAY_UNAUTHORIZED")
-    const owner = gateways.get(request.gatewayId)
-    const known = owner !== undefined || options.knownGatewayIds?.includes(request.gatewayId) === true
-    if (!known) throw protocolError("UNKNOWN_GATEWAY_ID")
-    if (owner?.physical === undefined) throw protocolError("GATEWAY_UNAVAILABLE")
-    physical.gatewayId = request.gatewayId
-    await sendControl(physical, V3FrameType.GATEWAY_SELECTED, 0, physical.generation, {gatewayId: request.gatewayId, generation: physical.generation})
+    const hasGatewayId = Object.hasOwn(request, "gatewayId")
+    const hasRouteClass = Object.hasOwn(request, "routeClass")
+    if (hasGatewayId === hasRouteClass || physical.principal === undefined) throw protocolError("INVALID_GATEWAY_SELECTION")
+    if (hasGatewayId) {
+      if (typeof request.gatewayId !== "string" || !GATEWAY_ID.test(request.gatewayId)) throw protocolError("INVALID_GATEWAY_SELECTION")
+      if (options.authorizeClientGateway({principal: physical.principal, gatewayId: request.gatewayId}) !== true) throw protocolError("GATEWAY_UNAUTHORIZED")
+      const owner = gateways.get(request.gatewayId)
+      const known = owner !== undefined || options.knownGatewayIds?.includes(request.gatewayId) === true
+      if (!known) throw protocolError("UNKNOWN_GATEWAY_ID")
+      if (owner?.physical === undefined) throw protocolError("GATEWAY_UNAVAILABLE")
+      physical.gatewayId = request.gatewayId
+      await sendControl(physical, V3FrameType.GATEWAY_SELECTED, 0, physical.generation, {gatewayId: request.gatewayId, generation: physical.generation})
+      return
+    }
+    if (typeof request.routeClass !== "string" || !ROUTE_CLASS.test(request.routeClass)) throw protocolError("INVALID_ROUTE_CLASS_SELECTION")
+    if (options.authorizeClientRouteClass?.({principal: physical.principal, routeClass: request.routeClass}) !== true) throw protocolError("ROUTE_CLASS_UNAUTHORIZED")
+    if (options.knownRouteClasses?.includes(request.routeClass) !== true) throw protocolError("UNKNOWN_ROUTE_CLASS")
+    physical.routeClass = request.routeClass
+    await sendControl(physical, V3FrameType.GATEWAY_SELECTED, 0, physical.generation, {routeClass: request.routeClass, generation: physical.generation})
   }
 
   /** @param {HubPhysical} client - Client physical. @param {import('../protocol/v3-frame.js').V3Frame} frame - OPEN. */
@@ -329,20 +359,51 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
     client.lastClientStreamId = frame.streamId
     const request = decodeV3Control(frame.payload)
     const target = parseTarget(request.target)
-    if (target === undefined || typeof request.gatewayId !== "string" || request.gatewayId !== client.gatewayId || !GATEWAY_ID.test(request.gatewayId) || typeof request.identifier !== "string" || !STABLE_IDENTIFIER.test(request.identifier) || typeof request.name !== "string" || request.name.length === 0 || request.name.length > 256 || client.principal === undefined) {
+    if (target === undefined || typeof request.identifier !== "string" || !STABLE_IDENTIFIER.test(request.identifier) || typeof request.name !== "string" || request.name.length === 0 || request.name.length > 256 || client.principal === undefined) {
       await sendControl(client, V3FrameType.RESET, frame.streamId, 0, {code: "INVALID_STREAM_OPEN"})
       return
     }
-    if (options.authorizeOpen({principal: client.principal, gatewayId: request.gatewayId, target}) !== true) {
+    let gatewayId
+    if (client.routeClass !== undefined) {
+      if (request.routeClass !== client.routeClass || Object.hasOwn(request, "gatewayId")) {
+        await sendControl(client, V3FrameType.RESET, frame.streamId, 0, {code: "ROUTE_CLASS_MISMATCH"})
+        return
+      }
+      const candidates = options.resolveOpenGateways?.({principal: client.principal, routeClass: client.routeClass, target})
+      if (!Array.isArray(candidates) || candidates.some((candidate) => typeof candidate !== "string" || !GATEWAY_ID.test(candidate))) {
+        rejectedOpens += 1
+        await sendControl(client, V3FrameType.RESET, frame.streamId, 0, {code: "INVALID_ROUTE_RESOLUTION"})
+        return
+      }
+      if (candidates.length === 0) {
+        rejectedOpens += 1
+        await sendControl(client, V3FrameType.RESET, frame.streamId, 0, {code: "TARGET_UNAUTHORIZED"})
+        return
+      }
+      if (candidates.length !== 1 || new Set(candidates).size !== 1) {
+        rejectedOpens += 1
+        await sendControl(client, V3FrameType.RESET, frame.streamId, 0, {code: "AMBIGUOUS_ROUTE"})
+        return
+      }
+      gatewayId = /** @type {string} */ (candidates[0])
+    } else {
+      if (typeof request.gatewayId !== "string" || request.gatewayId !== client.gatewayId || !GATEWAY_ID.test(request.gatewayId) || Object.hasOwn(request, "routeClass")) {
+        await sendControl(client, V3FrameType.RESET, frame.streamId, 0, {code: "INVALID_STREAM_OPEN"})
+        return
+      }
+      gatewayId = request.gatewayId
+    }
+    if (options.authorizeOpen({principal: client.principal, gatewayId, target}) !== true) {
       rejectedOpens += 1
       await sendControl(client, V3FrameType.RESET, frame.streamId, 0, {code: "TARGET_UNAUTHORIZED"})
       return
     }
-    const gatewayOwner = gateways.get(request.gatewayId)
+    const gatewayOwner = gateways.get(gatewayId)
     const gateway = gatewayOwner?.physical
-    if (gateway === undefined || gateway.socket.destroyed || gateway.gatewayId !== request.gatewayId) {
+    if (gatewayOwner === undefined || gateway === undefined || gateway.socket.destroyed || gateway.role !== "gateway" || gateway.gatewayId !== gatewayId || gatewayOwner.gatewayId !== gatewayId || gatewayOwner.userId !== gateway.principal?.userId) {
       rejectedOpens += 1
-      await sendControl(client, V3FrameType.RESET, frame.streamId, 0, {code: gatewayOwner === undefined ? "UNKNOWN_GATEWAY_ID" : "GATEWAY_UNAVAILABLE"})
+      const known = gatewayOwner !== undefined || options.knownGatewayIds?.includes(gatewayId) === true
+      await sendControl(client, V3FrameType.RESET, frame.streamId, 0, {code: known ? "GATEWAY_UNAVAILABLE" : "UNKNOWN_GATEWAY_ID"})
       return
     }
     const gatewayStreamId = gateway.nextGatewayStreamId
@@ -372,7 +433,7 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
     client.streams.set(frame.streamId, bridge)
     gateway.streams.set(gatewayStreamId, bridge)
     bridges += 1
-    await sendControl(gateway, V3FrameType.OPEN, gatewayStreamId, 0, {identifier: request.identifier, name: request.name, target, initialWindow})
+    forwardControl(gateway, V3FrameType.OPEN, gatewayStreamId, 0, {identifier: request.identifier, name: request.name, target, initialWindow})
   }
 
   /** @param {HubPhysical} source - Frame source. @param {import('../protocol/v3-frame.js').V3Frame} frame - Stream frame. */
@@ -390,7 +451,7 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
       const detail = decodeV3Control(frame.payload)
       if (detail.identifier !== bridge.identifier) throw protocolError("OPEN_IDENTIFIER_MISMATCH")
       bridge.state = "open"
-      await sendControl(destination, V3FrameType.OPENED, destinationStreamId, 0, {identifier: bridge.identifier, initialWindow})
+      forwardControl(destination, V3FrameType.OPENED, destinationStreamId, 0, {identifier: bridge.identifier, initialWindow})
       return
     }
     if (bridge.state === "opening" && frame.type !== V3FrameType.RESET) throw protocolError("STREAM_NOT_OPEN")
@@ -400,12 +461,12 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
       if (!Number.isSafeInteger(frame.sequence) || frame.sequence < previous || frame.sequence > maximum) throw protocolError("INVALID_ACK")
       if (fromClient) bridge.gatewayToClientAck = frame.sequence
       else bridge.clientToGatewayAck = frame.sequence
-      if (bridge.state !== "closing") await sendControl(destination, V3FrameType.ACK, destinationStreamId, frame.sequence, {})
+      if (bridge.state !== "closing") forwardControl(destination, V3FrameType.ACK, destinationStreamId, frame.sequence, {})
       return
     }
     if (frame.type === V3FrameType.WINDOW) {
       if (frame.sequence <= 0 || frame.sequence > initialWindow) throw protocolError("INVALID_WINDOW")
-      if (bridge.state !== "closing") await sendControl(destination, V3FrameType.WINDOW, destinationStreamId, frame.sequence, {})
+      if (bridge.state !== "closing") forwardControl(destination, V3FrameType.WINDOW, destinationStreamId, frame.sequence, {})
       return
     }
     if (bridge.state === "closing") {
@@ -426,8 +487,7 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
       const encoded = await encodeV3Data(raw, destination.codec, fromClient ? bridge.clientToGatewayCompressor : bridge.gatewayToClientCompressor, options.compressionLimits)
       rawDataBytes += encoded.rawBytes
       wireDataBytes += encoded.wireBytes
-      const delivered = await writeSocket(destination.socket, encodeV3Frame({type: V3FrameType.DATA, streamId: destinationStreamId, sequence: frame.sequence, flags: encoded.flags}, encoded.payload))
-      if (!delivered) closeBridge(bridge, "DESTINATION_CLOSED", source)
+      forwardOutput(destination, encodeV3Frame({type: V3FrameType.DATA, streamId: destinationStreamId, sequence: frame.sequence, flags: encoded.flags}, encoded.payload))
       return
     }
     if (frame.type === V3FrameType.END) {
@@ -436,14 +496,14 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
       if (fromClient) bridge.clientEnded = true
       else bridge.gatewayEnded = true
       bridge.state = "half-closed"
-      await sendControl(destination, V3FrameType.END, destinationStreamId, frame.sequence, {})
+      forwardControl(destination, V3FrameType.END, destinationStreamId, frame.sequence, {})
       return
     }
     if (frame.type === V3FrameType.CLOSE || frame.type === V3FrameType.RESET) {
       const expected = fromClient ? bridge.clientToGatewaySequence : bridge.gatewayToClientSequence
       if ((frame.type === V3FrameType.CLOSE && frame.sequence !== expected) || (frame.type === V3FrameType.RESET && frame.sequence !== 0)) throw protocolError("INVALID_STREAM_CLOSE")
       const detail = frame.payload.length === 0 ? {} : decodeV3Control(frame.payload)
-      await sendControl(destination, frame.type, destinationStreamId, frame.sequence, detail)
+      forwardControl(destination, frame.type, destinationStreamId, frame.sequence, detail)
       if (frame.type === V3FrameType.RESET || fromClient) removeBridge(bridge)
       else bridge.state = "closing"
       return
@@ -458,6 +518,16 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
     if (existed) bridges = Math.max(0, bridges - 1)
   }
 
+  /** @param {HubPhysical} destination - Frame destination. @param {Buffer} bytes - Encoded frame. */
+  function forwardOutput(destination, bytes) {
+    void enqueueOutput(destination, bytes)
+  }
+
+  /** @param {HubPhysical} destination - Frame destination. @param {number} type - Frame type. @param {number} streamId - Destination stream. @param {number} sequence - Frame sequence. @param {Record<string, unknown>} value - Control body. */
+  function forwardControl(destination, type, streamId, sequence, value) {
+    forwardOutput(destination, encodeV3Frame({type, streamId, sequence}, encodeV3Control(value)))
+  }
+
   /** @param {Bridge} bridge - Stream. @param {string} code - Reset code. @param {HubPhysical} [excluded] - Already-dead peer. */
   function closeBridge(bridge, code, excluded) {
     if (bridge.client !== excluded && !bridge.client.socket.destroyed) void sendControl(bridge.client, V3FrameType.RESET, bridge.clientStreamId, 0, {code})
@@ -471,7 +541,7 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
     physical.closing = true
     const forceTimer = setTimeout(() => physical.socket.destroy(), 1_000)
     forceTimer.unref?.()
-    void sendControl(physical, V3FrameType.GOAWAY, 0, 0, {code}).finally(() => {
+    void sendControl(physical, V3FrameType.GOAWAY, 0, 0, {code}, true).finally(() => {
       clearTimeout(forceTimer)
       physical.socket.destroy()
     })
@@ -481,6 +551,7 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
   function detachPhysical(physical, code) {
     if (!physicals.delete(physical)) return
     physical.closing = true
+    discardQueuedOutput(physical)
     for (const bridge of [...physical.streams.values()]) closeBridge(bridge, physical.role === "gateway" ? "GATEWAY_DISCONNECTED" : code, physical)
     if (physical.gatewayId !== undefined) {
       const owner = gateways.get(physical.gatewayId)
@@ -497,9 +568,64 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
     }
   }
 
-  /** @param {HubPhysical} physical - Destination. @param {number} type - Frame type. @param {number} streamId - Stream ID. @param {number} sequence - Sequence. @param {Record<string, unknown>} value - Control body. */
-  async function sendControl(physical, type, streamId, sequence, value) {
-    return await writeSocket(physical.socket, encodeV3Frame({type, streamId, sequence}, encodeV3Control(value)))
+  /** @param {HubPhysical} physical - Destination. @param {Buffer} bytes - Encoded frame. @param {boolean} [allowClosing] - Allow a final GOAWAY after closing starts. @returns {Promise<boolean>} Delivery result. */
+  function enqueueOutput(physical, bytes, allowClosing = false) {
+    if (physical.socket.destroyed || (physical.closing && !allowClosing)) return Promise.resolve(false)
+    if (physical.outputBytes + bytes.length > maxOutputBytes) {
+      abortOutput(physical)
+      return Promise.resolve(false)
+    }
+    physical.outputBytes += bytes.length
+    const queued = new Promise((resolve) => physical.outputQueue.push({bytes, resolve}))
+    void drainOutput(physical)
+    return queued
+  }
+
+  /** @param {HubPhysical} physical - Destination output owner. */
+  async function drainOutput(physical) {
+    if (physical.outputWriting) return
+    physical.outputWriting = true
+    try {
+      while (physical.outputQueue.length > 0) {
+        const item = /** @type {HubOutputItem} */ (physical.outputQueue.shift())
+        let delivered = false
+        try {
+          delivered = await writeSocket(physical.socket, item.bytes)
+        } catch (error) {
+          physical.socket.destroy(asError(error))
+        }
+        physical.outputBytes = Math.max(0, physical.outputBytes - item.bytes.length)
+        item.resolve(delivered)
+        if (!delivered) {
+          discardQueuedOutput(physical)
+          abortOutput(physical, "DESTINATION_CLOSED")
+          break
+        }
+      }
+    } finally {
+      physical.outputWriting = false
+      if (physical.outputQueue.length > 0) void drainOutput(physical)
+    }
+  }
+
+  /** @param {HubPhysical} physical - Destination whose pending output is no longer deliverable. */
+  function discardQueuedOutput(physical) {
+    for (const item of physical.outputQueue.splice(0)) {
+      physical.outputBytes = Math.max(0, physical.outputBytes - item.bytes.length)
+      item.resolve(false)
+    }
+  }
+
+  /** @param {HubPhysical} physical - Destination whose output transport failed. @param {string} [code] - Terminal code. */
+  function abortOutput(physical, code = "OUTPUT_BACKPRESSURE_LIMIT") {
+    physical.closing = true
+    discardQueuedOutput(physical)
+    if (!physical.socket.destroyed) physical.socket.destroy(protocolError(code))
+  }
+
+  /** @param {HubPhysical} physical - Destination. @param {number} type - Frame type. @param {number} streamId - Stream ID. @param {number} sequence - Sequence. @param {Record<string, unknown>} value - Control body. @param {boolean} [allowClosing] - Allow a final GOAWAY. @returns {Promise<boolean>} Delivery result. */
+  function sendControl(physical, type, streamId, sequence, value, allowClosing = false) {
+    return enqueueOutput(physical, encodeV3Frame({type, streamId, sequence}, encodeV3Control(value)), allowClosing)
   }
 
   await new Promise((resolve, reject) => {
@@ -517,6 +643,8 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
       physicalConnections: tcpSockets.size,
       gatewayPhysicalConnections: [...physicals].filter((physical) => physical.role === "gateway" && physical.gatewayId !== undefined).length,
       clientPhysicalConnections: [...physicals].filter((physical) => physical.role === "client" && physical.authenticated).length,
+      routeClassClientPhysicalConnections: [...physicals].filter((physical) => physical.role === "client" && physical.routeClass !== undefined).length,
+      queuedOutputBytes: [...physicals].reduce((total, physical) => total + physical.outputBytes, 0),
       retainedClientIdentities: clients.size,
       registeredGateways: gateways.size,
       healthyGateways: [...gateways.values()].filter((owner) => owner.physical !== undefined).length,
@@ -557,6 +685,9 @@ function validateOptions(options) {
   if (typeof options.tls !== "object" || options.tls === null || typeof options.tls.certFile !== "string" || typeof options.tls.keyFile !== "string") throw new TypeError("Reverse gateway hub requires TLS certFile and keyFile")
   if (!zstdAvailable()) throw new Error("Reverse gateway hub requires Node.js zstd support")
   if (options.knownGatewayIds !== undefined && (!Array.isArray(options.knownGatewayIds) || options.knownGatewayIds.some((gatewayId) => typeof gatewayId !== "string" || !GATEWAY_ID.test(gatewayId)) || new Set(options.knownGatewayIds).size !== options.knownGatewayIds.length)) throw new TypeError("knownGatewayIds must contain unique valid gateway IDs")
+  const routeClassPolicyConfigured = options.knownRouteClasses !== undefined || options.authorizeClientRouteClass !== undefined || options.resolveOpenGateways !== undefined
+  if (routeClassPolicyConfigured && (!Array.isArray(options.knownRouteClasses) || options.knownRouteClasses.length === 0 || typeof options.authorizeClientRouteClass !== "function" || typeof options.resolveOpenGateways !== "function")) throw new TypeError("Route-class hub policy requires knownRouteClasses, authorizeClientRouteClass, and resolveOpenGateways")
+  if (options.knownRouteClasses !== undefined && (options.knownRouteClasses.some((routeClass) => typeof routeClass !== "string" || !ROUTE_CLASS.test(routeClass)) || new Set(options.knownRouteClasses).size !== options.knownRouteClasses.length)) throw new TypeError("knownRouteClasses must contain unique valid route classes")
   const frame = positiveInteger(options.maxFrameBytes, "maxFrameBytes", DEFAULT_FRAME_BYTES)
   const window = positiveInteger(options.initialWindowBytes, "initialWindowBytes", DEFAULT_WINDOW)
   if (frame > window) throw new RangeError("maxFrameBytes must not exceed initialWindowBytes")

package/src/reverse/runtime.js

@@ -9,13 +9,28 @@ export async function startReverseHubRuntime(config) {
   if (config.relayTls === undefined) throw new Error("Reverse hub mode requires SOCKETDUCT_TLS_CERT_FILE and SOCKETDUCT_TLS_KEY_FILE")
   if (config.authTokens.length === 0) throw new Error("SOCKETDUCT_AUTH_TOKENS must contain hub client and gateway credentials")
   if (config.reverseGatewayBindings === undefined || config.reverseGatewayBindings.length === 0) throw new Error("SOCKETDUCT_REVERSE_GATEWAY_BINDINGS must bind at least one gateway ID to a credential username")
-  if (config.reverseRoutes === undefined || config.reverseRoutes.length === 0) throw new Error("SOCKETDUCT_REVERSE_ROUTES must allow at least one client/gateway/target route")
+  const exactRoutes = config.reverseRoutes ?? []
+  const routeClassRoutes = config.reverseRouteClassRoutes ?? []
+  if (exactRoutes.length === 0 && routeClassRoutes.length === 0) throw new Error("SOCKETDUCT_REVERSE_ROUTES or SOCKETDUCT_REVERSE_ROUTE_CLASS_ROUTES must allow at least one client route")
   if (config.compression === "off") throw new Error("Reverse hub mode requires SOCKETDUCT_COMPRESSION=auto")
   const bindings = new Map(config.reverseGatewayBindings.map((binding) => [binding.gatewayId, binding.username]))
-  const routes = new Set(config.reverseRoutes.map((route) => formatRoute(route.username, route.gatewayId, {host: route.host, port: route.port})))
-  const selections = new Set(config.reverseRoutes.map((route) => `${route.username}\0${route.gatewayId}`))
+  const authorizedRoutes = new Set([...exactRoutes, ...routeClassRoutes].map((route) => formatRoute(route.username, route.gatewayId, {host: route.host, port: route.port})))
+  const exactRouteKeys = new Set(exactRoutes.map((route) => formatRoute(route.username, route.gatewayId, {host: route.host, port: route.port})))
+  const exactSelections = new Set(exactRoutes.map((route) => `${route.username}\0${route.gatewayId}`))
+  const routeClassSelections = new Set(routeClassRoutes.map((route) => `${route.username}\0${route.routeClass}`))
+  const knownRouteClasses = [...new Set(routeClassRoutes.map((route) => route.routeClass))]
+  /** @type {Map<string, string[]>} */
+  const routeClassGateways = new Map()
+  for (const route of routeClassRoutes) {
+    const key = formatRouteClassRoute(route.username, route.routeClass, {host: route.host, port: route.port})
+    const gatewayIds = routeClassGateways.get(key) ?? []
+    gatewayIds.push(route.gatewayId)
+    routeClassGateways.set(key, gatewayIds)
+  }
+  const routeClassRows = new Set(routeClassRoutes.map((route) => `${formatRouteClassRoute(route.username, route.routeClass, {host: route.host, port: route.port})}\0${route.gatewayId}`))
   if (bindings.size !== config.reverseGatewayBindings.length) throw new Error("SOCKETDUCT_REVERSE_GATEWAY_BINDINGS contains a duplicate gateway ID")
-  if (routes.size !== config.reverseRoutes.length) throw new Error("SOCKETDUCT_REVERSE_ROUTES contains a duplicate route")
+  if (exactRouteKeys.size !== exactRoutes.length) throw new Error("SOCKETDUCT_REVERSE_ROUTES contains a duplicate route")
+  if (routeClassRows.size !== routeClassRoutes.length) throw new Error("SOCKETDUCT_REVERSE_ROUTE_CLASS_ROUTES contains a duplicate route")
   const relayTls = config.relayTls
   const tls = {
     certFile: relayTls.certFile,
@@ -28,9 +43,14 @@ export async function startReverseHubRuntime(config) {
     tls,
     tokens: new StaticTokenStore(config.authTokens),
     knownGatewayIds: [...bindings.keys()],
+    ...(knownRouteClasses.length === 0 ? {} : {knownRouteClasses}),
     authorizeGateway: ({principal, gatewayId}) => bindings.get(gatewayId) === principal.username,
-    authorizeClientGateway: ({principal, gatewayId}) => selections.has(`${principal.username}\0${gatewayId}`),
-    authorizeOpen: ({principal, gatewayId, target}) => routes.has(formatRoute(principal.username, gatewayId, target)),
+    authorizeClientGateway: ({principal, gatewayId}) => exactSelections.has(`${principal.username}\0${gatewayId}`),
+    ...(knownRouteClasses.length === 0 ? {} : {
+      authorizeClientRouteClass: ({principal, routeClass}) => routeClassSelections.has(`${principal.username}\0${routeClass}`),
+      resolveOpenGateways: ({principal, routeClass, target}) => [...(routeClassGateways.get(formatRouteClassRoute(principal.username, routeClass, target)) ?? [])]
+    }),
+    authorizeOpen: ({principal, gatewayId, target}) => authorizedRoutes.has(formatRoute(principal.username, gatewayId, target)),
     handshakeTimeoutMs: config.handshakeTimeoutMs,
     maxInputBytesPerConnection: config.maxInputBytesPerConnection,
     compressionLimits: compressionLimits(config)
@@ -68,6 +88,11 @@ function formatRoute(username, gatewayId, target) {
   return `${username}\0${gatewayId}\0${target.host}\0${target.port}`
 }
 
+/** @param {string} username - Client. @param {string} routeClass - Route class. @param {{host: string, port: number}} target - Target. */
+function formatRouteClassRoute(username, routeClass, target) {
+  return `${username}\0${routeClass}\0${target.host}\0${target.port}`
+}
+
 /** @param {import('../config/environment.js').RelayEnvironmentConfig} config - Runtime limits. @returns {import('../protocol/compression.js').CompressionLimits} Defined codec limits. */
 function compressionLimits(config) {
   return {

package/test/e2e/reverse-gateway-process.test.js

@@ -6,6 +6,7 @@ import {createServer} from "node:net"
 import {tmpdir} from "node:os"
 import {join} from "node:path"
 import test from "node:test"
+import {connect as connectTls} from "node:tls"
 
 import {ReverseGatewayConnection} from "../../src/reverse/client.js"
 import {generateTestCertificates} from "../helpers/tls-certificates.js"
@@ -283,3 +284,95 @@ test("spawned reverse hub and outbound gateway expose an allowlisted Docker stre
   assert(gatewayEntries.some(({event}) => event === "transport.connected"))
   assert.doesNotMatch(gatewayContents, /process-gateway-token|127\.0\.0\.1|docker-server/)
 })
+
+test("one route-class client physical connection interleaves streams through different gateway processes", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-route-class-process-"))
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const certificates = generateTestCertificates(root)
+  const targetSockets = new Set()
+  const targetA = createServer((socket) => {
+    targetSockets.add(socket)
+    socket.once("close", () => targetSockets.delete(socket))
+    socket.on("data", (chunk) => socket.write(Buffer.concat([Buffer.from("a:"), chunk])))
+  })
+  const targetB = createServer((socket) => {
+    targetSockets.add(socket)
+    socket.once("close", () => targetSockets.delete(socket))
+    socket.on("data", (chunk) => socket.write(Buffer.concat([Buffer.from("b:"), chunk])))
+  })
+  const targetAPort = await listen(targetA)
+  const targetBPort = await listen(targetB)
+  t.after(() => {
+    for (const socket of targetSockets) socket.destroy()
+    return Promise.all([
+      new Promise((resolve) => targetA.close(() => resolve(undefined))),
+      new Promise((resolve) => targetB.close(() => resolve(undefined)))
+    ])
+  })
+
+  const {child: hub, port: hubPort} = await startProcessOnReservedPort({
+    SOCKETDUCT_MODE: "reverse-hub",
+    SOCKETDUCT_RELAY_HOST: "127.0.0.1",
+    SOCKETDUCT_TLS_CERT_FILE: certificates.serverCertFile,
+    SOCKETDUCT_TLS_KEY_FILE: certificates.serverKeyFile,
+    SOCKETDUCT_AUTH_TOKENS: "home-a:gateway-a-token,home-b:gateway-b-token,tensorbuzz:client-token",
+    SOCKETDUCT_REVERSE_GATEWAY_BINDINGS: "server-a-starlink:home-a,server-b-starlink:home-b",
+    SOCKETDUCT_REVERSE_ROUTE_CLASS_ROUTES: `tensorbuzz:starlink:server-a-starlink:127.0.0.1:${targetAPort},tensorbuzz:starlink:server-b-starlink:127.0.0.1:${targetBPort}`,
+    SOCKETDUCT_STATUS_INTERVAL_MS: "0"
+  }, "reverse-hub.started")
+  t.after(() => stopProcess(hub))
+
+  const gatewayA = await startProcess({
+    SOCKETDUCT_MODE: "reverse-gateway",
+    SOCKETDUCT_REVERSE_GATEWAY_ID: "server-a-starlink",
+    SOCKETDUCT_REVERSE_CONNECTION_ID: "route_class_process_gateway_a",
+    SOCKETDUCT_REVERSE_HUB_HOST: "127.0.0.1",
+    SOCKETDUCT_REVERSE_HUB_PORT: String(hubPort),
+    SOCKETDUCT_REVERSE_TOKEN: "gateway-a-token",
+    SOCKETDUCT_REVERSE_HUB_CA_FILE: certificates.caCertFile,
+    SOCKETDUCT_REVERSE_HUB_SERVERNAME: "localhost",
+    SOCKETDUCT_TARGET_ALLOWLIST: `127.0.0.1:${targetAPort}`,
+    SOCKETDUCT_STATUS_INTERVAL_MS: "0"
+  }, "reverse-gateway.started")
+  t.after(() => stopProcess(gatewayA))
+  const gatewayB = await startProcess({
+    SOCKETDUCT_MODE: "reverse-gateway",
+    SOCKETDUCT_REVERSE_GATEWAY_ID: "server-b-starlink",
+    SOCKETDUCT_REVERSE_CONNECTION_ID: "route_class_process_gateway_b",
+    SOCKETDUCT_REVERSE_HUB_HOST: "127.0.0.1",
+    SOCKETDUCT_REVERSE_HUB_PORT: String(hubPort),
+    SOCKETDUCT_REVERSE_TOKEN: "gateway-b-token",
+    SOCKETDUCT_REVERSE_HUB_CA_FILE: certificates.caCertFile,
+    SOCKETDUCT_REVERSE_HUB_SERVERNAME: "localhost",
+    SOCKETDUCT_TARGET_ALLOWLIST: `127.0.0.1:${targetBPort}`,
+    SOCKETDUCT_STATUS_INTERVAL_MS: "0"
+  }, "reverse-gateway.started")
+  t.after(() => stopProcess(gatewayB))
+
+  let clientPhysicalConnections = 0
+  const client = new ReverseGatewayConnection({
+    routeClass: "starlink",
+    connectionId: "route_class_process_client",
+    hub: {host: "127.0.0.1", port: hubPort, token: "client-token"},
+    tls: {caFile: certificates.caCertFile, servername: "localhost"},
+    createPhysicalSocket: ({host, port, tls}) => {
+      clientPhysicalConnections += 1
+      return connectTls({host, port, ...tls})
+    }
+  })
+  t.after(() => client.close())
+  await withTimeout(client.connect(), "route-class process client connect")
+  const streamA = client.createConnection({host: "127.0.0.1", port: targetAPort, sessionName: "route-class-a"})
+  const streamB = client.createConnection({host: "127.0.0.1", port: targetBPort, sessionName: "route-class-b"})
+  await withTimeout(Promise.all([onceEvent(streamA, "connect"), onceEvent(streamB, "connect")]), "route-class process streams")
+  const responseA = new Promise((resolve, reject) => { streamA.once("error", reject); streamA.once("data", resolve) })
+  const responseB = new Promise((resolve, reject) => { streamB.once("error", reject); streamB.once("data", resolve) })
+  streamA.write("one")
+  streamB.write("two")
+  assert.equal(Buffer.from(/** @type {Uint8Array} */ (await withTimeout(responseA, "route-class response A"))).toString(), "a:one")
+  assert.equal(Buffer.from(/** @type {Uint8Array} */ (await withTimeout(responseB, "route-class response B"))).toString(), "b:two")
+  assert.equal(clientPhysicalConnections, 1)
+  assert.equal(client.status().physicalConnects, 1)
+  streamA.destroy()
+  streamB.destroy()
+})