socketduct 0.1.15

package/src/client/socketduct-socket.js

@@ -0,0 +1,1174 @@
+import {Duplex} from "node:stream"
+import {createConnection} from "node:net"
+import {connect as tlsConnect} from "node:tls"
+import {readFileSync} from "node:fs"
+
+import {errorDiagnostics, logDiagnostic} from "../logging/structured-logger.js"
+import {AdaptiveCompressor, availableCodecs, decodeStreamPayload, encodeStreamPayload, getMaxDecompressedBytes} from "../protocol/compression.js"
+import {encodeCompactAck, encodeCompactData, encodeFrame, FrameDecoder} from "../protocol/frame.js"
+import {SessionSpool as SessionSpoolStorage} from "../spool/spool-file.js"
+
+const RELAY_CONNECT_TIMEOUT_MS = 10_000
+const SESSION_CLOSE_TIMEOUT_MS = 1_000
+export const kCloseSocketductSession = Symbol("closeSocketductSession")
+
+export class SocketductRelayError extends Error {
+  /**
+   * @param {string} message - Safe relay-provided error message.
+   * @param {{code?: string, retryable?: boolean}} [details] - Machine-readable relay error details.
+   */
+  constructor(message, details = {}) {
+    super(message)
+    this.name = "SocketductRelayError"
+    this.code = details.code ?? "RELAY_ERROR"
+    this.retryable = details.retryable ?? false
+  }
+}
+
+/**
+ * @param {unknown} err - Error to inspect.
+ * @returns {boolean} - True when the error is a TLS verification/auth failure
+ *   that should not be retried (wrong CA, hostname mismatch, self-signed,
+ *   expired/revoked cert, or equivalent).
+ */
+function isTlsVerificationError(err) {
+  if (!(err instanceof Error)) return false
+  const code = /** @type {string | undefined} */ ((/** @type {{code?: unknown}} */ (err)).code)
+  if (typeof code !== "string") return false
+  if (code.startsWith("ERR_TLS_") || code.startsWith("ERR_SSL_")) return true
+  // OpenSSL error codes surfaced by Node.js TLS for cert/verify failures
+  if (code.includes("CERT_") || code.includes("_SIGNED_CERT") || code.startsWith("UNABLE_TO_")) return true
+  return false
+}
+
+/**
+ * @typedef {import('../spool/spool-file.js').SessionSpool} SessionSpool
+ * @typedef {import('../spool/spool-file.js').SessionSpoolOptions} SessionSpoolOptions
+ * @typedef {{host: string, port: number}} SocketductTarget
+ * @typedef {object} SocketductTlsOptions
+ * @property {string} [caFile] - Path to CA certificate file for server verification.
+ * @property {string} [certFile] - Path to client certificate file for mTLS (requires keyFile).
+ * @property {string} [keyFile] - Path to client private key file for mTLS (requires certFile).
+ * @property {string} [servername] - SNI hostname for certificate identity validation.
+ * @property {boolean} [rejectUnauthorized] - Whether to reject unauthorized certificates. Defaults to true.
+ * @typedef {object} SocketductSocketOptions
+ * @property {string} relayHost - Relay host.
+ * @property {number} relayPort - Relay port.
+ * @property {string} token - Auth token.
+ * @property {string} sessionName - Human-readable session name.
+ * @property {SocketductTarget} target - Target requested for this session.
+ * @property {SessionSpool} spool - Spool storage.
+ * @property {number} [reconnectDelayMs] - Reconnect delay.
+ * @property {SocketductTlsOptions} [tls] - TLS client options.
+ * @property {boolean} [compressionEnabled] - Whether to offer stream.data compression when the runtime supports it. Default true.
+ * @property {import('../protocol/compression.js').CompressionLimits} [compressionLimits] - Compression size and expansion-ratio bounds.
+ * @property {import('../logging/structured-logger.js').DiagnosticLogger} [logger] - Optional privacy-safe structured diagnostic logger.
+ * @typedef {object} SocketductSocketDependencies
+ * @property {(options: {host: string, port: number, tls?: Record<string, unknown>}) => import('node:net').Socket} [createRelaySocket] - Raw relay socket factory.
+ * @property {(callback: () => void, delay: number) => unknown} [setTimeout] - Timer factory.
+ * @property {(timer: unknown) => void} [clearTimeout] - Timer cleanup.
+ * @typedef {object} ConnectSocketductOptions
+ * @property {{host: string, port: number, token: string}} relay - Relay connection options.
+ * @property {string} sessionName - Human-readable session name.
+ * @property {SocketductTarget} target - Target requested for this session.
+ * @property {string} spoolDirectory - Spool directory.
+ * @property {{initialDelayMs?: number}} [reconnect] - Reconnect options.
+ * @property {SocketductTlsOptions} [tls] - TLS client options.
+ * @property {number} [maxBytes] - Maximum total spool bytes per session.
+ * @property {number} [maxAgeMs] - Maximum age of a spool session before operations are rejected.
+ * @property {boolean} [compressionEnabled] - Whether to offer stream.data compression when the runtime supports it. Default true.
+ * @property {import('../protocol/compression.js').CompressionLimits} [compressionLimits] - Compression size and expansion-ratio bounds.
+ * @property {import('../logging/structured-logger.js').DiagnosticLogger} [logger] - Optional privacy-safe structured diagnostic logger.
+ */
+
+/**
+ * @param {ConnectSocketductOptions} options - Public socket options.
+ * @param {() => void} [listener] - Optional connect listener.
+ * @returns {SocketductSocket} - Connected Socketduct socket.
+ */
+export function connectSocketduct(options, listener) {
+  /** @type {SessionSpoolOptions} */
+  const spoolOptions = {rootDir: options.spoolDirectory}
+  if (options.maxBytes !== undefined) {
+    spoolOptions.maxBytes = options.maxBytes
+  }
+  if (options.maxAgeMs !== undefined) {
+    spoolOptions.maxAgeMs = options.maxAgeMs
+  }
+  /** @type {SocketductSocketOptions} */
+  const socketOptions = {
+    relayHost: options.relay.host,
+    relayPort: options.relay.port,
+    token: options.relay.token,
+    sessionName: options.sessionName,
+    target: options.target,
+    spool: new SessionSpoolStorage(spoolOptions)
+  }
+  if (options.reconnect?.initialDelayMs !== undefined) {
+    socketOptions.reconnectDelayMs = options.reconnect.initialDelayMs
+  }
+  if (options.tls !== undefined) {
+    socketOptions.tls = options.tls
+  }
+  if (options.compressionEnabled !== undefined) {
+    socketOptions.compressionEnabled = options.compressionEnabled
+  }
+  if (options.compressionLimits !== undefined) {
+    socketOptions.compressionLimits = options.compressionLimits
+  }
+  if (options.logger !== undefined) {
+    socketOptions.logger = options.logger
+  }
+  const socket = new SocketductSocket(socketOptions)
+  if (listener !== undefined) {
+    socket.once("connect", listener)
+  }
+  socket.connect()
+  return socket
+}
+
+export class SocketductSocket extends Duplex {
+  /** @type {SocketductSocketOptions} */
+  #options
+
+  /** @type {import('node:net').Socket | undefined} */
+  #relaySocket
+
+  /** @type {Record<string, unknown> | undefined} */
+  #tlsContext
+
+  /** @type {string | undefined} */
+  #sessionId
+
+  /** @type {number} */
+  #sequence = 0
+
+  /** @type {number} */
+  #ackedSequence = 0
+
+  /** @type {number} */
+  #targetReceivedSequence = 0
+
+  /** @type {boolean} */
+  #relayWritable = false
+
+  /** @type {import('node:net').Socket | undefined} */
+  #authenticatedRelaySocket
+
+  /** Codec negotiated on the current relay connection; undefined means uncompressed stream data. */
+  /** @type {string | undefined} */
+  #codec
+
+  /** @type {number | undefined} */
+  #framing
+
+  /** @type {AdaptiveCompressor | undefined} */
+  #compressor
+
+  /** @type {boolean} */
+  #closed = false
+
+  /** @type {boolean} */
+  #applicationEof = false
+
+  /** @type {boolean} */
+  #spoolCleanedUp = false
+
+  /** @type {boolean} */
+  #connectStarted = false
+
+  /** @type {boolean} */
+  #connectEmitted = false
+
+  /** @type {number} */
+  #physicalAttempts = 0
+
+  /** @type {number} */
+  #physicalConnects = 0
+
+  /** @type {number} */
+  #generation = 0
+
+  /** @type {unknown} */
+  #reconnectTimer
+
+  /** @type {((options: {destroySocket: boolean, reconnect: boolean, error?: unknown}) => void) | undefined} */
+  #terminateRelayAttempt
+
+  /** @type {(options: {host: string, port: number, tls?: Record<string, unknown>}) => import('node:net').Socket} */
+  #createRelaySocket
+
+  /** @type {(callback: () => void, delay: number) => unknown} */
+  #setTimeout
+
+  /** @type {(timer: unknown) => void} */
+  #clearTimeout
+
+  /** @type {unknown} */
+  #timeoutTimer
+
+  /** @type {number} */
+  #timeoutMs = 0
+
+  /** @type {Promise<void>} */
+  #spoolQueue = Promise.resolve()
+
+  /** @type {Promise<void>} */
+  #relayFrameQueue = Promise.resolve()
+
+  /** @type {Promise<void | boolean>} */
+  #sendQueue = Promise.resolve()
+
+  /** @type {Promise<boolean> | undefined} */
+  #sessionClosePromise
+
+  /** @type {((sent: boolean) => void) | undefined} */
+  #resolveSessionClose
+
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  #sessionCloseTimer
+
+  /** @type {import('node:net').Socket | undefined} */
+  #sessionCloseRelay
+
+  /** @type {boolean} */
+  #sessionCloseAcknowledged = false
+
+  /** @type {number} */
+  bytesRead = 0
+
+  /** @type {number} */
+  bytesWritten = 0
+
+  /** @type {boolean} */
+  connecting = false
+
+  /** @type {boolean} */
+  pending = true
+
+  /** @type {string | undefined} */
+  remoteAddress
+
+  /** @type {number | undefined} */
+  remotePort
+
+  /** @type {string | undefined} */
+  localAddress
+
+  /** @type {number | undefined} */
+  localPort
+
+  /** @returns {string | undefined} - Current session identifier. */
+  get sessionIdentifier() {
+    return this.#sessionId
+  }
+
+  /**
+   * @param {SocketductSocketOptions} options - Socket options.
+   * @param {SocketductSocketDependencies} [dependencies] - Runtime dependencies.
+   */
+  constructor(options, dependencies = {}) {
+    super()
+    getMaxDecompressedBytes(options.compressionLimits)
+    this.#options = options
+    this.#createRelaySocket = dependencies.createRelaySocket ?? ((relayOptions) => {
+      if (relayOptions.tls !== undefined) {
+        return tlsConnect({
+          host: relayOptions.host,
+          port: relayOptions.port,
+          ...relayOptions.tls
+        })
+      }
+      return createConnection({host: relayOptions.host, port: relayOptions.port})
+    })
+    this.#setTimeout = dependencies.setTimeout ?? ((callback, delay) => setTimeout(callback, delay))
+    this.#clearTimeout = dependencies.clearTimeout ?? ((timer) => clearTimeout(/** @type {ReturnType<typeof setTimeout>} */ (timer)))
+    this.remoteAddress = options.target.host
+    this.remotePort = options.target.port
+  }
+
+  /**
+   * Starts the relay connection.
+   * @returns {this} - This socket.
+   */
+  connect() {
+    if (this.#connectStarted || this.destroyed) {
+      return this
+    }
+
+    this.#connectStarted = true
+    this.connecting = true
+    logDiagnostic(this.#options.logger, "virtual_stream.opening")
+    this.#connectRelay()
+    return this
+  }
+
+  /**
+   * @param {number} timeout - Timeout in milliseconds.
+   * @param {() => void} [callback] - Timeout callback.
+   * @returns {this} - This socket.
+   */
+  setTimeout(timeout, callback) {
+    if (callback !== undefined) {
+      this.once("timeout", callback)
+    }
+    this.#timeoutMs = timeout
+    this.#clearTimeoutTimer()
+    if (timeout > 0) {
+      this.#armTimeoutTimer()
+    }
+    return this
+  }
+
+  /** @returns {void} - Clears the current idle timeout. */
+  #clearTimeoutTimer() {
+    if (this.#timeoutTimer !== undefined) {
+      this.#clearTimeout(this.#timeoutTimer)
+      this.#timeoutTimer = undefined
+    }
+  }
+
+  /** @returns {void} - Arms the idle timeout, resetting it on each call. */
+  #armTimeoutTimer() {
+    this.#clearTimeoutTimer()
+    if (this.#timeoutMs > 0) {
+      const timer = this.#setTimeout(() => {
+        if (this.#timeoutTimer !== timer) return
+        this.#timeoutTimer = undefined
+        this.emit("timeout")
+      }, this.#timeoutMs)
+      this.#timeoutTimer = timer
+      const unref = /** @type {{unref?: () => void}} */ (timer)?.unref
+      unref?.call(timer)
+    }
+  }
+
+  /** @returns {void} - Resets the idle timeout on socket activity. */
+  #resetTimeoutTimer() {
+    if (this.#timeoutMs > 0) {
+      this.#armTimeoutTimer()
+    }
+  }
+
+  /** @returns {this} - This socket. */
+  setNoDelay() {
+    return this
+  }
+
+  /** @returns {this} - This socket. */
+  setKeepAlive() {
+    return this
+  }
+
+  /** @returns {{address: string, family: string, port: number}} - Socket address. */
+  address() {
+    return {
+      address: this.localAddress ?? "0.0.0.0",
+      family: "IPv4",
+      port: this.localPort ?? 0
+    }
+  }
+
+  /** @returns {this} - This socket. */
+  ref() {
+    this.#relaySocket?.ref()
+    return this
+  }
+
+  /** @returns {this} - This socket. */
+  unref() {
+    this.#relaySocket?.unref()
+    return this
+  }
+
+  /**
+   * Sends the logical session close control exactly once when the relay is
+   * available. Transport owners use this before destroying a wrapped socket.
+   * @returns {Promise<boolean>} True when the close frame reached the relay socket.
+   */
+  [kCloseSocketductSession]() {
+    if (this.#sessionClosePromise !== undefined) return this.#sessionClosePromise
+    this.#closed = true
+    this.#relayWritable = false
+    const relaySocket = this.#relaySocket
+    if (this.#sessionId === undefined) {
+      if (this.#reconnectTimer !== undefined) {
+        this.#clearTimeout(this.#reconnectTimer)
+        this.#reconnectTimer = undefined
+      }
+      this.#sessionClosePromise = Promise.resolve(false)
+      return this.#sessionClosePromise
+    }
+    this.#sessionClosePromise = new Promise((resolve) => {
+      this.#resolveSessionClose = resolve
+      this.#sessionCloseTimer = setTimeout(() => this.#settleSessionClose(false), SESSION_CLOSE_TIMEOUT_MS)
+      this.#sessionCloseTimer.unref?.()
+    })
+    if (relaySocket !== undefined && this.#authenticatedRelaySocket === relaySocket && !relaySocket.destroyed) {
+      this.#sendSessionClose(relaySocket)
+    } else if (relaySocket === undefined || relaySocket.destroyed) {
+      if (this.#reconnectTimer !== undefined) {
+        this.#clearTimeout(this.#reconnectTimer)
+        this.#reconnectTimer = undefined
+      }
+      this.#connectRelay()
+    }
+    return this.#sessionClosePromise
+  }
+
+  /**
+   * Sends close only on the relay connection that has authenticated and
+   * completed create/resume. A failed transport remains eligible for the
+   * bounded close-only reconnect until the close acknowledgement deadline.
+   * @param {import('node:net').Socket} relaySocket - Authenticated relay socket.
+   */
+  #sendSessionClose(relaySocket) {
+    if (!this.#needsRelayForClose() || this.#relaySocket !== relaySocket || this.#authenticatedRelaySocket !== relaySocket || relaySocket.destroyed || this.#sessionCloseRelay === relaySocket) return
+    this.#sessionCloseRelay = relaySocket
+    void this.#writeFrameToRelay(relaySocket, {type: "session.close", direction: "client-to-relay"})
+      .then((sent) => {
+        if (!sent && this.#relaySocket === relaySocket && !relaySocket.destroyed) relaySocket.destroy()
+      })
+      .catch((error) => relaySocket.destroy(error instanceof Error ? error : new Error(String(error))))
+  }
+
+  /** @returns {boolean} Whether destruction is waiting for an authenticated logical close. */
+  #needsRelayForClose() {
+    return this.#closed && this.#sessionId !== undefined && this.#resolveSessionClose !== undefined && !this.#sessionCloseAcknowledged
+  }
+
+  /** @returns {boolean} Whether a normal or close-only relay attempt may run. */
+  #mayConnectRelay() {
+    return (!this.#closed && !this.destroyed) || this.#needsRelayForClose()
+  }
+
+  /** Ends the application-facing readable side exactly once. */
+  #endApplicationReadable() {
+    if (this.#applicationEof) return
+    this.#applicationEof = true
+    if (!this.destroyed) this.push(null)
+  }
+
+  /** @param {boolean} sent */
+  #settleSessionClose(sent) {
+    if (this.#resolveSessionClose === undefined) return
+    const resolve = this.#resolveSessionClose
+    this.#resolveSessionClose = undefined
+    if (this.#sessionCloseTimer !== undefined) {
+      clearTimeout(this.#sessionCloseTimer)
+      this.#sessionCloseTimer = undefined
+    }
+    this.#sessionCloseRelay = undefined
+    resolve(sent)
+  }
+
+  /**
+   * @override
+   * @returns {void} - Pulls data from the internal buffer.
+   */
+  _read() {
+    this.#relaySocket?.resume()
+  }
+
+  /**
+   * @override
+   * @param {Buffer} chunk - Data chunk.
+   * @param {string} _encoding - Encoding value.
+   * @param {(error?: Error | null) => void} callback - Completion callback.
+   * @returns {void} - Writes chunk to Socketduct.
+   */
+  _write(chunk, _encoding, callback) {
+    this.#resetTimeoutTimer()
+    this.#handleAppData(chunk)
+      .then(() => callback())
+      .catch((error) => callback(error instanceof Error ? error : new Error(String(error))))
+  }
+
+  /**
+   * Node calls this only for writes already queued behind an in-flight async
+   * write. Merge those original bytes without delaying a sole chunk.
+   * @override
+   * @param {{chunk: Buffer, encoding: string}[]} chunks - Already queued writes.
+   * @param {(error?: Error | null) => void} callback - Completion callback.
+   */
+  _writev(chunks, callback) {
+    this.#resetTimeoutTimer()
+    const maxBytes = getMaxDecompressedBytes(this.#options.compressionLimits)
+    const groups = []
+    let pending = []
+    let pendingBytes = 0
+    for (const entry of chunks) {
+      let offset = 0
+      while (offset < entry.chunk.length) {
+        const available = maxBytes - pendingBytes
+        const length = Math.min(available, entry.chunk.length - offset)
+        pending.push(entry.chunk.subarray(offset, offset + length))
+        pendingBytes += length
+        offset += length
+        if (pendingBytes === maxBytes) {
+          groups.push(Buffer.concat(pending, pendingBytes))
+          pending = []
+          pendingBytes = 0
+        }
+      }
+    }
+    if (pendingBytes > 0) groups.push(Buffer.concat(pending, pendingBytes))
+    groups.reduce((work, group) => work.then(() => this.#handleAppData(group)), Promise.resolve())
+      .then(() => callback())
+      .catch((error) => callback(error instanceof Error ? error : new Error(String(error))))
+  }
+
+  /**
+   * @override
+   * @param {(error?: Error | null) => void} callback - Completion callback.
+   * @returns {void} - Ends the socket.
+   */
+  _final(callback) {
+    this.#closed = true
+    if (this.#reconnectTimer !== undefined) {
+      this.#clearTimeout(this.#reconnectTimer)
+      this.#reconnectTimer = undefined
+    }
+    this.#relayWritable = false
+    const relaySocket = this.#relaySocket
+    if (relaySocket !== undefined && !relaySocket.destroyed && this.#sessionId !== undefined) {
+      this[kCloseSocketductSession]()
+        .then(() => {
+          relaySocket.destroy()
+          return this.#cleanupSpool()
+        })
+        .then(() => {
+          this.#endApplicationReadable()
+          callback()
+        })
+        .catch((error) => callback(error))
+    } else {
+      if (this.#terminateRelayAttempt !== undefined) {
+        this.#terminateRelayAttempt({destroySocket: true, reconnect: false})
+      } else {
+        relaySocket?.destroy()
+      }
+      this.#cleanupSpool()
+        .then(() => {
+          this.#endApplicationReadable()
+          callback()
+        })
+        .catch((error) => callback(error))
+    }
+  }
+
+  /**
+   * @override
+   * @param {Error | null} error - Destroy error.
+   * @param {(error?: Error | null) => void} callback - Completion callback.
+   * @returns {void} - Destroys resources.
+   */
+  _destroy(error, callback) {
+    this.#applicationEof = true
+    this.#closed = true
+    this.#relayWritable = false
+    this.connecting = false
+    this.pending = false
+    logDiagnostic(this.#options.logger, error === null ? "virtual_stream.closed" : "virtual_stream.error", error === null ? {} : errorDiagnostics(error))
+    if (this.#reconnectTimer !== undefined) {
+      this.#clearTimeout(this.#reconnectTimer)
+      this.#reconnectTimer = undefined
+    }
+    if (this.#timeoutTimer !== undefined) {
+      this.#clearTimeout(this.#timeoutTimer)
+      this.#timeoutTimer = undefined
+    }
+    const relaySocket = this.#relaySocket
+    this[kCloseSocketductSession]()
+      .then(() => {
+        if (this.#terminateRelayAttempt !== undefined) {
+          this.#terminateRelayAttempt({destroySocket: true, reconnect: false})
+        } else {
+          relaySocket?.destroy()
+        }
+        return this.#cleanupSpool()
+      })
+      .then(() => callback(error))
+      .catch((cleanupError) => {
+        callback(error ?? cleanupError)
+      })
+  }
+
+  /**
+   * @returns {Promise<void>} - Resolves after spool directory is removed.
+   */
+  async #cleanupSpool() {
+    if (this.#spoolCleanedUp) {
+      return
+    }
+    this.#spoolCleanedUp = true
+    await this.#spoolQueue
+    await this.#relayFrameQueue.catch(() => {})
+    const sessionId = this.#sessionId
+    if (sessionId === undefined) {
+      return
+    }
+    await this.#options.spool.remove(sessionId)
+  }
+
+  /** @returns {{ca?: Buffer, cert?: Buffer, key?: Buffer, servername?: string}} - Resolved TLS context. */
+  #resolveTlsContext() {
+    if (this.#tlsContext !== undefined) {
+      return /** @type {{ca?: Buffer, cert?: Buffer, key?: Buffer, servername?: string}} */ (this.#tlsContext)
+    }
+
+    const tls = /** @type {SocketductTlsOptions} */ (this.#options.tls)
+    /** @type {{ca?: Buffer, cert?: Buffer, key?: Buffer, servername?: string}} */
+    const context = {}
+
+    if (tls.servername !== undefined) {
+      context.servername = tls.servername
+    }
+
+    if (tls.caFile !== undefined) {
+      context.ca = readFileSync(tls.caFile)
+    }
+
+    if (tls.certFile !== undefined || tls.keyFile !== undefined) {
+      if (tls.certFile === undefined || tls.keyFile === undefined) {
+        throw new Error("TLS client certFile and keyFile must both be set (atomic pair)")
+      }
+      context.cert = readFileSync(tls.certFile)
+      context.key = readFileSync(tls.keyFile)
+    }
+
+    this.#tlsContext = context
+    return context
+  }
+
+  /** @returns {void} - Opens a relay connection. */
+  #connectRelay() {
+    if (!this.#mayConnectRelay()) {
+      return
+    }
+
+    this.#physicalAttempts += 1
+    const reconnect = this.#physicalAttempts > 1 || this.#sessionId !== undefined
+    logDiagnostic(this.#options.logger, "transport.connecting", {
+      generation: this.#generation,
+      attempt: this.#physicalAttempts,
+      reconnect
+    })
+
+    /** @type {import('node:net').Socket} */
+    let relaySocket
+
+    const tlsEnabled = this.#options.tls !== undefined
+    try {
+      if (tlsEnabled) {
+        const context = this.#resolveTlsContext()
+        relaySocket = this.#createRelaySocket({
+          host: this.#options.relayHost,
+          port: this.#options.relayPort,
+          tls: {
+            ...context,
+            rejectUnauthorized: this.#options.tls?.rejectUnauthorized !== false
+          }
+        })
+      } else {
+        relaySocket = this.#createRelaySocket({host: this.#options.relayHost, port: this.#options.relayPort})
+      }
+    } catch (error) {
+      logDiagnostic(this.#options.logger, "transport.failed", {
+        generation: this.#generation,
+        attempt: this.#physicalAttempts,
+        ...errorDiagnostics(error)
+      })
+      this.destroy(error instanceof Error ? error : new Error(String(error)))
+      return
+    }
+
+    this.#relaySocket = relaySocket
+    // Compression is negotiated per connection; assume raw until the relay agrees.
+    this.#codec = undefined
+    this.#framing = undefined
+    this.#compressor = undefined
+    const decoder = new FrameDecoder({compactDirection: "target-to-client"})
+    const readinessEvent = tlsEnabled ? "secureConnect" : "connect"
+    let attemptTerminated = false
+    /** @type {unknown} */
+    let connectTimer
+
+    const clearConnectTimer = () => {
+      if (connectTimer !== undefined) {
+        this.#clearTimeout(connectTimer)
+        connectTimer = undefined
+      }
+    }
+    const removeAttemptListeners = () => {
+      relaySocket.off(readinessEvent, onReady)
+      relaySocket.off("data", onData)
+      relaySocket.off("close", onClose)
+      relaySocket.off("error", onError)
+    }
+    const ignoreLateError = () => {}
+    /** @param {{destroySocket: boolean, reconnect: boolean, error?: unknown}} options */
+    const terminateAttempt = ({destroySocket, reconnect, error}) => {
+      if (attemptTerminated) {
+        return
+      }
+      attemptTerminated = true
+      clearConnectTimer()
+      removeAttemptListeners()
+      relaySocket.on("error", ignoreLateError)
+      if (this.#terminateRelayAttempt === terminateAttempt) {
+        this.#terminateRelayAttempt = undefined
+      }
+      if (this.#relaySocket === relaySocket) {
+        this.#relaySocket = undefined
+      }
+      if (this.#authenticatedRelaySocket === relaySocket) {
+        this.#authenticatedRelaySocket = undefined
+      }
+      if (this.#sessionCloseRelay === relaySocket) {
+        this.#sessionCloseRelay = undefined
+      }
+      this.#relayWritable = false
+      if (destroySocket && !relaySocket.destroyed) {
+        relaySocket.destroy()
+      }
+      if (reconnect && !this.#closed) {
+        logDiagnostic(this.#options.logger, "transport.disconnected", {
+          generation: this.#generation,
+          virtualStreams: this.destroyed ? 0 : 1,
+          ...errorDiagnostics(error, "TRANSPORT_CLOSED")
+        })
+      }
+      if (reconnect && this.#mayConnectRelay()) {
+        if (this.#needsRelayForClose()) {
+          this.#connectRelay()
+        } else {
+          this.#scheduleReconnect(error)
+        }
+      }
+    }
+    const onReady = () => {
+      if (attemptTerminated) {
+        return
+      }
+      clearConnectTimer()
+      relaySocket.off(readinessEvent, onReady)
+      this.localAddress = relaySocket.localAddress
+      this.localPort = relaySocket.localPort
+      const offer = this.#offeredCodecs()
+      const header = this.#sessionId === undefined
+        ? {
+          type: "session.create",
+          token: this.#options.token,
+          name: this.#options.sessionName,
+          target: this.#options.target,
+          ...(offer.length > 0 ? {compression: offer} : {}),
+          framing: [2]
+        }
+        : {
+          type: "session.resume",
+          token: this.#options.token,
+          identifier: this.#sessionId,
+          targetToClientAck: this.#targetReceivedSequence,
+          ...(offer.length > 0 ? {compression: offer} : {}),
+          framing: [2]
+        }
+      this.#writeFrameToRelay(relaySocket, header).catch((error) => this.destroy(error))
+    }
+    /** @param {Buffer} chunk */
+    const onData = (chunk) => {
+      if (attemptTerminated) {
+        return
+      }
+      let frames
+      try {
+        frames = decoder.push(chunk)
+      } catch {
+        relaySocket.destroy()
+        return
+      }
+
+      for (const frame of frames) {
+        this.#relayFrameQueue = this.#relayFrameQueue
+          .then(() => this.#handleRelayFrame(frame.header, frame.payload, frame.wireFormat, relaySocket))
+          .catch((error) => { this.destroy(error instanceof Error ? error : new Error(String(error))) })
+      }
+    }
+    const onClose = () => {
+      if (attemptTerminated) {
+        return
+      }
+      terminateAttempt({destroySocket: false, reconnect: true})
+    }
+    /** @param {Error} err */
+    const onError = (err) => {
+      if (attemptTerminated) {
+        return
+      }
+      if (isTlsVerificationError(err)) {
+        logDiagnostic(this.#options.logger, "transport.failed", {
+          generation: this.#generation,
+          attempt: this.#physicalAttempts,
+          ...errorDiagnostics(err)
+        })
+        terminateAttempt({destroySocket: true, reconnect: false, error: err})
+        this.destroy(err)
+        this.#settleSessionClose(false)
+        return
+      }
+      terminateAttempt({destroySocket: true, reconnect: true, error: err})
+    }
+
+    this.#terminateRelayAttempt = terminateAttempt
+    relaySocket.on(readinessEvent, onReady)
+    relaySocket.on("data", onData)
+    relaySocket.on("close", onClose)
+    relaySocket.on("error", onError)
+    connectTimer = this.#setTimeout(() => {
+      terminateAttempt({destroySocket: true, reconnect: true, error: Object.assign(new Error("Socketduct relay connection timed out"), {code: "ETIMEDOUT"})})
+    }, RELAY_CONNECT_TIMEOUT_MS)
+    if (connectTimer && typeof connectTimer === "object" && "unref" in connectTimer && typeof connectTimer.unref === "function") {
+      connectTimer.unref()
+    }
+  }
+
+  /**
+   * @param {import('../protocol/frame.js').FrameHeader} header - Frame header.
+   * @param {Buffer} payload - Frame payload.
+   * @param {"compact" | "envelope"} wireFormat - Decoder-proven wire format.
+   * @param {import('node:net').Socket} relaySocket - Relay socket that produced this frame.
+   * @returns {Promise<void>} - Resolves after handling.
+   */
+  async #handleRelayFrame(header, payload, wireFormat, relaySocket) {
+    const staleRelayFrame = this.#relaySocket !== relaySocket
+
+    if (staleRelayFrame) {
+      return
+    }
+
+    if (header.compact === true && this.#framing !== 2) {
+      throw new Error("Relay sent compact framing without negotiating version 2")
+    }
+
+    if (header.type === "session.created" || header.type === "session.resumed") {
+      if (header.framing !== 2) {
+        throw new Error("Relay did not select required framing version 2")
+      }
+      if (typeof header.identifier !== "string") {
+        throw new Error("Relay did not provide a session identifier")
+      }
+      const identifier = header.identifier
+      if (header.type === "session.created") {
+        this.#targetReceivedSequence = 0
+        await this.#options.spool.create({sessionId: identifier, ownerId: "edge"})
+      }
+      const selectedCodec = typeof header.compression === "string" ? header.compression : undefined
+      this.#codec = this.#offeredCodecs().includes(selectedCodec ?? "") ? selectedCodec : undefined
+      this.#framing = 2
+      this.#compressor = this.#codec === undefined ? undefined : new AdaptiveCompressor()
+      this.#sessionId = identifier
+      if (typeof header.serverLastAck === "number") {
+        this.#ackedSequence = Math.max(this.#ackedSequence, header.serverLastAck)
+        await this.#queueSpoolOperation(() => this.#options.spool.truncateAcked(identifier, this.#ackedSequence))
+      }
+      this.connecting = false
+      this.pending = false
+      this.#relayWritable = true
+      this.#authenticatedRelaySocket = relaySocket
+      this.#generation += 1
+      this.#physicalConnects += 1
+      const resumed = header.type === "session.resumed" || this.#physicalConnects > 1
+      logDiagnostic(this.#options.logger, "transport.connected", {
+        generation: this.#generation,
+        attempt: this.#physicalAttempts,
+        physicalConnects: this.#physicalConnects,
+        reconnect: resumed
+      })
+      if (resumed) {
+        logDiagnostic(this.#options.logger, "transport.reconnect_succeeded", {
+          generation: this.#generation,
+          attempt: this.#physicalAttempts,
+          physicalConnects: this.#physicalConnects
+        })
+      }
+      if (this.#needsRelayForClose()) {
+        this.#sendSessionClose(relaySocket)
+        return
+      }
+      await this.#queueSpoolOperation(() => this.#flushSpooledChunks(relaySocket))
+      if (this.#relaySocket !== relaySocket || relaySocket.destroyed) {
+        this.#relayWritable = false
+        return
+      }
+      if (!this.#connectEmitted) {
+        this.#connectEmitted = true
+        logDiagnostic(this.#options.logger, "virtual_stream.opened", {generation: this.#generation, recovered: false})
+        this.emit("connect")
+      }
+      this.emit("ready")
+      return
+    }
+
+    if (header.type === "error") {
+      const message = typeof header.message === "string" ? header.message : "Socketduct relay error"
+      const code = typeof header.code === "string" ? header.code : undefined
+      const retryable = typeof header.retryable === "boolean" ? header.retryable : undefined
+      this.destroy(new SocketductRelayError(message, {
+        ...(code === undefined ? {} : {code}),
+        ...(retryable === undefined ? {} : {retryable})
+      }))
+      return
+    }
+
+    if ((header.type === "stream.data" || header.type === "stream.ack") && wireFormat !== "compact") {
+      throw new Error(`Relay sent length-prefixed ${header.type} after framing version 2 was established`)
+    }
+
+    if (header.type === "stream.ack") {
+      if (typeof header.ackSequence === "number" && this.#sessionId !== undefined) {
+        this.#ackedSequence = Math.max(this.#ackedSequence, header.ackSequence)
+        await this.#queueSpoolOperation(() => this.#options.spool.truncateAcked(this.#sessionId ?? "", this.#ackedSequence))
+      }
+      return
+    }
+
+    if (header.type === "stream.data" && header.direction === "target-to-client") {
+      const sequence = header.sequence
+      if (typeof sequence !== "number" || !Number.isSafeInteger(sequence) || sequence <= 0) {
+        throw new Error("Relay sent stream.data without a valid sequence")
+      }
+
+      const data = await decodeStreamPayload(header, payload, this.#codec, this.#options.compressionLimits ?? {})
+
+      if (this.#applicationEof || this.destroyed) {
+        return
+      }
+
+      // Duplicate replay after a resume: already delivered, so drop it silently.
+      if (sequence <= this.#targetReceivedSequence) {
+        return
+      }
+
+      // Sequences are cumulative uncompressed byte offsets, so a contiguous frame
+      // ends exactly one payload past the last one. Fail closed on a gap or overlap
+      // rather than acknowledging bytes we never delivered.
+      const expectedSequence = this.#targetReceivedSequence + data.length
+      if (sequence !== expectedSequence) {
+        const detail = sequence < expectedSequence ? "overlap" : "gap"
+        throw new Error(`Relay stream.data sequence ${sequence} creates a ${detail} (expected contiguous offset ${expectedSequence})`)
+      }
+
+      this.#targetReceivedSequence = sequence
+      this.bytesRead += data.length
+      this.#resetTimeoutTimer()
+      if (!this.push(data)) {
+        relaySocket.pause()
+      }
+      await this.#writeFrameToRelay(relaySocket, {type: "stream.ack", direction: "target-to-client", ackSequence: sequence})
+      return
+    }
+
+    if (header.type === "session.close" && header.direction === "target-to-client") {
+      this.#relayWritable = false
+      // Settle after this queued frame handler releases #relayFrameQueue; destroy
+      // cleanup awaits that queue before removing the spool.
+      if (header.acknowledged === true) {
+        this.#sessionCloseAcknowledged = true
+        setImmediate(() => this.#settleSessionClose(true))
+      }
+      this.#endApplicationReadable()
+    }
+  }
+
+  /**
+   * @param {Buffer} chunk - App data chunk.
+   * @returns {Promise<void>} - Resolves after spooling.
+   */
+  async #handleAppData(chunk) {
+    if (!this.#connectStarted) {
+      this.connect()
+    }
+
+    if (this.#sessionId === undefined) {
+      await this.#waitForSession()
+    }
+
+    if (this.#closed || this.destroyed) {
+      return
+    }
+
+    if (this.#sessionId === undefined) {
+      throw new Error("Socketduct session is not available")
+    }
+
+    // Sequences, spool offsets and byte counters stay in uncompressed units, and
+    // the spool always stores raw chunks so a replay can be re-encoded later.
+    this.#sequence += chunk.length
+    this.bytesWritten += chunk.length
+    await this.#queueSpoolOperation(() => this.#options.spool.appendChunk({
+      sessionId: this.#sessionId ?? "",
+      ownerId: "edge",
+      sequence: this.#sequence,
+      data: chunk
+    }))
+
+    if (this.#relayWritable) {
+      const {header, payload} = await this.#buildStreamDataFrame(this.#sequence, chunk)
+      await this.#writeFrame(header, payload)
+    }
+  }
+
+  /** @returns {string[]} - Codecs this client offers, empty when compression is disabled or unsupported. */
+  #offeredCodecs() {
+    if (this.#options.compressionEnabled === false) {
+      return []
+    }
+    return availableCodecs()
+  }
+
+  /**
+   * @param {number} sequence - Uncompressed cumulative byte offset of this chunk.
+   * @param {Buffer} chunk - Raw payload bytes.
+   * @returns {Promise<{header: import('../protocol/frame.js').FrameHeader, payload: Buffer}>} - Frame to send.
+   */
+  async #buildStreamDataFrame(sequence, chunk) {
+    const encoded = await encodeStreamPayload(chunk, this.#codec, this.#compressor, this.#options.compressionLimits ?? {})
+    /** @type {import('../protocol/frame.js').FrameHeader} */
+    const header = {type: "stream.data", direction: "client-to-target", session: this.#sessionId, sequence}
+    if (encoded.encoding !== undefined) {
+      header.encoding = encoded.encoding
+      header.dataLength = encoded.dataLength
+    }
+    return {header, payload: encoded.payload}
+  }
+
+  /**
+   * @param {() => Promise<void>} operation - Spool operation to serialize.
+   * @returns {Promise<void>} - Resolves after the operation.
+   */
+  async #queueSpoolOperation(operation) {
+    const next = this.#spoolQueue.then(operation)
+    this.#spoolQueue = next.catch(() => {})
+    await next
+  }
+
+  /** @returns {Promise<void>} - Resolves when a session is available. */
+  async #waitForSession() {
+    while (!this.#closed && !this.destroyed && this.#sessionId === undefined) {
+      await new Promise((resolve) => { setTimeout(resolve, 5) })
+    }
+  }
+
+  /**
+   * @param {import('node:net').Socket} relaySocket - Authenticated relay socket that should receive replayed frames.
+   * @returns {Promise<void>} - Sends unacknowledged spool chunks.
+   */
+  async #flushSpooledChunks(relaySocket) {
+    if (this.#sessionId === undefined) {
+      return
+    }
+
+    let lastSentSequence = this.#ackedSequence
+    while (!this.#closed && !this.destroyed) {
+      const chunks = await this.#options.spool.readChunksAfter(this.#sessionId, lastSentSequence)
+      if (chunks.length === 0) {
+        return
+      }
+
+      for (const chunk of chunks) {
+        const {header, payload} = await this.#buildStreamDataFrame(chunk.sequence, chunk.data)
+        const sent = await this.#writeFrameToRelay(relaySocket, header, payload)
+        if (!sent) {
+          return
+        }
+        lastSentSequence = Math.max(lastSentSequence, chunk.sequence)
+      }
+    }
+  }
+
+  /**
+   * @param {import('node:net').Socket} relaySocket - Relay socket that should receive the frame.
+   * @param {import('../protocol/frame.js').FrameHeader} header - Frame header.
+   * @param {Buffer} [payload] - Frame payload.
+   * @returns {Promise<boolean>} - Resolves true when sent, false if the relay was interrupted.
+   */
+  async #writeFrameToRelay(relaySocket, header, payload = Buffer.alloc(0)) {
+    const operation = this.#sendQueue.then(() => this.#sendFrameToRelayNow(relaySocket, header, payload))
+    this.#sendQueue = operation.catch(() => {})
+    return operation
+  }
+
+  /**
+   * @param {import('../protocol/frame.js').FrameHeader} header - Frame header.
+   * @param {Buffer} [payload] - Frame payload.
+   * @returns {Promise<boolean>} - Resolves true when sent, false if the relay was interrupted.
+   */
+  async #writeFrame(header, payload = Buffer.alloc(0)) {
+    const relaySocket = this.#relaySocket
+    if (relaySocket === undefined) {
+      return false
+    }
+    return this.#writeFrameToRelay(relaySocket, header, payload)
+  }
+
+  /**
+   * @param {import('node:net').Socket} relaySocket - Relay socket that should receive the frame.
+   * @param {import('../protocol/frame.js').FrameHeader} header - Frame header.
+   * @param {Buffer} [payload] - Frame payload.
+   * @returns {Promise<boolean>} - Resolves true when sent, false if the relay was interrupted.
+   */
+  async #sendFrameToRelayNow(relaySocket, header, payload = Buffer.alloc(0)) {
+    if (this.#relaySocket !== relaySocket || relaySocket.destroyed) {
+      return false
+    }
+
+    let encodedFrame
+    if (this.#framing === 2 && header.type === "stream.data") {
+      encodedFrame = encodeCompactData({sequence: /** @type {number} */ (header.sequence), payload, ...(header.encoding === "zstd" ? {dataLength: /** @type {number} */ (header.dataLength)} : {})})
+    } else if (this.#framing === 2 && header.type === "stream.ack") {
+      encodedFrame = encodeCompactAck(/** @type {number} */ (header.ackSequence))
+    } else {
+      encodedFrame = encodeFrame(header, payload)
+    }
+    if (!relaySocket.write(encodedFrame)) {
+      return new Promise((resolve) => {
+        const onDrain = () => {
+          cleanup()
+          resolve(true)
+        }
+        const onClose = () => {
+          cleanup()
+          resolve(false)
+        }
+        const cleanup = () => {
+          relaySocket.off("drain", onDrain)
+          relaySocket.off("close", onClose)
+        }
+        relaySocket.once("drain", onDrain)
+        relaySocket.once("close", onClose)
+      })
+    }
+    return true
+  }
+
+  /**
+   * @param {unknown} [error] - Safe-to-classify reconnect cause.
+   * @returns {void} Schedules a reconnect.
+   */
+  #scheduleReconnect(error) {
+    if (!this.#mayConnectRelay() || this.#reconnectTimer) {
+      return
+    }
+    const delayMs = this.#options.reconnectDelayMs ?? 25
+    logDiagnostic(this.#options.logger, "transport.reconnect_scheduled", {
+      generation: this.#generation,
+      attempt: this.#physicalAttempts,
+      delayMs,
+      ...errorDiagnostics(error, "TRANSPORT_CLOSED")
+    })
+    this.#reconnectTimer = this.#setTimeout(() => {
+      this.#reconnectTimer = undefined
+      this.#connectRelay()
+    }, delayMs)
+  }
+}