socketduct 0.1.15

package/test/integration/stream-compression.test.js

@@ -0,0 +1,1267 @@
+import assert from "node:assert/strict"
+import {randomBytes} from "node:crypto"
+import {mkdtemp, rm} from "node:fs/promises"
+import {createConnection, createServer} from "node:net"
+import {tmpdir} from "node:os"
+import {join} from "node:path"
+import test from "node:test"
+import zlib from "node:zlib"
+
+import {InMemoryUserStore, login, TokenStore} from "../../src/auth/user-store.js"
+import {connectSocketduct} from "../../src/client/socketduct-socket.js"
+import {decodeStreamPayload, encodeStreamPayload, zstdAvailable} from "../../src/protocol/compression.js"
+import {encodeCompactAck, encodeCompactData, encodeFrame as encodeEnvelope, FrameDecoder} from "../../src/protocol/frame.js"
+import {startTcpRelay} from "../../src/proxy/tcp-relay.js"
+import {SessionStore} from "../../src/sessions/session.js"
+
+/**
+ * Encode the V2 wire format used after session negotiation.
+ * @param {import('../../src/protocol/frame.js').FrameHeader} header - Frame metadata.
+ * @param {Buffer} [payload] - Frame payload.
+ * @returns {Buffer} Encoded wire bytes.
+ */
+function encodeFrame(header, payload = Buffer.alloc(0)) {
+  if (header.type === "stream.data") {
+    return encodeCompactData({
+      sequence: /** @type {number} */ (header.sequence),
+      payload,
+      ...(header.encoding === "zstd" ? {dataLength: /** @type {number} */ (header.dataLength)} : {})
+    })
+  }
+  if (header.type === "stream.ack") {
+    return encodeCompactAck(/** @type {number} */ (header.ackSequence))
+  }
+  const framedHeader = header.type === "session.create" || header.type === "session.resume"
+    ? {...header, framing: header.framing ?? [2]}
+    : header
+  return encodeEnvelope(framedHeader, payload)
+}
+
+/**
+ * @param {import('node:net').Server} server - Server to bind.
+ * @returns {Promise<number>} - Bound port.
+ */
+async function listen(server) {
+  await new Promise((resolve, reject) => {
+    server.once("error", reject)
+    server.listen(0, "127.0.0.1", () => {
+      server.off("error", reject)
+      resolve(undefined)
+    })
+  })
+  const address = server.address()
+  if (address === null || typeof address === "string") {
+    throw new Error("Server did not bind to a TCP port")
+  }
+  return /** @type {import('node:net').AddressInfo} */ (address).port
+}
+
+/**
+ * @param {number} size - Requested size in bytes.
+ * @returns {Buffer} - Highly compressible text payload.
+ */
+function compressibleChunk(size) {
+  const unit = "GET /api/v1/users?page=2 HTTP/1.1\r\nHost: example.com\r\nAccept: application/json\r\n\r\n"
+  return Buffer.from(unit.repeat(Math.ceil(size / unit.length))).subarray(0, size)
+}
+
+/**
+ * Accumulates stream data behind a single listener, so waiting for more bytes
+ * never stacks duplicate handlers.
+ * @param {import('node:stream').Readable} stream - Stream to collect.
+ * @returns {{bytes: () => Buffer, total: () => number, waitFor: (need: number) => Promise<void>}} - Collector.
+ */
+function collect(stream) {
+  /** @type {Buffer[]} */
+  const chunks = []
+  let total = 0
+  /** @type {{need: number, resolve: () => void} | undefined} */
+  let waiter
+
+  stream.on("data", (chunk) => {
+    chunks.push(chunk)
+    total += chunk.length
+    if (waiter !== undefined && total >= waiter.need) {
+      const pending = waiter
+      waiter = undefined
+      pending.resolve()
+    }
+  })
+
+  return {
+    bytes: () => Buffer.concat(chunks),
+    total: () => total,
+    waitFor: async (need) => {
+      if (total >= need) {
+        return
+      }
+      await new Promise((resolve) => {
+        waiter = {need, resolve: () => resolve(undefined)}
+      })
+    }
+  }
+}
+
+/**
+ * A relay plus an echo target that records everything it receives, wired to one
+ * authenticated token.
+ * @param {{compressionEnabled?: boolean}} [options] - Relay compression options.
+ * @returns {Promise<{relay: import('../../src/proxy/tcp-relay.js').TcpRelayHandle, relayPort: number, targetPort: number, token: string, targetReceived: () => number, close: () => Promise<void>}>} - Started fixture.
+ */
+async function startFixture(options = {}) {
+  let targetReceived = 0
+  const echoServer = createServer((socket) => {
+    socket.on("data", (chunk) => {
+      targetReceived += chunk.length
+      socket.write(chunk)
+    })
+  })
+  const targetPort = await listen(echoServer)
+
+  const users = new InMemoryUserStore()
+  const tokens = new TokenStore({now: () => 1000, tokenTtlMs: 60_000})
+  await users.createUser({username: "kasper", password: "correct horse battery staple"})
+  const token = await login(users, tokens, {username: "kasper", password: "correct horse battery staple"})
+
+  /** @type {import('../../src/proxy/tcp-relay.js').TcpRelayOptions} */
+  const relayOptions = {
+    authorizeTarget: ({target}) => target.host === "127.0.0.1" && target.port === targetPort,
+    tokens,
+    sessions: new SessionStore({now: () => 1000}),
+    resumeWindowMs: 5_000
+  }
+  if (options.compressionEnabled !== undefined) {
+    relayOptions.compressionEnabled = options.compressionEnabled
+  }
+  const relay = await startTcpRelay(relayOptions)
+
+  return {
+    relay,
+    relayPort: relay.port,
+    targetPort,
+    token: token.value,
+    targetReceived: () => targetReceived,
+    close: async () => {
+      await relay.close()
+      await new Promise((resolve) => echoServer.close(() => resolve(undefined)))
+    }
+  }
+}
+
+/**
+ * Minimal framed protocol client, so tests can assert on the exact headers and
+ * bytes that cross the relay link.
+ * @param {number} port - Relay port.
+ * @returns {Promise<{send: (header: import('../../src/protocol/frame.js').FrameHeader, payload?: Buffer) => void, next: () => Promise<import('../../src/protocol/frame.js').Frame>, closed: () => Promise<void>, close: () => void}>} - Framed client.
+ */
+async function framedClient(port) {
+  const socket = createConnection({host: "127.0.0.1", port})
+  await new Promise((resolve, reject) => {
+    socket.once("error", reject)
+    socket.once("connect", () => {
+      socket.off("error", reject)
+      resolve(undefined)
+    })
+  })
+  socket.on("error", () => {})
+
+  const decoder = new FrameDecoder({compactDirection: "target-to-client"})
+  /** @type {import('../../src/protocol/frame.js').Frame[]} */
+  const pending = []
+  /** @type {((frame: import('../../src/protocol/frame.js').Frame) => void)[]} */
+  const waiters = []
+
+  socket.on("data", (chunk) => {
+    for (const frame of decoder.push(chunk)) {
+      const waiter = waiters.shift()
+      if (waiter !== undefined) {
+        waiter(frame)
+      } else {
+        pending.push(frame)
+      }
+    }
+  })
+
+  return {
+    send: (header, payload = Buffer.alloc(0)) => {
+      socket.write(encodeFrame(header, payload))
+    },
+    next: async () => {
+      const buffered = pending.shift()
+      if (buffered !== undefined) {
+        return buffered
+      }
+      return new Promise((resolve) => waiters.push(resolve))
+    },
+    closed: async () => {
+      if (socket.destroyed || socket.readableEnded) {
+        return
+      }
+      await new Promise((resolve) => socket.once("close", () => resolve(undefined)))
+    },
+    close: () => socket.destroy()
+  }
+}
+
+/**
+ * A relay stub that completes the handshake and then hands the raw socket to the
+ * test, so the client's receive path can be driven with hand-crafted frames.
+ * @param {{compression?: string, framing?: number, onReady: (socket: import('node:net').Socket) => void}} options - Stub behavior.
+ * @returns {Promise<{port: number, received: import('../../src/protocol/frame.js').Frame[], close: () => Promise<void>}>} - Started stub.
+ */
+async function relayStub(options) {
+  /** @type {import('../../src/protocol/frame.js').Frame[]} */
+  const received = []
+  /** @type {import('node:net').Socket | undefined} */
+  let peer
+
+  const server = createServer((socket) => {
+    peer = socket
+    const decoder = new FrameDecoder({compactDirection: "client-to-target"})
+    socket.on("error", () => {})
+    socket.on("data", (chunk) => {
+      for (const frame of decoder.push(chunk)) {
+        received.push(frame)
+        if (frame.header.type !== "session.create") {
+          continue
+        }
+        /** @type {import('../../src/protocol/frame.js').FrameHeader} */
+        const created = {
+          type: "session.created",
+          identifier: "stub-session-identifier",
+          name: "stub",
+          state: "active",
+          target: {host: "127.0.0.1", port: 1}
+        }
+        if (options.compression !== undefined) {
+          created.compression = options.compression
+        }
+        created.framing = options.framing ?? 2
+        socket.write(encodeEnvelope(created))
+        options.onReady(socket)
+      }
+    })
+  })
+  const port = await listen(server)
+
+  return {
+    port,
+    received,
+    close: async () => {
+      peer?.destroy()
+      await new Promise((resolve) => server.close(() => resolve(undefined)))
+    }
+  }
+}
+
+/**
+ * Holds the next asynchronous Zstd completion callback.
+ * @returns {{entered: Promise<void>, release: () => void, restore: () => void}} Test controller.
+ */
+function holdNextZstdCompression() {
+  const originalCompress = /** @type {NonNullable<typeof zlib.zstdCompress>} */ (zlib.zstdCompress)
+  /** @type {import('node:zlib').CompressCallback | undefined} */
+  let heldCallback
+  /** @type {Buffer | undefined} */
+  let heldInput
+  /** @type {import('node:zlib').ZstdOptions | undefined} */
+  let heldOptions
+  /** @type {() => void} */
+  let enter = () => {}
+  const entered = new Promise((resolve) => { enter = () => resolve(undefined) })
+  /** @type {(input: import('node:zlib').InputType, options: import('node:zlib').ZstdOptions, callback: import('node:zlib').CompressCallback) => void} */
+  const patchedCompress = (input, options, callback) => {
+    heldCallback = callback
+    heldInput = /** @type {Buffer} */ (/** @type {unknown} */ (input))
+    heldOptions = options
+    enter()
+  }
+  // @ts-expect-error - TS lib __promisify__ required on typeof zstdCompress vs runtime
+  zlib.zstdCompress = patchedCompress
+  return {
+    entered,
+    release: () => {
+      zlib.zstdCompress = originalCompress
+      if (heldCallback !== undefined && heldInput !== undefined && heldOptions !== undefined) {
+        originalCompress(heldInput, heldOptions, heldCallback)
+      }
+    },
+    restore: () => {
+      zlib.zstdCompress = originalCompress
+    }
+  }
+}
+
+/**
+ * Holds the next asynchronous Zstd decompression callback.
+ * @returns {{entered: Promise<void>, release: () => void, restore: () => void}} Test controller.
+ */
+function holdNextZstdDecompression() {
+  const originalDecompress = /** @type {NonNullable<typeof zlib.zstdDecompress>} */ (zlib.zstdDecompress)
+  /** @type {import('node:zlib').CompressCallback | undefined} */
+  let heldCallback
+  /** @type {Buffer | undefined} */
+  let heldInput
+  /** @type {import('node:zlib').ZstdOptions | undefined} */
+  let heldOptions
+  /** @type {() => void} */
+  let enter = () => {}
+  const entered = new Promise((resolve) => { enter = () => resolve(undefined) })
+  /** @type {(input: import('node:zlib').InputType, options: import('node:zlib').ZstdOptions, callback: import('node:zlib').CompressCallback) => void} */
+  const patchedDecompress = (input, options, callback) => {
+    heldCallback = callback
+    heldInput = /** @type {Buffer} */ (/** @type {unknown} */ (input))
+    heldOptions = options
+    enter()
+  }
+  // @ts-expect-error - TS lib __promisify__ required on typeof zstdDecompress vs runtime
+  zlib.zstdDecompress = patchedDecompress
+  return {
+    entered,
+    release: () => {
+      zlib.zstdDecompress = originalDecompress
+      if (heldCallback !== undefined && heldInput !== undefined && heldOptions !== undefined) {
+        originalDecompress(heldInput, heldOptions, heldCallback)
+      }
+    },
+    restore: () => {
+      zlib.zstdDecompress = originalDecompress
+    }
+  }
+}
+
+test("closeActiveTunnel waits for queued relay frame lifecycle settlement", {skip: !zstdAvailable()}, async () => {
+  const fixture = await startFixture()
+  const client = await framedClient(fixture.relayPort)
+  const payload = compressibleChunk(16_384)
+  const encoded = await encodeStreamPayload(payload, "zstd")
+  assert.equal(encoded.encoding, "zstd")
+  const held = holdNextZstdDecompression()
+  /** @type {Promise<void> | undefined} */
+  let closing
+  /** @type {Promise<void> | undefined} */
+  let joiningClose
+  let released = false
+
+  try {
+    client.send({
+      type: "session.create",
+      token: fixture.token,
+      name: "queued-close-settlement",
+      target: {host: "127.0.0.1", port: fixture.targetPort},
+      compression: ["zstd"]
+    })
+    const created = await client.next()
+    assert.equal(created.header.type, "session.created")
+    assert.equal(created.header.compression, "zstd")
+
+    client.send({
+      type: "stream.data",
+      direction: "client-to-target",
+      sequence: payload.length,
+      encoding: "zstd",
+      dataLength: payload.length
+    }, encoded.payload)
+    await held.entered
+
+    let closeResolved = false
+    closing = fixture.relay.closeActiveTunnel().then(() => { closeResolved = true })
+    await client.closed()
+    let joiningCloseResolved = false
+    joiningClose = fixture.relay.closeActiveTunnel().then(() => { joiningCloseResolved = true })
+    await new Promise((resolve) => setImmediate(resolve))
+    assert.equal(closeResolved, false, "closeActiveTunnel must await queued frame lifecycle work")
+    assert.equal(joiningCloseResolved, false, "a concurrent close must join queued frame lifecycle work")
+
+    held.release()
+    released = true
+    await Promise.all([closing, joiningClose])
+    assert.equal(fixture.relay.status().attachedSessions, 0)
+  } finally {
+    if (!released) held.release()
+    held.restore()
+    await closing
+    await joiningClose
+    client.close()
+    await fixture.close()
+  }
+})
+
+test("client negotiates compact v2, receives uncompressed data, and returns a compact ACK", async () => {
+  const tempDir = await mkdtemp(join(tmpdir(), "socketduct-client-compact-v2-"))
+  const payload = Buffer.from("compact-v2-client-data")
+  const stub = await relayStub({
+    framing: 2,
+    onReady: (socket) => socket.write(encodeCompactData({sequence: payload.length, payload}))
+  })
+  const socket = connectSocketduct({
+    relay: {host: "127.0.0.1", port: stub.port, token: "stub-token"},
+    sessionName: "compact v2 client",
+    target: {host: "127.0.0.1", port: 1},
+    spoolDirectory: tempDir,
+    reconnect: {initialDelayMs: 60_000}
+  })
+  const received = collect(socket)
+  await received.waitFor(payload.length)
+  assert.deepEqual(received.bytes(), payload)
+  for (let attempt = 0; attempt < 100 && !stub.received.some((frame) => frame.header.compact === true && frame.header.type === "stream.ack"); attempt += 1) {
+    await new Promise((resolve) => setTimeout(resolve, 5))
+  }
+  const ack = stub.received.find((frame) => frame.header.compact === true && frame.header.type === "stream.ack")
+  assert.equal(ack?.header.ackSequence, payload.length)
+  socket.destroy()
+  await stub.close()
+  await rm(tempDir, {recursive: true, force: true})
+})
+
+test("client ignores a queued compact v2 frame from a stale relay while reconnect framing is reset", {skip: !zstdAvailable()}, async () => {
+  const tempDir = await mkdtemp(join(tmpdir(), "socketduct-client-stale-compact-v2-"))
+  const initial = Buffer.from("initial-current-relay-data")
+  const delayed = compressibleChunk(4_096)
+  const queuedStale = Buffer.from("queued-stale-relay-data")
+  const fresh = Buffer.from("fresh-reconnected-relay-data")
+  const encodedDelayed = await encodeStreamPayload(delayed, "zstd")
+  assert.equal(encodedDelayed.encoding, "zstd")
+
+  /** @type {import('node:net').Socket[]} */
+  const peers = []
+  /** @type {import('node:net').Socket | undefined} */
+  let firstPeer
+  /** @type {import('node:net').Socket | undefined} */
+  let resumedPeer
+  /** @type {() => void} */
+  let firstNegotiatedResolve = () => {}
+  const firstNegotiated = new Promise((resolve) => { firstNegotiatedResolve = () => resolve(undefined) })
+  /** @type {() => void} */
+  let resumeRequestedResolve = () => {}
+  const resumeRequested = new Promise((resolve) => { resumeRequestedResolve = () => resolve(undefined) })
+  const server = createServer((peer) => {
+    peers.push(peer)
+    peer.on("error", () => {})
+    const decoder = new FrameDecoder({compactDirection: "client-to-target"})
+    peer.on("data", (chunk) => {
+      for (const frame of decoder.push(chunk)) {
+        if (frame.header.type === "session.create") {
+          firstPeer = peer
+          peer.write(encodeFrame({type: "session.created", identifier: "stale-compact-v2", compression: "zstd", framing: 2}))
+          firstNegotiatedResolve()
+        } else if (frame.header.type === "session.resume") {
+          resumedPeer = peer
+          resumeRequestedResolve()
+        }
+      }
+    })
+  })
+  const port = await listen(server)
+  const socket = connectSocketduct({
+    relay: {host: "127.0.0.1", port, token: "stub-token"},
+    sessionName: "stale compact v2 client",
+    target: {host: "127.0.0.1", port: 1},
+    spoolDirectory: tempDir,
+    reconnect: {initialDelayMs: 10}
+  })
+  /** @type {Error[]} */
+  const errors = []
+  socket.on("error", (error) => errors.push(error))
+  const received = collect(socket)
+  const held = holdNextZstdDecompression()
+  try {
+    await firstNegotiated
+    firstPeer?.write(encodeCompactData({sequence: initial.length, payload: initial}))
+    await received.waitFor(initial.length)
+
+    firstPeer?.write(Buffer.concat([
+      encodeCompactData({sequence: initial.length, payload: encodedDelayed.payload, dataLength: delayed.length}),
+      encodeCompactData({sequence: initial.length + queuedStale.length, payload: queuedStale})
+    ]))
+    await held.entered
+
+    firstPeer?.destroy()
+    await resumeRequested
+    const reconnected = new Promise((resolve) => socket.once("ready", resolve))
+    held.release()
+    resumedPeer?.write(encodeFrame({type: "session.resumed", identifier: "stale-compact-v2", compression: "zstd", framing: 2}))
+    await reconnected
+    resumedPeer?.write(encodeCompactData({sequence: initial.length + fresh.length, payload: fresh}))
+    await received.waitFor(initial.length + fresh.length)
+
+    assert.equal(socket.destroyed, false)
+    assert.deepEqual(errors, [])
+    assert.deepEqual(received.bytes(), Buffer.concat([initial, fresh]))
+  } finally {
+    held.restore()
+    socket.destroy()
+    for (const peer of peers) peer.destroy()
+    await new Promise((resolve) => server.close(() => resolve(undefined)))
+    await rm(tempDir, {recursive: true, force: true})
+  }
+})
+
+test("client writev emits one compact v2 data record for corked writes", async () => {
+  const tempDir = await mkdtemp(join(tmpdir(), "socketduct-client-writev-"))
+  const stub = await relayStub({framing: 2, onReady: () => {}})
+  const socket = connectSocketduct({
+    relay: {host: "127.0.0.1", port: stub.port, token: "stub-token"},
+    sessionName: "writev client",
+    target: {host: "127.0.0.1", port: 1},
+    spoolDirectory: tempDir,
+    reconnect: {initialDelayMs: 60_000}
+  })
+  await new Promise((resolve) => socket.once("connect", resolve))
+  socket.cork()
+  socket.write("writev-")
+  socket.write("merged")
+  socket.uncork()
+  for (let attempt = 0; attempt < 100 && !stub.received.some((frame) => frame.header.type === "stream.data"); attempt += 1) {
+    await new Promise((resolve) => setTimeout(resolve, 5))
+  }
+  const dataFrames = stub.received.filter((frame) => frame.header.type === "stream.data")
+  assert.equal(dataFrames.length, 1)
+  assert.equal(dataFrames[0]?.header.compact, true)
+  assert.deepEqual(dataFrames[0]?.payload, Buffer.from("writev-merged"))
+  socket.destroy()
+  await stub.close()
+  await rm(tempDir, {recursive: true, force: true})
+})
+
+test("client writev splits an oversized write into bounded compact data records", async () => {
+  const tempDir = await mkdtemp(join(tmpdir(), "socketduct-client-writev-limit-"))
+  const stub = await relayStub({framing: 2, onReady: () => {}})
+  const socket = connectSocketduct({
+    relay: {host: "127.0.0.1", port: stub.port, token: "stub-token"},
+    sessionName: "bounded writev client",
+    target: {host: "127.0.0.1", port: 1},
+    spoolDirectory: tempDir,
+    compressionLimits: {maxDecompressedBytes: 8},
+    reconnect: {initialDelayMs: 60_000}
+  })
+  await new Promise((resolve) => socket.once("connect", resolve))
+  const payload = Buffer.from("abcdefghijklmnopqrst")
+  socket.cork()
+  socket.write(payload)
+  socket.write("uv")
+  socket.uncork()
+  for (let attempt = 0; attempt < 100 && stub.received.filter((frame) => frame.header.type === "stream.data").length < 3; attempt += 1) {
+    await new Promise((resolve) => setTimeout(resolve, 5))
+  }
+  const dataFrames = stub.received.filter((frame) => frame.header.type === "stream.data")
+  assert.deepEqual(dataFrames.map((frame) => frame.payload.length), [8, 8, 6])
+  assert.deepEqual(dataFrames.map((frame) => frame.header.sequence), [8, 16, 22])
+  assert.deepEqual(Buffer.concat(dataFrames.map((frame) => frame.payload)), Buffer.concat([payload, Buffer.from("uv")]))
+  socket.destroy()
+  await stub.close()
+  await rm(tempDir, {recursive: true, force: true})
+})
+
+test("client writev resets the idle timeout when queued writes become active", {skip: typeof zlib.zstdCompress !== "function"}, async (t) => {
+  const tempDir = await mkdtemp(join(tmpdir(), "socketduct-client-writev-timeout-"))
+  const stub = await relayStub({compression: "zstd", framing: 2, onReady: () => {}})
+  const socket = connectSocketduct({
+    relay: {host: "127.0.0.1", port: stub.port, token: "stub-token"},
+    sessionName: "writev timeout client",
+    target: {host: "127.0.0.1", port: 1},
+    spoolDirectory: tempDir,
+    reconnect: {initialDelayMs: 60_000}
+  })
+  const held = holdNextZstdCompression()
+  try {
+    await new Promise((resolve) => socket.once("connect", resolve))
+    t.mock.timers.enable({apis: ["setTimeout"]})
+    socket.setTimeout(50)
+    let timedOut = false
+    socket.once("timeout", () => { timedOut = true })
+
+    socket.write(compressibleChunk(16_384))
+    await held.entered
+    socket.cork()
+    socket.write("queued-")
+    const writevCompleted = new Promise((resolve) => socket.write("writev", resolve))
+    socket.uncork()
+
+    t.mock.timers.tick(35)
+    held.release()
+    await writevCompleted
+
+    t.mock.timers.tick(15)
+    assert.equal(timedOut, false, "queued _writev activity must replace the first write's deadline")
+    t.mock.timers.tick(34)
+    assert.equal(timedOut, false, "replacement deadline must start when _writev becomes active")
+    t.mock.timers.tick(1)
+    assert.equal(timedOut, true, "replacement deadline must remain armed")
+  } finally {
+    held.restore()
+    socket.setTimeout(0)
+    t.mock.timers.reset()
+    socket.destroy()
+    await stub.close()
+    await rm(tempDir, {recursive: true, force: true})
+  }
+})
+
+/**
+ * @param {{port: number}} stub - Relay stub.
+ * @param {string} tempDir - Spool directory.
+ * @returns {Promise<Error>} - The error the client failed closed with.
+ */
+async function expectClientError(stub, tempDir) {
+  const socket = connectSocketduct({
+    relay: {host: "127.0.0.1", port: stub.port, token: "stub-token"},
+    sessionName: "stub session",
+    target: {host: "127.0.0.1", port: 1},
+    spoolDirectory: tempDir,
+    // Do not reconnect: a fail-closed receive path must surface, not retry forever.
+    reconnect: {initialDelayMs: 60_000}
+  })
+
+  const error = await new Promise((resolve) => {
+    socket.once("error", (err) => resolve(err))
+  })
+  socket.destroy()
+  return error
+}
+
+test("client rejects length-prefixed stream.data after a v2 handshake", async () => {
+  const tempDir = await mkdtemp(join(tmpdir(), "socketduct-client-envelope-data-"))
+  const stub = await relayStub({
+    onReady: (socket) => {
+      socket.write(encodeEnvelope({type: "stream.data", direction: "target-to-client", sequence: 5}, Buffer.from("first")))
+    }
+  })
+
+  const socket = connectSocketduct({
+    relay: {host: "127.0.0.1", port: stub.port, token: "stub-token"},
+    sessionName: "envelope data rejection",
+    target: {host: "127.0.0.1", port: 1},
+    spoolDirectory: tempDir,
+    reconnect: {initialDelayMs: 60_000}
+  })
+  const error = await new Promise((resolve) => socket.once("error", resolve))
+  assert.match(String(error), /length-prefixed stream\.data/)
+
+  socket.destroy()
+  await stub.close()
+  await rm(tempDir, {recursive: true, force: true})
+})
+
+test("client rejects length-prefixed stream.ack after a v2 handshake", async () => {
+  const tempDir = await mkdtemp(join(tmpdir(), "socketduct-client-envelope-ack-"))
+  const stub = await relayStub({
+    onReady: (socket) => {
+      socket.write(encodeEnvelope({type: "stream.ack", direction: "client-to-target", ackSequence: 0}))
+    }
+  })
+
+  const error = await expectClientError(stub, tempDir)
+  assert.match(error.message, /length-prefixed stream\.ack/)
+
+  await stub.close()
+  await rm(tempDir, {recursive: true, force: true})
+})
+
+test("relay target-to-client delivery queue preserves uncompressed sequence order across multiple encoded frames", {skip: !zstdAvailable()}, async () => {
+  const fixture = await startFixture()
+  const client = await framedClient(fixture.relayPort)
+
+  client.send({
+    type: "session.create",
+    token: fixture.token,
+    name: "delivery order",
+    target: {host: "127.0.0.1", port: fixture.targetPort},
+    compression: ["zstd"]
+  })
+  const created = await client.next()
+  assert.equal(created.header.compression, "zstd")
+
+  const chunkSizes = [8_192, 4_096, 16_384, 1_024, 8_192]
+  const rawChunks = /** @type {Buffer[]} */ ([])
+  let sequence = 0
+  for (const size of chunkSizes) {
+    const chunk = compressibleChunk(size)
+    rawChunks.push(chunk)
+    sequence += size
+    const encoded = await encodeStreamPayload(chunk, "zstd")
+    client.send({
+      type: "stream.data",
+      direction: "client-to-target",
+      sequence,
+      encoding: encoded.encoding,
+      dataLength: encoded.dataLength
+    }, encoded.payload)
+  }
+
+  /** @type {{sequence: number, data: Buffer}[]} */
+  const dataFrames = []
+  let receivedBytes = 0
+  const totalBytes = chunkSizes.reduce((sum, s) => sum + s, 0)
+
+  while (receivedBytes < totalBytes) {
+    const frame = await client.next()
+    if (frame.header.type !== "stream.data" || frame.header.direction !== "target-to-client") {
+      continue
+    }
+    const decoded = await decodeStreamPayload(frame.header, frame.payload, "zstd")
+    dataFrames.push({sequence: /** @type {number} */ (frame.header.sequence), data: decoded})
+    receivedBytes += decoded.length
+  }
+
+  // Every frame carries the correct uncompressed cumulative sequence offset.
+  let expectedSeq = 0
+  for (const frame of dataFrames) {
+    expectedSeq += frame.data.length
+    assert.equal(frame.sequence, expectedSeq,
+      `Expected sequence ${expectedSeq} but got ${frame.sequence} (uncompressed length ${frame.data.length})`)
+  }
+  // Combined echoed data matches the raw payloads that were sent.
+  assert.deepEqual(Buffer.concat(dataFrames.map((f) => f.data)), Buffer.concat(rawChunks))
+
+  client.close()
+  await fixture.close()
+})
+
+test("relay tunnel frame queue preserves client-to-target processing order and ACK state", {skip: !zstdAvailable()}, async () => {
+  const fixture = await startFixture()
+  const client = await framedClient(fixture.relayPort)
+
+  client.send({
+    type: "session.create",
+    token: fixture.token,
+    name: "ack order",
+    target: {host: "127.0.0.1", port: fixture.targetPort},
+    compression: ["zstd"]
+  })
+  const created = await client.next()
+  assert.equal(created.header.compression, "zstd")
+
+  const chunkSizes = [4_096, 8_192, 2_048, 16_384, 32_768]
+  let sequence = 0
+  for (const size of chunkSizes) {
+    const chunk = compressibleChunk(size)
+    sequence += size
+    const encoded = await encodeStreamPayload(chunk, "zstd")
+    client.send({
+      type: "stream.data",
+      direction: "client-to-target",
+      sequence,
+      encoding: encoded.encoding,
+      dataLength: encoded.dataLength
+    }, encoded.payload)
+  }
+
+  /** @type {number[]} */
+  const acks = []
+  let receivedBytes = 0
+  const totalBytes = chunkSizes.reduce((sum, s) => sum + s, 0)
+
+  while (receivedBytes < totalBytes) {
+    const frame = await client.next()
+    if (frame.header.type === "stream.ack" && frame.header.direction === "client-to-target") {
+      acks.push(/** @type {number} */ (frame.header.ackSequence))
+    }
+    if (frame.header.type === "stream.data" && frame.header.direction === "target-to-client") {
+      const decoded = await decodeStreamPayload(frame.header, frame.payload, "zstd")
+      receivedBytes += decoded.length
+    }
+  }
+
+  assert.ok(acks.length > 0, "Expected at least one client-to-target ACK")
+
+  // ACKs arrive in monotonically non-decreasing order.
+  for (let index = 1; index < acks.length; index += 1) {
+    const previousAck = acks[index - 1]
+    const currentAck = acks[index]
+    if (previousAck === undefined || currentAck === undefined) {
+      throw new Error("Expected contiguous ACK entries")
+    }
+    assert.ok(currentAck >= previousAck,
+      `ACK ${currentAck} must be >= ${previousAck}`)
+  }
+  // The final ACK acknowledges the full uncompressed byte total.
+  const finalAck = acks.at(-1)
+  assert.equal(finalAck, totalBytes)
+
+  client.close()
+  await fixture.close()
+})
+
+test("client relay frame queue preserves ordering and ACK tracking across batched target-to-client frames", {skip: !zstdAvailable()}, async () => {
+  const tempDir = await mkdtemp(join(tmpdir(), "socketduct-client-frameq-"))
+
+  const rawChunks = [
+    compressibleChunk(4_096),
+    compressibleChunk(8_192),
+    compressibleChunk(16_384),
+    compressibleChunk(2_048)
+  ]
+  // Pre-encode all frames so the stub delivers valid zstd payloads.
+  /** @type {{encoding?: string, dataLength?: number, payload: Buffer}[]} */
+  const encodedFrames = []
+  for (const chunk of rawChunks) {
+    const encoded = await encodeStreamPayload(chunk, "zstd")
+    encodedFrames.push(encoded)
+  }
+
+  const stub = await relayStub({
+    compression: "zstd",
+    onReady: (socket) => {
+      let cumulativeSequence = 0
+      const wireFrames = []
+      for (let index = 0; index < encodedFrames.length; index += 1) {
+        const rawChunk = rawChunks[index]
+        const encoded = encodedFrames[index]
+        if (rawChunk === undefined || encoded === undefined) {
+          throw new Error("Expected matching encoded and uncompressed chunk")
+        }
+        cumulativeSequence += rawChunk.length
+        wireFrames.push(encodeFrame({
+          type: "stream.data",
+          direction: "target-to-client",
+          sequence: cumulativeSequence,
+          encoding: encoded.encoding,
+          dataLength: encoded.dataLength
+        }, encoded.payload))
+      }
+      // Deliver every frame in a single TCP write so the relay frame queue
+      // must deserialize them one-by-one across async zstd decode calls.
+      socket.write(Buffer.concat(wireFrames))
+    }
+  })
+
+  const socket = connectSocketduct({
+    relay: {host: "127.0.0.1", port: stub.port, token: "stub-token"},
+    sessionName: "client frame queue",
+    target: {host: "127.0.0.1", port: 1},
+    spoolDirectory: tempDir,
+    reconnect: {initialDelayMs: 60_000}
+  })
+
+  const received = collect(socket)
+  const totalExpected = rawChunks.reduce((sum, c) => sum + c.length, 0)
+  await received.waitFor(totalExpected)
+
+  // Data reaches the stream consumer intact and in the correct order.
+  assert.deepEqual(received.bytes(), Buffer.concat(rawChunks))
+
+  // The client must acknowledge every frame-level sequence advancement.
+  // Poll briefly since ACKs are serialised through a separate send queue.
+  /** @type {number[]} */
+  let acks = []
+  for (let attempt = 0; attempt < 30; attempt += 1) {
+    acks = stub.received.flatMap((frame) => (
+      frame.header.type === "stream.ack" &&
+      frame.header.direction === "target-to-client" &&
+      typeof frame.header.ackSequence === "number"
+        ? [frame.header.ackSequence]
+        : []
+    ))
+    if ((acks.at(-1) ?? 0) >= totalExpected) break
+    await new Promise((resolve) => setTimeout(resolve, 10))
+  }
+
+  assert.ok(acks.length >= rawChunks.length,
+    `Expected at least ${rawChunks.length} ACKs, got ${acks.length}`)
+  for (let index = 1; index < acks.length; index += 1) {
+    const previousAck = acks[index - 1]
+    const currentAck = acks[index]
+    if (previousAck === undefined || currentAck === undefined) {
+      throw new Error("Expected contiguous ACK entries")
+    }
+    assert.ok(currentAck >= previousAck,
+      `ACK ${currentAck} must be >= ${previousAck}`)
+  }
+  assert.equal(acks.at(-1), totalExpected)
+
+  socket.destroy()
+  await stub.close()
+  await rm(tempDir, {recursive: true, force: true})
+})
+
+test("client fails closed on a compressed frame when no codec was negotiated", async () => {
+  const tempDir = await mkdtemp(join(tmpdir(), "socketduct-client-unnegotiated-"))
+  const stub = await relayStub({
+    onReady: (socket) => {
+      socket.write(encodeFrame({
+        type: "stream.data",
+        direction: "target-to-client",
+        sequence: 64,
+        encoding: "zstd",
+        dataLength: 64
+      }, Buffer.from("not really compressed")))
+    }
+  })
+
+  const error = await expectClientError(stub, tempDir)
+  assert.match(error.message, /was not negotiated/)
+  // Nothing was acknowledged.
+  assert.equal(stub.received.some((frame) => frame.header.type === "stream.ack"), false)
+
+  await stub.close()
+  await rm(tempDir, {recursive: true, force: true})
+})
+
+test("client fails closed on a corrupt compressed frame", {skip: !zstdAvailable()}, async () => {
+  const tempDir = await mkdtemp(join(tmpdir(), "socketduct-client-corrupt-"))
+  const payload = compressibleChunk(4096)
+  const encoded = await encodeStreamPayload(payload, "zstd")
+  const corrupted = Buffer.from(encoded.payload)
+  corrupted.writeUInt8(corrupted.readUInt8(corrupted.length - 1) ^ 0xff, corrupted.length - 1)
+  corrupted.writeUInt8(corrupted.readUInt8(8) ^ 0xff, 8)
+
+  const stub = await relayStub({
+    compression: "zstd",
+    onReady: (socket) => {
+      socket.write(encodeFrame({
+        type: "stream.data",
+        direction: "target-to-client",
+        sequence: payload.length,
+        encoding: "zstd",
+        dataLength: payload.length
+      }, corrupted))
+    }
+  })
+
+  const error = await expectClientError(stub, tempDir)
+  assert.match(error.message, /failed to decompress/)
+  assert.equal(stub.received.some((frame) => frame.header.type === "stream.ack"), false)
+
+  await stub.close()
+  await rm(tempDir, {recursive: true, force: true})
+})
+
+test("client fails closed on a target-to-client sequence gap without acknowledging it", async () => {
+  const tempDir = await mkdtemp(join(tmpdir(), "socketduct-client-gap-"))
+  const stub = await relayStub({
+    onReady: (socket) => {
+      // 8 payload bytes but a sequence claiming offset 100: a 92-byte hole.
+      socket.write(encodeFrame({
+        type: "stream.data",
+        direction: "target-to-client",
+        sequence: 100
+      }, Buffer.from("12345678")))
+    }
+  })
+
+  const error = await expectClientError(stub, tempDir)
+  assert.match(error.message, /gap \(expected contiguous offset 8\)/)
+  assert.equal(stub.received.some((frame) => frame.header.type === "stream.ack"), false)
+
+  await stub.close()
+  await rm(tempDir, {recursive: true, force: true})
+})
+
+test("client fails closed on a target-to-client sequence overlap without acknowledging it", async () => {
+  const tempDir = await mkdtemp(join(tmpdir(), "socketduct-client-overlap-"))
+  const stub = await relayStub({
+    onReady: (socket) => {
+      // 8 payload bytes claiming to end at offset 4: overlaps bytes never sent.
+      socket.write(encodeFrame({
+        type: "stream.data",
+        direction: "target-to-client",
+        sequence: 4
+      }, Buffer.from("12345678")))
+    }
+  })
+
+  const error = await expectClientError(stub, tempDir)
+  assert.match(error.message, /overlap \(expected contiguous offset 8\)/)
+  assert.equal(stub.received.some((frame) => frame.header.type === "stream.ack"), false)
+
+  await stub.close()
+  await rm(tempDir, {recursive: true, force: true})
+})
+
+test("relay negotiates zstd and compresses target-to-client stream.data on the wire", {skip: !zstdAvailable()}, async () => {
+  const fixture = await startFixture()
+  const client = await framedClient(fixture.relayPort)
+
+  client.send({
+    type: "session.create",
+    token: fixture.token,
+    name: "compressed",
+    target: {host: "127.0.0.1", port: fixture.targetPort},
+    compression: ["zstd"]
+  })
+
+  const created = await client.next()
+  assert.equal(created.header.type, "session.created")
+  assert.equal(created.header.compression, "zstd")
+
+  const payload = compressibleChunk(16384)
+  const encoded = await encodeStreamPayload(payload, "zstd")
+  assert.equal(encoded.encoding, "zstd")
+
+  client.send({
+    type: "stream.data",
+    direction: "client-to-target",
+    sequence: payload.length,
+    encoding: encoded.encoding,
+    dataLength: encoded.dataLength
+  }, encoded.payload)
+
+  /** @type {Buffer[]} */
+  const echoed = []
+  let received = 0
+  let wireBytes = 0
+  let ackSequence = 0
+
+  while (received < payload.length || ackSequence === 0) {
+    const frame = await client.next()
+    if (frame.header.type === "stream.ack" && frame.header.direction === "client-to-target") {
+      ackSequence = /** @type {number} */ (frame.header.ackSequence)
+      continue
+    }
+    if (frame.header.type !== "stream.data") {
+      continue
+    }
+    assert.equal(frame.header.encoding, "zstd")
+    wireBytes += frame.payload.length
+    const decoded = await decodeStreamPayload(frame.header, frame.payload, "zstd")
+    echoed.push(decoded)
+    received += decoded.length
+  }
+
+  // Acknowledgements are in uncompressed byte units.
+  assert.equal(ackSequence, payload.length)
+  assert.deepEqual(Buffer.concat(echoed), payload)
+  assert.ok(wireBytes < payload.length / 2, `expected >50% saving, sent ${wireBytes} of ${payload.length}`)
+
+  client.close()
+  await fixture.close()
+})
+
+test("relay uses compact uncompressed records when the client offers no compression", async () => {
+  const fixture = await startFixture()
+  const client = await framedClient(fixture.relayPort)
+
+  client.send({
+    type: "session.create",
+    token: fixture.token,
+    name: "uncompressed compact",
+    target: {host: "127.0.0.1", port: fixture.targetPort}
+  })
+
+  const created = await client.next()
+  assert.equal(created.header.type, "session.created")
+  assert.equal("compression" in created.header, false)
+
+  const payload = compressibleChunk(8192)
+  client.send({type: "stream.data", direction: "client-to-target", sequence: payload.length}, payload)
+
+  /** @type {Buffer[]} */
+  const echoed = []
+  let received = 0
+  while (received < payload.length) {
+    const frame = await client.next()
+    if (frame.header.type !== "stream.data") {
+      continue
+    }
+    // No compression metadata may appear on an uncompressed compact tunnel.
+    assert.equal("encoding" in frame.header, false)
+    assert.equal("dataLength" in frame.header, false)
+    echoed.push(frame.payload)
+    received += frame.payload.length
+  }
+
+  assert.deepEqual(Buffer.concat(echoed), payload)
+
+  client.close()
+  await fixture.close()
+})
+
+test("relay declines compression when it is disabled, even if the client offers it", async () => {
+  const fixture = await startFixture({compressionEnabled: false})
+  const client = await framedClient(fixture.relayPort)
+
+  client.send({
+    type: "session.create",
+    token: fixture.token,
+    name: "disabled",
+    target: {host: "127.0.0.1", port: fixture.targetPort},
+    compression: ["zstd"]
+  })
+
+  const created = await client.next()
+  assert.equal(created.header.type, "session.created")
+  assert.equal("compression" in created.header, false)
+
+  client.close()
+  await fixture.close()
+})
+
+test("relay fails closed on a compressed frame when no codec was negotiated", async () => {
+  const fixture = await startFixture({compressionEnabled: false})
+  const client = await framedClient(fixture.relayPort)
+
+  client.send({
+    type: "session.create",
+    token: fixture.token,
+    name: "unnegotiated",
+    target: {host: "127.0.0.1", port: fixture.targetPort},
+    compression: ["zstd"]
+  })
+  await client.next()
+
+  client.send({
+    type: "stream.data",
+    direction: "client-to-target",
+    sequence: 100,
+    encoding: "zstd",
+    dataLength: 100
+  }, Buffer.from("not really compressed"))
+
+  const response = await client.next()
+  assert.equal(response.header.type, "error")
+  assert.equal(response.header.code, "PROTOCOL_VIOLATION")
+
+  // Fail closed: the connection ends and nothing reaches the target.
+  await client.closed()
+  assert.equal(fixture.targetReceived(), 0)
+
+  client.close()
+  await fixture.close()
+})
+
+test("relay fails closed on a corrupt compressed payload and never writes it to the target", {skip: !zstdAvailable()}, async () => {
+  const fixture = await startFixture()
+  const client = await framedClient(fixture.relayPort)
+
+  client.send({
+    type: "session.create",
+    token: fixture.token,
+    name: "corrupt",
+    target: {host: "127.0.0.1", port: fixture.targetPort},
+    compression: ["zstd"]
+  })
+  const created = await client.next()
+  assert.equal(created.header.compression, "zstd")
+
+  const payload = compressibleChunk(4096)
+  const encoded = await encodeStreamPayload(payload, "zstd")
+  const corrupted = Buffer.from(encoded.payload)
+  corrupted.writeUInt8(corrupted.readUInt8(corrupted.length - 1) ^ 0xff, corrupted.length - 1)
+  corrupted.writeUInt8(corrupted.readUInt8(8) ^ 0xff, 8)
+
+  client.send({
+    type: "stream.data",
+    direction: "client-to-target",
+    sequence: payload.length,
+    encoding: "zstd",
+    dataLength: payload.length
+  }, corrupted)
+
+  const response = await client.next()
+  assert.equal(response.header.type, "error")
+  assert.equal(response.header.code, "PROTOCOL_VIOLATION")
+
+  await client.closed()
+  assert.equal(fixture.targetReceived(), 0)
+
+  client.close()
+  await fixture.close()
+})
+
+test("relay fails closed on a dataLength that disagrees with the decompressed size", {skip: !zstdAvailable()}, async () => {
+  const fixture = await startFixture()
+  const client = await framedClient(fixture.relayPort)
+
+  client.send({
+    type: "session.create",
+    token: fixture.token,
+    name: "lying length",
+    target: {host: "127.0.0.1", port: fixture.targetPort},
+    compression: ["zstd"]
+  })
+  await client.next()
+
+  const payload = compressibleChunk(4096)
+  const encoded = await encodeStreamPayload(payload, "zstd")
+
+  client.send({
+    type: "stream.data",
+    direction: "client-to-target",
+    sequence: payload.length + 1,
+    encoding: "zstd",
+    dataLength: payload.length + 1
+  }, encoded.payload)
+
+  const response = await client.next()
+  assert.equal(response.header.type, "error")
+  assert.equal(response.header.code, "PROTOCOL_VIOLATION")
+
+  await client.closed()
+  assert.equal(fixture.targetReceived(), 0)
+
+  client.close()
+  await fixture.close()
+})
+
+test("SocketductSocket round-trips compressible and incompressible data with compression negotiated", {skip: !zstdAvailable()}, async () => {
+  const tempDir = await mkdtemp(join(tmpdir(), "socketduct-compression-test-"))
+  const fixture = await startFixture()
+
+  const socket = connectSocketduct({
+    relay: {host: "127.0.0.1", port: fixture.relayPort, token: fixture.token},
+    sessionName: "compressed session",
+    target: {host: "127.0.0.1", port: fixture.targetPort},
+    spoolDirectory: tempDir,
+    reconnect: {initialDelayMs: 10}
+  })
+  socket.on("error", () => {})
+
+  const received = collect(socket)
+  const payload = Buffer.concat([compressibleChunk(20_000), randomBytes(20_000), compressibleChunk(5_000)])
+  socket.write(payload)
+
+  await received.waitFor(payload.length)
+
+  assert.deepEqual(received.bytes(), payload)
+  assert.equal(socket.bytesWritten, payload.length)
+  assert.equal(socket.bytesRead, payload.length)
+
+  socket.destroy()
+  await fixture.close()
+  await rm(tempDir, {recursive: true, force: true})
+})
+
+test("SocketductSocket replays raw spooled chunks across a reconnect that renegotiates compression", {skip: !zstdAvailable()}, async () => {
+  const tempDir = await mkdtemp(join(tmpdir(), "socketduct-compression-replay-"))
+  const fixture = await startFixture()
+
+  const socket = connectSocketduct({
+    relay: {host: "127.0.0.1", port: fixture.relayPort, token: fixture.token},
+    sessionName: "replay session",
+    target: {host: "127.0.0.1", port: fixture.targetPort},
+    spoolDirectory: tempDir,
+    reconnect: {initialDelayMs: 10}
+  })
+  socket.on("error", () => {})
+
+  const received = collect(socket)
+  const first = compressibleChunk(8192)
+  socket.write(first)
+  await received.waitFor(first.length)
+  assert.deepEqual(received.bytes(), first)
+
+  const identifierBeforeDrop = socket.sessionIdentifier
+  assert.ok(identifierBeforeDrop !== undefined)
+
+  // Drop the tunnel for real, then write while it is still down. The chunk can only
+  // reach the target by being spooled raw and replayed on the resumed connection,
+  // which renegotiates the codec from scratch.
+  fixture.relay.closeActiveTunnel()
+  const second = compressibleChunk(4096)
+  socket.write(second)
+
+  await received.waitFor(first.length + second.length)
+
+  // Same session identifier proves this was a resume, not a fresh session.
+  assert.equal(socket.sessionIdentifier, identifierBeforeDrop)
+  // Sequences are uncompressed offsets, so the relay's contiguity check still lines
+  // up after the codec was renegotiated on the new connection.
+  assert.deepEqual(received.bytes(), Buffer.concat([first, second]))
+  assert.equal(socket.bytesWritten, first.length + second.length)
+  assert.equal(fixture.targetReceived(), first.length + second.length)
+
+  socket.destroy()
+  await fixture.close()
+  await rm(tempDir, {recursive: true, force: true})
+})