socketduct 0.1.15

package/src/proxy/multiplexed-relay.js

@@ -0,0 +1,798 @@
+/* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-param-type, jsdoc/require-returns */
+import {readFileSync} from "node:fs"
+import {createConnection, createServer} from "node:net"
+import {createServer as createTlsServer} from "node:tls"
+
+import {decodeV3Control, encodeV3Control, encodeV3Frame, V3FrameDecoder, V3FrameType} from "../protocol/v3-frame.js"
+
+const DEFAULT_WINDOW = 256 * 1024
+const DEFAULT_FRAME_BYTES = 16 * 1024
+const DEFAULT_STREAM_BYTES = 4 * 1024 * 1024
+const DEFAULT_CONNECTION_BYTES = 32 * 1024 * 1024
+const DEFAULT_RESUME_MS = 60_000
+const DEFAULT_HANDSHAKE_MS = 10_000
+const DEFAULT_MAX_INPUT_BYTES = 64 * 1024
+const DEFAULT_TARGET_CONNECT_TIMEOUT_MS = 10_000
+const MANIFEST_PAGE_STREAMS = 64
+const MAX_CONTROL_QUEUE_BYTES = 1024 * 1024
+const STABLE_IDENTIFIER = /^[A-Za-z0-9_-]{8,128}$/
+
+/**
+ * @typedef {{userId: string, username: string}} Principal
+ * @typedef {{host: string, port: number}} Target
+ * @typedef {object} MultiplexedRelayOptions
+ * @property {string} [host] - Listen host, default loopback.
+ * @property {number} [port] - Listen port.
+ * @property {{authenticate: (token: string) => Principal | undefined}} tokens - Bearer authenticator.
+ * @property {(input: {principal: Principal, target: Target}) => boolean} authorizeTarget - Exact per-open target policy.
+ * @property {(target: Target) => import('node:net').Socket} [createTargetConnection] - Target socket factory.
+ * @property {{certFile: string, keyFile: string, clientCaFile?: string}} [tls] - Outer TLS server settings.
+ * @property {number} [initialWindowBytes] - Per-stream flow-control window.
+ * @property {number} [maxFrameBytes] - Maximum DATA payload.
+ * @property {number} [maxStreamBufferBytes] - Per-stream retained output bound.
+ * @property {number} [maxConnectionBufferBytes] - Aggregate retained output bound.
+ * @property {number} [maxTotalBufferBytes] - Process-wide retained output bound across connection identities.
+ * @property {number} [maxStreams] - Streams per physical connection identity.
+ * @property {number} [resumeWindowMs] - Detached target retention.
+ * @property {number} [handshakeTimeoutMs] - Authentication deadline.
+ * @property {number} [maxInputBytesPerConnection] - Cumulative raw pre-authentication input bound.
+ * @property {number} [targetConnectTimeoutMs] - Per-stream target-open deadline.
+ * @typedef {object} MultiplexedRelayStatus
+ * @property {number} physicalAccepts - Lifetime accepted WAN transports.
+ * @property {number} physicalConnections - Current physical WAN transports.
+ * @property {number} authenticatedConnections - Current authenticated transports.
+ * @property {number} connectionIdentities - Retained resumable connections.
+ * @property {number} connectionGeneration - Highest current generation.
+ * @property {number} virtualStreams - Current virtual streams.
+ * @property {number} activeTargets - Current local target sockets.
+ * @property {number} queuedBytes - Bounded retained target bytes.
+ * @property {number} bufferedBytes - Process-wide retained replay payload bytes.
+ * @property {number} bufferLimitBytes - Process-wide replay payload limit.
+ * @property {number} openFailures - Target-open failures.
+ * @property {number} resets - Total stream resets.
+ * @property {number} resumeSuccesses - Resumed streams.
+ * @property {number} resumeFailures - Stream-local resume failures.
+ * @property {number} streamOpenLatencyMs - Average target-open latency.
+ * @property {Record<string, number>} resetReasons - Stable reason counters.
+ * @typedef {{sequence: number, data: Buffer}} RelayChunk
+ * @typedef {{wire: Buffer, type: number, payloadBytes: number}} RelayQueuedFrame
+ * @typedef {object} RelayStream
+ * @property {number} id - Wire stream ID.
+ * @property {string} identifier - Stable stream identifier.
+ * @property {string} name - Human name.
+ * @property {Target} target - Authorized target.
+ * @property {import('node:net').Socket} targetSocket - Local target connection.
+ * @property {boolean} opened - Target ready.
+ * @property {boolean} localEnded - Client sent EOF.
+ * @property {boolean} remoteEnded - Target sent EOF.
+ * @property {boolean} lost - Target was lost while detached.
+ * @property {number} openStartedAt - Monotonic-enough target open start timestamp.
+ * @property {ReturnType<typeof setTimeout> | undefined} openTimer - Target-open deadline.
+ * @property {number} receiveSequence - Client bytes committed to target.
+ * @property {number} pendingReceiveSequence - Client bytes accepted for ordered target writes.
+ * @property {number} sendSequence - Target bytes allocated.
+ * @property {number} sendAck - Client target-data acknowledgement.
+ * @property {number} sendWindow - Available client receive window.
+ * @property {number} bufferedBytes - Retained target bytes.
+ * @property {RelayChunk[]} replay - Unacknowledged target bytes.
+ * @property {RelayQueuedFrame[]} queue - Fair scheduler queue.
+ * @typedef {object} RelayConnection
+ * @property {string} id - Stable client physical identity.
+ * @property {Principal} principal - Authenticated owner.
+ * @property {number} generation - Current generation.
+ * @property {import('node:net').Socket | undefined} physical - Current WAN transport.
+ * @property {Map<number, RelayStream>} streams - Virtual streams.
+ * @property {Set<number>} seenStreamIds - IDs that cannot be reused.
+ * @property {Buffer[]} controlQueue - Priority control frames.
+ * @property {number} controlQueuedBytes - Bounded priority-control bytes.
+ * @property {boolean} pumping - Scheduler state.
+ * @property {number} cursor - Scheduler cursor.
+ * @property {number} bufferedBytes - Aggregate replay bytes.
+ * @property {ReturnType<typeof setTimeout> | undefined} expiryTimer - Detached expiry.
+ * @property {number} resumeNextPage - Expected resume manifest page.
+ * @property {Array<Record<string, unknown>>} resumeItems - Accumulated bounded manifest.
+ * @property {boolean} resumeRequired - Whether OPEN/data must wait for a complete manifest.
+ */
+
+/**
+ * Starts a protocol-v3 relay endpoint. Protocol-v2 remains available through startTcpRelay.
+ * @param {MultiplexedRelayOptions} options - Auth, authorization, TLS and bounds.
+ * @returns {Promise<{server: import('node:net').Server | import('node:tls').Server, port: number, status: () => MultiplexedRelayStatus, closeActiveTransport: () => Promise<void>, close: () => Promise<void>}>} Relay handle.
+ */
+export async function startMultiplexedTcpRelay(options) {
+  validateOptions(options)
+  const initialWindow = options.initialWindowBytes ?? DEFAULT_WINDOW
+  const maxFrameBytes = Math.min(options.maxFrameBytes ?? DEFAULT_FRAME_BYTES, 64 * 1024)
+  const maxStreamBytes = options.maxStreamBufferBytes ?? DEFAULT_STREAM_BYTES
+  const maxConnectionBytes = options.maxConnectionBufferBytes ?? DEFAULT_CONNECTION_BYTES
+  const maxTotalBufferBytes = options.maxTotalBufferBytes ?? DEFAULT_CONNECTION_BYTES
+  const maxStreams = options.maxStreams ?? 4096
+  const resumeWindowMs = options.resumeWindowMs ?? DEFAULT_RESUME_MS
+  const maxInputBytesPerConnection = options.maxInputBytesPerConnection ?? DEFAULT_MAX_INPUT_BYTES
+  const createTarget = options.createTargetConnection ?? ((target) => createConnection(target))
+  /** @type {Map<string, RelayConnection>} */
+  const connections = new Map()
+  /** @type {Set<import('node:net').Socket>} */
+  const physicals = new Set()
+  let physicalAccepts = 0
+  let authenticatedConnections = 0
+  let activeTargets = 0
+  let openFailures = 0
+  let resets = 0
+  let resumeSuccesses = 0
+  let resumeFailures = 0
+  let streamOpenLatencyTotalMs = 0
+  let streamOpenLatencyCount = 0
+  let processBufferedBytes = 0
+  /** @type {Map<string, number>} */
+  const resetReasons = new Map()
+  let closing = false
+
+  const server = options.tls === undefined
+    ? createServer(acceptPhysical)
+    : createTlsServer({
+      cert: readFileSync(options.tls.certFile),
+      key: readFileSync(options.tls.keyFile),
+      ...(options.tls.clientCaFile === undefined ? {} : {ca: readFileSync(options.tls.clientCaFile)}),
+      requestCert: options.tls.clientCaFile !== undefined,
+      rejectUnauthorized: options.tls.clientCaFile !== undefined
+    }, acceptPhysical)
+
+  /** @param {import('node:net').Socket} socket - Accepted physical connection. @returns {void} */
+  function acceptPhysical(socket) {
+    physicalAccepts += 1
+    physicals.add(socket)
+    const decoderLimit = Math.max(64 * 1024, maxFrameBytes)
+    const decoder = new V3FrameDecoder({maxFrameBytes: decoderLimit, maxBufferedBytes: decoderLimit * 2})
+    /** @type {RelayConnection | undefined} */
+    let connection
+    let authenticated = false
+    let unauthenticatedInputBytes = 0
+    let queue = Promise.resolve()
+    const handshakeTimer = setTimeout(() => {
+      if (!authenticated) sendImmediate(socket, V3FrameType.AUTH_ERROR, 0, 0, {code: "HANDSHAKE_TIMEOUT"}).finally(() => socket.end())
+    }, options.handshakeTimeoutMs ?? DEFAULT_HANDSHAKE_MS)
+    handshakeTimer.unref?.()
+
+    socket.on("data", (chunk) => {
+      const inputLimitExceeded = !authenticated && (unauthenticatedInputBytes += chunk.length) > maxInputBytesPerConnection
+      queue = queue.then(async () => {
+        if (inputLimitExceeded) throw protocolError("INPUT_LIMIT_EXCEEDED")
+        const frames = decoder.push(chunk)
+        for (const frame of frames) {
+          if (!authenticated) {
+            if (frame.type !== V3FrameType.AUTH || frame.streamId !== 0) throw protocolError("AUTH_REQUIRED")
+            const auth = decodeV3Control(frame.payload)
+            if (!Array.isArray(auth.versions) || !auth.versions.includes(3) || typeof auth.connectionId !== "string" || !STABLE_IDENTIFIER.test(auth.connectionId) || typeof auth.generation !== "number" || !Number.isSafeInteger(auth.generation) || auth.generation <= 0) {
+              await sendImmediate(socket, V3FrameType.AUTH_ERROR, 0, 0, {code: "PROTOCOL_NEGOTIATION_FAILED"})
+              socket.end()
+              return
+            }
+            const principal = typeof auth.token === "string" ? options.tokens.authenticate(auth.token) : undefined
+            if (principal === undefined) {
+              await sendImmediate(socket, V3FrameType.AUTH_ERROR, 0, 0, {code: "AUTH_REQUIRED"})
+              socket.end()
+              return
+            }
+            const existing = connections.get(auth.connectionId)
+            if (existing !== undefined && existing.principal.userId !== principal.userId) {
+              await sendImmediate(socket, V3FrameType.AUTH_ERROR, 0, 0, {code: "AUTH_OWNERSHIP_MISMATCH"})
+              socket.end()
+              return
+            }
+            if (existing !== undefined && auth.generation <= existing.generation) {
+              await sendImmediate(socket, V3FrameType.AUTH_ERROR, 0, 0, {code: "STALE_GENERATION"})
+              socket.end()
+              return
+            }
+            connection = existing ?? {
+              id: auth.connectionId,
+              principal,
+              generation: 0,
+              physical: undefined,
+              streams: new Map(),
+              seenStreamIds: new Set(),
+              controlQueue: [],
+              controlQueuedBytes: 0,
+              pumping: false,
+              cursor: 0,
+              bufferedBytes: 0,
+              expiryTimer: undefined,
+              resumeNextPage: 0,
+              resumeItems: [],
+              resumeRequired: false
+            }
+            if (connection.expiryTimer !== undefined) clearTimeout(connection.expiryTimer)
+            connection.expiryTimer = undefined
+            connection.controlQueue = []
+            connection.controlQueuedBytes = 0
+            connection.cursor = 0
+            for (const stream of connection.streams.values()) stream.queue = []
+            connection.physical?.destroy()
+            connection.physical = socket
+            connection.generation = auth.generation
+            connection.resumeNextPage = 0
+            connection.resumeItems = []
+            connection.resumeRequired = existing !== undefined
+            connections.set(connection.id, connection)
+            authenticated = true
+            authenticatedConnections += 1
+            clearTimeout(handshakeTimer)
+            await sendImmediate(socket, V3FrameType.AUTH_OK, 0, connection.generation, {
+              version: 3,
+              connectionId: connection.id,
+              generation: connection.generation,
+              resumed: existing !== undefined,
+              initialWindow,
+              compression: null
+            })
+            continue
+          }
+          if (connection === undefined || connection.physical !== socket) continue
+          await handleFrame(connection, frame)
+        }
+      }).catch(async (error) => {
+        const code = /** @type {{code?: unknown}} */ (error).code
+        await sendImmediate(socket, V3FrameType.GOAWAY, 0, 0, {code: typeof code === "string" ? code : "PROTOCOL_VIOLATION"}).catch(() => {})
+        socket.destroy()
+      })
+    })
+    socket.on("error", () => {})
+    socket.once("close", () => {
+      clearTimeout(handshakeTimer)
+      physicals.delete(socket)
+      if (authenticated) authenticatedConnections = Math.max(0, authenticatedConnections - 1)
+      void queue.finally(() => {
+        if (connection === undefined || connection.physical !== socket || closing) return
+        connection.physical = undefined
+        connection.controlQueue = []
+        connection.controlQueuedBytes = 0
+        for (const stream of connection.streams.values()) stream.queue = []
+        const detachedConnection = connection
+        detachedConnection.expiryTimer = setTimeout(() => destroyConnection(detachedConnection), resumeWindowMs)
+        detachedConnection.expiryTimer.unref?.()
+      })
+    })
+  }
+
+  /**
+   * @param {RelayConnection} connection - Authenticated connection. @param {import('../protocol/v3-frame.js').V3Frame} frame - Frame. @returns {Promise<void>}
+   * @param frame
+   */
+  async function handleFrame(connection, frame) {
+    if (frame.type === V3FrameType.PING) {
+      queueControl(connection, V3FrameType.PONG, 0, frame.sequence, {})
+      return
+    }
+    if (frame.type === V3FrameType.PONG) return
+    if (frame.type === V3FrameType.GOAWAY) {
+      destroyConnection(connection)
+      connection.physical?.end()
+      return
+    }
+    if (connection.resumeRequired && frame.type !== V3FrameType.RESUME) throw protocolError("RESUME_REQUIRED")
+    if (frame.type === V3FrameType.RESUME) {
+      const manifest = decodeV3Control(frame.payload)
+      if (manifest.page !== connection.resumeNextPage || !Array.isArray(manifest.streams) || manifest.streams.length > MANIFEST_PAGE_STREAMS || connection.resumeItems.length + manifest.streams.length > maxStreams) throw protocolError("INVALID_RESUME_MANIFEST")
+      connection.resumeNextPage += 1
+      connection.resumeItems.push(...manifest.streams.filter((item) => typeof item === "object" && item !== null))
+      if (manifest.final !== true) return
+      const presented = new Set()
+      /** @type {Array<Record<string, unknown>>} */
+      const results = []
+      for (const value of connection.resumeItems) {
+        if (typeof value !== "object" || value === null) continue
+        const item = /** @type {{streamId?: unknown, identifier?: unknown, clientToTargetAck?: unknown, targetToClientAck?: unknown, localEnded?: unknown}} */ (value)
+        if (typeof item.streamId !== "number" || typeof item.identifier !== "string") continue
+        if (presented.has(item.streamId)) throw protocolError("DUPLICATE_RESUME_STREAM")
+        presented.add(item.streamId)
+        const stream = connection.streams.get(item.streamId)
+        if (stream === undefined || stream.identifier !== item.identifier || stream.lost || stream.targetSocket.destroyed) {
+          results.push({streamId: item.streamId, status: "reset", code: "RESUME_SESSION_LOST"})
+          resumeFailures += 1
+          if (stream !== undefined) destroyStream(connection, stream)
+          continue
+        }
+        if (typeof item.targetToClientAck === "number") acknowledgeTarget(connection, stream, item.targetToClientAck)
+        results.push({
+          streamId: stream.id,
+          status: "resumed",
+          clientToTargetAck: stream.receiveSequence,
+          targetToClientAck: stream.sendAck,
+          opened: stream.opened
+        })
+        if (item.localEnded === true && !stream.localEnded) {
+          stream.localEnded = true
+          stream.targetSocket.end()
+        }
+        resumeSuccesses += 1
+      }
+      for (const stream of [...connection.streams.values()]) {
+        if (!presented.has(stream.id)) destroyStream(connection, stream)
+      }
+      const pageCount = Math.max(1, Math.ceil(results.length / MANIFEST_PAGE_STREAMS))
+      for (let page = 0; page < pageCount; page += 1) {
+        queueControl(connection, V3FrameType.RESUMED, 0, connection.generation, {
+          page,
+          final: page === pageCount - 1,
+          streams: results.slice(page * MANIFEST_PAGE_STREAMS, (page + 1) * MANIFEST_PAGE_STREAMS)
+        })
+      }
+      connection.resumeItems = []
+      connection.resumeRequired = false
+      connection.cursor = 0
+      for (const stream of connection.streams.values()) {
+        stream.queue = stream.queue.filter((entry) => entry.type !== V3FrameType.DATA)
+        // Credit belongs to the replaced physical generation. The resume ACKs
+        // above establish the durable replay boundary for a fresh full window.
+        stream.sendWindow = initialWindow
+        for (const chunk of stream.replay) if (chunk.sequence > stream.sendAck) queueData(connection, stream, chunk)
+      }
+      return
+    }
+    if (frame.type === V3FrameType.OPEN) {
+      if (connection.seenStreamIds.has(frame.streamId) || connection.streams.size >= maxStreams || frame.streamId % 2 === 0) throw protocolError("INVALID_STREAM_ID")
+      connection.seenStreamIds.add(frame.streamId)
+      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 || typeof request.initialWindow !== "number" || !Number.isSafeInteger(request.initialWindow) || request.initialWindow <= 0) {
+        queueControl(connection, V3FrameType.RESET, frame.streamId, 0, {code: "INVALID_STREAM_OPEN"})
+        return
+      }
+      if (options.authorizeTarget({principal: connection.principal, target}) !== true) {
+        queueControl(connection, V3FrameType.RESET, frame.streamId, 0, {code: "TARGET_UNAUTHORIZED"})
+        recordReset("TARGET_UNAUTHORIZED")
+        return
+      }
+      const targetSocket = createTarget(target)
+      const stream = /** @type {RelayStream} */ ({
+        id: frame.streamId,
+        identifier: request.identifier,
+        name: request.name,
+        target,
+        targetSocket,
+        opened: false,
+        localEnded: false,
+        remoteEnded: false,
+        lost: false,
+        openStartedAt: Date.now(),
+        openTimer: undefined,
+        receiveSequence: 0,
+        pendingReceiveSequence: 0,
+        sendSequence: 0,
+        sendAck: 0,
+        sendWindow: typeof request.initialWindow === "number" ? Math.min(request.initialWindow, initialWindow) : initialWindow,
+        bufferedBytes: 0,
+        replay: [],
+        queue: []
+      })
+      connection.streams.set(stream.id, stream)
+      attachTarget(connection, stream)
+      return
+    }
+    const stream = connection.streams.get(frame.streamId)
+    if (stream === undefined) {
+      if (frame.type !== V3FrameType.RESET && frame.type !== V3FrameType.CLOSE) queueControl(connection, V3FrameType.RESET, frame.streamId, 0, {code: "UNKNOWN_STREAM"})
+      return
+    }
+    if (!stream.opened && frame.type !== V3FrameType.RESET) throw protocolError("STREAM_NOT_OPEN")
+    if (frame.type === V3FrameType.DATA) {
+      if (frame.flags !== 0) throw protocolError("COMPRESSION_NOT_NEGOTIATED")
+      if (frame.payload.length > maxFrameBytes) throw protocolError("FRAME_TOO_LARGE")
+      if (frame.sequence <= stream.receiveSequence) {
+        queueControl(connection, V3FrameType.ACK, stream.id, stream.receiveSequence, {})
+        return
+      }
+      if (frame.sequence <= stream.pendingReceiveSequence) return
+      if (frame.sequence !== stream.pendingReceiveSequence + frame.payload.length) {
+        resetStream(connection, stream, "SEQUENCE_GAP")
+        return
+      }
+      const committedSequence = frame.sequence
+      const receivedGeneration = connection.generation
+      stream.pendingReceiveSequence = committedSequence
+      if (stream.pendingReceiveSequence - stream.receiveSequence > initialWindow) {
+        resetStream(connection, stream, "FLOW_CONTROL_ERROR")
+        return
+      }
+      stream.targetSocket.write(frame.payload, (error) => {
+        if (error || stream.targetSocket.destroyed) {
+          resetStream(connection, stream, "TARGET_WRITE_UNCERTAIN")
+          return
+        }
+        stream.receiveSequence = Math.max(stream.receiveSequence, committedSequence)
+        if (connection.generation === receivedGeneration && connection.physical !== undefined && !connection.resumeRequired) queueControl(connection, V3FrameType.ACK, stream.id, committedSequence, {})
+      })
+      return
+    }
+    if (frame.type === V3FrameType.ACK) {
+      acknowledgeTarget(connection, stream, frame.sequence)
+      return
+    }
+    if (frame.type === V3FrameType.WINDOW) {
+      if (frame.sequence > initialWindow) throw protocolError("INVALID_WINDOW")
+      stream.sendWindow = Math.min(initialWindow, stream.sendWindow + frame.sequence)
+      schedulePump(connection)
+      return
+    }
+    if (frame.type === V3FrameType.END) {
+      if (!stream.localEnded) {
+        stream.localEnded = true
+        stream.targetSocket.end()
+      }
+      return
+    }
+    if (frame.type === V3FrameType.RESET || frame.type === V3FrameType.CLOSE) {
+      destroyStream(connection, stream)
+      return
+    }
+    throw protocolError("UNSUPPORTED_FRAME")
+  }
+
+  /**
+   * @param {RelayConnection} connection - Owner. @param {RelayStream} stream - Stream. @returns {void}
+   * @param stream
+   */
+  function attachTarget(connection, stream) {
+    let connected = false
+    stream.openTimer = setTimeout(() => {
+      if (connected || !connection.streams.has(stream.id)) return
+      openFailures += 1
+      resetStream(connection, stream, "TARGET_OPEN_TIMEOUT")
+    }, options.targetConnectTimeoutMs ?? DEFAULT_TARGET_CONNECT_TIMEOUT_MS)
+    stream.openTimer.unref?.()
+    stream.targetSocket.once("connect", () => {
+      connected = true
+      if (stream.openTimer !== undefined) clearTimeout(stream.openTimer)
+      stream.openTimer = undefined
+      stream.opened = true
+      activeTargets += 1
+      streamOpenLatencyTotalMs += Math.max(0, Date.now() - stream.openStartedAt)
+      streamOpenLatencyCount += 1
+      queueControl(connection, V3FrameType.OPENED, stream.id, 0, {identifier: stream.identifier, initialWindow})
+    })
+    stream.targetSocket.on("data", (chunk) => {
+      if (!stream.opened || stream.lost) return
+      if (processBufferedBytes + chunk.length > maxTotalBufferBytes) {
+        resetStream(connection, stream, "PROCESS_BUFFER_LIMIT")
+        return
+      }
+      if (stream.bufferedBytes + chunk.length > maxStreamBytes || connection.bufferedBytes + chunk.length > maxConnectionBytes) {
+        resetStream(connection, stream, "BUFFER_LIMIT")
+        return
+      }
+      for (let offset = 0; offset < chunk.length; offset += maxFrameBytes) {
+        const data = Buffer.from(chunk.subarray(offset, Math.min(chunk.length, offset + maxFrameBytes)))
+        stream.sendSequence += data.length
+        const replay = {sequence: stream.sendSequence, data}
+        stream.replay.push(replay)
+        stream.bufferedBytes += data.length
+        connection.bufferedBytes += data.length
+        processBufferedBytes += data.length
+        queueData(connection, stream, replay)
+      }
+      if (stream.bufferedBytes >= maxStreamBytes || connection.bufferedBytes >= maxConnectionBytes || processBufferedBytes >= maxTotalBufferBytes || stream.sendWindow === 0) stream.targetSocket.pause()
+    })
+    stream.targetSocket.once("end", () => {
+      stream.remoteEnded = true
+      if (connection.physical !== undefined) queueStream(connection, stream, V3FrameType.END, stream.sendSequence)
+    })
+    stream.targetSocket.once("error", () => {
+      if (stream.openTimer !== undefined) clearTimeout(stream.openTimer)
+      stream.openTimer = undefined
+      if (!connected) {
+        if (connection.streams.has(stream.id)) {
+          openFailures += 1
+          resetStream(connection, stream, "TARGET_OPEN_FAILED")
+        }
+      } else if (connection.physical === undefined) {
+        stream.lost = true
+      } else {
+        resetStream(connection, stream, "TARGET_CLOSED")
+      }
+    })
+    stream.targetSocket.once("close", () => {
+      if (connected) activeTargets = Math.max(0, activeTargets - 1)
+      if (!connection.streams.has(stream.id)) return
+      if (connection.physical === undefined) {
+        stream.lost = true
+        return
+      }
+      stream.remoteEnded = true
+      queueStream(connection, stream, V3FrameType.CLOSE, stream.sendSequence)
+    })
+  }
+
+  /**
+   * @param {RelayConnection} connection - Owner. @param {RelayStream} stream - Stream. @param {RelayChunk} chunk - Chunk. @returns {void}
+   * @param stream
+   * @param chunk
+   */
+  function queueData(connection, stream, chunk) {
+    stream.queue.push({
+      wire: encodeV3Frame({type: V3FrameType.DATA, streamId: stream.id, sequence: chunk.sequence}, chunk.data),
+      type: V3FrameType.DATA,
+      payloadBytes: chunk.data.length
+    })
+    schedulePump(connection)
+  }
+
+  /**
+   * @param {RelayConnection} connection - Owner. @param {RelayStream} stream - Stream. @param {number} type - Type. @param {number} sequence - Sequence. @returns {void}
+   * @param stream
+   * @param type
+   * @param sequence
+   */
+  function queueStream(connection, stream, type, sequence) {
+    stream.queue.push({wire: encodeV3Frame({type, streamId: stream.id, sequence}), type, payloadBytes: 0})
+    schedulePump(connection)
+  }
+
+  /**
+   * @param {RelayConnection} connection - Owner. @param {number} type - Type. @param {number} streamId - Stream. @param {number} sequence - Sequence. @param {Record<string, unknown>} detail - Body. @returns {void}
+   * @param type
+   * @param streamId
+   * @param sequence
+   * @param detail
+   */
+  function queueControl(connection, type, streamId, sequence, detail) {
+    const wire = encodeV3Frame({type, streamId, sequence}, encodeV3Control(detail))
+    if (connection.controlQueuedBytes + wire.length > MAX_CONTROL_QUEUE_BYTES) {
+      destroyConnection(connection)
+      return
+    }
+    connection.controlQueue.push(wire)
+    connection.controlQueuedBytes += wire.length
+    schedulePump(connection)
+  }
+
+  /** @param {RelayConnection} connection - Owner. @returns {void} */
+  function schedulePump(connection) {
+    if (connection.pumping || connection.physical === undefined || connection.physical.destroyed) return
+    connection.pumping = true
+    setImmediate(() => void pump(connection))
+  }
+
+  /** @param {RelayConnection} connection - Owner. @returns {Promise<void>} */
+  async function pump(connection) {
+    const ownerPhysical = connection.physical
+    try {
+      while (ownerPhysical !== undefined && connection.physical === ownerPhysical && !ownerPhysical.destroyed) {
+        const physical = ownerPhysical
+        const control = connection.controlQueue.shift()
+        if (control !== undefined) {
+          connection.controlQueuedBytes = Math.max(0, connection.controlQueuedBytes - control.length)
+          if (!await writePhysical(physical, control)) break
+          continue
+        }
+        if (connection.resumeRequired) break
+        const streams = [...connection.streams.values()]
+        let selected
+        for (let index = 0; index < streams.length; index += 1) {
+          const cursor = (connection.cursor + index) % streams.length
+          const stream = /** @type {RelayStream} */ (streams[cursor])
+          const frame = stream.queue[0]
+          if (frame !== undefined && (frame.type !== V3FrameType.DATA || frame.payloadBytes <= stream.sendWindow)) {
+            selected = {stream, frame, next: (cursor + 1) % streams.length}
+            break
+          }
+        }
+        if (selected === undefined) break
+        selected.stream.queue.shift()
+        connection.cursor = selected.next
+        if (selected.frame.type === V3FrameType.DATA) selected.stream.sendWindow -= selected.frame.payloadBytes
+        if (!await writePhysical(physical, selected.frame.wire)) break
+        await new Promise((resolve) => setImmediate(resolve))
+      }
+    } finally {
+      connection.pumping = false
+      if (connection.controlQueue.length > 0 || (!connection.resumeRequired && [...connection.streams.values()].some((stream) => {
+        const frame = stream.queue[0]
+        return frame !== undefined && (frame.type !== V3FrameType.DATA || frame.payloadBytes <= stream.sendWindow)
+      }))) schedulePump(connection)
+    }
+  }
+
+  /**
+   * @param {RelayConnection} connection - Owner. @param {RelayStream} stream - Stream. @param {number} sequence - Ack. @returns {void}
+   * @param stream
+   * @param sequence
+   */
+  function acknowledgeTarget(connection, stream, sequence) {
+    if (!Number.isSafeInteger(sequence) || sequence < stream.sendAck || sequence > stream.sendSequence) throw protocolError("INVALID_ACK")
+    if (sequence === stream.sendAck) return
+    const oldAck = stream.sendAck
+    stream.sendAck = sequence
+    let removed = 0
+    stream.replay = stream.replay.filter((chunk) => {
+      if (chunk.sequence <= sequence) {
+        removed += chunk.data.length
+        return false
+      }
+      return true
+    })
+    releaseBuffered(connection, stream, removed)
+    stream.sendWindow = Math.min(initialWindow, stream.sendWindow + (sequence - oldAck))
+    resumeEligibleTargets()
+    schedulePump(connection)
+  }
+
+  /**
+   * Releases a retained-payload reservation exactly once at all ownership levels.
+   * @param {RelayConnection} connection - Connection owner.
+   * @param {RelayStream} stream - Stream owner.
+   * @param {number} requestedBytes - Bytes no longer retained.
+   * @returns {void}
+   */
+  function releaseBuffered(connection, stream, requestedBytes) {
+    const released = Math.min(Math.max(0, requestedBytes), stream.bufferedBytes)
+    stream.bufferedBytes -= released
+    connection.bufferedBytes = Math.max(0, connection.bufferedBytes - released)
+    processBufferedBytes = Math.max(0, processBufferedBytes - released)
+  }
+
+  /** @returns {void} Resumes targets made eligible by any process-wide release. */
+  function resumeEligibleTargets() {
+    if (processBufferedBytes >= maxTotalBufferBytes) return
+    for (const owner of connections.values()) {
+      if (owner.bufferedBytes >= maxConnectionBytes) continue
+      for (const candidate of owner.streams.values()) {
+        if (candidate.targetSocket.isPaused() && candidate.bufferedBytes < maxStreamBytes && candidate.sendWindow > 0) candidate.targetSocket.resume()
+      }
+    }
+  }
+
+  /**
+   * @param {RelayConnection} connection - Owner. @param {RelayStream} stream - Stream. @param {string} code - Safe reset code. @returns {void}
+   * @param stream
+   * @param code
+   */
+  function resetStream(connection, stream, code) {
+    if (!connection.streams.has(stream.id)) return
+    recordReset(code)
+    queueControl(connection, V3FrameType.RESET, stream.id, 0, {code})
+    destroyStream(connection, stream, true)
+  }
+
+  /**
+   * @param {RelayConnection} connection - Owner. @param {RelayStream} stream - Stream. @param {boolean} [keepQueuedReset] - Preserve connection control reset. @returns {void}
+   * @param stream
+   * @param keepQueuedReset
+   */
+  function destroyStream(connection, stream, keepQueuedReset = false) {
+    connection.streams.delete(stream.id)
+    releaseBuffered(connection, stream, stream.bufferedBytes)
+    stream.replay = []
+    stream.queue = []
+    if (stream.openTimer !== undefined) clearTimeout(stream.openTimer)
+    stream.openTimer = undefined
+    stream.targetSocket.destroy()
+    resumeEligibleTargets()
+    if (!keepQueuedReset) schedulePump(connection)
+  }
+
+  /** @param {RelayConnection} connection - Connection. @returns {void} */
+  function destroyConnection(connection) {
+    if (connection.expiryTimer !== undefined) clearTimeout(connection.expiryTimer)
+    connection.expiryTimer = undefined
+    if (connections.get(connection.id) === connection) connections.delete(connection.id)
+    for (const stream of [...connection.streams.values()]) destroyStream(connection, stream)
+    connection.physical?.destroy()
+    connection.physical = undefined
+  }
+
+  /** @param {string} reason - Privacy-safe stable reset reason. @returns {void} */
+  function recordReset(reason) {
+    resets += 1
+    resetReasons.set(reason, (resetReasons.get(reason) ?? 0) + 1)
+  }
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject)
+    server.listen(options.port ?? 0, options.host ?? "127.0.0.1", () => {
+      server.off("error", reject)
+      resolve(undefined)
+    })
+  })
+  const address = server.address()
+  if (address === null || typeof address === "string") throw new Error("Multiplexed relay did not bind to a TCP port")
+
+  return {
+    server,
+    port: address.port,
+    status: () => ({
+      physicalAccepts,
+      physicalConnections: physicals.size,
+      authenticatedConnections,
+      connectionIdentities: connections.size,
+      connectionGeneration: Math.max(0, ...[...connections.values()].map((connection) => connection.generation)),
+      virtualStreams: [...connections.values()].reduce((sum, connection) => sum + connection.streams.size, 0),
+      activeTargets,
+      queuedBytes: processBufferedBytes + [...connections.values()].reduce((sum, connection) => sum + connection.controlQueuedBytes, 0),
+      bufferedBytes: processBufferedBytes,
+      bufferLimitBytes: maxTotalBufferBytes,
+      openFailures,
+      resets,
+      resumeSuccesses,
+      resumeFailures,
+      streamOpenLatencyMs: streamOpenLatencyCount === 0 ? 0 : Math.round(streamOpenLatencyTotalMs / streamOpenLatencyCount),
+      resetReasons: Object.fromEntries(resetReasons)
+    }),
+    closeActiveTransport: async () => {
+      await Promise.all([...physicals].map((socket) => new Promise((resolve) => {
+        if (socket.destroyed) { resolve(undefined); return }
+        socket.once("close", () => resolve(undefined))
+        socket.destroy()
+      })))
+    },
+    close: async () => {
+      closing = true
+      for (const connection of [...connections.values()]) destroyConnection(connection)
+      for (const socket of physicals) socket.destroy()
+      await new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve(undefined)))
+    }
+  }
+}
+
+/** @param {MultiplexedRelayOptions} options - Options. @returns {void} */
+function validateOptions(options) {
+  if (options?.tokens === undefined || typeof options.tokens.authenticate !== "function" || typeof options.authorizeTarget !== "function") throw new TypeError("V3 relay requires tokens and authorizeTarget")
+  for (const [name, value] of Object.entries({
+    initialWindowBytes: options.initialWindowBytes,
+    maxFrameBytes: options.maxFrameBytes,
+    maxStreamBufferBytes: options.maxStreamBufferBytes,
+    maxConnectionBufferBytes: options.maxConnectionBufferBytes,
+    maxTotalBufferBytes: options.maxTotalBufferBytes,
+    maxStreams: options.maxStreams,
+    resumeWindowMs: options.resumeWindowMs,
+    handshakeTimeoutMs: options.handshakeTimeoutMs,
+    maxInputBytesPerConnection: options.maxInputBytesPerConnection,
+    targetConnectTimeoutMs: options.targetConnectTimeoutMs
+  })) {
+    if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0)) throw new RangeError(`${name} must be a positive integer`)
+  }
+  if ((options.maxFrameBytes ?? DEFAULT_FRAME_BYTES) > (options.initialWindowBytes ?? DEFAULT_WINDOW)) throw new RangeError("maxFrameBytes must not exceed initialWindowBytes")
+  if ((options.initialWindowBytes ?? DEFAULT_WINDOW) > (options.maxStreamBufferBytes ?? DEFAULT_STREAM_BYTES)) throw new RangeError("initialWindowBytes must not exceed maxStreamBufferBytes")
+}
+
+/** @param {unknown} value - Target. @returns {Target | undefined} */
+function parseTarget(value) {
+  if (typeof value !== "object" || value === null) return undefined
+  const target = /** @type {{host?: unknown, port?: unknown}} */ (value)
+  if (typeof target.host !== "string" || target.host.length === 0 || target.host.length > 253 || typeof target.port !== "number" || !Number.isInteger(target.port) || target.port < 1 || target.port > 65_535) return undefined
+  return {host: target.host, port: target.port}
+}
+
+/**
+ * @param {import('node:net').Socket} socket - Socket. @param {number} type - Type. @param {number} streamId - Stream. @param {number} sequence - Sequence. @param {Record<string, unknown>} body - Control body. @returns {Promise<boolean>}
+ * @param type
+ * @param streamId
+ * @param sequence
+ * @param body
+ */
+async function sendImmediate(socket, type, streamId, sequence, body) {
+  return await writePhysical(socket, encodeV3Frame({type, streamId, sequence}, encodeV3Control(body)))
+}
+
+/**
+ * @param {import('node:net').Socket} socket - Socket. @param {Buffer} bytes - Frame. @returns {Promise<boolean>}
+ * @param bytes
+ */
+async function writePhysical(socket, bytes) {
+  if (socket.destroyed || !socket.writable) return false
+  if (socket.write(bytes)) return true
+  return await new Promise((resolve) => {
+    const cleanup = () => { socket.off("drain", onDrain); socket.off("close", onClose) }
+    const onDrain = () => { cleanup(); resolve(true) }
+    const onClose = () => { cleanup(); resolve(false) }
+    socket.once("drain", onDrain)
+    socket.once("close", onClose)
+  })
+}
+
+/** @param {string} code - Stable code. @returns {Error & {code: string}} */
+function protocolError(code) {
+  const error = /** @type {Error & {code: string}} */ (new Error("Socketduct v3 protocol violation"))
+  error.code = code
+  return error
+}