socketduct 0.1.24 → 0.1.26

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

@@ -1,11 +1,10 @@
-import assert from "node:assert/strict"
+import {describe, expect, it} from "@velocious/testing"
 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"
@@ -180,7 +179,7 @@ class FakeTimers {
    * @returns {void}
    */
   run(timer) {
-    assert.equal(timer.active, true, "expected timer to be active")
+    expect(timer.active).toBe(true) // expected timer to be active
     timer.active = false
     timer.callback()
   }
@@ -188,8 +187,8 @@ class FakeTimers {
   /** @returns {void} - Runs the active relay connect timer. */
   runConnectTimeout() {
     const timer = this.timers.find((candidate) => candidate.active && candidate.delay === 10_000)
+    if (!timer) throw new Error("expected active relay connect timer")
 
-    assert.ok(timer, "expected the relay connect timeout to be armed")
     timer.active = false
     timer.callback()
   }
@@ -226,41 +225,41 @@ async function createFakeRelaySocketClient({tls = false} = {}) {
   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
-  })
+describe("SocketductSocket", () => {
+  it("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})
+    expect(socket instanceof Duplex).toBe(true)
+    expect(socket.connecting).toBe(false)
+    expect(socket.pending).toBe(true)
+    expect(socket.remoteAddress).toBe("docker-api")
+    expect(socket.remotePort).toBe(2375)
+    expect(socket.bytesRead).toBe(0)
+    expect(socket.bytesWritten).toBe(0)
+    expect(typeof socket.connect).toBe("function")
+    expect(socket.setNoDelay()).toBe(socket)
+    expect(socket.setKeepAlive()).toBe(socket)
+    expect(socket.setTimeout(0)).toBe(socket)
+    expect(socket.ref()).toBe(socket)
+    expect(socket.unref()).toBe(socket)
+    expect(socket.address()).toEqual({address: "0.0.0.0", family: "IPv4", port: 0})
 
-  socket.destroy()
-  await rm(rootDir, {recursive: true, force: true})
-})
+    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({
+  it("SocketductSocket and relay reject invalid compression chunk limits", async () => {
+    const {rootDir, spool} = await createTestSpool()
+    try {
+      expect(() => new SocketductSocket({
         relayHost: "127.0.0.1",
         relayPort: 3100,
         token: "token",
@@ -268,336 +267,215 @@ test("SocketductSocket and relay reject invalid compression chunk limits", async
         target: {host: "docker-api", port: 2375},
         spool,
         compressionLimits: {maxDecompressedBytes: 0}
-      }),
-      /compressionLimits\.maxDecompressedBytes must be a positive safe integer/
-    )
+      })).toThrow(/compressionLimits\.maxDecompressedBytes must be a positive safe integer/)
 
-    await assert.rejects(
-      () => startTcpRelay({
+      await expect(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
+      })).rejects.toThrow(/compressionLimits\.maxDecompressedBytes must be a positive safe integer/)
+    } finally {
+      await rm(rootDir, {recursive: true, force: true})
+    }
   })
 
-  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))
+  it("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
     })
-    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))
+
+    expect(socket.connect()).toBe(socket)
+    expect(socket.connecting).toBe(true)
     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()
+  it("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)
+      expect(initialTimer).toBeDefined() // setting an idle timeout must arm the injected scheduler
+      if (!initialTimer) throw new Error("expected initial idle timer to be armed")
+
+      await new Promise((resolve, reject) => {
+        socket.write("ping", (error) => error ? reject(error) : resolve(undefined))
+      })
+      const afterWriteTimer = timers.activeTimer(50)
+      expect(afterWriteTimer).toBeDefined() // write activity must leave one idle timer armed
+      if (!afterWriteTimer) throw new Error("expected idle timer after write")
+      expect(afterWriteTimer).not.toBe(initialTimer)
+      expect(initialTimer.active).toBe(false)
+      expect(timeoutEvents).toBe(0)
+
+      const received = readOnce(socket)
+      fakeRelaySocket.emit("data", encodeCompactData({sequence: 4, payload: Buffer.from("pong")}))
+      expect((await received).toString("utf8")).toBe("pong")
+      const afterReadTimer = timers.activeTimer(50)
+      expect(afterReadTimer).toBeDefined() // read activity must leave one idle timer armed
+      if (!afterReadTimer) throw new Error("expected idle timer after read")
+      expect(afterReadTimer).not.toBe(afterWriteTimer)
+      expect(afterWriteTimer.active).toBe(false)
+      expect(timeoutEvents).toBe(0)
+
+      initialTimer.callback()
+      afterWriteTimer.callback()
+      expect(timeoutEvents).toBe(0) // cleared idle timer callbacks already queued before activity must be stale
+
+      timers.run(afterReadTimer)
+      expect(timeoutEvents).toBe(1) // the current idle timer must fire without later activity
+      socket.setTimeout(0)
+      expect(timers.activeTimer(50)).toBe(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})
+    }
+  })
 
-  assert.equal(fakeRelaySocket.destroyCount, 1)
-  assert.equal(timers.activeReconnectTimers(), 1)
+  it("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
 
-  fakeRelaySocket.emit("connect")
-  fakeRelaySocket.emit("error", new Error("late connect error"))
-  fakeRelaySocket.emit("close")
+    socket.on("connect", () => { connectEvents += 1 })
+    socket.on("ready", () => { readyEvents += 1 })
+    socket.connect()
+    timers.runConnectTimeout()
 
-  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)
+    expect(fakeRelaySocket.destroyCount).toBe(1)
+    expect(timers.activeReconnectTimers()).toBe(1)
 
-  socket.destroy()
-  await rm(rootDir, {recursive: true, force: true})
-})
+    fakeRelaySocket.emit("connect")
+    fakeRelaySocket.emit("error", new Error("late connect error"))
+    fakeRelaySocket.emit("close")
 
-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
+    expect(fakeRelaySocket.destroyCount).toBe(1)
+    expect(fakeRelaySocket.writes.length).toBe(0)
+    expect(connectEvents).toBe(0)
+    expect(readyEvents).toBe(0)
+    expect(socket.connecting).toBe(true)
+    expect(socket.pending).toBe(true)
+    expect(timers.activeReconnectTimers()).toBe(1)
 
-  socket.on("connect", () => { connectEvents += 1 })
-  socket.on("ready", () => { readyEvents += 1 })
-  socket.connect()
-  timers.runConnectTimeout()
+    socket.destroy()
+    await rm(rootDir, {recursive: true, force: true})
+  })
 
-  assert.equal(fakeRelaySocket.destroyCount, 1)
-  assert.equal(timers.activeReconnectTimers(), 1)
+  it("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
 
-  fakeRelaySocket.emit("secureConnect")
-  fakeRelaySocket.emit("error", new Error("late TLS error"))
-  fakeRelaySocket.emit("close")
+    socket.on("connect", () => { connectEvents += 1 })
+    socket.on("ready", () => { readyEvents += 1 })
+    socket.connect()
+    timers.runConnectTimeout()
 
-  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)
+    expect(fakeRelaySocket.destroyCount).toBe(1)
+    expect(timers.activeReconnectTimers()).toBe(1)
 
-  socket.destroy()
-  await rm(rootDir, {recursive: true, force: true})
-})
+    fakeRelaySocket.emit("secureConnect")
+    fakeRelaySocket.emit("error", new Error("late TLS error"))
+    fakeRelaySocket.emit("close")
 
-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
-  })
+    expect(fakeRelaySocket.destroyCount).toBe(1)
+    expect(fakeRelaySocket.writes.length).toBe(0)
+    expect(connectEvents).toBe(0)
+    expect(readyEvents).toBe(0)
+    expect(socket.connecting).toBe(true)
+    expect(socket.pending).toBe(true)
+    expect(timers.activeReconnectTimers()).toBe(1)
 
-  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)
+  it("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"}))
+        }
+      })
     })
-  })
-  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)
+    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
     })
-  })
-  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
+    try {
+      let connected = false
+      socket.on("connect", () => { connected = true })
+      const error = new Promise((resolve) => socket.once("error", resolve))
+      socket.connect()
+      const handshakeError = await error
+      expect(String(handshakeError)).toMatch(/required framing version 2/)
+      expect(connected).toBe(false)
+      expect(await readdir(rootDir)).toEqual([])
+    } finally {
+      socket.destroy()
+      await new Promise((resolve, reject) => relay.close((closeError) => closeError ? reject(closeError) : resolve(undefined)))
+      await rm(rootDir, {recursive: true, force: true})
+    }
   })
 
-  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)
+  it("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")}`)))
     })
-  })
-  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)
+    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})
     })
-  })
-  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 })
+    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) => {
@@ -607,23 +485,70 @@ test("SocketductSocket reconnect replays writes without re-emitting connect", as
         resolve(undefined)
       })
     })
-    socket.write("first")
-    assert.equal((await readOnce(socket)).toString("utf8"), "again:first")
+    socket.write("hello")
+    expect((await readOnce(socket)).toString("utf8")).toBe("echo:hello")
+    expect(socket.bytesWritten).toBe(5)
+    expect(socket.bytesRead).toBe(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})
+  })
+
+  it("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
+    })
 
-    const resumed = new Promise((resolve, reject) => {
+    socket.connect()
+    await new Promise((resolve, reject) => {
       socket.once("error", reject)
-      socket.once("ready", () => {
+      socket.once("connect", () => {
         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.write("bye")
+    expect((await readOnce(socket)).toString("utf8")).toBe("ended:bye")
+    socket.end()
+    await new Promise((resolve) => { setTimeout(resolve, 50) })
+    expect(relayConnections).toBe(1)
+
     socket.destroy()
     await relay.close()
     await new Promise((resolve, reject) => {
@@ -636,489 +561,561 @@ test("SocketductSocket reconnect replays writes without re-emitting connect", as
       })
     })
     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})
-  }
-})
+  it("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
+    })
 
-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)
+    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")
+      expect((await readOnce(socket)).toString("utf8")).toBe("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
+      expect((await readOnce(socket)).toString("utf8")).toBe("again:second")
+      expect(connectEvents).toBe(1)
+      expect(readyEvents >= 2).toBe(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})
+    }
   })
 
-  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})
-  }
-})
+  it("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)
+    })
 
-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 {
+      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)
+      expect(reconnectTimer).toBeDefined()
+      if (!reconnectTimer) throw new Error("expected active reconnect timer")
+      reconnectTimer.active = false
+      reconnectTimer.callback()
+
+      const closeEvent = new Promise((resolve) => socket.once("close", resolve))
+      socket.destroy()
+      secondRelay.emit("connect")
+      await settleRelayFrames()
+      expect(writtenHeaders(secondRelay).map((header) => header.type)).toEqual(["session.resume"])
+
+      secondRelay.emit("data", encodeFrame({type: "session.resumed", identifier: "close-reconnect", framing: 2}))
+      await settleRelayFrames()
+      expect(writtenHeaders(secondRelay).map((header) => header.type)).toEqual(["session.resume", "session.close"])
+      secondRelay.emit("data", encodeFrame({type: "session.close", direction: "target-to-client", acknowledged: true}))
+      await closeEvent
+      expect(relaySockets.length).toBe(0)
+      expect(timers.timers.filter((timer) => timer.active).length).toBe(0)
+      expect(secondRelay.destroyCount).toBe(1)
+      expect(secondRelay.listenerCount("connect")).toBe(0)
+      expect(secondRelay.listenerCount("data")).toBe(0)
+      expect(secondRelay.listenerCount("close")).toBe(0)
+      expect(await readdir(rootDir)).toEqual([])
+    } finally {
+      await destroyAndWait(socket)
+      await rm(rootDir, {recursive: true, force: true})
+    }
   })
 
-  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
+  it("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)
     })
-    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))
+    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")
+      expect(timers.activeReconnectTimers()).toBe(1)
+
+      const closeEvent = new Promise((resolve) => socket.once("close", resolve))
+      socket.destroy()
+      expect(timers.activeReconnectTimers()).toBe(0)
+      expect(relaySockets.length).toBe(0) // logical close should start its own authenticated reconnect immediately
+      secondRelay.emit("connect")
+      await settleRelayFrames()
+      expect(writtenHeaders(secondRelay).map((header) => header.type)).toEqual(["session.resume"])
+      secondRelay.emit("data", encodeFrame({type: "session.resumed", identifier: "close-between", framing: 2}))
+      await settleRelayFrames()
+      expect(writtenHeaders(secondRelay).map((header) => header.type)).toEqual(["session.resume", "session.close"])
+      secondRelay.emit("data", encodeFrame({type: "session.close", direction: "target-to-client", acknowledged: true}))
+      await closeEvent
+      expect(timers.timers.filter((timer) => timer.active).length).toBe(0)
+      expect(secondRelay.destroyCount).toBe(1)
+      expect(secondRelay.listenerCount("connect")).toBe(0)
+      expect(secondRelay.listenerCount("data")).toBe(0)
+      expect(secondRelay.listenerCount("close")).toBe(0)
+      expect(await readdir(rootDir)).toEqual([])
+    } finally {
+      await destroyAndWait(socket)
+      await rm(rootDir, {recursive: true, force: true})
+    }
   })
-  /** @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})
-  })
+  it("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
+    })
 
-  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}
+    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)
+      expect(relay.status()).toEqual({
+        activeTunnels: 0, activeTargets: 0, sessions: 0, attachedSessions: 0,
+        detachedSessions: 0, bufferedTargetBytes: 0, targetConnectionAttempts: 0, targetRetryTimers: 0
+      })
+      expect(await readdir(rootDir)).toEqual([])
+    } 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})
+    }
   })
 
-  await new Promise((resolve, reject) => {
-    socket.once("error", reject)
-    socket.once("connect", () => {
-      socket.off("error", reject)
-      resolve(undefined)
+  it("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()
+
+      expect(chunks).toEqual([])
+      expect(errors).toEqual([])
+      expect(socket.bytesRead).toBe(0)
+      expect(socket.destroyed).toBe(false)
+      expect(socket.readable).toBe(false)
+      const closed = new Promise((resolve) => socket.once("close", resolve))
+      socket.destroy()
+      await settleRelayFrames()
+      expect(writtenHeaders(relay).at(-1)?.type).toBe("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})
+    }
   })
-  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)
+  it("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})
     })
-  })
-  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 = 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}
+    })
 
-  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
-  })
+    await new Promise((resolve, reject) => {
+      socket.once("error", reject)
+      socket.once("connect", () => {
+        socket.off("error", reject)
+        resolve(undefined)
+      })
+    })
+    socket.write("hello")
+    expect((await readOnce(socket)).toString("utf8")).toBe("factory:hello")
 
-  socket.connect()
-  await new Promise((resolve, reject) => {
-    socket.once("error", reject)
-    socket.once("connect", () => {
-      socket.off("error", reject)
-      resolve(undefined)
+    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})
   })
-  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)
+  it("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})
     })
-  })
-  socket.destroy()
-  await closePromise
 
-  const {readdir} = await import("node:fs/promises")
-  const entries = await readdir(rootDir)
-  assert.deepEqual(entries, [])
+    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
+    })
 
-  await relay.close()
-  await new Promise((resolve, reject) => {
-    echoServer.close((error) => {
-      if (error) {
-        reject(error)
-        return
-      }
-      resolve(undefined)
+    socket.connect()
+    await new Promise((resolve, reject) => {
+      socket.once("error", reject)
+      socket.once("connect", () => {
+        socket.off("error", reject)
+        resolve(undefined)
+      })
     })
-  })
-  await rm(rootDir, {recursive: true, force: true})
-})
+    socket.write("hello")
+    expect((await readOnce(socket)).toString("utf8")).toBe("cleanup:hello")
 
-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 closePromise = new Promise((resolve, hookReject) => {
+      socket.on("error", hookReject)
+      socket.on("close", () => {
+        socket.off("error", hookReject)
+        resolve(undefined)
+      })
+    })
+    socket.destroy()
+    await closePromise
 
-  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
-  })
+    const entries = await readdir(rootDir)
+    expect(entries).toEqual([])
 
-  socket.connect()
-  await new Promise((resolve, reject) => {
-    socket.once("error", reject)
-    socket.once("connect", () => {
-      socket.off("error", reject)
-      resolve(undefined)
+    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})
   })
-  socket.write("endtest")
 
-  const finishPromise = new Promise((resolve, hookReject) => {
-    socket.on("error", hookReject)
-    socket.on("finish", () => {
-      socket.off("error", hookReject)
-      resolve(undefined)
+  it("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})
     })
-  })
-  socket.end()
-  await finishPromise
 
-  const {readdir: readdir2} = await import("node:fs/promises")
-  const entries2 = await readdir2(rootDir)
-  assert.deepEqual(entries2, [])
+    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.destroy()
-  await relay.close()
-  await new Promise((resolve, reject) => {
-    echoServer.close((error) => {
-      if (error) {
-        reject(error)
-        return
-      }
-      resolve(undefined)
+    socket.connect()
+    await new Promise((resolve, reject) => {
+      socket.once("error", reject)
+      socket.once("connect", () => {
+        socket.off("error", reject)
+        resolve(undefined)
+      })
     })
-  })
-  await rm(rootDir, {recursive: true, force: true})
-})
+    socket.write("endtest")
 
-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 finishPromise = new Promise((resolve, hookReject) => {
+      socket.on("error", hookReject)
+      socket.on("finish", () => {
+        socket.off("error", hookReject)
+        resolve(undefined)
+      })
+    })
+    socket.end()
+    await finishPromise
 
-  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}
-  })
+    const entries2 = await readdir(rootDir)
+    expect(entries2).toEqual([])
 
-  await new Promise((resolve, reject) => {
-    socket.once("error", reject)
-    socket.once("connect", () => {
-      socket.off("error", reject)
-      resolve(undefined)
+    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})
   })
 
-  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)
+  it("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})
     })
-  })
-  await rm(rootDir2, {recursive: true, force: true})
-})
 
-test("createSocketductConnectionFactory forwards maxAgeMs to factory options", async () => {
-  const {createSocketductConnectionFactory} = await import("../../../src/client/connect.js")
+    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}
+    })
 
-  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
+    await new Promise((resolve, reject) => {
+      socket.once("error", reject)
+      socket.once("connect", () => {
+        socket.off("error", reject)
+        resolve(undefined)
+      })
     })
 
-    const socket = factory({host: "127.0.0.1", port: 2375})
-    assert.ok(socket instanceof SocketductSocket)
+    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])
+    expect(result).toBeInstanceOf(Error) // Expected spool quota error to surface as an error event
 
     socket.destroy()
-  } finally {
-    await rm(spoolDir, {recursive: true, force: true})
-  }
-})
+    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("SocketductHttpAgent forwards maxBytes to createConnection sockets", async () => {
-  const {SocketductHttpAgent} = await import("../../../src/client/http-agent.js")
+  it("createSocketductConnectionFactory forwards maxAgeMs to factory options", async () => {
+    const {createSocketductConnectionFactory} = await import("../../../src/client/connect.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 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 = agent.createConnection({})
-    assert.ok(socket instanceof SocketductSocket)
+      const socket = factory({host: "127.0.0.1", port: 2375})
+      expect(socket).toBeInstanceOf(SocketductSocket)
 
-    socket.destroy()
-  } finally {
-    await rm(spoolDir, {recursive: true, force: true})
-  }
+      socket.destroy()
+    } finally {
+      await rm(spoolDir, {recursive: true, force: true})
+    }
+  })
+
+  it("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({})
+      expect(socket).toBeInstanceOf(SocketductSocket)
+
+      socket.destroy()
+    } finally {
+      await rm(spoolDir, {recursive: true, force: true})
+    }
+  })
 })