socketduct 0.1.16 → 0.1.17

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,7 +265,7 @@ 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}),
@@ -267,10 +274,10 @@ export class MultiplexedSocketductTransportSet extends EventEmitter {
           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 +328,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 +412,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 +433,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 +450,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 +552,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 +561,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 +613,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 +691,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 +706,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 +751,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 +769,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 +797,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 +828,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.

package/src/reverse/client.js

@@ -20,6 +20,7 @@ import {
   parseTarget,
   positiveInteger,
   resolveVerifiedTls,
+  ROUTE_CLASS,
   STABLE_IDENTIFIER,
   writeSocket
 } from "./common.js"
@@ -29,7 +30,8 @@ const DEFAULT_CONNECTION_BUFFER_BYTES = 32 * 1024 * 1024
 
 /**
  * @typedef {object} ReverseGatewayConnectionOptions
- * @property {string} gatewayId - Registered home gateway selected by this member.
+ * @property {string} [gatewayId] - Registered exact gateway selected by this legacy member.
+ * @property {string} [routeClass] - Server-resolved route class selected by this member.
  * @property {string} [connectionId] - Stable client transport identity.
  * @property {{host: string, port: number, token: string}} hub - Server3 hub endpoint.
  * @property {{caFile?: string, certFile?: string, keyFile?: string, servername?: string}} tls - Mandatory verified outer TLS.
@@ -82,7 +84,7 @@ const DEFAULT_CONNECTION_BUFFER_BYTES = 32 * 1024 * 1024
  * @property {((error?: Error | null) => void) | undefined} endCallback
  */
 
-/** Server3/TensorBuzz-facing virtual socket connection to one registered gateway. */
+/** Server3/TensorBuzz-facing virtual socket connection to an exact gateway or server-resolved route class. */
 export class ReverseGatewayConnection extends EventEmitter {
   /** @type {ReverseGatewayConnectionOptions} */ #options
   /** @type {string} */ #connectionId
@@ -180,11 +182,11 @@ export class ReverseGatewayConnection extends EventEmitter {
     logDiagnostic(this.#options.logger, "virtual_stream.opening", {
       streamId: id,
       generation: this.#generation,
-      gatewayId: this.#options.gatewayId,
+      ...this.#routeIdentityFields(),
       recovered: false
     })
     if (callback !== undefined) installCallback(socket, callback)
-    void this.#sendControl(V3FrameType.OPEN, id, 0, {gatewayId: this.#options.gatewayId, identifier, name, target, initialWindow: this.#initialWindow()}).catch((error) => socket._receiveError(asError(error)))
+    void this.#sendControl(V3FrameType.OPEN, id, 0, {...this.#routeIdentityFields(), identifier, name, target, initialWindow: this.#initialWindow()}).catch((error) => socket._receiveError(asError(error)))
     return socket
   }
 
@@ -265,7 +267,7 @@ export class ReverseGatewayConnection extends EventEmitter {
     logDiagnostic(this.#options.logger, error === null ? "virtual_stream.closed" : "virtual_stream.error", {
       streamId,
       generation: this.#generation,
-      gatewayId: this.#options.gatewayId,
+      ...this.#routeIdentityFields(),
       ...(error === null ? {} : errorDiagnostics(error))
     })
     this.#retireStream(stream, error ?? new SocketductStreamError("Reverse stream is not writable", "ERR_STREAM_DESTROYED"))
@@ -297,7 +299,7 @@ export class ReverseGatewayConnection extends EventEmitter {
     logDiagnostic(this.#options.logger, "transport.connecting", {
       generation,
       attempt: this.#physicalAttempts,
-      gatewayId: this.#options.gatewayId,
+      ...this.#routeIdentityFields(),
       reconnect: this.#physicalAttempts > 1
     })
     const tls = resolveVerifiedTls(this.#options.tls)
@@ -308,7 +310,7 @@ export class ReverseGatewayConnection extends EventEmitter {
       logDiagnostic(this.#options.logger, "transport.failed", {
         generation,
         attempt: this.#physicalAttempts,
-        gatewayId: this.#options.gatewayId,
+        ...this.#routeIdentityFields(),
         ...errorDiagnostics(error)
       })
       this.#scheduleReconnect(asError(error))
@@ -346,13 +348,14 @@ export class ReverseGatewayConnection extends EventEmitter {
             authenticated = true
             this.#codec = ZSTD_CODEC
             this.#sendWindowLimit = Math.min(this.#initialWindow(), detail.initialWindow)
-            await writeSocket(physical, encodeV3Frame({type: V3FrameType.GATEWAY_SELECT, streamId: 0, sequence: generation}, encodeV3Control({gatewayId: this.#options.gatewayId})))
+            await writeSocket(physical, encodeV3Frame({type: V3FrameType.GATEWAY_SELECT, streamId: 0, sequence: generation}, encodeV3Control(this.#routeIdentityFields())))
             continue
           }
           if (!selected) {
             if (frame.type !== V3FrameType.GATEWAY_SELECTED) throw fatalError("GATEWAY_SELECTION_FAILED")
             const detail = decodeV3Control(frame.payload)
-            if (detail.gatewayId !== this.#options.gatewayId || detail.generation !== generation) throw fatalError("GATEWAY_SELECTION_FAILED")
+            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")
             selected = true
             clearTimeout(timer)
             this.#physicalConnects += 1
@@ -361,7 +364,7 @@ export class ReverseGatewayConnection extends EventEmitter {
             logDiagnostic(this.#options.logger, "transport.connected", {
               generation,
               attempt: this.#physicalAttempts,
-              gatewayId: this.#options.gatewayId,
+              ...this.#routeIdentityFields(),
               physicalConnects: this.#physicalConnects,
               reconnect: this.#physicalConnects > 1
             })
@@ -369,7 +372,7 @@ export class ReverseGatewayConnection extends EventEmitter {
               logDiagnostic(this.#options.logger, "transport.reconnect_succeeded", {
                 generation,
                 attempt: this.#reconnectAttempts,
-                gatewayId: this.#options.gatewayId,
+                ...this.#routeIdentityFields(),
                 physicalConnects: this.#physicalConnects
               })
             }
@@ -397,7 +400,7 @@ export class ReverseGatewayConnection extends EventEmitter {
         if (!this.#closing) {
           logDiagnostic(this.#options.logger, "transport.disconnected", {
             generation,
-            gatewayId: this.#options.gatewayId,
+            ...this.#routeIdentityFields(),
             virtualStreams: this.#streams.size,
             ...errorDiagnostics(attemptError ?? lost, "GATEWAY_DISCONNECTED")
           })
@@ -411,7 +414,7 @@ export class ReverseGatewayConnection extends EventEmitter {
           logDiagnostic(this.#options.logger, "transport.failed", {
             generation,
             attempt: this.#physicalAttempts,
-            gatewayId: this.#options.gatewayId,
+            ...this.#routeIdentityFields(),
             ...errorDiagnostics(terminalError, "GATEWAY_DISCONNECTED")
           })
           this.#rejectConnect?.(terminalError)
@@ -441,7 +444,7 @@ export class ReverseGatewayConnection extends EventEmitter {
       logDiagnostic(this.#options.logger, "virtual_stream.opened", {
         streamId: stream.id,
         generation: this.#generation,
-        gatewayId: this.#options.gatewayId,
+        ...this.#routeIdentityFields(),
         recovered: false
       })
       stream.socket._markConnected()
@@ -474,7 +477,7 @@ export class ReverseGatewayConnection extends EventEmitter {
       logDiagnostic(this.#options.logger, "virtual_stream.closed", {
         streamId: stream.id,
         generation: this.#generation,
-        gatewayId: this.#options.gatewayId
+        ...this.#routeIdentityFields()
       })
       this.#retireStream(stream, new SocketductStreamError("Reverse stream closed before pending writes completed", "ERR_STREAM_DESTROYED"))
       stream.socket._receiveEnd()
@@ -652,7 +655,7 @@ export class ReverseGatewayConnection extends EventEmitter {
       generation: this.#generation,
       attempt: this.#reconnectAttempts,
       delayMs: delay,
-      gatewayId: this.#options.gatewayId,
+      ...this.#routeIdentityFields(),
       ...errorDiagnostics(error, "GATEWAY_DISCONNECTED")
     })
     this.#reconnectDelay = Math.min(this.#reconnectDelay * 2, this.#options.maxReconnectDelayMs ?? 30_000)
@@ -673,13 +676,24 @@ export class ReverseGatewayConnection extends EventEmitter {
 
   #settleConnect() { this.#connectPromise = undefined; this.#resolveConnect = undefined; this.#rejectConnect = undefined }
   #setState(/** @type {'configured' | 'connecting' | 'ready' | 'reconnecting' | 'closed'} */ state, /** @type {Error | undefined} */ error = undefined) { if (this.#state === state) return; this.#state = state; this.emit("stateChange", state, error) }
+  /** @returns {{gatewayId: string} | {routeClass: string}} Stable physical route identity. */
+  #routeIdentityFields() {
+    return this.#options.routeClass === undefined
+      ? {gatewayId: /** @type {string} */ (this.#options.gatewayId)}
+      : {routeClass: this.#options.routeClass}
+  }
   #initialWindow() { return this.#options.initialWindowBytes ?? DEFAULT_WINDOW }
   #maxFrameBytes() { return Math.min(this.#options.maxFrameBytes ?? DEFAULT_FRAME_BYTES, getMaxDecompressedBytes(this.#options.compressionLimits), 64 * 1024) }
 }
 
 /** @param {ReverseGatewayConnectionOptions} options - Options. */
 function validateOptions(options) {
-  if (typeof options !== "object" || options === null || typeof options.gatewayId !== "string" || !GATEWAY_ID.test(options.gatewayId)) throw new TypeError("Reverse gateway connection requires a valid gatewayId")
+  if (typeof options !== "object" || options === null) throw new TypeError("Reverse gateway connection options are required")
+  const hasGatewayId = Object.hasOwn(options, "gatewayId")
+  const hasRouteClass = Object.hasOwn(options, "routeClass")
+  if (hasGatewayId === hasRouteClass) throw new TypeError("Reverse gateway connection requires exactly one gatewayId or routeClass")
+  if (hasGatewayId && (typeof options.gatewayId !== "string" || !GATEWAY_ID.test(options.gatewayId))) throw new TypeError("Reverse gateway connection requires a valid gatewayId")
+  if (hasRouteClass && (typeof options.routeClass !== "string" || !ROUTE_CLASS.test(options.routeClass))) throw new TypeError("Reverse gateway connection requires a valid routeClass")
   if (options.connectionId !== undefined && (typeof options.connectionId !== "string" || !STABLE_IDENTIFIER.test(options.connectionId))) throw new TypeError("Reverse gateway connectionId must be 8-128 URL-safe characters")
   if (typeof options.hub !== "object" || options.hub === null || typeof options.hub.host !== "string" || options.hub.host.length === 0 || !Number.isInteger(options.hub.port) || options.hub.port < 1 || options.hub.port > 65_535 || typeof options.hub.token !== "string" || options.hub.token.length === 0) throw new TypeError("Reverse gateway connection requires hub host, port and token")
   resolveVerifiedTls(options.tls)

package/src/reverse/common.js

@@ -3,6 +3,7 @@ import {readFileSync} from "node:fs"
 import {connect as tlsConnect} from "node:tls"
 
 export const GATEWAY_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{1,63}$/
+export const ROUTE_CLASS = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/
 export const STABLE_IDENTIFIER = /^[A-Za-z0-9_-]{8,128}$/
 export const DEFAULT_WINDOW = 256 * 1024
 export const DEFAULT_FRAME_BYTES = 16 * 1024