socketduct 0.1.15

package/test/unit/client/socketduct-socket.test.js

@@ -0,0 +1,1124 @@
+import assert from "node:assert/strict"
+import {mkdtemp, readdir, rm} from "node:fs/promises"
+import {tmpdir} from "node:os"
+import {join} from "node:path"
+import {createServer} from "node:net"
+import {Duplex} from "node:stream"
+import {EventEmitter} from "node:events"
+import test from "node:test"
+
+import {InMemoryUserStore, login, TokenStore} from "../../../src/auth/user-store.js"
+import {connectSocketduct, SocketductSocket} from "../../../src/client/socketduct-socket.js"
+import {encodeCompactData, encodeFrame, FrameDecoder} from "../../../src/protocol/frame.js"
+import {startTcpRelay} from "../../../src/proxy/tcp-relay.js"
+import {SessionStore} from "../../../src/sessions/session.js"
+import {SessionSpool} from "../../../src/spool/spool-file.js"
+
+/**
+ * @returns {Promise<{rootDir: string, spool: SessionSpool}>} - Test spool.
+ */
+async function createTestSpool() {
+  const rootDir = await mkdtemp(join(tmpdir(), "socketduct-socket-test-"))
+  return {rootDir, spool: new SessionSpool({rootDir})}
+}
+
+/**
+ * @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 {() => boolean} predicate - Completion predicate.
+ * @param {number} [timeoutMs] - Maximum wait.
+ */
+async function waitUntil(predicate, timeoutMs = 1_000) {
+  const deadline = Date.now() + timeoutMs
+  while (!predicate()) {
+    if (Date.now() >= deadline) throw new Error("timed out waiting for condition")
+    await new Promise((resolve) => setTimeout(resolve, 2))
+  }
+}
+
+/**
+ * @template T
+ * @param {Promise<T>} promise - Operation to bound.
+ * @param {string} message - Timeout error.
+ * @returns {Promise<T>} Bounded operation.
+ */
+function withDeadline(promise, message) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(message)), 250)
+    promise.then(
+      (value) => {
+        clearTimeout(timer)
+        resolve(value)
+      },
+      (error) => {
+        clearTimeout(timer)
+        reject(error)
+      }
+    )
+  })
+}
+
+/**
+ * @param {SocketductSocket} socket - Socket to read from.
+ * @returns {Promise<Buffer>} - Next chunk.
+ */
+async function readOnce(socket) {
+  return new Promise((resolve) => {
+    socket.once("data", (chunk) => resolve(chunk))
+  })
+}
+
+class FakeRelaySocket extends EventEmitter {
+  constructor() {
+    super()
+    this.destroyed = false
+    this.destroyCount = 0
+    this.localAddress = "127.0.0.1"
+    this.localPort = 43100
+    /** @type {Buffer[]} */
+    this.writes = []
+  }
+
+  /** @returns {this} - Destroyed fake socket. */
+  destroy() {
+    this.destroyCount += 1
+    this.destroyed = true
+    return this
+  }
+
+  /**
+   * @param {Buffer} chunk - Bytes written to the fake socket.
+   * @returns {boolean} - Always writable.
+   */
+  write(chunk) {
+    this.writes.push(chunk)
+    return true
+  }
+
+  resume() {}
+
+  pause() {}
+
+  ref() {}
+
+  unref() {}
+}
+
+/** @returns {Promise<void>} Allows queued relay-frame work to settle. */
+async function settleRelayFrames() {
+  await new Promise((resolve) => setImmediate(resolve))
+  await new Promise((resolve) => setImmediate(resolve))
+}
+
+/** @param {SocketductSocket} socket - Socket to destroy and await. */
+async function destroyAndWait(socket) {
+  if (socket.closed) return
+  const closed = new Promise((resolve) => socket.once("close", resolve))
+  socket.destroy()
+  await closed
+}
+
+/**
+ * @param {FakeRelaySocket} relaySocket - Fake relay whose writes should be decoded.
+ * @returns {import('../../../src/protocol/frame.js').FrameHeader[]} Decoded control headers.
+ */
+function writtenHeaders(relaySocket) {
+  const decoder = new FrameDecoder({compactDirection: "client-to-target"})
+  return relaySocket.writes.flatMap((write) => decoder.push(write)).map((frame) => frame.header)
+}
+
+class FakeTimers {
+  constructor() {
+    /** @type {Array<{active: boolean, callback: () => void, delay: number}>} */
+    this.timers = []
+  }
+
+  /**
+   * @param {() => void} callback - Timer callback.
+   * @param {number} delay - Timer delay.
+   * @returns {{active: boolean, callback: () => void, delay: number}} - Fake timer.
+   */
+  setTimeout(callback, delay) {
+    const timer = {active: true, callback, delay}
+
+    this.timers.push(timer)
+    return timer
+  }
+
+  /** @param {{active: boolean}} timer - Fake timer to clear. */
+  clearTimeout(timer) {
+    timer.active = false
+  }
+
+  /**
+   * @param {number} delay - Timer delay to select.
+   * @returns {{active: boolean, callback: () => void, delay: number} | undefined} - Active matching timer.
+   */
+  activeTimer(delay) {
+    return this.timers.find((timer) => timer.active && timer.delay === delay)
+  }
+
+  /**
+   * @param {{active: boolean, callback: () => void}} timer - Active timer to run.
+   * @returns {void}
+   */
+  run(timer) {
+    assert.equal(timer.active, true, "expected timer to be active")
+    timer.active = false
+    timer.callback()
+  }
+
+  /** @returns {void} - Runs the active relay connect timer. */
+  runConnectTimeout() {
+    const timer = this.timers.find((candidate) => candidate.active && candidate.delay === 10_000)
+
+    assert.ok(timer, "expected the relay connect timeout to be armed")
+    timer.active = false
+    timer.callback()
+  }
+
+  /** @returns {number} - Active reconnect timer count. */
+  activeReconnectTimers() {
+    return this.timers.filter((timer) => timer.active && timer.delay === 60_000).length
+  }
+}
+
+/**
+ * @param {{tls?: boolean}} [options]
+ * @returns {Promise<{fakeRelaySocket: FakeRelaySocket, rootDir: string, socket: SocketductSocket, timers: FakeTimers}>} - Fake client and controls.
+ */
+async function createFakeRelaySocketClient({tls = false} = {}) {
+  const {rootDir, spool} = await createTestSpool()
+  const fakeRelaySocket = new FakeRelaySocket()
+  const timers = new FakeTimers()
+  const socket = new SocketductSocket({
+    relayHost: "relay.invalid",
+    relayPort: 3100,
+    token: "token",
+    sessionName: tls ? "tls timeout" : "plain timeout",
+    target: {host: "docker-api", port: 2375},
+    spool,
+    reconnectDelayMs: 60_000,
+    ...(tls ? {tls: {rejectUnauthorized: false}} : {})
+  }, {
+    clearTimeout: (timer) => timers.clearTimeout(/** @type {{active: boolean}} */ (timer)),
+    createRelaySocket: () => /** @type {import("node:net").Socket} */ (/** @type {unknown} */ (fakeRelaySocket)),
+    setTimeout: (callback, delay) => timers.setTimeout(callback, delay)
+  })
+
+  return {fakeRelaySocket, rootDir, socket, timers}
+}
+
+test("SocketductSocket is a Duplex-compatible socket facade", async () => {
+  const {rootDir, spool} = await createTestSpool()
+  const socket = new SocketductSocket({
+    relayHost: "127.0.0.1",
+    relayPort: 3100,
+    token: "token",
+    sessionName: "unit socket",
+    target: {host: "docker-api", port: 2375},
+    spool
+  })
+
+  assert.equal(socket instanceof Duplex, true)
+  assert.equal(socket.connecting, false)
+  assert.equal(socket.pending, true)
+  assert.equal(socket.remoteAddress, "docker-api")
+  assert.equal(socket.remotePort, 2375)
+  assert.equal(socket.bytesRead, 0)
+  assert.equal(socket.bytesWritten, 0)
+  assert.equal(typeof socket.connect, "function")
+  assert.equal(socket.setNoDelay(), socket)
+  assert.equal(socket.setKeepAlive(), socket)
+  assert.equal(socket.setTimeout(0), socket)
+  assert.equal(socket.ref(), socket)
+  assert.equal(socket.unref(), socket)
+  assert.deepEqual(socket.address(), {address: "0.0.0.0", family: "IPv4", port: 0})
+
+  socket.destroy()
+  await rm(rootDir, {recursive: true, force: true})
+})
+
+test("SocketductSocket and relay reject invalid compression chunk limits", async () => {
+  const {rootDir, spool} = await createTestSpool()
+  try {
+    assert.throws(
+      () => new SocketductSocket({
+        relayHost: "127.0.0.1",
+        relayPort: 3100,
+        token: "token",
+        sessionName: "invalid compression limit",
+        target: {host: "docker-api", port: 2375},
+        spool,
+        compressionLimits: {maxDecompressedBytes: 0}
+      }),
+      /compressionLimits\.maxDecompressedBytes must be a positive safe integer/
+    )
+
+    await assert.rejects(
+      () => startTcpRelay({
+        authorizeTarget: () => false,
+        compressionLimits: {maxDecompressedBytes: 1.5},
+        tokens: new TokenStore({now: () => 1000, tokenTtlMs: 60_000}),
+        sessions: new SessionStore({now: () => 1000})
+      }),
+      /compressionLimits\.maxDecompressedBytes must be a positive safe integer/
+    )
+  } finally {
+    await rm(rootDir, {recursive: true, force: true})
+  }
+})
+
+test("SocketductSocket connect returns the socket", async () => {
+  const {rootDir, spool} = await createTestSpool()
+  const socket = new SocketductSocket({
+    relayHost: "127.0.0.1",
+    relayPort: 9,
+    token: "token",
+    sessionName: "unit socket",
+    target: {host: "docker-api", port: 2375},
+    spool,
+    reconnectDelayMs: 60_000
+  })
+
+  assert.equal(socket.connect(), socket)
+  assert.equal(socket.connecting, true)
+  socket.destroy()
+  await rm(rootDir, {recursive: true, force: true})
+})
+
+test("SocketductSocket idle timeout resets on write and read activity before firing when idle", async () => {
+  const {fakeRelaySocket, rootDir, socket, timers} = await createFakeRelaySocketClient()
+  let timeoutEvents = 0
+  socket.on("timeout", () => { timeoutEvents += 1 })
+
+  try {
+    socket.connect()
+    fakeRelaySocket.emit("connect")
+    const connected = new Promise((resolve) => socket.once("connect", resolve))
+    fakeRelaySocket.emit("data", encodeFrame({type: "session.created", identifier: "idle-timeout", framing: 2}))
+    await connected
+
+    socket.setTimeout(50)
+    const initialTimer = timers.activeTimer(50)
+    assert.ok(initialTimer, "setting an idle timeout must arm the injected scheduler")
+
+    await new Promise((resolve, reject) => {
+      socket.write("ping", (error) => error ? reject(error) : resolve(undefined))
+    })
+    const afterWriteTimer = timers.activeTimer(50)
+    assert.ok(afterWriteTimer, "write activity must leave one idle timer armed")
+    assert.notEqual(afterWriteTimer, initialTimer)
+    assert.equal(initialTimer.active, false)
+    assert.equal(timeoutEvents, 0)
+
+    const received = readOnce(socket)
+    fakeRelaySocket.emit("data", encodeCompactData({sequence: 4, payload: Buffer.from("pong")}))
+    assert.equal((await received).toString("utf8"), "pong")
+    const afterReadTimer = timers.activeTimer(50)
+    assert.ok(afterReadTimer, "read activity must leave one idle timer armed")
+    assert.notEqual(afterReadTimer, afterWriteTimer)
+    assert.equal(afterWriteTimer.active, false)
+    assert.equal(timeoutEvents, 0)
+
+    initialTimer.callback()
+    afterWriteTimer.callback()
+    assert.equal(timeoutEvents, 0, "cleared idle timer callbacks already queued before activity must be stale")
+
+    timers.run(afterReadTimer)
+    assert.equal(timeoutEvents, 1, "the current idle timer must fire without later activity")
+    socket.setTimeout(0)
+    assert.equal(timers.activeTimer(50), undefined)
+  } finally {
+    socket.setTimeout(0)
+    const closed = new Promise((resolve) => socket.once("close", resolve))
+    socket.destroy()
+    await settleRelayFrames()
+    fakeRelaySocket.emit("data", encodeFrame({type: "session.close", direction: "target-to-client", acknowledged: true}))
+    await closed
+    await rm(rootDir, {recursive: true, force: true})
+  }
+})
+
+test("SocketductSocket destroys a timed-out plain relay socket once and ignores late events", async () => {
+  const {fakeRelaySocket, rootDir, socket, timers} = await createFakeRelaySocketClient()
+  let connectEvents = 0
+  let readyEvents = 0
+
+  socket.on("connect", () => { connectEvents += 1 })
+  socket.on("ready", () => { readyEvents += 1 })
+  socket.connect()
+  timers.runConnectTimeout()
+
+  assert.equal(fakeRelaySocket.destroyCount, 1)
+  assert.equal(timers.activeReconnectTimers(), 1)
+
+  fakeRelaySocket.emit("connect")
+  fakeRelaySocket.emit("error", new Error("late connect error"))
+  fakeRelaySocket.emit("close")
+
+  assert.equal(fakeRelaySocket.destroyCount, 1)
+  assert.equal(fakeRelaySocket.writes.length, 0)
+  assert.equal(connectEvents, 0)
+  assert.equal(readyEvents, 0)
+  assert.equal(socket.connecting, true)
+  assert.equal(socket.pending, true)
+  assert.equal(timers.activeReconnectTimers(), 1)
+
+  socket.destroy()
+  await rm(rootDir, {recursive: true, force: true})
+})
+
+test("SocketductSocket destroys a timed-out TLS relay socket once and ignores late secureConnect events", async () => {
+  const {fakeRelaySocket, rootDir, socket, timers} = await createFakeRelaySocketClient({tls: true})
+  let connectEvents = 0
+  let readyEvents = 0
+
+  socket.on("connect", () => { connectEvents += 1 })
+  socket.on("ready", () => { readyEvents += 1 })
+  socket.connect()
+  timers.runConnectTimeout()
+
+  assert.equal(fakeRelaySocket.destroyCount, 1)
+  assert.equal(timers.activeReconnectTimers(), 1)
+
+  fakeRelaySocket.emit("secureConnect")
+  fakeRelaySocket.emit("error", new Error("late TLS error"))
+  fakeRelaySocket.emit("close")
+
+  assert.equal(fakeRelaySocket.destroyCount, 1)
+  assert.equal(fakeRelaySocket.writes.length, 0)
+  assert.equal(connectEvents, 0)
+  assert.equal(readyEvents, 0)
+  assert.equal(socket.connecting, true)
+  assert.equal(socket.pending, true)
+  assert.equal(timers.activeReconnectTimers(), 1)
+
+  socket.destroy()
+  await rm(rootDir, {recursive: true, force: true})
+})
+
+test("SocketductSocket rejects a legacy session handshake without framing v2", async () => {
+  const {rootDir, spool} = await createTestSpool()
+  const relay = createServer((peer) => {
+    const decoder = new FrameDecoder()
+    peer.on("data", (chunk) => {
+      const frames = decoder.push(chunk)
+      if (frames.some((frame) => frame.header.type === "session.create")) {
+        peer.write(encodeFrame({type: "session.created", identifier: "legacy-session"}))
+      }
+    })
+  })
+  const relayPort = await listen(relay)
+  const socket = new SocketductSocket({
+    relayHost: "127.0.0.1",
+    relayPort,
+    token: "token",
+    sessionName: "legacy handshake",
+    target: {host: "docker-api", port: 2375},
+    spool,
+    reconnectDelayMs: 60_000
+  })
+
+  try {
+    let connected = false
+    socket.on("connect", () => { connected = true })
+    const error = new Promise((resolve) => socket.once("error", resolve))
+    socket.connect()
+    const handshakeError = await error
+    assert.match(String(handshakeError), /required framing version 2/)
+    assert.equal(connected, false)
+    assert.deepEqual(await readdir(rootDir), [])
+  } finally {
+    socket.destroy()
+    await new Promise((resolve, reject) => relay.close((closeError) => closeError ? reject(closeError) : resolve(undefined)))
+    await rm(rootDir, {recursive: true, force: true})
+  }
+})
+
+test("SocketductSocket relays target traffic directly", async () => {
+  const {rootDir, spool} = await createTestSpool()
+  const echoServer = createServer((socket) => {
+    socket.on("data", (chunk) => socket.write(Buffer.from(`echo:${chunk.toString("utf8")}`)))
+  })
+  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"})
+  const relay = await startTcpRelay({
+    authorizeTarget: ({target}) => target.host === "127.0.0.1" && target.port === targetPort,
+    tokens,
+    sessions: new SessionStore({now: () => 1000})
+  })
+
+  const socket = new SocketductSocket({
+    relayHost: "127.0.0.1",
+    relayPort: relay.port,
+    token: token.value,
+    sessionName: "direct socket integration",
+    target: {host: "127.0.0.1", port: targetPort},
+    spool,
+    reconnectDelayMs: 10
+  })
+
+  socket.connect()
+  await new Promise((resolve, reject) => {
+    socket.once("error", reject)
+    socket.once("connect", () => {
+      socket.off("error", reject)
+      resolve(undefined)
+    })
+  })
+  socket.write("hello")
+  assert.equal((await readOnce(socket)).toString("utf8"), "echo:hello")
+  assert.equal(socket.bytesWritten, 5)
+  assert.equal(socket.bytesRead, 10)
+
+  socket.destroy()
+  await relay.close()
+  await new Promise((resolve, reject) => {
+    echoServer.close((error) => {
+      if (error) {
+        reject(error)
+        return
+      }
+      resolve(undefined)
+    })
+  })
+  await rm(rootDir, {recursive: true, force: true})
+})
+
+test("SocketductSocket end does not reopen the relay tunnel", async () => {
+  const {rootDir, spool} = await createTestSpool()
+  const echoServer = createServer((socket) => {
+    socket.on("data", (chunk) => socket.write(Buffer.from(`ended:${chunk.toString("utf8")}`)))
+  })
+  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"})
+  const relay = await startTcpRelay({
+    authorizeTarget: ({target}) => target.host === "127.0.0.1" && target.port === targetPort,
+    tokens,
+    sessions: new SessionStore({now: () => 1000})
+  })
+  let relayConnections = 0
+  relay.server.on("connection", () => {
+    relayConnections += 1
+  })
+
+  const socket = new SocketductSocket({
+    relayHost: "127.0.0.1",
+    relayPort: relay.port,
+    token: token.value,
+    sessionName: "intentional end",
+    target: {host: "127.0.0.1", port: targetPort},
+    spool,
+    reconnectDelayMs: 10
+  })
+
+  socket.connect()
+  await new Promise((resolve, reject) => {
+    socket.once("error", reject)
+    socket.once("connect", () => {
+      socket.off("error", reject)
+      resolve(undefined)
+    })
+  })
+  socket.write("bye")
+  assert.equal((await readOnce(socket)).toString("utf8"), "ended:bye")
+  socket.end()
+  await new Promise((resolve) => { setTimeout(resolve, 50) })
+  assert.equal(relayConnections, 1)
+
+  socket.destroy()
+  await relay.close()
+  await new Promise((resolve, reject) => {
+    echoServer.close((error) => {
+      if (error) {
+        reject(error)
+        return
+      }
+      resolve(undefined)
+    })
+  })
+  await rm(rootDir, {recursive: true, force: true})
+})
+
+test("SocketductSocket reconnect replays writes without re-emitting connect", async () => {
+  const {rootDir, spool} = await createTestSpool()
+  const echoServer = createServer((socket) => {
+    socket.on("data", (chunk) => socket.write(Buffer.from(`again:${chunk.toString("utf8")}`)))
+  })
+  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"})
+  const relay = await startTcpRelay({
+    authorizeTarget: ({target}) => target.host === "127.0.0.1" && target.port === targetPort,
+    tokens,
+    sessions: new SessionStore({now: () => 1000}),
+    resumeWindowMs: 1_000
+  })
+
+  const socket = new SocketductSocket({
+    relayHost: "127.0.0.1",
+    relayPort: relay.port,
+    token: token.value,
+    sessionName: "socket reconnect",
+    target: {host: "127.0.0.1", port: targetPort},
+    spool,
+    reconnectDelayMs: 10
+  })
+  try {
+    let connectEvents = 0
+    let readyEvents = 0
+    socket.on("connect", () => { connectEvents += 1 })
+    socket.on("ready", () => { readyEvents += 1 })
+
+    socket.connect()
+    await new Promise((resolve, reject) => {
+      socket.once("error", reject)
+      socket.once("connect", () => {
+        socket.off("error", reject)
+        resolve(undefined)
+      })
+    })
+    socket.write("first")
+    assert.equal((await readOnce(socket)).toString("utf8"), "again:first")
+
+    const resumed = new Promise((resolve, reject) => {
+      socket.once("error", reject)
+      socket.once("ready", () => {
+        socket.off("error", reject)
+        resolve(undefined)
+      })
+    })
+    relay.closeActiveTunnel()
+    socket.write("second")
+    await resumed
+    assert.equal((await readOnce(socket)).toString("utf8"), "again:second")
+    assert.equal(connectEvents, 1)
+    assert.equal(readyEvents >= 2, true)
+  } finally {
+    socket.destroy()
+    await relay.close()
+    await new Promise((resolve, reject) => {
+      echoServer.close((error) => {
+        if (error) {
+          reject(error)
+          return
+        }
+        resolve(undefined)
+      })
+    })
+    await rm(rootDir, {recursive: true, force: true})
+  }
+})
+
+test("SocketductSocket defers an intentional close until an in-flight reconnect is authenticated and resumed", async () => {
+  const {rootDir, spool} = await createTestSpool()
+  const firstRelay = new FakeRelaySocket()
+  const secondRelay = new FakeRelaySocket()
+  const relaySockets = [firstRelay, secondRelay]
+  const timers = new FakeTimers()
+  const socket = new SocketductSocket({
+    relayHost: "relay.invalid",
+    relayPort: 3100,
+    token: "token",
+    sessionName: "close during reconnect",
+    target: {host: "docker-api", port: 2375},
+    spool,
+    reconnectDelayMs: 60_000
+  }, {
+    clearTimeout: (timer) => timers.clearTimeout(/** @type {{active: boolean}} */ (timer)),
+    createRelaySocket: () => /** @type {import('node:net').Socket} */ (/** @type {unknown} */ (relaySockets.shift())),
+    setTimeout: (callback, delay) => timers.setTimeout(callback, delay)
+  })
+
+  try {
+    socket.connect()
+    firstRelay.emit("connect")
+    const connected = new Promise((resolve) => socket.once("connect", resolve))
+    firstRelay.emit("data", encodeFrame({type: "session.created", identifier: "close-reconnect", framing: 2}))
+    await connected
+
+    firstRelay.destroyed = true
+    firstRelay.emit("close")
+    const reconnectTimer = timers.timers.find((timer) => timer.active && timer.delay === 60_000)
+    assert.ok(reconnectTimer)
+    reconnectTimer.active = false
+    reconnectTimer.callback()
+
+    const closeEvent = new Promise((resolve) => socket.once("close", resolve))
+    socket.destroy()
+    secondRelay.emit("connect")
+    await settleRelayFrames()
+    assert.deepEqual(writtenHeaders(secondRelay).map((header) => header.type), ["session.resume"])
+
+    secondRelay.emit("data", encodeFrame({type: "session.resumed", identifier: "close-reconnect", framing: 2}))
+    await settleRelayFrames()
+    assert.deepEqual(writtenHeaders(secondRelay).map((header) => header.type), ["session.resume", "session.close"])
+    secondRelay.emit("data", encodeFrame({type: "session.close", direction: "target-to-client", acknowledged: true}))
+    await closeEvent
+    assert.equal(relaySockets.length, 0)
+    assert.equal(timers.timers.filter((timer) => timer.active).length, 0)
+    assert.equal(secondRelay.destroyCount, 1)
+    assert.equal(secondRelay.listenerCount("connect"), 0)
+    assert.equal(secondRelay.listenerCount("data"), 0)
+    assert.equal(secondRelay.listenerCount("close"), 0)
+    assert.deepEqual(await readdir(rootDir), [])
+  } finally {
+    await destroyAndWait(socket)
+    await rm(rootDir, {recursive: true, force: true})
+  }
+})
+
+test("SocketductSocket reconnects immediately to close an announced session between attempts", async () => {
+  const {rootDir, spool} = await createTestSpool()
+  const firstRelay = new FakeRelaySocket()
+  const secondRelay = new FakeRelaySocket()
+  const relaySockets = [firstRelay, secondRelay]
+  const timers = new FakeTimers()
+  const socket = new SocketductSocket({
+    relayHost: "relay.invalid",
+    relayPort: 3100,
+    token: "token",
+    sessionName: "close between reconnects",
+    target: {host: "docker-api", port: 2375},
+    spool,
+    reconnectDelayMs: 60_000
+  }, {
+    clearTimeout: (timer) => timers.clearTimeout(/** @type {{active: boolean}} */ (timer)),
+    createRelaySocket: () => /** @type {import('node:net').Socket} */ (/** @type {unknown} */ (relaySockets.shift())),
+    setTimeout: (callback, delay) => timers.setTimeout(callback, delay)
+  })
+
+  try {
+    socket.connect()
+    firstRelay.emit("connect")
+    const connected = new Promise((resolve) => socket.once("connect", resolve))
+    firstRelay.emit("data", encodeFrame({type: "session.created", identifier: "close-between", framing: 2}))
+    await connected
+    firstRelay.destroyed = true
+    firstRelay.emit("close")
+    assert.equal(timers.activeReconnectTimers(), 1)
+
+    const closeEvent = new Promise((resolve) => socket.once("close", resolve))
+    socket.destroy()
+    assert.equal(timers.activeReconnectTimers(), 0)
+    assert.equal(relaySockets.length, 0, "logical close should start its own authenticated reconnect immediately")
+    secondRelay.emit("connect")
+    await settleRelayFrames()
+    assert.deepEqual(writtenHeaders(secondRelay).map((header) => header.type), ["session.resume"])
+    secondRelay.emit("data", encodeFrame({type: "session.resumed", identifier: "close-between", framing: 2}))
+    await settleRelayFrames()
+    assert.deepEqual(writtenHeaders(secondRelay).map((header) => header.type), ["session.resume", "session.close"])
+    secondRelay.emit("data", encodeFrame({type: "session.close", direction: "target-to-client", acknowledged: true}))
+    await closeEvent
+    assert.equal(timers.timers.filter((timer) => timer.active).length, 0)
+    assert.equal(secondRelay.destroyCount, 1)
+    assert.equal(secondRelay.listenerCount("connect"), 0)
+    assert.equal(secondRelay.listenerCount("data"), 0)
+    assert.equal(secondRelay.listenerCount("close"), 0)
+    assert.deepEqual(await readdir(rootDir), [])
+  } finally {
+    await destroyAndWait(socket)
+    await rm(rootDir, {recursive: true, force: true})
+  }
+})
+
+test("SocketductSocket destroy while detached promptly removes the resumable relay session", async () => {
+  const {rootDir, spool} = await createTestSpool()
+  const targetServer = createServer((socket) => socket.on("data", (chunk) => socket.write(chunk)))
+  const targetPort = await listen(targetServer)
+  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"})
+  const relay = await startTcpRelay({
+    authorizeTarget: ({target}) => target.host === "127.0.0.1" && target.port === targetPort,
+    resumeWindowMs: 10_000,
+    sessions: new SessionStore({now: () => 1000}),
+    tokens
+  })
+  const socket = new SocketductSocket({
+    relayHost: "127.0.0.1",
+    relayPort: relay.port,
+    token: token.value,
+    sessionName: "destroy while detached",
+    target: {host: "127.0.0.1", port: targetPort},
+    spool,
+    reconnectDelayMs: 60_000
+  })
+
+  try {
+    const connected = new Promise((resolve) => socket.once("connect", resolve))
+    socket.connect()
+    await connected
+    await relay.closeActiveTunnel()
+    await waitUntil(() => relay.status().detachedSessions === 1)
+
+    await destroyAndWait(socket)
+    await waitUntil(() => relay.status().sessions === 0)
+    assert.deepEqual(relay.status(), {
+      activeTunnels: 0, activeTargets: 0, sessions: 0, attachedSessions: 0,
+      detachedSessions: 0, bufferedTargetBytes: 0, targetConnectionAttempts: 0, targetRetryTimers: 0
+    })
+    assert.deepEqual(await readdir(rootDir), [])
+  } finally {
+    await destroyAndWait(socket)
+    await relay.close()
+    await new Promise((resolve, reject) => targetServer.close((error) => error ? reject(error) : resolve(undefined)))
+    await rm(rootDir, {recursive: true, force: true})
+  }
+})
+
+test("SocketductSocket ignores queued target data after target EOF", async () => {
+  const {rootDir, spool} = await createTestSpool()
+  const relay = new FakeRelaySocket()
+  const socket = new SocketductSocket({
+    relayHost: "relay.invalid",
+    relayPort: 3100,
+    token: "token",
+    sessionName: "queued data after eof",
+    target: {host: "docker-api", port: 2375},
+    spool,
+    reconnectDelayMs: 60_000
+  }, {
+    createRelaySocket: () => /** @type {import('node:net').Socket} */ (/** @type {unknown} */ (relay))
+  })
+  /** @type {Error[]} */
+  const errors = []
+  /** @type {Buffer[]} */
+  const chunks = []
+  socket.on("error", (error) => errors.push(error))
+  socket.on("data", (chunk) => chunks.push(chunk))
+
+  try {
+    socket.connect()
+    relay.emit("connect")
+    const connected = new Promise((resolve) => socket.once("connect", resolve))
+    relay.emit("data", encodeFrame({type: "session.created", identifier: "queued-after-eof", framing: 2}))
+    await connected
+    relay.emit("data", Buffer.concat([
+      encodeFrame({type: "session.close", direction: "target-to-client"}),
+      encodeCompactData({sequence: 4, payload: Buffer.from("late")})
+    ]))
+    await settleRelayFrames()
+
+    assert.deepEqual(chunks, [])
+    assert.deepEqual(errors, [])
+    assert.equal(socket.bytesRead, 0)
+    assert.equal(socket.destroyed, false)
+    assert.equal(socket.readable, false)
+    const closed = new Promise((resolve) => socket.once("close", resolve))
+    socket.destroy()
+    await settleRelayFrames()
+    assert.equal(writtenHeaders(relay).at(-1)?.type, "session.close")
+    relay.emit("data", encodeFrame({type: "session.close", direction: "target-to-client", acknowledged: true}))
+    await withDeadline(closed, "timed out waiting for logical close acknowledgement")
+  } finally {
+    await destroyAndWait(socket)
+    await rm(rootDir, {recursive: true, force: true})
+  }
+})
+
+test("connectSocketduct creates and connects the public socket option shape", async () => {
+  const {rootDir} = await createTestSpool()
+  const echoServer = createServer((socket) => {
+    socket.on("data", (chunk) => socket.write(Buffer.from(`factory:${chunk.toString("utf8")}`)))
+  })
+  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"})
+  const relay = await startTcpRelay({
+    authorizeTarget: ({target}) => target.host === "127.0.0.1" && target.port === targetPort,
+    tokens,
+    sessions: new SessionStore({now: () => 1000})
+  })
+
+  const socket = connectSocketduct({
+    relay: {host: "127.0.0.1", port: relay.port, token: token.value},
+    sessionName: "public socket options",
+    target: {host: "127.0.0.1", port: targetPort},
+    spoolDirectory: rootDir,
+    reconnect: {initialDelayMs: 10}
+  })
+
+  await new Promise((resolve, reject) => {
+    socket.once("error", reject)
+    socket.once("connect", () => {
+      socket.off("error", reject)
+      resolve(undefined)
+    })
+  })
+  socket.write("hello")
+  assert.equal((await readOnce(socket)).toString("utf8"), "factory:hello")
+
+  socket.destroy()
+  await relay.close()
+  await new Promise((resolve, reject) => {
+    echoServer.close((error) => {
+      if (error) {
+        reject(error)
+        return
+      }
+      resolve(undefined)
+    })
+  })
+  await rm(rootDir, {recursive: true, force: true})
+})
+
+test("SocketductSocket cleans up spool directory on destroy", async () => {
+  const {rootDir, spool} = await createTestSpool()
+  const echoServer = createServer((socket) => {
+    socket.on("data", (chunk) => socket.write(Buffer.from(`cleanup:${chunk.toString("utf8")}`)))
+  })
+  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"})
+  const relay = await startTcpRelay({
+    authorizeTarget: ({target}) => target.host === "127.0.0.1" && target.port === targetPort,
+    tokens,
+    sessions: new SessionStore({now: () => 1000})
+  })
+
+  const socket = new SocketductSocket({
+    relayHost: "127.0.0.1",
+    relayPort: relay.port,
+    token: token.value,
+    sessionName: "spool cleanup on destroy",
+    target: {host: "127.0.0.1", port: targetPort},
+    spool,
+    reconnectDelayMs: 10
+  })
+
+  socket.connect()
+  await new Promise((resolve, reject) => {
+    socket.once("error", reject)
+    socket.once("connect", () => {
+      socket.off("error", reject)
+      resolve(undefined)
+    })
+  })
+  socket.write("hello")
+  assert.equal((await readOnce(socket)).toString("utf8"), "cleanup:hello")
+
+  const closePromise = new Promise((resolve, hookReject) => {
+    socket.on("error", hookReject)
+    socket.on("close", () => {
+      socket.off("error", hookReject)
+      resolve(undefined)
+    })
+  })
+  socket.destroy()
+  await closePromise
+
+  const {readdir} = await import("node:fs/promises")
+  const entries = await readdir(rootDir)
+  assert.deepEqual(entries, [])
+
+  await relay.close()
+  await new Promise((resolve, reject) => {
+    echoServer.close((error) => {
+      if (error) {
+        reject(error)
+        return
+      }
+      resolve(undefined)
+    })
+  })
+  await rm(rootDir, {recursive: true, force: true})
+})
+
+test("SocketductSocket end cleans up spool directory before finish event", async () => {
+  const {rootDir, spool} = await createTestSpool()
+  const echoServer = createServer((socket) => {
+    socket.on("data", (chunk) => socket.write(Buffer.from(`endclean:${chunk.toString("utf8")}`)))
+  })
+  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"})
+  const relay = await startTcpRelay({
+    authorizeTarget: ({target}) => target.host === "127.0.0.1" && target.port === targetPort,
+    tokens,
+    sessions: new SessionStore({now: () => 1000})
+  })
+
+  const socket = new SocketductSocket({
+    relayHost: "127.0.0.1",
+    relayPort: relay.port,
+    token: token.value,
+    sessionName: "spool cleanup on end",
+    target: {host: "127.0.0.1", port: targetPort},
+    spool,
+    reconnectDelayMs: 10
+  })
+
+  socket.connect()
+  await new Promise((resolve, reject) => {
+    socket.once("error", reject)
+    socket.once("connect", () => {
+      socket.off("error", reject)
+      resolve(undefined)
+    })
+  })
+  socket.write("endtest")
+
+  const finishPromise = new Promise((resolve, hookReject) => {
+    socket.on("error", hookReject)
+    socket.on("finish", () => {
+      socket.off("error", hookReject)
+      resolve(undefined)
+    })
+  })
+  socket.end()
+  await finishPromise
+
+  const {readdir: readdir2} = await import("node:fs/promises")
+  const entries2 = await readdir2(rootDir)
+  assert.deepEqual(entries2, [])
+
+  socket.destroy()
+  await relay.close()
+  await new Promise((resolve, reject) => {
+    echoServer.close((error) => {
+      if (error) {
+        reject(error)
+        return
+      }
+      resolve(undefined)
+    })
+  })
+  await rm(rootDir, {recursive: true, force: true})
+})
+
+test("connectSocketduct forwards maxBytes to spool storage", async () => {
+  const rootDir2 = await mkdtemp(join(tmpdir(), "socketduct-socket-test-"))
+  const echoServer = createServer((socket) => {
+    socket.on("data", (chunk) => socket.write(Buffer.from(`maxbytes:${chunk.toString("utf8")}`)))
+  })
+  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"})
+  const relay = await startTcpRelay({
+    authorizeTarget: ({target}) => target.host === "127.0.0.1" && target.port === targetPort,
+    tokens,
+    sessions: new SessionStore({now: () => 1000})
+  })
+
+  const socket = connectSocketduct({
+    relay: {host: "127.0.0.1", port: relay.port, token: token.value},
+    sessionName: "public maxBytes",
+    target: {host: "127.0.0.1", port: targetPort},
+    spoolDirectory: rootDir2,
+    maxBytes: 50,
+    reconnect: {initialDelayMs: 10}
+  })
+
+  await new Promise((resolve, reject) => {
+    socket.once("error", reject)
+    socket.once("connect", () => {
+      socket.off("error", reject)
+      resolve(undefined)
+    })
+  })
+
+  socket.write(Buffer.alloc(60))
+  const errorPromise = new Promise((resolve) => {
+    socket.once("error", (err) => resolve(err))
+  })
+  const timeout = new Promise((resolve) => setTimeout(() => resolve(null), 500))
+  const result = await Promise.race([errorPromise, timeout])
+  assert.ok(result instanceof Error, "Expected spool quota error to surface as an error event")
+
+  socket.destroy()
+  await relay.close()
+  await new Promise((resolve, reject) => {
+    echoServer.close((error) => {
+      if (error) {
+        reject(error)
+        return
+      }
+      resolve(undefined)
+    })
+  })
+  await rm(rootDir2, {recursive: true, force: true})
+})
+
+test("createSocketductConnectionFactory forwards maxAgeMs to factory options", async () => {
+  const {createSocketductConnectionFactory} = await import("../../../src/client/connect.js")
+
+  const spoolDir = await mkdtemp(join(tmpdir(), "socketduct-factory-test-"))
+  try {
+    const factory = createSocketductConnectionFactory({
+      relay: {host: "127.0.0.1", port: 9999, token: "test-token"},
+      spoolDirectory: spoolDir,
+      maxAgeMs: 1
+    })
+
+    const socket = factory({host: "127.0.0.1", port: 2375})
+    assert.ok(socket instanceof SocketductSocket)
+
+    socket.destroy()
+  } finally {
+    await rm(spoolDir, {recursive: true, force: true})
+  }
+})
+
+test("SocketductHttpAgent forwards maxBytes to createConnection sockets", async () => {
+  const {SocketductHttpAgent} = await import("../../../src/client/http-agent.js")
+
+  const spoolDir = await mkdtemp(join(tmpdir(), "socketduct-agent-test-"))
+  try {
+    const agent = new SocketductHttpAgent({
+      relay: {host: "127.0.0.1", port: 9999, token: "test-token"},
+      target: {host: "127.0.0.1", port: 2375},
+      spoolDirectory: spoolDir,
+      maxBytes: 200
+    })
+
+    const socket = agent.createConnection({})
+    assert.ok(socket instanceof SocketductSocket)
+
+    socket.destroy()
+  } finally {
+    await rm(spoolDir, {recursive: true, force: true})
+  }
+})