socketduct 0.1.16 → 0.1.18

package/docs/socket-api.md

@@ -104,7 +104,7 @@ responsible for durably reconciling application state after uncertain results.
 `detach()` requires an explicit `connectionId`, preserves active spools and
 does not send stream resets. `close()` remains terminal and removes spools.
 
-### `MultiplexedSocketductTransportSet` (multi-gateway v3 API)
+### `MultiplexedSocketductTransportSet` (multi-route v3 API)
 
 Use one transport set per Node process when the process has several genuinely
 distinct gateway paths:
@@ -133,14 +133,38 @@ agent.createConnection = set.createConnection
 await starting
 ```
 
-Every entry must have a stable 2-64 character `gatewayId` and an explicit
-`endpoint.relay`. An optional, gateway-specific `endpoint.createPhysicalSocket`
-can pin an interface, routing table or external transport. Repeating the same
-relay address without distinct pinned factories is rejected: assigning three
-names to one load-balanced endpoint is not path diversity. Socketduct cannot
-inspect arbitrary DNS or factory routing, so callers remain responsible for
-making each declared endpoint/factory genuinely gateway-pinned. Blank,
-duplicate and path-unsafe IDs and malformed endpoint entries fail synchronously.
+For native reverse hubs, configure first-class route classes instead of exact
+gateways. Exactly one of `gateways` or `routeClasses` is accepted:
+
+```js
+const set = new MultiplexedSocketductTransportSet({
+  connectionId: "runner_01_stable_identity",
+  minimumReadyMembers: 1,
+  routeClasses: ["starlink", "zyxel", "o2"].map((routeClass) => ({
+    routeClass,
+    endpoint: {
+      reverseHub: {host: "hub.example.net", port: 3100, token},
+      tls: {caFile: "/certs/hub-ca.crt", servername: "hub.example.net"}
+    }
+  }))
+})
+```
+
+Each route-class member owns one physical connection and stable identity for
+the `{connectionId, routeClass}` pair. The hub resolves every requested target
+to one exact registered gateway, so the physical count is independent of the
+number of server-local target gateways. Route classes require a verified
+`reverseHub` endpoint; they cannot wrap an ordinary relay.
+
+For the exact-gateway relay form, every entry must have a stable 2-64 character
+`gatewayId` and an explicit `endpoint.relay`. An optional, gateway-specific
+`endpoint.createPhysicalSocket` can pin an interface, routing table or external
+transport. Repeating the same relay address without distinct pinned factories
+is rejected: assigning three names to one load-balanced endpoint is not path
+diversity. Socketduct cannot inspect arbitrary DNS or factory routing, so callers
+remain responsible for making each declared endpoint/factory genuinely
+gateway-pinned. Blank, duplicate and path-unsafe IDs and malformed endpoint
+entries fail synchronously.
 
 `start()` constructs no new members: the constructor creates exactly one
 `MultiplexedSocketductConnection` per gateway and `start()` warms all of them
@@ -159,12 +183,16 @@ its normal `connecting`/`pending` state. Opens wait FIFO until initial
 member may resume the queue. New calls never wait behind a reconnecting route
 when a healthy sibling is ready.
 
-Waiting does not assign an anonymous or merely connecting member. `gatewayId`
-is `undefined` until one ready member accepts the open, then becomes the stable,
-immutable configured ID for that socket. Destroying the socket first removes
-the pending open, so later readiness cannot leak a member stream. A member
-selected immediately before its path drops retains the stream and performs
-member-local v3 recovery; the set never speculatively migrates it.
+Waiting does not assign an anonymous or merely connecting member. For an exact
+set, `gatewayId` is `undefined` until one ready member accepts the open, then
+becomes the stable, immutable configured ID. For a route-class set,
+`routeClass` behaves the same way and `gatewayId` remains undefined. Destroying
+the socket first removes the pending open, so later readiness cannot leak a
+member stream. An exact relay member selected immediately before its path drops
+retains the stream and performs member-local v3 recovery; the set never
+speculatively migrates it. A reverse route-class stream likewise remains on its
+resolved target gateway while Socketduct replaces and resumes the physical
+client/gateway transports underneath it.
 
 `createConnection(options, callback)` is pre-bound and invokes its callback once
 on `connect` or the terminal pre-connect error; the socket emits `connect` before
@@ -189,9 +217,13 @@ socket with ordinary `tls.connect` target options such as `servername`, `ca`,
 `cert` and `key`. Node TLS owns the handshake, `secureConnect`, TLS errors and
 the callback, which runs exactly once only after `secureConnect` or failure.
 Both methods count only completed member assignments and preserve stream
-stickiness. Every returned raw or TLS socket exposes enumerable `gatewayId`;
-persist its immutable value after connection so a replacement can recover the
-stream on its original member.
+stickiness. Every returned raw or TLS socket exposes enumerable `gatewayId` and
+`routeClass` allocation metadata. Only the configured identity is set. Persist
+an exact set's immutable `gatewayId` after connection so a replacement can
+recover the stream on its original member. Reverse route-class streams are not
+recoverable across process replacement, but they do recover transparently from
+a transient physical transport loss while the original objects and target
+socket remain alive.
 
 Process-replacement recovery is deliberately separate from ordinary selection.
 First detach the old set when an orderly handoff is possible. Construct the
@@ -217,8 +249,8 @@ await replacement.start()
 gateway ID, an explicit `recover` option, or registration after `start()` has
 begun. It bypasses round-robin only to reach that configured member; it never
 migrates or replays the stream on a sibling. Ordinary `createConnection()` and
-`createTlsConnection()` reject `recover: true` and `gatewayId`, so new opens
-cannot force a path. `detach()` coalesces with concurrent shutdown calls,
+`createTlsConnection()` reject `recover: true`, `gatewayId`, and `routeClass`,
+so new opens cannot force a path. `detach()` coalesces with concurrent shutdown calls,
 preserves active member spools, and retires empty warmed lanes; `close()` remains
 terminal and removes their spools.
 
@@ -239,7 +271,7 @@ capacity occupied and fails the affected member visibly.
 
 `status()` returns only safe aggregate counts/bytes, `pendingOpens`, its maximum,
 and an ordered member list:
-gateway ID, lifecycle state, assignments, physical connects/reconnects, virtual
+gateway ID or route class, lifecycle state, assignments, physical connects/reconnects, virtual
 stream count and queued/spool bytes. It excludes relays, targets, tokens,
 credentials, names, payloads and spool contents. Concurrent `close()` calls
 share one promise. Every member is attempted once in configured order; multiple
@@ -370,8 +402,12 @@ It selects exactly one registered gateway during `connect()`. The existing
 `MultiplexedSocketductTransportSet` accepts `endpoint.reverseHub`, allowing
 three ready members to retain deterministic health-aware round-robin behavior.
 Reverse established operations deliberately do not support
-`registerRecoveredConnection()` or durable replay; a transport loss is a typed
-terminal result requiring application reconciliation.
+`registerRecoveredConnection()` across process replacement. They do durably
+spool unacknowledged send chunks during the lifetime of the client and gateway
+objects, then use paired v3 resume manifests to survive physical transport
+replacement without reopening the target or replaying an application request
+as a new logical stream. Target loss, resume expiry, identity mismatch, or a
+configured bound remains terminal and requires application reconciliation.
 
 Reverse virtual sockets accept individual writes larger than their configured
 retained-byte limit. The connection progresses those writes in slices bounded by

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "socketduct",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Resilient authenticated tunnel/proxy for keeping socket streams alive across flaky links.",
   "type": "module",
   "main": "./src/index.js",

package/src/client/deferred-virtual-socket.js

@@ -212,6 +212,9 @@ export class DeferredVirtualSocket extends VirtualSocket {
   /** @type {string | undefined} */
   #gatewayId
 
+  /** @type {string | undefined} */
+  #routeClass
+
   /**
    * @param {{host: string, port: number, allowHalfOpen?: boolean, readableHighWaterMark?: number, writableHighWaterMark?: number}} socketOptions - Target/socket options.
    * @param {DeferredVirtualSocketOptions} deferredOptions - Set-owned wait policy.
@@ -222,6 +225,7 @@ export class DeferredVirtualSocket extends VirtualSocket {
     this.#owner = owner
     owner.attach(this)
     Object.defineProperty(this, "gatewayId", {get: () => this.#gatewayId, enumerable: true, configurable: false})
+    Object.defineProperty(this, "routeClass", {get: () => this.#routeClass, enumerable: true, configurable: false})
   }
 
   /** @returns {string | undefined} Immutable assignment selected only after readiness. */
@@ -229,6 +233,11 @@ export class DeferredVirtualSocket extends VirtualSocket {
     return this.#gatewayId
   }
 
+  /** @returns {string | undefined} Immutable route-class assignment selected only after readiness. */
+  get routeClass() {
+    return this.#routeClass
+  }
+
   /**
    * @override
    * @returns {number} Assigned protocol stream ID, or zero while unassigned.
@@ -239,13 +248,16 @@ export class DeferredVirtualSocket extends VirtualSocket {
 
   /**
    * @param {VirtualSocket} socket - Selected ready-member socket.
-   * @param {string} gatewayId - Stable selected gateway ID.
+   * @param {string | {gatewayId?: string, routeClass?: string}} selection - Stable selected member identity.
    * @returns {boolean} Whether assignment succeeded before cancellation.
    */
-  assign(socket, gatewayId) {
-    if (this.#gatewayId !== undefined) throw new Error("Deferred Socketduct socket gateway is already assigned")
+  assign(socket, selection) {
+    if (this.#gatewayId !== undefined || this.#routeClass !== undefined) throw new Error("Deferred Socketduct socket member is already assigned")
+    const allocation = typeof selection === "string" ? {gatewayId: selection} : selection
+    if ((typeof allocation.gatewayId === "string") === (typeof allocation.routeClass === "string")) throw new Error("Deferred Socketduct socket requires exactly one gatewayId or routeClass assignment")
     if (!this.#owner.assign(socket)) return false
-    this.#gatewayId = gatewayId
+    this.#gatewayId = allocation.gatewayId
+    this.#routeClass = allocation.routeClass
     return true
   }
 

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

@@ -7,6 +7,7 @@ import {connect as tlsConnect} from "node:tls"
 
 import {errorDiagnostics, logDiagnostic} from "../logging/structured-logger.js"
 import {ReverseGatewayConnection} from "../reverse/client.js"
+import {ROUTE_CLASS} from "../reverse/common.js"
 import {DeferredVirtualSocket} from "./deferred-virtual-socket.js"
 import {MultiplexedSocketductConnection} from "./multiplexed-connection.js"
 
@@ -26,10 +27,14 @@ const GATEWAY_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{1,63}$/
  * @typedef {object} GatewayConfiguration
  * @property {string} gatewayId - Stable, privacy-safe gateway identity.
  * @property {GatewayEndpoint} endpoint - Explicit gateway-pinned endpoint/factory.
+ * @typedef {object} RouteClassConfiguration
+ * @property {string} routeClass - Stable WAN route-class identity.
+ * @property {GatewayEndpoint} endpoint - Shared reverse-hub endpoint/factory.
  * @typedef {object} TransportSetOptions
  * @property {string} connectionId - Stable process/base connection identity.
  * @property {string} [spoolDirectory] - Base directory for derived gateway spool namespaces.
- * @property {GatewayConfiguration[]} gateways - Explicit configured gateways.
+ * @property {GatewayConfiguration[]} [gateways] - Explicit configured exact gateways.
+ * @property {RouteClassConfiguration[]} [routeClasses] - Explicit configured route-class members.
  * @property {number} [minimumReadyMembers] - Required ready members for start(), default 1.
  * @property {number} [maxTotalBufferBytes] - Set-wide retained data limit.
  * @property {number} [maxTotalSpoolBytes] - Set-wide durable spool data limit.
@@ -58,9 +63,10 @@ const GATEWAY_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{1,63}$/
  * @property {() => unknown} [ref] - Reference resources.
  * @property {() => unknown} [unref] - Unreference resources.
  * @typedef {object} TransportSetDependencies
- * @property {(options: import('./multiplexed-connection.js').MultiplexedConnectionOptions | import('../reverse/client.js').ReverseGatewayConnectionOptions, gatewayId: string) => TransportMemberConnection} [createMember] - Narrow test dependency.
+ * @property {(options: import('./multiplexed-connection.js').MultiplexedConnectionOptions | import('../reverse/client.js').ReverseGatewayConnectionOptions, memberIdentity: string) => TransportMemberConnection} [createMember] - Narrow test dependency.
  * @typedef {object} TransportMember
- * @property {string} gatewayId - Stable gateway ID.
+ * @property {string | undefined} gatewayId - Stable exact gateway ID.
+ * @property {string | undefined} routeClass - Stable route-class identity.
  * @property {TransportMemberConnection} connection - Single-lane owner.
  * @property {number} assignments - Virtual sockets assigned for life.
  * @property {Error | undefined} startupError - Terminal startup error.
@@ -69,8 +75,8 @@ const GATEWAY_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{1,63}$/
  * @typedef {object} PendingOpen
  * @property {import('./multiplexed-connection.js').VirtualConnectionOptions} options - Validated caller options.
  * @property {DeferredVirtualSocket} socket - Immediate app-facing socket.
- * @typedef {import('./virtual-socket.js').VirtualSocket & {readonly gatewayId: string | undefined}} GatewayVirtualSocket
- * @typedef {import('node:tls').TLSSocket & {readonly gatewayId: string | undefined}} GatewayTlsSocket
+ * @typedef {import('./virtual-socket.js').VirtualSocket & {readonly gatewayId: string | undefined, readonly routeClass: string | undefined}} GatewayVirtualSocket
+ * @typedef {import('node:tls').TLSSocket & {readonly gatewayId: string | undefined, readonly routeClass: string | undefined}} GatewayTlsSocket
  */
 
 /** No configured gateway is currently safe for a new virtual stream. */
@@ -239,11 +245,12 @@ export class MultiplexedSocketductTransportSet extends EventEmitter {
     this.#maxPendingOpens = validated.maxPendingOpens
     this.#budget = new AggregateTransportBudget(validated.limits)
     this.#logger = options.logger
-    const createMember = dependencies.createMember ?? ((memberOptions) => "gatewayId" in memberOptions
+    const createMember = dependencies.createMember ?? ((memberOptions) => "hub" in memberOptions
       ? new ReverseGatewayConnection(memberOptions)
       : new MultiplexedSocketductConnection(memberOptions))
-    this.#members = validated.gateways.map(({gatewayId, endpoint}) => {
-      const identity = deriveGatewayIdentity(options.connectionId, gatewayId)
+    this.#members = validated.members.map(({gatewayId, routeClass, endpoint}) => {
+      const memberIdentity = /** @type {string} */ (gatewayId ?? routeClass)
+      const identity = gatewayId === undefined ? deriveRouteClassIdentity(options.connectionId, memberIdentity) : deriveGatewayIdentity(options.connectionId, gatewayId)
       const memberOptions = endpoint.reverseHub === undefined
         ? /** @type {import('./multiplexed-connection.js').MultiplexedConnectionOptions} */ ({
           ...validated.memberOptions,
@@ -258,19 +265,20 @@ export class MultiplexedSocketductTransportSet extends EventEmitter {
         })
         : /** @type {import('../reverse/client.js').ReverseGatewayConnectionOptions} */ (/** @type {unknown} */ ({
           ...validated.memberOptions,
-          gatewayId,
+          ...(gatewayId === undefined ? {routeClass} : {gatewayId}),
           hub: endpoint.reverseHub,
           tls: endpoint.tls,
           ...(endpoint.createPhysicalSocket === undefined ? {} : {createPhysicalSocket: endpoint.createPhysicalSocket}),
           connectionId: identity.connectionId,
+          spoolDirectory: join(validated.spoolDirectory, identity.spoolName),
           continuousReconnect: true,
           aggregateBudget: this.#budget,
           ...(this.#logger === undefined ? {} : {logger: this.#logger})
         }))
-      const connection = /** @type {TransportMemberConnection} */ (createMember(memberOptions, gatewayId))
+      const connection = /** @type {TransportMemberConnection} */ (createMember(memberOptions, memberIdentity))
       validateMember(connection)
       /** @type {TransportMember} */
-      const member = {gatewayId, connection, assignments: 0, startupError: undefined, terminalError: undefined, lastReadyGeneration: undefined}
+      const member = {gatewayId, routeClass, connection, assignments: 0, startupError: undefined, terminalError: undefined, lastReadyGeneration: undefined}
       connection.on("stateChange", (state, error) => this.#memberStateChanged(member, state, error))
       return member
     })
@@ -321,8 +329,8 @@ export class MultiplexedSocketductTransportSet extends EventEmitter {
     if (selection === undefined) return this.#deferConnection(options, socketOptions, callback)
     try {
       /** @type {((error: Error | null, socket: import('./virtual-socket.js').VirtualSocket) => void) | undefined} */
-      const memberCallback = callback === undefined ? undefined : (error, socket) => callback(error, exposeGateway(socket, selection.member.gatewayId))
-      const socket = exposeGateway(/** @type {import('./virtual-socket.js').VirtualSocket} */ (selection.member.connection.createConnection(options, memberCallback)), selection.member.gatewayId)
+      const memberCallback = callback === undefined ? undefined : (error, socket) => callback(error, exposeAllocation(socket, memberAllocation(selection.member)))
+      const socket = exposeAllocation(/** @type {import('./virtual-socket.js').VirtualSocket} */ (selection.member.connection.createConnection(options, memberCallback)), memberAllocation(selection.member))
       selection.member.assignments += 1
       this.#virtualOpens += 1
       return socket
@@ -405,9 +413,10 @@ export class MultiplexedSocketductTransportSet extends EventEmitter {
     if (member === undefined) throw new Error(`Unknown gatewayId: ${options.gatewayId}`)
     const virtualOptions = {...options}
     delete /** @type {{gatewayId?: string}} */ (virtualOptions).gatewayId
+    const allocation = memberAllocation(member)
     /** @type {((error: Error | null, socket: import('./virtual-socket.js').VirtualSocket) => void) | undefined} */
-    const memberCallback = callback === undefined ? undefined : (error, socket) => callback(error, exposeGateway(socket, member.gatewayId))
-    const socket = exposeGateway(/** @type {import('./virtual-socket.js').VirtualSocket} */ (member.connection.registerRecoveredConnection({...virtualOptions, recover: true}, memberCallback)), member.gatewayId)
+    const memberCallback = callback === undefined ? undefined : (error, socket) => callback(error, exposeAllocation(socket, allocation))
+    const socket = exposeAllocation(/** @type {import('./virtual-socket.js').VirtualSocket} */ (member.connection.registerRecoveredConnection({...virtualOptions, recover: true}, memberCallback)), allocation)
     member.assignments += 1
     this.#virtualOpens += 1
     return socket
@@ -425,7 +434,7 @@ export class MultiplexedSocketductTransportSet extends EventEmitter {
     const raw = this.createConnection(virtualOptions)
     const tlsOptions = omitVirtualOptions(options)
     const secure = tlsConnect({...tlsOptions, socket: raw})
-    const exposed = exposeGatewayGetter(secure, () => raw.gatewayId)
+    const exposed = exposeAllocationGetters(secure, () => raw.gatewayId, () => raw.routeClass)
     if (callback !== undefined) installTlsCallback(exposed, callback)
     return exposed
   }
@@ -442,12 +451,12 @@ export class MultiplexedSocketductTransportSet extends EventEmitter {
     return this
   }
 
-  /** @returns {{state: string, configuredMembers: number, connectingMembers: number, readyMembers: number, degradedMembers: number, closedMembers: number, minimumReadyMembers: number, pendingOpens: number, maxPendingOpens: number, virtualOpens: number, physicalConnects: number, reconnectAttempts: number, budgets: {dataBytes: number, spoolBytes: number, queuedBytes: number, maxDataBytes: number, maxSpoolBytes: number, maxQueuedBytes: number}, members: Array<{gatewayId: string, state: string, assignments: number, physicalConnects: number, reconnectAttempts: number, reconnectSuccesses: number, virtualStreams: number, queuedBytes: number, spoolBytes: number, spoolCleanupFailures: number, terminalErrorCode: string | null}>}} Privacy-safe aggregate and per-gateway status. */
+  /** @returns {{state: string, configuredMembers: number, connectingMembers: number, readyMembers: number, degradedMembers: number, closedMembers: number, minimumReadyMembers: number, pendingOpens: number, maxPendingOpens: number, virtualOpens: number, physicalConnects: number, reconnectAttempts: number, budgets: {dataBytes: number, spoolBytes: number, queuedBytes: number, maxDataBytes: number, maxSpoolBytes: number, maxQueuedBytes: number}, members: Array<{gatewayId?: string, routeClass?: string, state: string, assignments: number, physicalConnects: number, reconnectAttempts: number, reconnectSuccesses: number, virtualStreams: number, queuedBytes: number, spoolBytes: number, spoolCleanupFailures: number, terminalErrorCode: string | null}>}} Privacy-safe aggregate and per-member status. */
   status() {
     const members = this.#members.map((member) => {
       const status = member.connection.status()
       return {
-        gatewayId: member.gatewayId,
+        ...memberAllocation(member),
         state: status.physicalState,
         assignments: member.assignments,
         physicalConnects: status.physicalConnects,
@@ -544,7 +553,7 @@ export class MultiplexedSocketductTransportSet extends EventEmitter {
     if (member !== undefined && typeof state === "string") {
       const status = member.connection.status()
       logDiagnostic(this.#logger, "transport_set.member_state", {
-        gatewayId: member.gatewayId,
+        ...memberAllocation(member),
         state,
         generation: status.connectionGeneration,
         physicalConnects: status.physicalConnects,
@@ -553,7 +562,7 @@ export class MultiplexedSocketductTransportSet extends EventEmitter {
       })
       if (state === "ready" && member.lastReadyGeneration !== undefined && status.connectionGeneration > member.lastReadyGeneration) {
         logDiagnostic(this.#logger, "transport_set.member_replaced", {
-          gatewayId: member.gatewayId,
+          ...memberAllocation(member),
           generation: status.connectionGeneration,
           physicalConnects: status.physicalConnects
         })
@@ -605,8 +614,9 @@ export class MultiplexedSocketductTransportSet extends EventEmitter {
       /** @type {import('./virtual-socket.js').VirtualSocket | undefined} */
       let memberSocket
       try {
-        memberSocket = exposeGateway(selection.member.connection.createConnection(pending.options), selection.member.gatewayId)
-        if (!pending.socket.assign(memberSocket, selection.member.gatewayId)) {
+        const allocation = memberAllocation(selection.member)
+        memberSocket = exposeAllocation(selection.member.connection.createConnection(pending.options), allocation)
+        if (!pending.socket.assign(memberSocket, allocation)) {
           this.#cursor = selection.previousCursor
           continue
         }
@@ -682,9 +692,13 @@ function errorClassification(error, fallback) {
 function validateTransportSetOptions(options) {
   if (typeof options !== "object" || options === null) throw new TypeError("Socketduct transport-set options are required")
   if (typeof options.connectionId !== "string" || !STABLE_IDENTIFIER.test(options.connectionId)) throw new TypeError("Transport-set connectionId must be 8-128 URL-safe opaque characters")
-  if (!Array.isArray(options.gateways) || options.gateways.length === 0) throw new TypeError("Transport-set gateways must be a non-empty array")
+  const hasGateways = options.gateways !== undefined
+  const hasRouteClasses = options.routeClasses !== undefined
+  if (hasGateways === hasRouteClasses) throw new TypeError("Transport set requires exactly one non-empty gateways or routeClasses array")
+  const configuredMembers = hasGateways ? options.gateways : options.routeClasses
+  if (!Array.isArray(configuredMembers) || configuredMembers.length === 0) throw new TypeError("Transport-set members must be a non-empty array")
   const minimumReadyMembers = options.minimumReadyMembers === undefined ? 1 : options.minimumReadyMembers
-  if (!Number.isSafeInteger(minimumReadyMembers) || minimumReadyMembers < 1 || minimumReadyMembers > options.gateways.length) throw new RangeError("minimumReadyMembers must be between 1 and the configured gateway count")
+  if (!Number.isSafeInteger(minimumReadyMembers) || minimumReadyMembers < 1 || minimumReadyMembers > configuredMembers.length) throw new RangeError("minimumReadyMembers must be between 1 and the configured member count")
   const maxPendingOpens = positiveLimit(options.maxPendingOpens, DEFAULT_MAX_PENDING_OPENS, "maxPendingOpens")
   const limits = {
     maxDataBytes: positiveLimit(options.maxTotalBufferBytes, DEFAULT_TOTAL_BUFFER_BYTES, "maxTotalBufferBytes"),
@@ -693,38 +707,42 @@ function validateTransportSetOptions(options) {
   }
   const memberOptions = options.memberOptions === undefined ? {} : options.memberOptions
   if (typeof memberOptions !== "object" || memberOptions === null || Array.isArray(memberOptions)) throw new TypeError("memberOptions must be an object")
-  for (const forbidden of ["relay", "hub", "gatewayId", "tls", "createPhysicalSocket", "connectionId", "spoolDirectory", "continuousReconnect", "aggregateBudget", "logger"]) {
+  for (const forbidden of ["relay", "hub", "gatewayId", "routeClass", "tls", "createPhysicalSocket", "connectionId", "spoolDirectory", "continuousReconnect", "aggregateBudget", "logger"]) {
     if (Object.hasOwn(memberOptions, forbidden)) throw new TypeError(`memberOptions.${forbidden} is owned by the transport set`)
   }
-  /** @type {GatewayConfiguration[]} */
-  const gateways = []
-  const gatewayIds = new Set()
-  for (const raw of options.gateways) {
-    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new TypeError("Each gateway entry must be an object")
+  /** @type {Array<{gatewayId: string | undefined, routeClass: string | undefined, endpoint: GatewayEndpoint}>} */
+  const members = []
+  const memberIds = new Set()
+  for (const raw of configuredMembers) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new TypeError("Each transport-set member must be an object")
     for (const key of Object.keys(raw)) {
-      if (key !== "gatewayId" && key !== "endpoint") throw new TypeError(`Unknown gateway field ${key}; gateway relay and factory settings belong under endpoint`)
+      const identityKey = hasGateways ? "gatewayId" : "routeClass"
+      if (key !== identityKey && key !== "endpoint") throw new TypeError(`Unknown transport-set member field ${key}; identity and endpoint must be explicit`)
     }
-    const gateway = /** @type {Partial<GatewayConfiguration>} */ (raw)
-    if (typeof gateway.gatewayId !== "string" || !GATEWAY_ID.test(gateway.gatewayId)) throw new TypeError("gatewayId must be 2-64 URL-safe characters and cannot contain path separators")
-    if (gatewayIds.has(gateway.gatewayId)) throw new TypeError(`Duplicate gatewayId: ${gateway.gatewayId}`)
-    gatewayIds.add(gateway.gatewayId)
-    if (typeof gateway.endpoint !== "object" || gateway.endpoint === null || Array.isArray(gateway.endpoint)) throw new TypeError(`Gateway ${gateway.gatewayId} requires an explicit endpoint`)
-    const endpoint = /** @type {Partial<GatewayEndpoint>} */ (gateway.endpoint)
+    const member = /** @type {Partial<GatewayConfiguration & RouteClassConfiguration>} */ (raw)
+    const memberId = hasGateways ? member.gatewayId : member.routeClass
+    const validMemberId = hasGateways ? typeof memberId === "string" && GATEWAY_ID.test(memberId) : typeof memberId === "string" && ROUTE_CLASS.test(memberId)
+    if (!validMemberId) throw new TypeError(hasGateways ? "gatewayId must be 2-64 URL-safe characters and cannot contain path separators" : "routeClass must be 1-64 URL-safe characters and cannot contain path separators")
+    if (memberIds.has(memberId)) throw new TypeError(`Duplicate ${hasGateways ? "gatewayId" : "routeClass"}: ${memberId}`)
+    memberIds.add(memberId)
+    if (typeof member.endpoint !== "object" || member.endpoint === null || Array.isArray(member.endpoint)) throw new TypeError(`Transport-set member ${memberId} requires an explicit endpoint`)
+    const endpoint = /** @type {Partial<GatewayEndpoint>} */ (member.endpoint)
     for (const key of Object.keys(endpoint)) {
       if (key !== "relay" && key !== "reverseHub" && key !== "tls" && key !== "createPhysicalSocket") throw new TypeError(`Unknown endpoint field: ${key}`)
     }
-    if ((endpoint.relay === undefined) === (endpoint.reverseHub === undefined)) throw new TypeError(`Gateway ${gateway.gatewayId} requires exactly one relay or reverseHub endpoint`)
+    if ((endpoint.relay === undefined) === (endpoint.reverseHub === undefined)) throw new TypeError(`Transport-set member ${memberId} requires exactly one relay or reverseHub endpoint`)
+    if (hasRouteClasses && endpoint.reverseHub === undefined) throw new TypeError(`Route class ${memberId} requires a reverseHub endpoint`)
     const selectedEndpoint = endpoint.relay ?? endpoint.reverseHub
-    if (typeof selectedEndpoint !== "object" || selectedEndpoint === null || typeof selectedEndpoint.host !== "string" || selectedEndpoint.host.length === 0 || !validPort(selectedEndpoint.port) || typeof selectedEndpoint.token !== "string" || selectedEndpoint.token.length === 0) throw new TypeError(`Gateway ${gateway.gatewayId} endpoint host, port, and token are required`)
-    if (endpoint.tls !== undefined && (typeof endpoint.tls !== "object" || endpoint.tls === null || Array.isArray(endpoint.tls))) throw new TypeError(`Gateway ${gateway.gatewayId} tls must be an object`)
-    if (endpoint.reverseHub !== undefined && endpoint.tls === undefined) throw new TypeError(`Gateway ${gateway.gatewayId} reverseHub requires verified TLS settings`)
-    if (endpoint.createPhysicalSocket !== undefined && typeof endpoint.createPhysicalSocket !== "function") throw new TypeError(`Gateway ${gateway.gatewayId} createPhysicalSocket must be a function`)
-    gateways.push(/** @type {GatewayConfiguration} */ ({gatewayId: gateway.gatewayId, endpoint}))
-  }
-  for (let left = 0; left < gateways.length; left += 1) {
-    for (let right = left + 1; right < gateways.length; right += 1) {
-      const first = /** @type {GatewayConfiguration} */ (gateways[left]).endpoint
-      const second = /** @type {GatewayConfiguration} */ (gateways[right]).endpoint
+    if (typeof selectedEndpoint !== "object" || selectedEndpoint === null || typeof selectedEndpoint.host !== "string" || selectedEndpoint.host.length === 0 || !validPort(selectedEndpoint.port) || typeof selectedEndpoint.token !== "string" || selectedEndpoint.token.length === 0) throw new TypeError(`Transport-set member ${memberId} endpoint host, port, and token are required`)
+    if (endpoint.tls !== undefined && (typeof endpoint.tls !== "object" || endpoint.tls === null || Array.isArray(endpoint.tls))) throw new TypeError(`Transport-set member ${memberId} tls must be an object`)
+    if (endpoint.reverseHub !== undefined && endpoint.tls === undefined) throw new TypeError(`Transport-set member ${memberId} reverseHub requires verified TLS settings`)
+    if (endpoint.createPhysicalSocket !== undefined && typeof endpoint.createPhysicalSocket !== "function") throw new TypeError(`Transport-set member ${memberId} createPhysicalSocket must be a function`)
+    members.push({gatewayId: hasGateways ? memberId : undefined, routeClass: hasRouteClasses ? memberId : undefined, endpoint: /** @type {GatewayEndpoint} */ (endpoint)})
+  }
+  for (let left = 0; left < members.length; left += 1) {
+    for (let right = left + 1; right < members.length; right += 1) {
+      const first = /** @type {{endpoint: GatewayEndpoint}} */ (members[left]).endpoint
+      const second = /** @type {{endpoint: GatewayEndpoint}} */ (members[right]).endpoint
       if (first.relay === undefined || second.relay === undefined) continue
       const sameAddress = first.relay.host === second.relay.host && first.relay.port === second.relay.port
       const sameFactory = first.createPhysicalSocket === second.createPhysicalSocket
@@ -734,7 +752,7 @@ function validateTransportSetOptions(options) {
   const defaultSpoolDirectory = join(tmpdir(), `socketduct-${typeof process.getuid === "function" ? process.getuid() : "user"}`, "multiplexed-set")
   if (options.spoolDirectory !== undefined && (typeof options.spoolDirectory !== "string" || options.spoolDirectory.length === 0)) throw new TypeError("spoolDirectory must be a non-empty string")
   return {
-    gateways,
+    members,
     minimumReadyMembers,
     maxPendingOpens,
     limits,
@@ -752,6 +770,15 @@ function deriveGatewayIdentity(baseId, gatewayId) {
   return {connectionId: `gateway_${digest}`, spoolName: `gateway-${digest}`}
 }
 
+/**
+ * @param {string} baseId - Base identity.
+ * @param {string} routeClass - Route-class identity.
+ */
+function deriveRouteClassIdentity(baseId, routeClass) {
+  const digest = createHash("sha256").update("socketduct-v3-route-class\0").update(baseId).update("\0").update(routeClass).digest("base64url")
+  return {connectionId: `route_${digest}`, spoolName: `route-${digest}`}
+}
+
 /**
  * @param {unknown} value - Raw limit.
  * @param {number} defaultValue - Default.
@@ -771,8 +798,8 @@ function validateReservation(bytes) {
 /** @param {unknown} options - Ordinary open options. */
 function validateOrdinaryOpenOptions(options) {
   if (typeof options !== "object" || options === null) throw new TypeError("Virtual connection options are required")
-  if (Object.hasOwn(options, "gatewayId") || /** @type {{recover?: unknown}} */ (options).recover === true) {
-    throw new TypeError("Gateway-bound durable recovery must use recoverConnection before start")
+  if (Object.hasOwn(options, "gatewayId") || Object.hasOwn(options, "routeClass") || /** @type {{recover?: unknown}} */ (options).recover === true) {
+    throw new TypeError("Transport member selection is set-owned; gateway-bound durable recovery must use recoverConnection before start")
   }
 }
 
@@ -802,28 +829,42 @@ function validateMember(member) {
 /**
  * @template {object} T
  * @param {T} socket - Selected member socket.
- * @param {string} gatewayId - Stable configured gateway ID.
- * @returns {T & {readonly gatewayId: string}} Socket with immutable public allocation metadata.
+ * @param {{gatewayId: string} | {routeClass: string}} allocation - Stable configured member identity.
+ * @returns {T & {readonly gatewayId: string | undefined, readonly routeClass: string | undefined}} Socket with immutable public allocation metadata.
  */
-function exposeGateway(socket, gatewayId) {
-  const existing = Object.getOwnPropertyDescriptor(socket, "gatewayId")
-  if (existing !== undefined) {
-    if (existing.value !== gatewayId) throw new Error("Socketduct gateway allocation metadata mismatch")
-    return /** @type {T & {readonly gatewayId: string}} */ (socket)
-  }
-  Object.defineProperty(socket, "gatewayId", {value: gatewayId, enumerable: true, writable: false, configurable: false})
-  return /** @type {T & {readonly gatewayId: string}} */ (socket)
+function exposeAllocation(socket, allocation) {
+  const values = "gatewayId" in allocation
+    ? {gatewayId: allocation.gatewayId, routeClass: undefined}
+    : {gatewayId: undefined, routeClass: allocation.routeClass}
+  for (const key of /** @type {const} */ (["gatewayId", "routeClass"])) {
+    const existing = Object.getOwnPropertyDescriptor(socket, key)
+    if (existing !== undefined) {
+      if (/** @type {Record<string, unknown>} */ (socket)[key] !== values[key]) throw new Error("Socketduct member allocation metadata mismatch")
+      continue
+    }
+    Object.defineProperty(socket, key, {value: values[key], enumerable: true, writable: false, configurable: false})
+  }
+  return /** @type {T & {readonly gatewayId: string | undefined, readonly routeClass: string | undefined}} */ (socket)
 }
 
 /**
  * @template {object} T
  * @param {T} socket - Socket whose assignment is owned by another socket.
- * @param {() => string | undefined} gatewayId - Live immutable assignment lookup.
- * @returns {T & {readonly gatewayId: string | undefined}} Socket with immutable public allocation metadata.
+ * @param {() => string | undefined} gatewayId - Live exact-gateway assignment lookup.
+ * @param {() => string | undefined} routeClass - Live route-class assignment lookup.
+ * @returns {T & {readonly gatewayId: string | undefined, readonly routeClass: string | undefined}} Socket with immutable public allocation metadata.
  */
-function exposeGatewayGetter(socket, gatewayId) {
+function exposeAllocationGetters(socket, gatewayId, routeClass) {
   Object.defineProperty(socket, "gatewayId", {get: gatewayId, enumerable: true, configurable: false})
-  return /** @type {T & {readonly gatewayId: string | undefined}} */ (socket)
+  Object.defineProperty(socket, "routeClass", {get: routeClass, enumerable: true, configurable: false})
+  return /** @type {T & {readonly gatewayId: string | undefined, readonly routeClass: string | undefined}} */ (socket)
+}
+
+/** @param {TransportMember} member - Configured member. @returns {{gatewayId: string} | {routeClass: string}} */
+function memberAllocation(member) {
+  if (member.gatewayId !== undefined) return {gatewayId: member.gatewayId}
+  if (member.routeClass !== undefined) return {routeClass: member.routeClass}
+  throw new Error("Socketduct transport-set member identity is unavailable")
 }
 
 /**

package/src/config/environment.js

@@ -64,6 +64,7 @@ const SUPPORTED_PROTOCOL_VERSIONS = new Set([2, 3])
  * @property {RelayTlsConfig} [relayTls] - Optional TLS configuration.
  * @property {Array<{gatewayId: string, username: string}>} [reverseGatewayBindings] - Hub gateway identity bindings.
  * @property {Array<{username: string, gatewayId: string, host: string, port: number}>} [reverseRoutes] - Hub client route policy.
+ * @property {Array<{username: string, routeClass: string, gatewayId: string, host: string, port: number}>} [reverseRouteClassRoutes] - Hub route-class resolution policy.
  * @property {string} [reverseGatewayId] - Outbound gateway stable ID.
  * @property {string} [reverseConnectionId] - Outbound gateway stable transport identity.
  * @property {{host: string, port: number, token: string}} [reverseHub] - Outbound hub endpoint.
@@ -206,7 +207,8 @@ export function loadEnvironmentConfig(env = process.env) {
     ...(relayTls !== undefined ? {relayTls} : {}),
     ...(mode === "reverse-hub" ? {
       reverseGatewayBindings: parseReverseGatewayBindings(env.SOCKETDUCT_REVERSE_GATEWAY_BINDINGS ?? ""),
-      reverseRoutes: parseReverseRoutes(env.SOCKETDUCT_REVERSE_ROUTES ?? "")
+      reverseRoutes: parseReverseRoutes(env.SOCKETDUCT_REVERSE_ROUTES ?? ""),
+      reverseRouteClassRoutes: parseReverseRouteClassRoutes(env.SOCKETDUCT_REVERSE_ROUTE_CLASS_ROUTES ?? "")
     } : {}),
     ...(mode === "reverse-gateway" ? {
       reverseGatewayId: env.SOCKETDUCT_REVERSE_GATEWAY_ID?.trim() ?? "",
@@ -252,6 +254,27 @@ function parseReverseRoutes(value) {
   })
 }
 
+/**
+ * @param {string} value - Comma-separated username:routeClass:gatewayId:host:port routes.
+ * @returns {Array<{username: string, routeClass: string, gatewayId: string, host: string, port: number}>} Route-class routes.
+ */
+function parseReverseRouteClassRoutes(value) {
+  return splitList(value).map((entry) => {
+    const first = entry.indexOf(":")
+    const second = entry.indexOf(":", first + 1)
+    const third = entry.indexOf(":", second + 1)
+    const last = entry.lastIndexOf(":")
+    if (first <= 0 || second <= first + 1 || third <= second + 1 || last <= third + 1 || last === entry.length - 1) throw new Error("SOCKETDUCT_REVERSE_ROUTE_CLASS_ROUTES entries must use username:routeClass:gatewayId:host:port")
+    return {
+      username: entry.slice(0, first),
+      routeClass: entry.slice(first + 1, second),
+      gatewayId: entry.slice(second + 1, third),
+      host: entry.slice(third + 1, last),
+      port: parsePort(entry.slice(last + 1), "SOCKETDUCT_REVERSE_ROUTE_CLASS_ROUTES port", DEFAULT_RELAY_PORT)
+    }
+  })
+}
+
 /**
  * @param {string | undefined} value - Raw version.
  * @returns {2 | 3} Selected protocol version.