socketduct 0.1.16 → 0.1.17

package/.env.example

@@ -115,6 +115,9 @@ SOCKETDUCT_TARGET_ALLOWLIST=docker-socket-shim:2375
 # SOCKETDUCT_REVERSE_GATEWAY_BINDINGS=o2:home-o2,zyxel:home-zyxel,starlink:home-starlink
 # Authorize exact client username, gateway ID, and home-local target tuples.
 # SOCKETDUCT_REVERSE_ROUTES=tensorbuzz:o2:docker-server:2375,tensorbuzz:zyxel:docker-server:2375,tensorbuzz:starlink:docker-server:2375
+# Or bind one client physical connection to a route class and resolve each
+# requested target to one exact registered gateway. Ambiguous rows fail closed.
+# SOCKETDUCT_REVERSE_ROUTE_CLASS_ROUTES=tensorbuzz:starlink:server-a-starlink:docker-a:2375,tensorbuzz:starlink:server-b-starlink:docker-b:2375
 
 # Home member: change SOCKETDUCT_MODE to reverse-gateway. Run one process in
 # each router-pinned namespace and use distinct stable identity/credential data.

package/changelog.d/20260924120000-wan-route-classes.md

@@ -0,0 +1 @@
+Socketduct reverse clients can now share one authenticated physical connection per route class while the hub securely resolves each target stream and isolates backpressured server-local gateways.

package/docs/architecture.md

@@ -78,6 +78,13 @@ failure retains the spool reservation and fails that member rather than
 advertising capacity that still exists on disk. These process bounds supplement,
 rather than replace, member and stream limits.
 
+For native reverse mode, the set can instead receive `routeClasses`. It creates
+one `ReverseGatewayConnection` and one stable derived connection identity per
+`{process connectionId, routeClass}`. The hub chooses an exact server-local
+gateway independently for each target `OPEN`, so adding target gateways does not
+multiply client physical connections. Allocation metadata is `routeClass`;
+legacy exact-gateway sets keep `gatewayId` and their existing identity derivation.
+
 Replacement recovery is registered before set startup and addresses the
 original configured gateway ID directly. The set derives the same member
 identity/spool namespace and delegates recovery to that member before any
@@ -93,14 +100,20 @@ rollback. A relay listener selects v2 or v3 explicitly.
 The reverse hub is a rendezvous and stream-ID translation boundary on Server3.
 Authenticated home gateway processes connect outward, register stable IDs, and
 accept hub-created even stream IDs. Authenticated local application members
-select one ID and create odd-ID streams. The hub maps frames without opening
-the target or nesting another Socketduct transport. Each home gateway applies
-the final local allowlist before connecting to `docker-server:2375`.
+select either one exact ID or a route class and create odd-ID streams. The class
+stays bound to the client physical connection while the exact gateway is
+resolved from the requested target for each `OPEN`. The hub maps frames without
+opening the target or nesting another Socketduct transport. Each home gateway
+applies the final local allowlist before connecting to its private Docker shim.
 
 Gateway registration reconnects with generation fencing. Established reverse
 streams are terminal on transport loss because replaying an ambiguous Docker
 operation would be unsafe. Live-transport buffers remain bounded; durable
 spooling and resume continue to apply to ordinary Socketduct sessions only.
+The hub serializes output independently for each physical destination with a
+bounded queue, so one backpressured target gateway cannot stop client frames
+bound for a healthy sibling gateway. Exceeding that destination bound closes
+only the unhealthy physical owner and releases its mapped streams.
 See [Native reverse gateway](reverse-gateway.md).
 
 ### Edge

package/docs/protocol.md

@@ -103,11 +103,23 @@ relay's per-stream result rather than being sent again.
 ### Native reverse-gateway extension
 
 Reverse mode reuses the v3 physical transport and stream frames directly. A
-home gateway registers outbound; a Server3 client selects it. Client streams
-are odd and the hub maps them to even gateway-side IDs. The hub authorizes the
-principal/gateway/target tuple and the gateway separately authorizes its local
-target. Registration reconnect uses a higher generation, but any established
-stream is reset on gateway loss and never replayed.
+home gateway registers outbound. A Server3 client selects exactly one legacy
+`gatewayId` or one first-class `routeClass` in `GATEWAY_SELECT`; the response
+echoes the same selector. Client streams are odd and the hub maps them to even
+gateway-side IDs. For a class-bound connection, every `OPEN` repeats the bound
+class and the hub resolves `{authenticated principal, routeClass, target}` to
+exactly one current gateway. The client never supplies that gateway ID. The hub
+then authorizes the exact principal/gateway/target tuple and the gateway
+separately authorizes its local target. Zero, multiple, stale, disconnected, or
+mismatched resolutions reset the stream without weakening sibling routes.
+Registration reconnect uses a higher generation, but any established stream on
+the lost gateway is reset and never replayed.
+
+Hub output has one ordered owner per physical destination. Frames for a
+backpressured gateway remain in that gateway's bounded queue while frames for
+other gateways continue independently; a destination that exceeds its output
+bound is disconnected and its streams are reset without blocking healthy
+destinations. Ordering within each destination and stream is preserved.
 
 Stream IDs must increase monotonically on each physical connection. END and
 CLOSE positions must match the sender's accepted raw-byte sequence; a

package/docs/reverse-gateway.md

@@ -10,26 +10,29 @@ The roles are deliberately separate:
 
 ```text
 TensorBuzz / local application on Server3
-  -> ReverseGatewayConnection (verified TLS client, one selected gateway ID)
+  -> ReverseGatewayConnection (verified TLS client, one selected route class)
   -> reverse hub on Server3
-  <- OutboundReverseGateway (verified TLS client from the home Docker host)
-  -> docker-server:2375 on a private Compose network
+  <- OutboundReverseGateway A -> target A on its private Compose network
+  <- OutboundReverseGateway B -> target B on its private Compose network
 ```
 
 - `startReverseGatewayHub(options)` is the reachable Server3 broker. It
   authenticates both kinds of physical connection, binds gateway IDs to
-  principals, applies `authorizeClientGateway` before selection, authorizes
-  every client/gateway/target tuple, and never connects to a target itself.
+  principals, authorizes exact-gateway or route-class selection, resolves each
+  route-class `OPEN` to exactly one current gateway, authorizes the resulting
+  client/gateway/target tuple, and never connects to a target itself.
 - `OutboundReverseGateway` is one home member. It makes one persistent outbound
   TLS connection, registers one stable `gatewayId`, applies its own exact local
   target policy, and multiplexes all accepted target streams on that transport.
-- `ReverseGatewayConnection` is the local application API. It selects one
-  registered gateway during connection readiness and returns ordinary
-  `VirtualSocket` objects from `createConnection()`.
-- `MultiplexedSocketductTransportSet` accepts `endpoint.reverseHub` members, so
-  TensorBuzz can keep its existing health-aware ordered round-robin behavior.
-  A three-member set points all three members at the same hub but selects
-  `o2`, `zyxel`, and `starlink` independently.
+- `ReverseGatewayConnection` is the local application API. Supplying
+  `routeClass` binds one authenticated physical connection to that class; each
+  `createConnection()` is routed from its requested target. Supplying the
+  legacy `gatewayId` instead retains exact-gateway behavior unchanged.
+- `MultiplexedSocketductTransportSet` accepts a `routeClasses` array of
+  `endpoint.reverseHub` members. A three-member WAN set therefore owns exactly
+  one client physical connection for each class such as `o2`, `zyxel`, and
+  `starlink`, independent of how many server-local gateways those classes can
+  reach.
 
 Import these APIs from `socketduct/reverse`. The ordinary v2 and v3 edge/relay
 APIs and wire handshakes remain unchanged.
@@ -42,11 +45,17 @@ frames authenticate registration and selection:
 
 - `GATEWAY_REGISTER` / `GATEWAY_REGISTERED` bind the authenticated outbound
   transport to a configured gateway ID and monotonically increasing generation.
-- `GATEWAY_SELECT` / `GATEWAY_SELECTED` make client readiness depend on that
-  gateway currently being registered.
+- `GATEWAY_SELECT` / `GATEWAY_SELECTED` carry exactly one `gatewayId` or
+  `routeClass`. Exact selection still makes readiness depend on that gateway;
+  route-class readiness authenticates the class independently of individual
+  gateway availability.
 - Client-created streams use odd IDs. The hub maps each one to a hub-created
-even ID on the selected gateway transport. `OPEN`, `OPENED`, `DATA`, `ACK`,
-`WINDOW`, `END`, `CLOSE`, and `RESET` then retain their v3 meanings.
+even ID on the exact gateway transport selected for that `OPEN`. A class-bound
+`OPEN` repeats its authenticated `routeClass` and never supplies a gateway ID;
+the hub resolves `{principal, routeClass, target}` to exactly one registered
+gateway before applying the existing exact route authorization. `OPEN`,
+`OPENED`, `DATA`, `ACK`, `WINDOW`, `END`, `CLOSE`, and `RESET` then retain their
+v3 meanings.
 Gateway-originated `CLOSE` is acknowledged by a client `CLOSE`, after which the
 hub releases both mapped IDs; `RESET` remains immediately terminal.
 Valid `ACK` and `WINDOW` frames already in flight when that close starts are
@@ -58,7 +67,10 @@ malformed frames, unauthorized routes, and configured limits. A higher
 generation from the same stable connection identity fences its prior transport.
 At the configured identity bound, the oldest disconnected client identity is
 evicted; active owners are never evicted and retain generation fencing.
-The home gateway independently rejects any target outside its local allowlist.
+Zero eligible gateways denies the target, and multiple eligible gateways deny
+the stream as ambiguous. Unknown classes, class mismatches, stale registrations,
+and disconnected resolved gateways also fail closed. The home gateway
+independently rejects any target outside its local allowlist.
 
 Reverse DATA compression is negotiated as `zstd`. The one DATA-only flag means
 the payload starts with a four-byte uncompressed length followed by one
@@ -74,6 +86,14 @@ senders use the smaller local and peer window for stream credit. A graceful hub
 shutdown is transient and reconnects the client and gateway registrations, while
 authentication, authorization, and stale-generation rejections remain terminal.
 
+The hub owns a separate ordered output queue for every client and gateway
+physical connection. Each queue defaults to a 32 MiB bound and can be set with
+the programmatic `maxOutputBytesPerConnection` hub option. Backpressure on one
+gateway therefore cannot pause client input for a healthy gateway in the same
+route class. If one destination exceeds its bound, the hub closes that physical
+connection and its mapped streams through the normal detach path; sibling
+gateways and the route-class client connection remain usable.
+
 An application write may be larger than the configured reverse-stream buffer.
 The client admits it in bounded slices no larger than the negotiated peer window
 as acknowledgements release capacity, holding Node's Writable callback while
@@ -92,7 +112,9 @@ in-memory gateway registry across independent cluster workers.
 Gateway registration reconnects with bounded exponential delay and a higher
 generation. An established Docker stream does **not** survive that transport
 loss: the hub resets it with `GATEWAY_DISCONNECTED`, both endpoints release the
-stream, and the gateway destroys its local Docker socket. This is intentional.
+stream, and the gateway destroys its local Docker socket. A route-class client
+physical connection stays authenticated, so streams through other gateways in
+the class and later opens to those targets remain usable. This is intentional.
 A Docker request whose write reached dockerd but whose response did not reach
 TensorBuzz has an ambiguous outcome and must never be replayed automatically.
 TensorBuzz must reconcile that Docker operation and then create a new stream.
@@ -118,40 +140,44 @@ SOCKETDUCT_RELAY_HOST=0.0.0.0 \
 SOCKETDUCT_RELAY_PORT=3100 \
 SOCKETDUCT_TLS_CERT_FILE=/certs/hub.crt \
 SOCKETDUCT_TLS_KEY_FILE=/certs/hub.key \
-SOCKETDUCT_AUTH_TOKENS='home-o2:<secret>,home-zyxel:<secret>,home-starlink:<secret>,tensorbuzz:<secret>' \
-SOCKETDUCT_REVERSE_GATEWAY_BINDINGS='o2:home-o2,zyxel:home-zyxel,starlink:home-starlink' \
-SOCKETDUCT_REVERSE_ROUTES='tensorbuzz:o2:docker-server:2375,tensorbuzz:zyxel:docker-server:2375,tensorbuzz:starlink:docker-server:2375' \
+SOCKETDUCT_AUTH_TOKENS='server-a-starlink:<secret>,server-b-starlink:<secret>,tensorbuzz:<secret>' \
+SOCKETDUCT_REVERSE_GATEWAY_BINDINGS='server-a-starlink:server-a-starlink,server-b-starlink:server-b-starlink' \
+SOCKETDUCT_REVERSE_ROUTE_CLASS_ROUTES='tensorbuzz:starlink:server-a-starlink:docker-a:2375,tensorbuzz:starlink:server-b-starlink:docker-b:2375' \
 node src/index.js
 ```
 
 Values shown as `<secret>` are placeholders for secret-manager input, not
 literal values. The runtime refuses to start without TLS, credentials,
-bindings, and routes.
+bindings, and either exact or route-class routes. Exact legacy rows remain
+available as `SOCKETDUCT_REVERSE_ROUTES=username:gatewayId:host:port`.
+Route-class rows use `username:routeClass:gatewayId:host:port`. If two rows make
+different gateways eligible for the same authenticated class and target, that
+`OPEN` is rejected as ambiguous rather than choosing one implicitly.
 
-## One outbound member per router
+## One outbound member per target and route class
 
-Run this once in each existing router-pinned network namespace, changing the
-two stable IDs and credential for the member:
+Run this once in each target server's route-pinned network namespace, changing
+the stable IDs, credential, and private target name for the member:
 
 ```sh
 SOCKETDUCT_MODE=reverse-gateway \
-SOCKETDUCT_REVERSE_GATEWAY_ID=o2 \
-SOCKETDUCT_REVERSE_CONNECTION_ID=home_o2_gateway_01 \
+SOCKETDUCT_REVERSE_GATEWAY_ID=server-a-starlink \
+SOCKETDUCT_REVERSE_CONNECTION_ID=server_a_starlink_gateway_01 \
 SOCKETDUCT_REVERSE_HUB_HOST=server3.example.net \
 SOCKETDUCT_REVERSE_HUB_PORT=3100 \
 SOCKETDUCT_REVERSE_TOKEN='<secret>' \
 SOCKETDUCT_REVERSE_HUB_CA_FILE=/certs/hub-ca.crt \
 SOCKETDUCT_REVERSE_HUB_SERVERNAME=server3.example.net \
-SOCKETDUCT_TARGET_ALLOWLIST=docker-server:2375 \
+SOCKETDUCT_TARGET_ALLOWLIST=docker-a:2375 \
 node src/index.js
 ```
 
-The namespace/default-route configuration remains outside Socketduct. Pin the
-three processes to the routes whose next hops are O2 `192.168.86.1`, Zyxel
-`192.168.86.3`, and Starlink `192.168.86.25`. Socketduct needs no inbound rule
-on any home router. Do not publish port 2375: the gateway resolves
-`docker-server` and reaches plaintext Docker TCP only on their shared private
-Compose network.
+The namespace/default-route configuration remains outside Socketduct. Each
+gateway registration represents one exact target server and WAN class;
+Socketduct does not aggregate away either identity. Socketduct needs no inbound
+rule on the WAN router. Do not publish port 2375: the gateway resolves only its
+allowlisted Docker shim and reaches plaintext Docker TCP on that server's
+private Compose network.
 
 ## TensorBuzz transport set
 
@@ -160,8 +186,8 @@ import {MultiplexedSocketductTransportSet} from "socketduct/multiplexed"
 
 const set = new MultiplexedSocketductTransportSet({
   connectionId: "tensorbuzz_docker_transport_01",
-  gateways: ["o2", "zyxel", "starlink"].map((gatewayId) => ({
-    gatewayId,
+  routeClasses: ["o2", "zyxel", "starlink"].map((routeClass) => ({
+    routeClass,
     endpoint: {
       reverseHub: {
         host: "127.0.0.1",
@@ -174,10 +200,15 @@ const set = new MultiplexedSocketductTransportSet({
 })
 
 const starting = set.start()
-const socket = set.createConnection({host: "docker-server", port: 2375})
+const socket = set.createConnection({host: "docker-a", port: 2375})
 await starting
 ```
 
+Route-class sockets expose immutable `routeClass` allocation metadata and an
+undefined `gatewayId`. Exact-gateway sets retain immutable `gatewayId` metadata.
+Callers cannot override either selection per open. Reverse streams remain
+non-recoverable after an uncertain transport loss.
+
 The socket is returned immediately and waits inside Socketduct until the set
 reaches minimum readiness. New sockets rotate equally across ready members and
 stay on their assigned member. If all members are reconnecting, new sockets wait

package/docs/security.md

@@ -153,6 +153,19 @@ Reverse transports require verified TLS and negotiated zstd. There is no
 plaintext or certificate-verification opt-out. Docker port 2375 is permitted
 only as a private `docker-server:2375` target and is never host-published.
 
+A route-class client authenticates one explicit class on its physical
+connection. It cannot name a gateway per stream. For every `OPEN`, the hub uses
+the authenticated principal, bound class, and exact requested target to obtain
+the eligible gateway IDs and proceeds only when there is exactly one. Unknown
+or unauthorized classes, missing routes, duplicate eligible routes, class
+mismatches, stale owners, and disconnected gateways fail closed. The resolved
+gateway still passes the existing hub authorization and its own server-local
+target allowlist; route classes introduce no wildcard authorization or fallback.
+Hub output is ordered and byte-bounded per physical destination. A gateway that
+stops reading cannot grow an unbounded queue or stall authorization, DATA, or
+OPEN processing for a healthy sibling; exceeding the bound disconnects only
+that destination and resets its owned streams.
+
 Reverse registration can reconnect; established Docker streams cannot resume
 or spool across loss. They fail with an explicit uncertain-operation error so
 the caller must reconcile before retrying. This prevents privileged Docker API

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,15 @@ 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 fails terminally on an
+uncertain transport loss and is never replayed.
 
 `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 +216,11 @@ 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 after an uncertain transport loss.
 
 Process-replacement recovery is deliberately separate from ordinary selection.
 First detach the old set when an orderly handoff is possible. Construct the
@@ -217,8 +246,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 +268,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "socketduct",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "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
   }