socketduct 0.1.15

package/src/reverse/client.js

@@ -0,0 +1,721 @@
+/* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-jsdoc, jsdoc/require-param, jsdoc/require-property-description, jsdoc/require-returns */
+import {randomBytes} from "node:crypto"
+import {EventEmitter} from "node:events"
+
+import {availableCodecs, getMaxDecompressedBytes, ZSTD_CODEC, zstdAvailable} from "../protocol/compression.js"
+import {errorDiagnostics, logDiagnostic} from "../logging/structured-logger.js"
+import {decodeV3Data, encodeV3Data, AdaptiveCompressor} from "../protocol/v3-compression.js"
+import {decodeV3Control, encodeV3Control, encodeV3Frame, V3FrameDecoder, V3FrameType} from "../protocol/v3-frame.js"
+import {SocketductSessionLostError, SocketductStreamError, VirtualSocket} from "../client/virtual-socket.js"
+import {
+  asError,
+  createHubSocket,
+  DEFAULT_CONNECT_TIMEOUT_MS,
+  DEFAULT_FRAME_BYTES,
+  DEFAULT_KEEP_ALIVE_INITIAL_DELAY_MS,
+  DEFAULT_MAX_STREAMS,
+  DEFAULT_WINDOW,
+  GATEWAY_ID,
+  MAX_CONTROL_BYTES,
+  parseTarget,
+  positiveInteger,
+  resolveVerifiedTls,
+  STABLE_IDENTIFIER,
+  writeSocket
+} from "./common.js"
+
+const DEFAULT_STREAM_BUFFER_BYTES = 4 * 1024 * 1024
+const DEFAULT_CONNECTION_BUFFER_BYTES = 32 * 1024 * 1024
+
+/**
+ * @typedef {object} ReverseGatewayConnectionOptions
+ * @property {string} gatewayId - Registered home gateway 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.
+ * @property {number} [initialWindowBytes] - Flow-control window.
+ * @property {number} [maxFrameBytes] - Maximum raw DATA frame.
+ * @property {number} [maxStreams] - Concurrent stream limit.
+ * @property {number} [maxStreamBufferBytes] - Per-stream client output bound.
+ * @property {number} [maxConnectionBufferBytes] - Aggregate client output bound.
+ * @property {number} [connectTimeoutMs] - TLS/auth deadline.
+ * @property {number} [reconnectDelayMs] - Initial reconnect delay.
+ * @property {number} [maxReconnectDelayMs] - Maximum reconnect delay.
+ * @property {number} [initialGeneration] - Monotonic seed for controlled replacement; defaults to wall-clock microseconds.
+ * @property {boolean} [continuousReconnect] - Keep the member warm after loss, default true.
+ * @property {import('../protocol/compression.js').CompressionLimits} [compressionLimits] - zstd safety bounds.
+ * @property {(options: {host: string, port: number, tls: object}) => import('node:tls').TLSSocket} [createPhysicalSocket] - Test transport factory.
+ * @property {{reserveData(bytes: number): void, reserveMemory(bytes: number): void, releaseMemory(bytes: number): void, releaseSpool(bytes: number): void, reserveControl(bytes: number): void, releaseControl(bytes: number): void}} [aggregateBudget] - Optional transport-set budget.
+ * @property {import('../logging/structured-logger.js').DiagnosticLogger} [logger] - Optional privacy-safe structured diagnostic logger.
+ * @typedef {object} ClientChunk
+ * @property {number} sequence
+ * @property {Buffer} data
+ * @property {boolean} sent
+ * @typedef {object} PendingClientWrite
+ * @property {Buffer} data
+ * @property {number} offset
+ * @property {(error?: Error | null) => void} callback
+ * @typedef {object} ReverseClientStream
+ * @property {number} id
+ * @property {string} identifier
+ * @property {string} name
+ * @property {{host: string, port: number}} target
+ * @property {VirtualSocket} socket
+ * @property {'opening' | 'open' | 'half-closed' | 'closed' | 'reset'} state
+ * @property {number} sendSequence
+ * @property {number} transmittedSequence
+ * @property {number} sendAck
+ * @property {number} sendWindow
+ * @property {number} sendWindowLimit
+ * @property {number} receiveSequence
+ * @property {number} receiveAck
+ * @property {number | undefined} pendingReceiveAck
+ * @property {boolean} remoteEnded
+ * @property {number} bufferedBytes
+ * @property {ClientChunk[]} replay
+ * @property {AdaptiveCompressor} compressor
+ * @property {boolean} pumping
+ * @property {PendingClientWrite | undefined} pendingWrite
+ * @property {boolean} progressingWrite
+ * @property {boolean} localEnded
+ * @property {boolean} endSent
+ * @property {((error?: Error | null) => void) | undefined} endCallback
+ */
+
+/** Server3/TensorBuzz-facing virtual socket connection to one registered gateway. */
+export class ReverseGatewayConnection extends EventEmitter {
+  /** @type {ReverseGatewayConnectionOptions} */ #options
+  /** @type {string} */ #connectionId
+  /** @type {import('node:tls').TLSSocket | undefined} */ #physical
+  /** @type {Map<number, ReverseClientStream>} */ #streams = new Map()
+  /** @type {number} */ #nextStreamId = 1
+  /** @type {'configured' | 'connecting' | 'ready' | 'reconnecting' | 'closed'} */ #state = "configured"
+  /** @type {number} */ #generation
+  /** @type {string | undefined} */ #codec
+  /** @type {boolean} */ #closing = false
+  /** @type {boolean} */ #fatal = false
+  /** @type {Error | undefined} */ #fatalError
+  /** @type {boolean} */ #referenced = true
+  /** @type {boolean} */ #warm = false
+  /** @type {ReturnType<typeof setTimeout> | undefined} */ #reconnectTimer
+  /** @type {Promise<void> | undefined} */ #connectPromise
+  /** @type {(() => void) | undefined} */ #resolveConnect
+  /** @type {((error: Error) => void) | undefined} */ #rejectConnect
+  /** @type {number} */ #reconnectDelay
+  /** @type {number} */ #sendWindowLimit
+  /** @type {number} */ #physicalConnects = 0
+  /** @type {number} */ #physicalAttempts = 0
+  /** @type {number} */ #reconnectAttempts = 0
+  /** @type {number} */ #bufferedBytes = 0
+  /** @type {number} */ #rawDataBytes = 0
+  /** @type {number} */ #wireDataBytes = 0
+  /** @type {number} */ #lastProgressedStreamId = 0
+
+  /** @param {ReverseGatewayConnectionOptions} options - Hub route and safety policy. */
+  constructor(options) {
+    super()
+    validateOptions(options)
+    this.#options = options
+    this.#connectionId = options.connectionId ?? randomBytes(24).toString("base64url")
+    this.#generation = options.initialGeneration ?? Date.now() * 1000
+    this.#reconnectDelay = options.reconnectDelayMs ?? 250
+    this.#sendWindowLimit = this.#initialWindow()
+    this.createConnection = this.createConnection.bind(this)
+  }
+
+  /** Warms the selected reverse member. */
+  connect() {
+    if (this.#closing) return Promise.reject(closedError())
+    if (this.#fatalError !== undefined) return Promise.reject(this.#fatalError)
+    if (this.#state === "ready") return Promise.resolve()
+    if (this.#connectPromise !== undefined) return this.#connectPromise
+    this.#warm = true
+    this.#connectPromise = new Promise((resolve, reject) => { this.#resolveConnect = resolve; this.#rejectConnect = reject })
+    this.#connectPhysical()
+    return this.#connectPromise
+  }
+
+  /** Allocates one stream on the already-warm gateway transport. */
+  createConnection(/** @type {import('../client/multiplexed-connection.js').VirtualConnectionOptions} */ options, /** @type {((error: Error | null, socket: VirtualSocket) => void) | undefined} */ callback = undefined) {
+    if (this.#closing) throw closedError()
+    if (this.#state !== "ready") throw Object.assign(new Error("Reverse gateway member is not ready"), {code: "SOCKETDUCT_TRANSPORT_SET_NOT_READY"})
+    if (this.#streams.size >= (this.#options.maxStreams ?? DEFAULT_MAX_STREAMS)) throw new Error("Maximum reverse virtual stream count exceeded")
+    const target = parseTarget(options?.target ?? {host: options?.host, port: options?.port})
+    if (target === undefined) throw new TypeError("Reverse virtual connection target host and port are required")
+    const identifier = options.identifier ?? randomBytes(24).toString("base64url")
+    if (typeof identifier !== "string" || !STABLE_IDENTIFIER.test(identifier)) throw new TypeError("Reverse virtual stream identifier must be 8-128 URL-safe characters")
+    const id = this.#allocateStreamId()
+    const name = options.sessionName ?? `socketduct-reverse-${id}`
+    if (typeof name !== "string" || name.length === 0 || name.length > 256) throw new TypeError("Reverse virtual stream name must be 1-256 characters")
+    const socket = new VirtualSocket(/** @type {import('../client/multiplexed-connection.js').MultiplexedSocketductConnection} */ (/** @type {unknown} */ (this)), id, {
+      ...target,
+      ...(options.allowHalfOpen === undefined ? {} : {allowHalfOpen: options.allowHalfOpen}),
+      ...(options.readableHighWaterMark === undefined ? {} : {readableHighWaterMark: options.readableHighWaterMark}),
+      ...(options.writableHighWaterMark === undefined ? {} : {writableHighWaterMark: options.writableHighWaterMark})
+    })
+    /** @type {ReverseClientStream} */
+    const stream = {
+      id, identifier, name, target, socket,
+      state: "opening",
+      sendSequence: 0,
+      transmittedSequence: 0,
+      sendAck: 0,
+      sendWindow: this.#sendWindowLimit,
+      sendWindowLimit: this.#sendWindowLimit,
+      receiveSequence: 0,
+      receiveAck: 0,
+      pendingReceiveAck: undefined,
+      remoteEnded: false,
+      bufferedBytes: 0,
+      replay: [],
+      compressor: new AdaptiveCompressor(),
+      pumping: false,
+      pendingWrite: undefined,
+      progressingWrite: false,
+      localEnded: false,
+      endSent: false,
+      endCallback: undefined
+    }
+    this.#streams.set(id, stream)
+    logDiagnostic(this.#options.logger, "virtual_stream.opening", {
+      streamId: id,
+      generation: this.#generation,
+      gatewayId: this.#options.gatewayId,
+      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)))
+    return socket
+  }
+
+  /** Reverse established operations are intentionally not recoverable across process/transport loss. */
+  registerRecoveredConnection() {
+    throw Object.assign(new Error("Reverse gateway streams cannot be recovered; reconcile the Docker operation before retrying"), {code: "REVERSE_STREAM_RECOVERY_UNSUPPORTED"})
+  }
+
+  status() {
+    /** @type {Record<string, number>} */
+    const streamStates = {}
+    for (const stream of this.#streams.values()) streamStates[stream.state] = (streamStates[stream.state] ?? 0) + 1
+    return {
+      physicalState: this.#state,
+      connectionGeneration: this.#generation,
+      virtualStreams: this.#streams.size,
+      streamStates,
+      queuedBytes: this.#bufferedBytes,
+      dataQueuedBytes: this.#bufferedBytes,
+      controlQueuedBytes: 0,
+      spoolBytes: 0,
+      spoolCleanupFailures: 0,
+      physicalConnects: this.#physicalConnects,
+      reconnectAttempts: this.#reconnectAttempts,
+      reconnectSuccesses: Math.max(0, this.#physicalConnects - 1),
+      resumeFailures: 0,
+      compression: this.#codec ?? null,
+      rawDataBytes: this.#rawDataBytes,
+      wireDataBytes: this.#wireDataBytes,
+      compressionBytesSaved: Math.max(0, this.#rawDataBytes - this.#wireDataBytes)
+    }
+  }
+
+  physicalAddress() { return {address: this.#physical?.localAddress, port: this.#physical?.localPort} }
+  ref() { this.#referenced = true; this.#physical?.ref(); this.#reconnectTimer?.ref?.(); return this }
+  unref() { this.#referenced = false; this.#physical?.unref(); this.#reconnectTimer?.unref?.(); return this }
+
+  async close() {
+    if (this.#closing) return
+    this.#closing = true
+    if (this.#reconnectTimer !== undefined) clearTimeout(this.#reconnectTimer)
+    this.#reconnectTimer = undefined
+    this.#setState("closed")
+    for (const stream of [...this.#streams.values()]) stream.socket.destroy()
+    const physical = this.#physical
+    this.#physical = undefined
+    if (physical !== undefined && !physical.destroyed) {
+      await writeSocket(physical, encodeV3Frame({type: V3FrameType.GOAWAY, streamId: 0, sequence: 0}, encodeV3Control({reason: "client_shutdown"}))).catch(() => false)
+      physical.destroy()
+    }
+    this.#rejectConnect?.(closedError())
+    this.#settleConnect()
+  }
+
+  /** Detach is terminal because ambiguous reverse streams are never durably replayed. */
+  detach() { return this.close() }
+
+  _writeStream(/** @type {number} */ streamId, /** @type {Buffer} */ data, /** @type {(error?: Error | null) => void} */ callback) {
+    const stream = this.#streams.get(streamId)
+    if (stream === undefined || stream.localEnded || stream.state === "closed" || stream.state === "reset") { callback(new SocketductStreamError("Reverse stream is not writable", "ERR_STREAM_DESTROYED")); return }
+    stream.pendingWrite = {data, offset: 0, callback}
+    this.#progressPendingWrites()
+  }
+
+  _endStream(/** @type {number} */ streamId, /** @type {(error?: Error | null) => void} */ callback) {
+    const stream = this.#streams.get(streamId)
+    if (stream === undefined || stream.localEnded) { callback(); return }
+    stream.localEnded = true
+    if (stream.state === "closed") { callback(); return }
+    stream.endCallback = callback
+    void this.#pumpStream(stream).catch((error) => this.#finishEnd(stream, asError(error)))
+  }
+
+  _destroyStream(/** @type {number} */ streamId, /** @type {Error | null} */ error) {
+    const stream = this.#streams.get(streamId)
+    if (stream === undefined) return
+    const wasClosed = stream.state === "closed"
+    logDiagnostic(this.#options.logger, error === null ? "virtual_stream.closed" : "virtual_stream.error", {
+      streamId,
+      generation: this.#generation,
+      gatewayId: this.#options.gatewayId,
+      ...(error === null ? {} : errorDiagnostics(error))
+    })
+    this.#retireStream(stream, error ?? new SocketductStreamError("Reverse stream is not writable", "ERR_STREAM_DESTROYED"))
+    if (!wasClosed && !this.#closing && this.#state === "ready") void this.#sendControl(V3FrameType.RESET, streamId, 0, {code: error instanceof SocketductStreamError ? error.code : "CLIENT_CANCELLED"}).catch(() => {})
+  }
+
+  _resumeReadable(/** @type {number} */ streamId) {
+    const stream = this.#streams.get(streamId)
+    if (stream?.pendingReceiveAck === undefined) return
+    const sequence = stream.pendingReceiveAck
+    stream.pendingReceiveAck = undefined
+    this.#ackReceived(stream, sequence)
+  }
+
+  #allocateStreamId() {
+    const id = this.#nextStreamId
+    if (id > 0xffff_fffd) throw new Error("Reverse v3 stream ID space exhausted")
+    this.#nextStreamId += 2
+    return id
+  }
+
+  #connectPhysical() {
+    if (this.#closing || this.#fatal || this.#physical !== undefined) return
+    this.#sendWindowLimit = this.#initialWindow()
+    this.#setState(this.#physicalConnects === 0 ? "connecting" : "reconnecting")
+    this.#generation += 1
+    this.#physicalAttempts += 1
+    const generation = this.#generation
+    logDiagnostic(this.#options.logger, "transport.connecting", {
+      generation,
+      attempt: this.#physicalAttempts,
+      gatewayId: this.#options.gatewayId,
+      reconnect: this.#physicalAttempts > 1
+    })
+    const tls = resolveVerifiedTls(this.#options.tls)
+    let physical
+    try {
+      physical = (this.#options.createPhysicalSocket ?? createHubSocket)({host: this.#options.hub.host, port: this.#options.hub.port, tls})
+    } catch (error) {
+      logDiagnostic(this.#options.logger, "transport.failed", {
+        generation,
+        attempt: this.#physicalAttempts,
+        gatewayId: this.#options.gatewayId,
+        ...errorDiagnostics(error)
+      })
+      this.#scheduleReconnect(asError(error))
+      return
+    }
+    this.#physical = physical
+    if (!this.#referenced) physical.unref()
+    physical.setNoDelay(true)
+    physical.setKeepAlive(true, DEFAULT_KEEP_ALIVE_INITIAL_DELAY_MS)
+    const decoder = new V3FrameDecoder({maxFrameBytes: Math.max(MAX_CONTROL_BYTES, this.#maxFrameBytes() + 4), maxBufferedBytes: Math.max(MAX_CONTROL_BYTES, this.#maxFrameBytes() + 4) * 2})
+    let queue = Promise.resolve()
+    let authenticated = false
+    let selected = false
+    /** @type {Error | undefined} */
+    let attemptError
+    const timer = setTimeout(() => physical.destroy(Object.assign(new Error("Reverse client TLS/auth timeout"), {code: "SOCKETDUCT_AUTH_TIMEOUT"})), this.#options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS)
+    timer.unref?.()
+    physical.once("secureConnect", () => {
+      const body = encodeV3Control({role: "client", token: this.#options.hub.token, versions: [3], connectionId: this.#connectionId, generation, compression: availableCodecs()})
+      void writeSocket(physical, encodeV3Frame({type: V3FrameType.AUTH, streamId: 0, sequence: generation}, body))
+        .catch((error) => physical.destroy(asError(error)))
+    })
+    physical.on("data", (chunk) => {
+      physical.pause()
+      queue = queue.then(async () => {
+        for (const frame of decoder.push(chunk)) {
+          if (frame.type === V3FrameType.AUTH_ERROR || frame.type === V3FrameType.GOAWAY) {
+            const detail = decodeV3Control(frame.payload)
+            throw connectionError(typeof detail.code === "string" ? detail.code : "CONNECTION_REJECTED")
+          }
+          if (!authenticated) {
+            if (frame.type !== V3FrameType.AUTH_OK) throw fatalError("AUTH_NEGOTIATION_FAILED")
+            const detail = decodeV3Control(frame.payload)
+            if (detail.version !== 3 || detail.role !== "client" || detail.connectionId !== this.#connectionId || detail.generation !== generation || detail.compression !== ZSTD_CODEC || !validPeerWindow(detail.initialWindow)) throw fatalError("AUTH_NEGOTIATION_FAILED")
+            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})))
+            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")
+            selected = true
+            clearTimeout(timer)
+            this.#physicalConnects += 1
+            this.#reconnectDelay = this.#options.reconnectDelayMs ?? 250
+            this.#setState("ready")
+            logDiagnostic(this.#options.logger, "transport.connected", {
+              generation,
+              attempt: this.#physicalAttempts,
+              gatewayId: this.#options.gatewayId,
+              physicalConnects: this.#physicalConnects,
+              reconnect: this.#physicalConnects > 1
+            })
+            if (this.#physicalConnects > 1) {
+              logDiagnostic(this.#options.logger, "transport.reconnect_succeeded", {
+                generation,
+                attempt: this.#reconnectAttempts,
+                gatewayId: this.#options.gatewayId,
+                physicalConnects: this.#physicalConnects
+              })
+            }
+            this.#resolveConnect?.()
+            this.#settleConnect()
+            continue
+          }
+          await this.#handleFrame(frame)
+        }
+      }).catch((error) => {
+        attemptError = asError(error)
+        if (/** @type {{fatal?: unknown}} */ (attemptError).fatal === true) this.#fatal = true
+        physical.destroy(attemptError)
+      }).finally(() => { if (!physical.destroyed) physical.resume() })
+    })
+    physical.once("error", (error) => { attemptError = error; if (isFatalTransportError(error)) this.#fatal = true })
+    physical.once("close", () => {
+      clearTimeout(timer)
+      void queue.finally(() => {
+        if (this.#physical !== physical) return
+        this.#physical = undefined
+        this.#codec = undefined
+        if (!this.#closing && !this.#fatal) this.#setState("reconnecting")
+        const lost = new SocketductSessionLostError("Reverse gateway transport was lost; operation outcome may be uncertain", "GATEWAY_DISCONNECTED")
+        if (!this.#closing) {
+          logDiagnostic(this.#options.logger, "transport.disconnected", {
+            generation,
+            gatewayId: this.#options.gatewayId,
+            virtualStreams: this.#streams.size,
+            ...errorDiagnostics(attemptError ?? lost, "GATEWAY_DISCONNECTED")
+          })
+        }
+        for (const stream of [...this.#streams.values()]) stream.socket._receiveError(lost)
+        if (this.#closing) return
+        if (this.#fatal) {
+          const terminalError = attemptError ?? lost
+          this.#fatalError = terminalError
+          this.#setState("closed", terminalError)
+          logDiagnostic(this.#options.logger, "transport.failed", {
+            generation,
+            attempt: this.#physicalAttempts,
+            gatewayId: this.#options.gatewayId,
+            ...errorDiagnostics(terminalError, "GATEWAY_DISCONNECTED")
+          })
+          this.#rejectConnect?.(terminalError)
+          this.#settleConnect()
+          return
+        }
+        if (this.#warm || this.#options.continuousReconnect !== false) this.#scheduleReconnect(attemptError)
+      })
+    })
+  }
+
+  /** @param {import('../protocol/v3-frame.js').V3Frame} frame - Hub frame. */
+  async #handleFrame(frame) {
+    if (frame.type === V3FrameType.PING) { await this.#sendControl(V3FrameType.PONG, 0, frame.sequence, {}); return }
+    if (frame.type === V3FrameType.PONG) return
+    const stream = this.#streams.get(frame.streamId)
+    if (stream === undefined) {
+      if (frame.type !== V3FrameType.CLOSE && frame.type !== V3FrameType.RESET) await this.#sendControl(V3FrameType.RESET, frame.streamId, 0, {code: "UNKNOWN_STREAM"})
+      return
+    }
+    if (frame.type === V3FrameType.OPENED) {
+      const detail = decodeV3Control(frame.payload)
+      if (stream.state !== "opening" || frame.sequence !== 0 || detail.identifier !== stream.identifier || !validPeerWindow(detail.initialWindow)) throw new Error("Invalid reverse OPENED response")
+      stream.sendWindowLimit = Math.min(stream.sendWindowLimit, detail.initialWindow)
+      stream.sendWindow = Math.min(stream.sendWindow, stream.sendWindowLimit)
+      stream.state = "open"
+      logDiagnostic(this.#options.logger, "virtual_stream.opened", {
+        streamId: stream.id,
+        generation: this.#generation,
+        gatewayId: this.#options.gatewayId,
+        recovered: false
+      })
+      stream.socket._markConnected()
+      this.#progressPendingWrites()
+      await this.#pumpStream(stream)
+      return
+    }
+    if (frame.type === V3FrameType.DATA) {
+      if (stream.remoteEnded) throw new Error("Reverse client received DATA after END")
+      const data = await decodeV3Data(frame, this.#codec, this.#options.compressionLimits)
+      if (data.length === 0 || data.length > this.#maxFrameBytes() || frame.sequence !== stream.receiveSequence + data.length || frame.sequence - stream.receiveAck > this.#initialWindow()) throw new Error("Invalid reverse client DATA sequence or window")
+      stream.receiveSequence = frame.sequence
+      const canContinue = stream.socket._receive(data)
+      if (canContinue) this.#ackReceived(stream, frame.sequence)
+      else stream.pendingReceiveAck = frame.sequence
+      return
+    }
+    if (frame.type === V3FrameType.ACK) { this.#acknowledge(stream, frame.sequence); return }
+    if (frame.type === V3FrameType.WINDOW) { this.#addWindow(stream, frame.sequence); return }
+    if (frame.type === V3FrameType.END) {
+      if (stream.remoteEnded || frame.sequence !== stream.receiveSequence) throw new Error("Invalid reverse client END")
+      stream.remoteEnded = true
+      stream.socket._receiveEnd()
+      return
+    }
+    if (frame.type === V3FrameType.CLOSE) {
+      if (frame.sequence !== stream.receiveSequence) throw new Error("Invalid reverse client CLOSE")
+      await this.#sendControl(V3FrameType.CLOSE, stream.id, stream.transmittedSequence, {})
+      stream.state = "closed"
+      logDiagnostic(this.#options.logger, "virtual_stream.closed", {
+        streamId: stream.id,
+        generation: this.#generation,
+        gatewayId: this.#options.gatewayId
+      })
+      this.#retireStream(stream, new SocketductStreamError("Reverse stream closed before pending writes completed", "ERR_STREAM_DESTROYED"))
+      stream.socket._receiveEnd()
+      if (!stream.socket.writableEnded && !stream.socket.destroyed) stream.socket.end()
+      this.#finishEnd(stream)
+      return
+    }
+    if (frame.type === V3FrameType.RESET) {
+      const detail = decodeV3Control(frame.payload)
+      const code = typeof detail.code === "string" ? detail.code : "STREAM_RESET"
+      stream.state = "reset"
+      const error = new SocketductStreamError("Reverse gateway stream was reset", code)
+      stream.socket._receiveError(error)
+      return
+    }
+    throw new Error("Unsupported reverse client frame")
+  }
+
+  /** @param {ReverseClientStream} stream - Stream. */
+  async #pumpStream(stream) {
+    if (stream.pumping || stream.state === "opening" || !this.#streams.has(stream.id) || this.#state !== "ready") return
+    stream.pumping = true
+    try {
+      for (const chunk of stream.replay) {
+        if (chunk.sent) continue
+        if (chunk.data.length > stream.sendWindow) break
+        const encoded = await encodeV3Data(chunk.data, this.#codec, stream.compressor, this.#options.compressionLimits)
+        if (!this.#streams.has(stream.id) || this.#state !== "ready") return
+        this.#rawDataBytes += encoded.rawBytes
+        this.#wireDataBytes += encoded.wireBytes
+        const sent = await writeSocket(/** @type {import('node:tls').TLSSocket} */ (this.#physical), encodeV3Frame({type: V3FrameType.DATA, streamId: stream.id, sequence: chunk.sequence, flags: encoded.flags}, encoded.payload), () => { stream.transmittedSequence = chunk.sequence })
+        if (!sent) return
+        chunk.sent = true
+        stream.sendWindow -= chunk.data.length
+      }
+      if (stream.localEnded && !stream.endSent && stream.replay.every((chunk) => chunk.sent)) {
+        stream.endSent = true
+        stream.state = "half-closed"
+        await this.#sendControl(V3FrameType.END, stream.id, stream.sendSequence, {})
+        this.#finishEnd(stream)
+      }
+    } finally { stream.pumping = false }
+  }
+
+  /** @param {ReverseClientStream} stream - Stream with an active application write. */
+  async #progressWrite(stream) {
+    const pending = stream.pendingWrite
+    if (pending === undefined || stream.progressingWrite || stream.state === "opening") return
+    stream.progressingWrite = true
+    try {
+      if (pending.offset < pending.data.length && this.#streams.get(stream.id) === stream) {
+        const available = this.#writeCapacity(stream)
+        if (available <= 0) return
+        const chunk = Buffer.from(pending.data.subarray(pending.offset, Math.min(pending.data.length, pending.offset + available)))
+        try {
+          if (this.#options.aggregateBudget?.reserveMemory !== undefined) this.#options.aggregateBudget.reserveMemory(chunk.length)
+          else this.#options.aggregateBudget?.reserveData(chunk.length)
+        } catch (error) {
+          this.#finishWrite(stream, asError(error))
+          return
+        }
+        pending.offset += chunk.length
+        stream.sendSequence += chunk.length
+        stream.replay.push({sequence: stream.sendSequence, data: chunk, sent: false})
+        stream.bufferedBytes += chunk.length
+        this.#bufferedBytes += chunk.length
+      }
+      await this.#pumpStream(stream)
+      if (pending.offset === pending.data.length && stream.pendingWrite === pending) this.#finishWrite(stream)
+    } catch (error) {
+      this.#finishWrite(stream, asError(error))
+    } finally {
+      stream.progressingWrite = false
+      this.#progressPendingWrites()
+    }
+  }
+
+  /** @param {ReverseClientStream} stream - Stream. @returns {number} Retained-byte headroom for its next frame. */
+  #writeCapacity(stream) {
+    return Math.max(0, Math.min(
+      this.#maxFrameBytes(),
+      stream.sendWindowLimit,
+      (this.#options.maxStreamBufferBytes ?? DEFAULT_STREAM_BUFFER_BYTES) - stream.bufferedBytes,
+      (this.#options.maxConnectionBufferBytes ?? DEFAULT_CONNECTION_BUFFER_BYTES) - this.#bufferedBytes
+    ))
+  }
+
+  /** Starts one bounded pending-write slice using rotating stream priority. */
+  #progressPendingWrites() {
+    const streams = [...this.#streams.values()]
+    if (streams.length === 0) return
+    const previousIndex = streams.findIndex((stream) => stream.id === this.#lastProgressedStreamId)
+    const startIndex = previousIndex === -1 ? 0 : (previousIndex + 1) % streams.length
+    for (let offset = 0; offset < streams.length; offset += 1) {
+      const stream = /** @type {ReverseClientStream} */ (streams[(startIndex + offset) % streams.length])
+      const pending = stream.pendingWrite
+      if (pending === undefined || stream.progressingWrite || stream.state === "opening" || (pending.offset < pending.data.length && this.#writeCapacity(stream) <= 0)) continue
+      this.#lastProgressedStreamId = stream.id
+      void this.#progressWrite(stream)
+      return
+    }
+  }
+
+  /** @param {ReverseClientStream} stream - Stream. @param {Error} [error] - Write failure. */
+  #finishWrite(stream, error) {
+    const pending = stream.pendingWrite
+    if (pending === undefined) return
+    stream.pendingWrite = undefined
+    pending.callback(error)
+  }
+
+  /** @param {ReverseClientStream} stream - Stream. @param {Error} [error] - Terminal send error. */
+  #finishEnd(stream, error) {
+    const callback = stream.endCallback
+    stream.endCallback = undefined
+    callback?.(error)
+  }
+
+  /** @param {ReverseClientStream} stream - Terminal stream. @param {Error} [pendingWriteError] - Pending write failure. */
+  #retireStream(stream, pendingWriteError = new SocketductStreamError("Reverse stream is not writable", "ERR_STREAM_DESTROYED")) {
+    if (!this.#streams.delete(stream.id)) return
+    this.#bufferedBytes = Math.max(0, this.#bufferedBytes - stream.bufferedBytes)
+    this.#options.aggregateBudget?.releaseMemory(stream.bufferedBytes)
+    if (this.#options.aggregateBudget?.reserveMemory === undefined) this.#options.aggregateBudget?.releaseSpool(stream.bufferedBytes)
+    stream.replay = []
+    stream.bufferedBytes = 0
+    this.#finishWrite(stream, pendingWriteError)
+    this.#progressPendingWrites()
+  }
+
+  /** @param {ReverseClientStream} stream - Stream. @param {number} sequence - ACK. */
+  #acknowledge(stream, sequence) {
+    if (!Number.isSafeInteger(sequence) || sequence < stream.sendAck || sequence > stream.sendSequence) throw new Error("Invalid reverse client ACK")
+    if (sequence === stream.sendAck) return
+    const delta = sequence - stream.sendAck
+    stream.sendAck = sequence
+    let released = 0
+    stream.replay = stream.replay.filter((chunk) => { if (chunk.sequence <= sequence) { released += chunk.data.length; return false } return true })
+    stream.bufferedBytes = Math.max(0, stream.bufferedBytes - released)
+    this.#bufferedBytes = Math.max(0, this.#bufferedBytes - released)
+    this.#options.aggregateBudget?.releaseMemory(released)
+    if (this.#options.aggregateBudget?.reserveMemory === undefined) this.#options.aggregateBudget?.releaseSpool(released)
+    stream.sendWindow = Math.min(stream.sendWindowLimit, stream.sendWindow + delta)
+    this.#progressPendingWrites()
+    void this.#pumpStream(stream).catch((error) => stream.socket._receiveError(asError(error)))
+  }
+
+  /** @param {ReverseClientStream} stream - Stream. @param {number} credit - Credit. */
+  #addWindow(stream, credit) {
+    if (!Number.isSafeInteger(credit) || credit <= 0 || credit > stream.sendWindowLimit) throw new Error("Invalid reverse client WINDOW")
+    stream.sendWindow = Math.min(stream.sendWindowLimit, stream.sendWindow + credit)
+    void this.#pumpStream(stream).catch((error) => stream.socket._receiveError(asError(error)))
+  }
+
+  /** @param {ReverseClientStream} stream - Stream. @param {number} sequence - Receive ack. */
+  #ackReceived(stream, sequence) {
+    if (sequence <= stream.receiveAck) return
+    stream.receiveAck = sequence
+    void this.#sendControl(V3FrameType.ACK, stream.id, sequence, {}).catch(() => {})
+  }
+
+  /** @param {number} type - Type. @param {number} streamId - Stream. @param {number} sequence - Sequence. @param {Record<string, unknown>} body - Body. */
+  async #sendControl(type, streamId, sequence, body) {
+    const physical = this.#physical
+    if (physical === undefined || physical.destroyed) throw new SocketductSessionLostError("Reverse gateway transport is unavailable", "GATEWAY_DISCONNECTED")
+    return await writeSocket(physical, encodeV3Frame({type, streamId, sequence}, encodeV3Control(body)))
+  }
+
+  #scheduleReconnect(/** @type {Error | undefined} */ error) {
+    if (this.#closing || this.#fatal || this.#reconnectTimer !== undefined) return
+    this.#reconnectAttempts += 1
+    this.#setState("reconnecting")
+    const delay = this.#reconnectDelay
+    logDiagnostic(this.#options.logger, "transport.reconnect_scheduled", {
+      generation: this.#generation,
+      attempt: this.#reconnectAttempts,
+      delayMs: delay,
+      gatewayId: this.#options.gatewayId,
+      ...errorDiagnostics(error, "GATEWAY_DISCONNECTED")
+    })
+    this.#reconnectDelay = Math.min(this.#reconnectDelay * 2, this.#options.maxReconnectDelayMs ?? 30_000)
+    this.#reconnectTimer = setTimeout(() => {
+      this.#reconnectTimer = undefined
+      if (this.#connectPromise === undefined) {
+        this.#connectPromise = new Promise((resolve, reject) => { this.#resolveConnect = resolve; this.#rejectConnect = reject })
+        this.#connectPromise.catch(() => {})
+      }
+      this.#connectPhysical()
+    }, delay)
+    if (!this.#referenced) this.#reconnectTimer.unref?.()
+    if (this.#physicalConnects === 0 && this.#options.continuousReconnect === false) {
+      this.#rejectConnect?.(error ?? new Error("Reverse hub connection failed"))
+      this.#settleConnect()
+    }
+  }
+
+  #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) }
+  #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 (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)
+  if (!zstdAvailable()) throw new Error("Reverse gateway mode requires Node.js zstd support")
+  getMaxDecompressedBytes(options.compressionLimits)
+  const frame = positiveInteger(options.maxFrameBytes, "maxFrameBytes", DEFAULT_FRAME_BYTES)
+  const window = positiveInteger(options.initialWindowBytes, "initialWindowBytes", DEFAULT_WINDOW)
+  if (frame > window) throw new RangeError("maxFrameBytes must not exceed initialWindowBytes")
+  positiveInteger(options.maxStreams, "maxStreams", DEFAULT_MAX_STREAMS)
+  positiveInteger(options.maxStreamBufferBytes, "maxStreamBufferBytes", DEFAULT_STREAM_BUFFER_BYTES)
+  positiveInteger(options.maxConnectionBufferBytes, "maxConnectionBufferBytes", DEFAULT_CONNECTION_BUFFER_BYTES)
+  if (options.initialGeneration !== undefined && (!Number.isSafeInteger(options.initialGeneration) || options.initialGeneration < 0)) throw new RangeError("initialGeneration must be a non-negative safe integer")
+}
+
+/** @param {VirtualSocket} socket - Socket. @param {(error: Error | null, socket: VirtualSocket) => void} callback - Callback. */
+function installCallback(socket, callback) {
+  let settled = false
+  const cleanup = () => { socket.off("connect", onConnect); socket.off("error", onError) }
+  const onConnect = () => { if (settled) return; settled = true; cleanup(); callback(null, socket) }
+  const onError = (/** @type {Error} */ error) => { if (settled) return; settled = true; cleanup(); callback(error, socket) }
+  socket.once("connect", onConnect)
+  socket.once("error", onError)
+}
+
+function fatalError(/** @type {string} */ code) { return Object.assign(new Error("Reverse gateway client was rejected by the hub"), {code, fatal: true}) }
+function connectionError(/** @type {string} */ code) {
+  if (code === "HUB_SHUTDOWN" || code === "GATEWAY_UNAVAILABLE" || code === "GATEWAY_DISCONNECTED" || code === "GATEWAY_REPLACED") return Object.assign(new Error("Selected reverse gateway is temporarily unavailable"), {code, fatal: false})
+  return fatalError(code)
+}
+/** @param {unknown} value - Advertised peer receive window. @returns {value is number} Whether valid. */
+function validPeerWindow(value) { return Number.isSafeInteger(value) && /** @type {number} */ (value) > 0 }
+function closedError() { return Object.assign(new Error("Reverse gateway connection is closed"), {code: "SOCKETDUCT_CONNECTION_CLOSED"}) }
+function isFatalTransportError(/** @type {Error} */ error) {
+  const code = /** @type {{code?: unknown}} */ (error).code
+  return typeof code === "string" && (code.startsWith("ERR_TLS_") || code.startsWith("ERR_SSL_") || code.includes("CERT") || code.includes("VERIFY") || code.includes("SELF_SIGNED") || code.includes("ISSUER"))
+}
+
+/** @param {ReverseGatewayConnectionOptions} options - Options. */
+export function createReverseGatewayConnection(options) { return new ReverseGatewayConnection(options) }