socketduct 0.1.15

package/src/reverse/gateway.js

@@ -0,0 +1,663 @@
+/* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-jsdoc, jsdoc/require-param, jsdoc/require-property-description, jsdoc/require-returns */
+import {EventEmitter} from "node:events"
+import {createConnection as netConnect} from "node:net"
+
+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 {
+  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_TOTAL_BUFFER_BYTES = 32 * 1024 * 1024
+
+/**
+ * @typedef {object} OutboundReverseGatewayOptions
+ * @property {string} gatewayId - Stable configured gateway identity.
+ * @property {string} connectionId - Stable process identity retained across reconnects.
+ * @property {{host: string, port: number, token: string}} hub - Server3 hub endpoint and bearer credential.
+ * @property {{caFile?: string, certFile?: string, keyFile?: string, servername?: string}} tls - Mandatory verified outer TLS.
+ * @property {(target: {host: string, port: number}) => boolean} authorizeTarget - Local deny-by-default target policy.
+ * @property {(target: {host: string, port: number}) => import('node:net').Socket} [createTargetConnection] - Local target socket factory.
+ * @property {number} [initialWindowBytes] - Per-stream flow-control window.
+ * @property {number} [maxFrameBytes] - Maximum uncompressed DATA frame.
+ * @property {number} [maxStreams] - Concurrent local target bound.
+ * @property {number} [maxStreamBufferBytes] - Per-stream unacknowledged target output bound.
+ * @property {number} [maxTotalBufferBytes] - Gateway-wide unacknowledged target output bound.
+ * @property {number} [connectTimeoutMs] - TLS/auth/register deadline.
+ * @property {number} [targetConnectTimeoutMs] - Local target connection 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 {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 {import('../logging/structured-logger.js').DiagnosticLogger} [logger] - Optional privacy-safe structured diagnostic logger.
+ * @typedef {object} GatewayReplay
+ * @property {number} sequence
+ * @property {Buffer} data
+ * @property {boolean} sent
+ * @typedef {object} GatewayStream
+ * @property {number} id
+ * @property {string} identifier
+ * @property {{host: string, port: number}} target
+ * @property {import('node:net').Socket} targetSocket
+ * @property {'opening' | 'open' | 'half-closed'} state
+ * @property {number} receiveSequence
+ * @property {number} receiveAck
+ * @property {boolean} remoteEnded
+ * @property {number} sendSequence
+ * @property {number} sendAck
+ * @property {number} sendWindow
+ * @property {number} sendWindowLimit
+ * @property {number} bufferedBytes
+ * @property {GatewayReplay[]} replay
+ * @property {AdaptiveCompressor} compressor
+ * @property {Promise<void>} targetQueue
+ * @property {boolean} pumping
+ * @property {boolean} targetEnded
+ * @property {boolean} targetClosed
+ * @property {string | undefined} targetResetCode
+ * @property {boolean} endSent
+ * @property {ReturnType<typeof setTimeout> | undefined} openTimer
+ * @property {boolean} targetOpened
+ * @property {boolean} targetTerminalLogged
+ */
+
+/** One outbound home member carrying many hub-opened local target streams. */
+export class OutboundReverseGateway extends EventEmitter {
+  /** @type {OutboundReverseGatewayOptions} */ #options
+  /** @type {import('node:tls').TLSSocket | undefined} */ #physical
+  /** @type {Map<number, GatewayStream>} */ #streams = new Map()
+  /** @type {number} */ #lastStreamId = 0
+  /** @type {'configured' | 'connecting' | 'registering' | 'ready' | 'reconnecting' | 'closed'} */ #state = "configured"
+  /** @type {number} */ #generation
+  /** @type {string | undefined} */ #codec
+  /** @type {boolean} */ #closing = false
+  /** @type {boolean} */ #fatal = false
+  /** @type {boolean} */ #referenced = true
+  /** @type {ReturnType<typeof setTimeout> | undefined} */ #reconnectTimer
+  /** @type {Promise<void> | undefined} */ #startPromise
+  /** @type {(() => void) | undefined} */ #resolveStart
+  /** @type {((error: Error) => void) | undefined} */ #rejectStart
+  /** @type {number} */ #reconnectDelay
+  /** @type {number} */ #sendWindowLimit
+  /** @type {number} */ #physicalConnects = 0
+  /** @type {number} */ #physicalAttempts = 0
+  /** @type {number} */ #reconnectAttempts = 0
+  /** @type {number} */ #targetOpens = 0
+  /** @type {number} */ #targetOpenFailures = 0
+  /** @type {number} */ #bufferedBytes = 0
+  /** @type {number} */ #rawDataBytes = 0
+  /** @type {number} */ #wireDataBytes = 0
+
+  /** @param {OutboundReverseGatewayOptions} options - Identity, hub, TLS and local policy. */
+  constructor(options) {
+    super()
+    validateOptions(options)
+    this.#options = options
+    this.#generation = options.initialGeneration ?? Date.now() * 1000
+    this.#reconnectDelay = options.reconnectDelayMs ?? 250
+    this.#sendWindowLimit = this.#initialWindow()
+  }
+
+  /** Starts and resolves after authenticated registration. */
+  start() {
+    if (this.#startPromise !== undefined) return this.#startPromise
+    if (this.#closing) return Promise.reject(closedError())
+    this.#startPromise = new Promise((resolve, reject) => { this.#resolveStart = resolve; this.#rejectStart = reject })
+    this.#connect()
+    return this.#startPromise
+  }
+
+  /** Alias for lifecycle symmetry with client transports. */
+  connect() { return this.start() }
+
+  /** Privacy-safe runtime state and compression accounting. */
+  status() {
+    return {
+      physicalState: this.#state,
+      connectionGeneration: this.#generation,
+      physicalConnects: this.#physicalConnects,
+      reconnectAttempts: this.#reconnectAttempts,
+      reconnectSuccesses: Math.max(0, this.#physicalConnects - 1),
+      virtualStreams: this.#streams.size,
+      activeTargets: [...this.#streams.values()].filter((stream) => stream.state !== "opening").length,
+      targetOpens: this.#targetOpens,
+      targetOpenFailures: this.#targetOpenFailures,
+      queuedBytes: this.#bufferedBytes,
+      spoolBytes: 0,
+      spoolCleanupFailures: 0,
+      compression: this.#codec ?? null,
+      rawDataBytes: this.#rawDataBytes,
+      wireDataBytes: this.#wireDataBytes,
+      compressionBytesSaved: Math.max(0, this.#rawDataBytes - this.#wireDataBytes)
+    }
+  }
+
+  /** Current local TLS address for socket-shaped metadata. */
+  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 }
+
+  /** Gracefully retires this member and every local target. */
+  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()]) this.#destroyStream(stream)
+    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: "gateway_shutdown"}))).catch(() => false)
+      physical.destroy()
+    }
+    this.#rejectStart?.(closedError())
+    this.#settleStart()
+  }
+
+  #connect() {
+    if (this.#closing || this.#fatal) 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(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()
+    /** @type {Error | undefined} */
+    let attemptError
+    let authenticated = false
+    let registered = false
+    const timer = setTimeout(() => physical.destroy(Object.assign(new Error("Reverse gateway connect/auth/register timeout"), {code: "SOCKETDUCT_AUTH_TIMEOUT"})), this.#options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS)
+    timer.unref?.()
+    physical.once("secureConnect", () => {
+      if (this.#physical !== physical || physical.destroyed) return
+      const auth = encodeV3Control({
+        role: "gateway",
+        token: this.#options.hub.token,
+        versions: [3],
+        connectionId: this.#options.connectionId,
+        generation,
+        compression: availableCodecs()
+      })
+      void writeSocket(physical, encodeV3Frame({type: V3FrameType.AUTH, streamId: 0, sequence: generation}, auth))
+    })
+    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 !== "gateway" || detail.connectionId !== this.#options.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)
+            this.#setState("registering")
+            await this.#sendControl(V3FrameType.GATEWAY_REGISTER, 0, generation, {gatewayId: this.#options.gatewayId})
+            continue
+          }
+          if (!registered) {
+            if (frame.type !== V3FrameType.GATEWAY_REGISTERED) throw fatalError("GATEWAY_REGISTRATION_FAILED")
+            const detail = decodeV3Control(frame.payload)
+            if (detail.gatewayId !== this.#options.gatewayId || detail.generation !== generation) throw fatalError("GATEWAY_REGISTRATION_FAILED")
+            registered = 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.#resolveStart?.()
+            this.#settleStart()
+            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")
+        if (!this.#closing) {
+          logDiagnostic(this.#options.logger, "transport.disconnected", {
+            generation,
+            gatewayId: this.#options.gatewayId,
+            virtualStreams: this.#streams.size,
+            ...errorDiagnostics(attemptError, "TRANSPORT_CLOSED")
+          })
+        }
+        for (const stream of [...this.#streams.values()]) this.#destroyStream(stream, "GATEWAY_DISCONNECTED")
+        this.#lastStreamId = 0
+        if (this.#closing) return
+        if (this.#fatal) {
+          this.#setState("closed")
+          const failure = attemptError ?? new Error("Reverse gateway registration failed")
+          logDiagnostic(this.#options.logger, "transport.failed", {
+            generation,
+            attempt: this.#physicalAttempts,
+            gatewayId: this.#options.gatewayId,
+            ...errorDiagnostics(failure, "GATEWAY_REGISTRATION_FAILED")
+          })
+          this.#rejectStart?.(failure)
+          this.#settleStart()
+          return
+        }
+        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
+    if (frame.type === V3FrameType.OPEN) { await this.#openStream(frame); 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 (stream.state === "opening" && frame.type !== V3FrameType.RESET) throw new Error("Reverse stream received data before target readiness")
+    if (frame.type === V3FrameType.DATA) {
+      if (stream.remoteEnded) throw new Error("Reverse stream 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 stream DATA sequence or window")
+      try {
+        await writeTarget(stream.targetSocket, data)
+      } catch {
+        this.#resetStream(stream, "TARGET_CLOSED")
+        return
+      }
+      stream.receiveSequence = frame.sequence
+      stream.receiveAck = frame.sequence
+      await this.#sendControl(V3FrameType.ACK, stream.id, 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 stream END")
+      stream.remoteEnded = true
+      stream.state = "half-closed"
+      stream.targetSocket.end()
+      return
+    }
+    if (frame.type === V3FrameType.CLOSE || frame.type === V3FrameType.RESET) { this.#destroyStream(stream); return }
+    throw new Error("Unsupported reverse gateway stream frame")
+  }
+
+  /** @param {import('../protocol/v3-frame.js').V3Frame} frame - Hub OPEN. */
+  async #openStream(frame) {
+    if (frame.sequence !== 0 || frame.streamId % 2 !== 0 || frame.streamId <= this.#lastStreamId) throw new Error("Invalid reverse gateway stream ID")
+    this.#lastStreamId = frame.streamId
+    if (this.#streams.size >= (this.#options.maxStreams ?? DEFAULT_MAX_STREAMS)) {
+      logDiagnostic(this.#options.logger, "reverse_gateway.target_open_failed", {
+        streamId: frame.streamId,
+        generation: this.#generation,
+        gatewayId: this.#options.gatewayId,
+        ...errorDiagnostics({code: "GATEWAY_STREAM_LIMIT"})
+      })
+      await this.#sendControl(V3FrameType.RESET, frame.streamId, 0, {code: "GATEWAY_STREAM_LIMIT"})
+      return
+    }
+    const request = decodeV3Control(frame.payload)
+    const target = parseTarget(request.target)
+    if (target === undefined || typeof request.identifier !== "string" || !STABLE_IDENTIFIER.test(request.identifier) || typeof request.name !== "string" || request.name.length === 0 || request.name.length > 256 || !validPeerWindow(request.initialWindow) || this.#options.authorizeTarget(target) !== true) {
+      const code = target === undefined ? "INVALID_STREAM_OPEN" : "TARGET_UNAUTHORIZED"
+      logDiagnostic(this.#options.logger, "reverse_gateway.target_open_failed", {
+        streamId: frame.streamId,
+        generation: this.#generation,
+        gatewayId: this.#options.gatewayId,
+        ...errorDiagnostics({code})
+      })
+      await this.#sendControl(V3FrameType.RESET, frame.streamId, 0, {code})
+      return
+    }
+    let targetSocket
+    try {
+      targetSocket = (this.#options.createTargetConnection ?? ((endpoint) => netConnect(endpoint)))(target)
+    } catch (error) {
+      this.#targetOpenFailures += 1
+      logDiagnostic(this.#options.logger, "reverse_gateway.target_open_failed", {
+        streamId: frame.streamId,
+        generation: this.#generation,
+        gatewayId: this.#options.gatewayId,
+        ...errorDiagnostics(error, "TARGET_OPEN_FAILED")
+      })
+      await this.#sendControl(V3FrameType.RESET, frame.streamId, 0, {code: "TARGET_OPEN_FAILED"})
+      return
+    }
+    /** @type {GatewayStream} */
+    const stream = {
+      id: frame.streamId,
+      identifier: request.identifier,
+      target,
+      targetSocket,
+      state: "opening",
+      receiveSequence: 0,
+      receiveAck: 0,
+      remoteEnded: false,
+      sendSequence: 0,
+      sendAck: 0,
+      sendWindow: Math.min(this.#sendWindowLimit, request.initialWindow),
+      sendWindowLimit: Math.min(this.#sendWindowLimit, request.initialWindow),
+      bufferedBytes: 0,
+      replay: [],
+      compressor: new AdaptiveCompressor(),
+      targetQueue: Promise.resolve(),
+      pumping: false,
+      targetEnded: false,
+      targetClosed: false,
+      targetResetCode: undefined,
+      endSent: false,
+      openTimer: undefined,
+      targetOpened: false,
+      targetTerminalLogged: false
+    }
+    this.#streams.set(stream.id, stream)
+    stream.openTimer = setTimeout(() => this.#resetStream(stream, "TARGET_OPEN_TIMEOUT"), this.#options.targetConnectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS)
+    stream.openTimer.unref?.()
+    targetSocket.once("connect", () => {
+      if (!this.#streams.has(stream.id)) return
+      if (stream.openTimer !== undefined) clearTimeout(stream.openTimer)
+      stream.openTimer = undefined
+      stream.state = "open"
+      stream.targetOpened = true
+      this.#targetOpens += 1
+      logDiagnostic(this.#options.logger, "reverse_gateway.target_opened", {
+        streamId: stream.id,
+        generation: this.#generation,
+        gatewayId: this.#options.gatewayId
+      })
+      void this.#sendControl(V3FrameType.OPENED, stream.id, 0, {identifier: stream.identifier, initialWindow: this.#initialWindow()})
+    })
+    targetSocket.on("data", (chunk) => {
+      targetSocket.pause()
+      stream.targetQueue = stream.targetQueue.then(() => this.#retainTargetData(stream, chunk)).catch(() => this.#resetStream(stream, "TARGET_READ_FAILED"))
+    })
+    targetSocket.once("end", () => {
+      stream.targetQueue = stream.targetQueue.then(async () => {
+        if (!this.#streams.has(stream.id)) return
+        stream.targetEnded = true
+        await this.#pumpStream(stream)
+      }).catch(() => this.#resetStream(stream, "TARGET_READ_FAILED"))
+    })
+    targetSocket.once("error", () => {
+      if (!this.#streams.has(stream.id)) return
+      const code = stream.state === "opening" ? "TARGET_OPEN_FAILED" : "TARGET_CLOSED"
+      this.#targetOpenFailures += stream.state === "opening" ? 1 : 0
+      this.#logTargetTerminal(stream, code)
+      stream.targetQueue = stream.targetQueue.then(async () => {
+        if (!this.#streams.has(stream.id)) return
+        stream.targetResetCode = code
+        await this.#pumpStream(stream)
+      }).catch(() => this.#resetStream(stream, "TARGET_READ_FAILED"))
+    })
+    targetSocket.once("close", () => {
+      this.#logTargetTerminal(stream, "TARGET_CLOSED")
+      stream.targetQueue = stream.targetQueue.then(async () => {
+        if (!this.#streams.has(stream.id)) return
+        stream.targetClosed = true
+        await this.#pumpStream(stream)
+      }).catch(() => this.#resetStream(stream, "TARGET_READ_FAILED"))
+    })
+  }
+
+  /** @param {GatewayStream} stream - Stream. @param {Buffer} chunk - Target output. */
+  async #retainTargetData(stream, chunk) {
+    if (!this.#streams.has(stream.id) || stream.state === "opening") return
+    for (let offset = 0; offset < chunk.length; offset += this.#maxFrameBytes()) {
+      const data = Buffer.from(chunk.subarray(offset, Math.min(chunk.length, offset + this.#maxFrameBytes())))
+      if (stream.bufferedBytes + data.length > (this.#options.maxStreamBufferBytes ?? DEFAULT_STREAM_BUFFER_BYTES) || this.#bufferedBytes + data.length > (this.#options.maxTotalBufferBytes ?? DEFAULT_TOTAL_BUFFER_BYTES)) {
+        this.#resetStream(stream, "BUFFER_LIMIT")
+        return
+      }
+      stream.sendSequence += data.length
+      stream.replay.push({sequence: stream.sendSequence, data, sent: false})
+      stream.bufferedBytes += data.length
+      this.#bufferedBytes += data.length
+    }
+    await this.#pumpStream(stream)
+  }
+
+  /** @param {GatewayStream} stream - Stream. */
+  async #pumpStream(stream) {
+    if (stream.pumping || !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))
+        if (!sent) return
+        chunk.sent = true
+        stream.sendWindow -= chunk.data.length
+      }
+      if (!stream.replay.some((chunk) => !chunk.sent)) {
+        if (stream.targetResetCode !== undefined) {
+          const code = stream.targetResetCode
+          stream.targetResetCode = undefined
+          await this.#sendControl(V3FrameType.RESET, stream.id, 0, {code})
+          this.#destroyStream(stream, code)
+          return
+        }
+        if (stream.targetEnded && !stream.endSent) {
+          stream.endSent = true
+          await this.#sendControl(V3FrameType.END, stream.id, stream.sendSequence, {})
+        }
+        if (stream.targetClosed && (!stream.targetEnded || stream.endSent)) {
+          await this.#sendControl(V3FrameType.CLOSE, stream.id, stream.sendSequence, {})
+          this.#destroyStream(stream)
+        }
+      }
+    } finally {
+      stream.pumping = false
+      if (this.#streams.has(stream.id) && !stream.replay.some((chunk) => !chunk.sent) && stream.bufferedBytes < (this.#options.maxStreamBufferBytes ?? DEFAULT_STREAM_BUFFER_BYTES) && this.#bufferedBytes < (this.#options.maxTotalBufferBytes ?? DEFAULT_TOTAL_BUFFER_BYTES)) stream.targetSocket.resume()
+    }
+  }
+
+  /** @param {GatewayStream} stream - Stream. @param {number} sequence - Cumulative ack. */
+  #acknowledge(stream, sequence) {
+    if (!Number.isSafeInteger(sequence) || sequence < stream.sendAck || sequence > stream.sendSequence) throw new Error("Invalid reverse gateway 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)
+    stream.sendWindow = Math.min(stream.sendWindowLimit, stream.sendWindow + delta)
+    void this.#pumpStream(stream).catch(() => this.#resetStream(stream, "TARGET_READ_FAILED"))
+  }
+
+  /** @param {GatewayStream} stream - Stream. @param {number} credit - Window credit. */
+  #addWindow(stream, credit) {
+    if (!Number.isSafeInteger(credit) || credit <= 0 || credit > stream.sendWindowLimit) throw new Error("Invalid reverse gateway WINDOW")
+    stream.sendWindow = Math.min(stream.sendWindowLimit, stream.sendWindow + credit)
+    void this.#pumpStream(stream).catch(() => this.#resetStream(stream, "TARGET_READ_FAILED"))
+  }
+
+  /** @param {GatewayStream} stream - Stream. @param {string} code - Reset code. */
+  #resetStream(stream, code) {
+    if (!this.#streams.has(stream.id)) return
+    this.#logTargetTerminal(stream, code)
+    void this.#sendControl(V3FrameType.RESET, stream.id, 0, {code})
+    this.#destroyStream(stream)
+  }
+
+  /** @param {GatewayStream} stream - Stream. */
+  #destroyStream(stream, code = "TARGET_CLOSED") {
+    if (!this.#streams.delete(stream.id)) return
+    this.#logTargetTerminal(stream, code)
+    if (stream.openTimer !== undefined) clearTimeout(stream.openTimer)
+    this.#bufferedBytes = Math.max(0, this.#bufferedBytes - stream.bufferedBytes)
+    stream.replay = []
+    stream.bufferedBytes = 0
+    stream.targetSocket.destroy()
+  }
+
+  /** @param {GatewayStream} stream - Stream. @param {string} code - Terminal classification. */
+  #logTargetTerminal(stream, code) {
+    if (stream.targetTerminalLogged) return
+    stream.targetTerminalLogged = true
+    logDiagnostic(this.#options.logger, stream.targetOpened ? "reverse_gateway.target_closed" : "reverse_gateway.target_open_failed", {
+      streamId: stream.id,
+      generation: this.#generation,
+      gatewayId: this.#options.gatewayId,
+      ...errorDiagnostics({code}, stream.targetOpened ? "TARGET_CLOSED" : "TARGET_OPEN_FAILED")
+    })
+  }
+
+  /** @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) return false
+    return await writeSocket(physical, encodeV3Frame({type, streamId, sequence}, encodeV3Control(body)))
+  }
+
+  #scheduleReconnect(/** @type {unknown} */ error = undefined) {
+    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, "TRANSPORT_CLOSED")
+    })
+    this.#reconnectDelay = Math.min(this.#reconnectDelay * 2, this.#options.maxReconnectDelayMs ?? 30_000)
+    this.#reconnectTimer = setTimeout(() => { this.#reconnectTimer = undefined; this.#connect() }, delay)
+    if (!this.#referenced) this.#reconnectTimer.unref?.()
+  }
+
+  #settleStart() { this.#resolveStart = undefined; this.#rejectStart = undefined }
+  #setState(/** @type {'configured' | 'connecting' | 'registering' | 'ready' | 'reconnecting' | 'closed'} */ state) { if (this.#state === state) return; this.#state = state; this.emit("stateChange", state) }
+  #initialWindow() { return this.#options.initialWindowBytes ?? DEFAULT_WINDOW }
+  #maxFrameBytes() { return Math.min(this.#options.maxFrameBytes ?? DEFAULT_FRAME_BYTES, getMaxDecompressedBytes(this.#options.compressionLimits), 64 * 1024) }
+}
+
+/** @param {OutboundReverseGatewayOptions} options - Options. */
+function validateOptions(options) {
+  if (typeof options !== "object" || options === null || typeof options.gatewayId !== "string" || !GATEWAY_ID.test(options.gatewayId)) throw new TypeError("Outbound reverse gateway requires a valid gatewayId")
+  if (typeof options.connectionId !== "string" || !STABLE_IDENTIFIER.test(options.connectionId)) throw new TypeError("Outbound reverse gateway requires a stable connectionId")
+  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("Outbound reverse gateway requires hub host, port and token")
+  if (typeof options.authorizeTarget !== "function") throw new TypeError("Outbound reverse gateway requires a local target authorization policy")
+  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.maxTotalBufferBytes, "maxTotalBufferBytes", DEFAULT_TOTAL_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 {import('node:net').Socket} socket - Local target. @param {Buffer} data - Bytes. */
+async function writeTarget(socket, data) {
+  if (socket.destroyed || !socket.writable) throw new Error("Local target is unavailable")
+  await new Promise((resolve, reject) => socket.write(data, (error) => error ? reject(error) : resolve(undefined)))
+}
+
+function fatalError(/** @type {string} */ code) {
+  const error = /** @type {Error & {code: string, fatal: boolean}} */ (Object.assign(new Error("Reverse gateway was rejected by the hub"), {code, fatal: true}))
+  return error
+}
+
+function connectionError(/** @type {string} */ code) {
+  if (code === "HUB_SHUTDOWN") return Object.assign(new Error("Reverse gateway hub 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("Outbound reverse gateway is closed"), {code: "SOCKETDUCT_GATEWAY_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 {OutboundReverseGatewayOptions} options - Options. */
+export function createOutboundReverseGateway(options) { return new OutboundReverseGateway(options) }