socketduct 0.1.18 → 0.1.19

package/README.md

@@ -91,8 +91,8 @@ and automatically rejoin selection. A socket created before readiness is
 returned immediately and waits inside Socketduct with normal callback, event,
 timeout and backpressure behavior; assignment stays FIFO and occurs only on a
 ready member. A virtual socket never changes members.
-Durable process-replacement recovery uses `recoverConnection()` with the
-original gateway ID before the replacement set starts.
+Durable process-replacement recovery uses `recoverConnection()` with exactly
+the original gateway ID or reverse route class before the replacement set starts.
 
 For home Docker hosts behind O2, Zyxel, and Starlink, run
 `OutboundReverseGateway` in each router-pinned namespace and

package/changelog.d/20260925143000-reverse-client-process-recovery.md

@@ -0,0 +1 @@
+Reverse clients can now recover crash-consistent persistent streams in a replacement process with application-consumption ACKs and a quiescent detach handoff, without reopening the surviving gateway target, while unsupported hub, gateway, and target loss fails closed.

package/docs/architecture.md

@@ -85,12 +85,12 @@ 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
-physical attempt; round-robin is never involved. An orderly set detach preserves
-active spools while retiring empty warmed lanes. Ordinary new opens cannot name
-a gateway.
+Replacement recovery is registered before set startup and addresses exactly one
+original configured selector: `gatewayId` or `routeClass`. The set derives the
+same member identity/spool namespace and delegates recovery to that member
+before any physical attempt; round-robin is never involved. An orderly set
+detach preserves active spools while retiring empty warmed lanes. Ordinary new
+opens cannot name a member.
 
 Protocol v2 retains the original one-session-per-tunnel architecture for
 rollback. A relay listener selects v2 or v3 explicitly.
@@ -112,9 +112,11 @@ keeps its original target socket and both endpoints durably retain
 unacknowledged send chunks. Replacement physical generations exchange paired
 resume manifests; the hub reconciles receiver-committed sequence positions
 before either side replays. This resumes the same byte stream without reopening
-the target or issuing a second application request. Reverse process replacement
-remains terminal because the original target/app socket objects cannot move to
-a new process.
+the target or issuing a second application request. The Server3 reverse-client
+object/process may be replaced from persistent spool state because the home
+gateway still owns the target socket; the replacement creates a new app-facing
+`VirtualSocket` and resumes from its durable receive ACK. The hub process,
+gateway process, and target socket are not reconstructable by this mechanism.
 
 The hub serializes output independently for each physical destination with a
 bounded queue, so one backpressured target gateway cannot stop client frames

package/docs/protocol.md

@@ -141,9 +141,22 @@ Reverse send replay is persisted before transmission on both the Server3 client
 and outbound gateway. ACKs truncate those private temporary spools. Missing
 targets, expired retention, identity or manifest mismatch, and configured
 buffer/spool/output bounds produce one terminal stream error with the causal
-code. Process-replacement recovery remains unsupported for reverse streams
-because a replacement gateway process cannot inherit the original target TCP
-socket.
+code. A replacement reverse client may restore its generation, selector,
+lifecycle, directional sequences/ACKs, END state, and contiguous send replay
+from persistent spool state before making a physical attempt. It presents the
+durable receive ACK, not the dead object's readable-buffer high-water mark, so
+the surviving gateway conservatively replays any target bytes that were not
+durably acknowledged. A reverse client advances that ACK only after bytes are
+returned to the application; merely buffering them below the readable
+high-water mark is process-local and does not make them safe across replacement.
+It never emits `OPEN`.
+
+Only the reverse client is replaceable in this protocol boundary. The same hub
+process and retained bridge, outbound gateway process, and original target TCP
+socket must survive. Hub restart reconstruction, gateway process/socket-keeper
+or FD transfer, target reconnection, and replay after target loss are not
+defined. A fresh gateway that encounters retained bridges submits an empty
+manifest; normal omitted-stream resets retire them without target creation.
 
 Hub output has one ordered owner per physical destination. Frames for a
 backpressured gateway remain in that gateway's bounded queue while frames for

package/docs/reverse-gateway.md

@@ -125,8 +125,10 @@ in-memory gateway registry across independent cluster workers.
 
 Gateway registration reconnects with bounded exponential delay and a higher
 generation. An established Docker stream survives a transient physical loss
-when the hub process and its retained state, live client object, outbound gateway process, and
+when the hub process and its retained state, outbound gateway process, and
 original target socket remain available through the configured resume window.
+The original client object may reconnect in place, or a replacement reverse
+client process may reconstruct a new `VirtualSocket` from durable spool state.
 Socketduct keeps
 the app-facing socket open, durably spools each direction's unacknowledged raw
 chunks before sending them, reconciles the two receiver-committed ACK positions,
@@ -145,14 +147,39 @@ mismatches, invalid manifests, spool/buffer limits, and authorization failures
 fail closed.
 
 Reverse replay state is bounded per stream and connection and stored in private
-temporary spool directories. ACKed chunks are truncated, and terminal
-close/reset removes the spool. `status().spoolBytes` reports retained durable
-payload. `registerRecoveredConnection()` remains unsupported for reverse mode:
-a process replacement cannot inherit the live target socket or the prior
-`VirtualSocket`. If either endpoint process disappears, the target socket is
-lost, or the hub resume window expires, the logical stream fails once with the
-causal session-loss/reset code and the application must reconcile at its own
-protocol layer.
+spool directories. ACKed chunks are truncated, and terminal close/reset removes
+the spool. `status().spoolBytes` reports retained durable payload. Reverse-client
+replacement requires the same explicit `connectionId`, an explicit persistent
+`spoolDirectory`, and the same stream identifier, name, target, and one original
+selector (`gatewayId` or `routeClass`). Register every stream with
+`registerRecoveredConnection({...options, recover: true})` before `connect()`;
+registration synchronously rejects missing, expired, corrupt, wrong-owner,
+mismatched, noncontiguous, or oversized state before any network attempt. The
+stored generation is advanced and persisted before AUTH, recovered outbound
+replay starts above the gateway high-water position, and inbound delivery starts
+at the durable receive ACK because unread bytes in the dead `VirtualSocket` no
+longer exist. Receive ACKs advance only after the application consumes bytes,
+not when `VirtualSocket` merely accepts them into its readable buffer. Recovery
+uses the committed recovery record to discard an uncommitted chunk tail and
+repair derivable usage accounting after an abrupt process loss; structural,
+identity, sequence, quota, and non-tail corruption still fail closed. Recovery
+never sends `OPEN`.
+
+The default reverse spool is under `/tmp`, and the sample reverse-gateway
+Compose mounts `/tmp` as tmpfs. Those defaults do not survive a container or
+host replacement. A caller claiming process/container recovery must supply a
+private persistent directory; Socketduct maintains `0700` directories and
+`0600` files and never writes hub credentials or session tokens there.
+
+This boundary does not reconstruct a hub after hub process loss: the current
+manifests have no durable hub epoch, hub-minted bridge identity, endpoint-pairing
+journal, or split-brain fence. It also does not transfer gateway worker file
+descriptors, recover an outbound gateway process, reopen a lost target socket,
+or replay a Docker request after gateway/container/host loss. A newly constructed
+gateway owns no inherited targets; if the hub reports retained bridges, it sends
+an empty resume manifest so omitted bridges reset once, without calling the
+target factory or emitting `OPEN`. Loss outside the supported boundary fails the
+logical stream and leaves higher-level reconciliation to the application.
 
 Target bytes already observed by the gateway are ordered before a subsequent
 target-error reset. Stream `END` remains a directional half-close, while protocol
@@ -238,6 +265,11 @@ Callers cannot override either selection per open. Reverse streams remain
 sticky to their selected gateway/target but resume transparently after a
 transient physical transport replacement.
 
+For process replacement, call `recoverConnection()` before `start()` with
+exactly the socket's immutable original selector: `gatewayId` for an exact set
+or `routeClass` for a route-class set. Recovery derives the original member
+identity and spool namespace and never falls back to or probes a sibling.
+
 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/running.md

@@ -210,6 +210,6 @@ inspect its ordered aggregate causes or privacy-safe per-member status codes.
 No extra physical member is created. Configure the set-wide buffer/spool/queue
 limits for the whole process rather than multiplying a desired budget by
 gateway count.
-For process replacement, call `recoverConnection()` with each stream's original
-gateway ID before `start()`; see the exact sequence in
+For process replacement, call `recoverConnection()` with exactly each stream's
+original gateway ID or reverse route class before `start()`; see the sequence in
 [Node-compatible socket API design](socket-api.md#multiplexedsocketducttransportset-multi-gateway-v3-api).

package/docs/security.md

@@ -176,8 +176,15 @@ only above it. This preserves exact-once delivery without reopening or
 reissuing a privileged Docker request. Ownership mismatches, missing targets,
 invalid or incomplete manifests, resource-bound failures, and expired resume
 windows fail the affected logical stream once instead of falling back to a new
-stream. Process replacement remains terminal because the live app and target
-sockets cannot be inherited safely.
+stream. Reverse-client process replacement is allowed only from caller-selected
+private persistent storage with the same stable connection/stream identities
+and exactly one original gateway or route-class selector. Recovery validates
+ownership, age, identity, lifecycle, contiguous chunks, and bounds before
+network activity; spool files contain no bearer credential or session token.
+The same in-memory hub bridge, gateway process, and live target socket must
+survive. Hub reconstruction, gateway FD transfer, and target reopen/retry remain
+unsupported, and a replacement gateway resets retained bridges with an empty
+manifest rather than recreating a privileged operation.
 
 ## Network exposure
 

package/docs/session-lifecycle.md

@@ -27,9 +27,20 @@ without opening a second target or retrying an application operation.
 
 If the original target socket disappears, an owner/identifier or sequence does
 not match, a buffer/spool bound is exceeded, or the resume window expires, that
-logical stream fails once with the causal error and releases both sides. Reverse
-process-replacement recovery remains unsupported because the live target and
-app-facing socket cannot be transferred to replacement JavaScript objects.
+logical stream fails once with the causal error and releases both sides. A dead
+reverse-client process may be replaced: the new object creates a new
+`VirtualSocket`, restores the durable generation/lifecycle and replay state, and
+registers every stream before connecting. The same hub bridge, outbound gateway
+process, and original target socket must still exist. The dead app-facing socket
+is not transferred; target bytes above its durable receive ACK replay to the new
+socket. That ACK covers bytes returned to the application, not bytes merely
+buffered in the dead process. An orderly `detach()` drains already-queued frame
+handling before its final durable snapshot and handoff.
+
+Hub process reconstruction, gateway process or file-descriptor transfer, and
+target reopen/retry are unsupported. A replacement gateway has no live target
+sockets and therefore completes retained-state registration with an empty
+manifest, resetting omitted bridges rather than issuing a second `OPEN`.
 
 The bounded, paginated resume manifest carries stable identifiers and both
 directional acknowledgement positions. The relay returns an independent result

package/docs/socket-api.md

@@ -219,24 +219,23 @@ 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` 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.
+an exact set's immutable original selector after connection: `gatewayId` for a
+gateway member or `routeClass` for a reverse member. A replacement uses that
+selector to recover the stream on its original member without running selection
+again.
 
 Process-replacement recovery is deliberately separate from ordinary selection.
 First detach the old set when an orderly handoff is possible. Construct the
-replacement with the same base `connectionId`, spool directory, gateway IDs and
-pinned endpoints. Then register each durable stream with its original
-`gatewayId` before calling `start()`:
+replacement with the same base `connectionId`, spool directory, and configured
+member endpoints. Then register each durable stream with exactly its original
+`gatewayId` or `routeClass` before calling `start()`:
 
 ```js
 await set.detach()
 
 const replacement = new MultiplexedSocketductTransportSet(sameSetOptions)
 const recovered = replacement.recoverConnection({
-  gatewayId: durableRecord.gatewayId, // captured from the original socket
+  routeClass: durableRecord.routeClass, // exact sets use gatewayId instead
   host: "api.internal",
   port: 443,
   identifier: "build_stream_01",
@@ -245,10 +244,11 @@ const recovered = replacement.recoverConnection({
 await replacement.start()
 ```
 
-`recoverConnection()` implies durable recovery and rejects a missing or unknown
-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
+`recoverConnection()` implies durable recovery and rejects a missing,
+ambiguous, invalid, or unknown original selector, an explicit `recover` option,
+or registration after `start()` has begun. It bypasses selection only to reach
+that configured member; it never migrates or replays the stream on a sibling.
+Ordinary `createConnection()` and
 `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
@@ -401,13 +401,47 @@ Target `ca`, `cert`, and `key` accept Node TLS certificate material. `cert` and
 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()` 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.
+An established reverse stream can be cold-registered in a replacement client
+process before its first physical connection:
+
+```js
+const replacement = new ReverseGatewayConnection({
+  routeClass: durableRecord.routeClass,
+  connectionId: durableRecord.connectionId,
+  spoolDirectory: "/srv/socketduct/recovery",
+  hub,
+  tls
+})
+const socket = replacement.registerRecoveredConnection({
+  recover: true,
+  host: durableRecord.host,
+  port: durableRecord.port,
+  identifier: durableRecord.identifier,
+  sessionName: durableRecord.sessionName
+})
+await replacement.connect()
+```
+
+Recovery restores the durable stream lifecycle, sequences, acknowledgements,
+and generation. It never emits a new `OPEN` or recreates the target; target data
+above the durable receive acknowledgement is replayed by the surviving gateway.
+Reverse receive ACKs cover bytes returned to the application, not unread bytes
+held only in the old process. `detach()` resolves only after queued physical
+frame handling is quiescent and the resulting recovery state is durable, so a
+replacement cannot race a late write from the retired object.
+The caller must supply stable `connectionId` and private persistent
+`spoolDirectory` values. The default `/tmp` spool and the sample gateway
+Compose tmpfs do not survive container or host replacement. Spool directories
+remain mode 0700, files remain mode 0600, and credentials or session tokens are
+not persisted.
+
+This boundary requires the same hub bridge, reverse-gateway process, and target
+TCP socket to survive. It does not reconstruct a restarted hub, keep or transfer
+gateway sockets between processes, reopen a lost target, or replay an ambiguous
+target request after gateway, container, or host loss. If a newly constructed
+outbound gateway finds retained hub bridges but owns no live target sockets, it
+sends an empty resume manifest so the hub resets those omitted streams instead
+of creating targets.
 
 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.18",
+  "version": "0.1.19",
   "description": "Resilient authenticated tunnel/proxy for keeping socket streams alive across flaky links.",
   "type": "module",
   "main": "./src/index.js",

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

@@ -399,20 +399,27 @@ export class MultiplexedSocketductTransportSet extends EventEmitter {
   }
 
   /**
-   * Registers a durable stream on its original gateway before any member starts.
-   * @param {import('./multiplexed-connection.js').VirtualConnectionOptions & {gatewayId: string}} options - Original gateway and recovery identity.
+   * Registers a durable stream on its one original member before any member starts.
+   * @param {import('./multiplexed-connection.js').VirtualConnectionOptions & ({gatewayId: string, routeClass?: never} | {routeClass: string, gatewayId?: never})} options - Original gateway or route-class recovery identity.
    * @param {(error: Error | null, socket: GatewayVirtualSocket) => void} [callback] - Existing callback convention.
    * @returns {GatewayVirtualSocket} Original member-owned virtual socket with stable gateway metadata.
    */
   recoverConnection(options, callback) {
     if (this.#closed) throw closedError()
     if (this.#started) throw new Error("Recovered streams must be registered before start()")
-    if (typeof options !== "object" || options === null || typeof options.gatewayId !== "string" || !GATEWAY_ID.test(options.gatewayId)) throw new TypeError("recoverConnection requires a valid configured gatewayId")
+    if (typeof options !== "object" || options === null) throw new TypeError("recoverConnection requires exactly one configured gatewayId or routeClass")
+    const hasGatewayId = Object.hasOwn(options, "gatewayId")
+    const hasRouteClass = Object.hasOwn(options, "routeClass")
+    if (hasGatewayId === hasRouteClass) throw new TypeError("recoverConnection requires exactly one configured gatewayId or routeClass")
+    if (hasGatewayId && (typeof options.gatewayId !== "string" || !GATEWAY_ID.test(options.gatewayId))) throw new TypeError("recoverConnection requires a valid configured gatewayId")
+    if (hasRouteClass && (typeof options.routeClass !== "string" || !ROUTE_CLASS.test(options.routeClass))) throw new TypeError("recoverConnection requires a valid configured routeClass")
     if (Object.hasOwn(options, "recover")) throw new TypeError("recoverConnection owns the recover option")
-    const member = this.#members.find((candidate) => candidate.gatewayId === options.gatewayId)
-    if (member === undefined) throw new Error(`Unknown gatewayId: ${options.gatewayId}`)
+    const selector = hasGatewayId ? options.gatewayId : options.routeClass
+    const member = this.#members.find((candidate) => hasGatewayId ? candidate.gatewayId === selector : candidate.routeClass === selector)
+    if (member === undefined) throw new Error(`Unknown ${hasGatewayId ? "gatewayId" : "routeClass"}: ${selector}`)
     const virtualOptions = {...options}
     delete /** @type {{gatewayId?: string}} */ (virtualOptions).gatewayId
+    delete /** @type {{routeClass?: string}} */ (virtualOptions).routeClass
     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, exposeAllocation(socket, allocation))

package/src/client/virtual-socket.js

@@ -7,6 +7,7 @@ import {Duplex} from "node:stream"
  * @property {(streamId: number, callback: (error?: Error | null) => void) => void} _endStream - End the writable side.
  * @property {(streamId: number, error: Error | null) => void} _destroyStream - Destroy the virtual stream.
  * @property {(streamId: number) => void} _resumeReadable - Resume inbound flow.
+ * @property {(streamId: number, bytes: number) => void} [_consumeReadable] - Report bytes returned to the application.
  * @property {() => {address?: string, port?: number}} physicalAddress - Current physical endpoint.
  * @property {() => unknown} ref - Reference owner resources.
  * @property {() => unknown} unref - Unreference owner resources.
@@ -60,6 +61,9 @@ export class VirtualSocket extends Duplex {
   /** @type {boolean} */
   #remoteEnded = false
 
+  /** @type {number} */
+  #emittedDataBytes = 0
+
   /** @type {boolean} */
   connecting = true
 
@@ -123,6 +127,44 @@ export class VirtualSocket extends Duplex {
     this.#connection._resumeReadable(this.#streamId)
   }
 
+  /**
+   * Reports application consumption after Node has emitted flowing data or
+   * fulfilled a paused-mode read. Owners that need durable receive ACKs can
+   * therefore distinguish consumed bytes from process-local readable bytes.
+   * @param {number} [size] - Requested bytes.
+   * @returns {Buffer | string | null} Readable chunk.
+   * @override
+   */
+  read(size) {
+    const emittedBefore = this.#emittedDataBytes
+    const chunk = super.read(size)
+    if (chunk !== null) {
+      const bytes = typeof chunk === "string" ? Buffer.byteLength(chunk) : chunk.length
+      const emittedBytes = this.#emittedDataBytes - emittedBefore
+      if (bytes > emittedBytes) this.#connection._consumeReadable?.(this.#streamId, bytes - emittedBytes)
+    }
+    return chunk
+  }
+
+  /**
+   * A flowing Readable may emit directly from push() without returning a chunk
+   * through read(). Report DATA only after application listeners have run.
+   * @param {string | symbol} event - Event name.
+   * @param {...unknown} args - Event values.
+   * @returns {boolean} Whether the event had listeners.
+   * @override
+   */
+  emit(event, ...args) {
+    const emitted = super.emit(event, ...args)
+    const chunk = args[0]
+    if (event === "data" && (typeof chunk === "string" || Buffer.isBuffer(chunk))) {
+      const bytes = typeof chunk === "string" ? Buffer.byteLength(chunk) : chunk.length
+      this.#emittedDataBytes += bytes
+      this.#connection._consumeReadable?.(this.#streamId, bytes)
+    }
+    return emitted
+  }
+
   /**
    * @override
    * @param {Buffer | string | Uint8Array} chunk - Application bytes.