socketduct 0.1.15

package/test/integration/multiplexed-corrections.test.js

@@ -0,0 +1,551 @@
+/* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-returns */
+import assert from "node:assert/strict"
+import {mkdir, mkdtemp, rm, writeFile} from "node:fs/promises"
+import {createConnection, createServer} from "node:net"
+import {tmpdir} from "node:os"
+import {join} from "node:path"
+import {Duplex} from "node:stream"
+import test from "node:test"
+
+import {StaticTokenStore} from "../../src/auth/static-token-store.js"
+import {MultiplexedSocketductConnection} from "../../src/client/multiplexed-connection.js"
+import {decodeV3Control, encodeV3Control, encodeV3Frame, V3FrameDecoder, V3FrameType} from "../../src/protocol/v3-frame.js"
+import {startMultiplexedTcpRelay} from "../../src/proxy/multiplexed-relay.js"
+import {SessionSpool} from "../../src/spool/spool-file.js"
+
+/** @type {WeakMap<import('node:net').Server, Set<import('node:net').Socket>>} */
+const socketsByServer = new WeakMap()
+
+/** @param {import('node:net').Server} server - Server. @returns {Promise<number>} */
+async function listen(server) {
+  const sockets = new Set()
+  socketsByServer.set(server, sockets)
+  server.on("connection", (socket) => {
+    sockets.add(socket)
+    socket.once("close", () => sockets.delete(socket))
+  })
+  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()
+  assert(address !== null && typeof address !== "string")
+  return address.port
+}
+
+/** @param {import('node:net').Server} server - Server. @returns {Promise<void>} */
+async function closeServer(server) {
+  for (const socket of socketsByServer.get(server) ?? []) socket.destroy()
+  if (server.listening) await new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve(undefined)))
+}
+
+/**
+ * @param {import('node:events').EventEmitter} emitter - Emitter.
+ * @param {string} event - Event.
+ * @returns {Promise<unknown[]>} Event arguments.
+ */
+async function onceEvent(emitter, event) {
+  return await new Promise((resolve, reject) => {
+    emitter.once("error", reject)
+    /** @param {...unknown} values - Event arguments. */
+    const onEvent = (...values) => { emitter.off("error", reject); resolve(values) }
+    emitter.once(event, onEvent)
+  })
+}
+
+/** @param {import('node:stream').Duplex} socket - Socket. @returns {Promise<Error & {code?: string}>} */
+async function nextError(socket) {
+  return await new Promise((resolve) => socket.once("error", (error) => resolve(/** @type {Error & {code?: string}} */ (error))))
+}
+
+/**
+ * @param {() => boolean} predicate - Condition.
+ * @param {number} [timeoutMs] - Deadline.
+ * @returns {Promise<void>} Completion.
+ */
+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, 5))
+  }
+}
+
+/** @returns {StaticTokenStore} Test token store. */
+function tokens() {
+  return new StaticTokenStore([{username: "edge", token: "valid-token"}])
+}
+
+/**
+ * Creates a frame-aware TCP fault proxy. Only the first physical generation is
+ * faulted; later generations pass through unchanged.
+ * @param {number} relayPort - Upstream relay port.
+ * @param {"drop-client-window" | "drop-second-relay-data" | "observe-client"} mode - Injected loss or observation.
+ */
+async function createFaultProxy(relayPort, mode) {
+  let accepts = 0
+  let faultTriggered = false
+  /** @type {import('../../src/protocol/v3-frame.js').V3Frame[]} */
+  const clientFrames = []
+  const proxy = createServer((downstream) => {
+    accepts += 1
+    const generation = accepts
+    const upstream = createConnection({host: "127.0.0.1", port: relayPort})
+    if (generation !== 1) {
+      downstream.pipe(upstream)
+      upstream.pipe(downstream)
+      return
+    }
+    const clientDecoder = new V3FrameDecoder({maxFrameBytes: 64 * 1024, maxBufferedBytes: 128 * 1024})
+    const relayDecoder = new V3FrameDecoder({maxFrameBytes: 64 * 1024, maxBufferedBytes: 128 * 1024})
+    let clientDataBytes = 0
+    let relayDataFrames = 0
+    const sever = () => {
+      if (faultTriggered) return
+      faultTriggered = true
+      downstream.destroy()
+      upstream.destroy()
+    }
+    downstream.on("data", (chunk) => {
+      for (const frame of clientDecoder.push(chunk)) {
+        clientFrames.push(frame)
+        if (mode === "drop-client-window" && frame.type === V3FrameType.DATA) {
+          clientDataBytes += frame.payload.length
+          if (clientDataBytes >= 32) sever()
+          continue
+        }
+        upstream.write(encodeV3Frame(frame, frame.payload))
+      }
+    })
+    upstream.on("data", (chunk) => {
+      for (const frame of relayDecoder.push(chunk)) {
+        if (mode === "drop-second-relay-data" && frame.type === V3FrameType.DATA) {
+          relayDataFrames += 1
+          if (relayDataFrames === 2) {
+            sever()
+            continue
+          }
+        }
+        downstream.write(encodeV3Frame(frame, frame.payload))
+      }
+    })
+    downstream.on("error", () => {})
+    upstream.on("error", () => {})
+    downstream.once("close", () => upstream.destroy())
+    upstream.once("close", () => downstream.destroy())
+  })
+  const port = await listen(proxy)
+  return {proxy, port, status: () => ({accepts, faultTriggered, clientFrames})}
+}
+
+/**
+ * Minimal v3 endpoint: the configured number of first accepts stay silent,
+ * then AUTH and OPEN complete successfully.
+ * @param {number} blackholeAccepts - Silent physical accepts.
+ */
+async function createBlackholeThenReadyServer(blackholeAccepts) {
+  let accepts = 0
+  const server = createServer((socket) => {
+    accepts += 1
+    if (accepts <= blackholeAccepts) return
+    const decoder = new V3FrameDecoder()
+    socket.on("data", (chunk) => {
+      for (const frame of decoder.push(chunk)) {
+        if (frame.type === V3FrameType.AUTH) {
+          const auth = decodeV3Control(frame.payload)
+          socket.write(encodeV3Frame({type: V3FrameType.AUTH_OK, streamId: 0, sequence: frame.sequence}, encodeV3Control({
+            version: 3,
+            connectionId: auth.connectionId,
+            generation: auth.generation,
+            resumed: false
+          })))
+        } else if (frame.type === V3FrameType.OPEN) {
+          const opened = decodeV3Control(frame.payload)
+          socket.write(encodeV3Frame({type: V3FrameType.OPENED, streamId: frame.streamId, sequence: 0}, encodeV3Control({
+            identifier: opened.identifier,
+            initialWindow: 32
+          })))
+        }
+      }
+    })
+  })
+  const port = await listen(server)
+  return {server, port, status: () => ({accepts})}
+}
+
+test("a full lost client window is credited again before replay", async (t) => {
+  let received = Buffer.alloc(0)
+  const target = createServer((socket) => socket.on("data", (chunk) => { received = Buffer.concat([received, chunk]) }))
+  const targetPort = await listen(target)
+  t.after(() => closeServer(target))
+  const relay = await startMultiplexedTcpRelay({tokens: tokens(), authorizeTarget: ({target: requested}) => requested.port === targetPort, initialWindowBytes: 32, maxFrameBytes: 32})
+  t.after(() => relay.close())
+  const fault = await createFaultProxy(relay.port, "drop-client-window")
+  t.after(() => closeServer(fault.proxy))
+  const connection = new MultiplexedSocketductConnection({relay: {host: "127.0.0.1", port: fault.port, token: "valid-token"}, initialWindowBytes: 32, maxFrameBytes: 32, reconnectDelayMs: 10})
+  t.after(() => connection.close())
+  const socket = connection.createConnection({host: "127.0.0.1", port: targetPort})
+  await onceEvent(socket, "connect")
+  socket.write(Buffer.alloc(32, 0x61))
+  await waitUntil(() => fault.status().faultTriggered)
+  await waitUntil(() => received.length === 32)
+  assert.equal(received.toString(), "a".repeat(32))
+  assert.equal(fault.status().accepts, 2)
+})
+
+test("partial target replay is delivered exactly once after reconnect", async (t) => {
+  const payload = Buffer.from("0123456789abcdefABCDEFGHIJKLMNOP")
+  const target = createServer((socket) => socket.write(payload))
+  const targetPort = await listen(target)
+  t.after(() => closeServer(target))
+  const relay = await startMultiplexedTcpRelay({tokens: tokens(), authorizeTarget: ({target: requested}) => requested.port === targetPort, initialWindowBytes: 32, maxFrameBytes: 16})
+  t.after(() => relay.close())
+  const fault = await createFaultProxy(relay.port, "drop-second-relay-data")
+  t.after(() => closeServer(fault.proxy))
+  const connection = new MultiplexedSocketductConnection({relay: {host: "127.0.0.1", port: fault.port, token: "valid-token"}, initialWindowBytes: 32, maxFrameBytes: 16, reconnectDelayMs: 10})
+  t.after(() => connection.close())
+  const socket = connection.createConnection({host: "127.0.0.1", port: targetPort, readableHighWaterMark: 1})
+  await onceEvent(socket, "connect")
+  await waitUntil(() => fault.status().faultTriggered)
+  await waitUntil(() => connection.status().reconnectSuccesses === 1)
+  await waitUntil(() => relay.status().bufferedBytes === 16)
+  /** @type {Buffer[]} */
+  const chunks = []
+  socket.on("data", (chunk) => chunks.push(Buffer.from(chunk)))
+  socket.resume()
+  await waitUntil(() => Buffer.concat(chunks).length === payload.length)
+  assert.deepEqual(Buffer.concat(chunks), payload)
+  assert.equal(fault.status().accepts, 2)
+  await connection.close()
+})
+
+test("a recreated client recovers durable replay without reopening the target", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-v3-recovery-"))
+  let targetAccepts = 0
+  let received = Buffer.alloc(0)
+  const target = createServer((socket) => {
+    targetAccepts += 1
+    socket.on("data", (chunk) => { received = Buffer.concat([received, chunk]) })
+  })
+  const targetPort = await listen(target)
+  t.after(() => closeServer(target))
+  const relay = await startMultiplexedTcpRelay({tokens: tokens(), authorizeTarget: ({target: requested}) => requested.port === targetPort, initialWindowBytes: 32, maxFrameBytes: 32, resumeWindowMs: 2_000})
+  t.after(() => relay.close())
+  const fault = await createFaultProxy(relay.port, "drop-client-window")
+  t.after(() => closeServer(fault.proxy))
+  const shared = {relay: {host: "127.0.0.1", port: fault.port, token: "valid-token"}, connectionId: "stable_connection_01", spoolDirectory: root, initialWindowBytes: 32, maxFrameBytes: 32, reconnectDelayMs: 1_000}
+  const first = new MultiplexedSocketductConnection(shared)
+  const initial = first.createConnection({host: "127.0.0.1", port: targetPort, identifier: "stable_stream_01", sessionName: "durable"})
+  await onceEvent(initial, "connect")
+  await new Promise((resolve, reject) => initial.write(Buffer.alloc(32, 0x72), (error) => error ? reject(error) : resolve(undefined)))
+  await waitUntil(() => fault.status().faultTriggered)
+  await first.detach()
+
+  const accidentalFresh = new MultiplexedSocketductConnection(shared)
+  const duplicate = accidentalFresh.createConnection({host: "127.0.0.1", port: targetPort, identifier: "stable_stream_01", sessionName: "durable"})
+  assert.match((await nextError(duplicate)).message, /explicit recovery is required/i)
+  await accidentalFresh.close()
+
+  const second = new MultiplexedSocketductConnection(shared)
+  t.after(() => second.close())
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const recovered = second.createConnection({host: "127.0.0.1", port: targetPort, identifier: "stable_stream_01", sessionName: "durable", recover: true})
+  await onceEvent(recovered, "connect")
+  await waitUntil(() => received.length === 32)
+  assert.equal(received.toString(), "r".repeat(32))
+  assert.equal(targetAccepts, 1)
+})
+
+test("corrupt durable recovery state fails closed", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-v3-corrupt-"))
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const directory = join(root, "stable_stream_02")
+  await mkdir(directory, {recursive: true})
+  await writeFile(join(directory, "metadata.json"), JSON.stringify({sessionId: "stable_stream_02", ownerId: "edge-v3", createdAt: new Date().toISOString()}))
+  await writeFile(join(directory, "recovery.json"), "{not-json")
+  const connection = new MultiplexedSocketductConnection({relay: {host: "127.0.0.1", port: 9, token: "valid-token"}, connectionId: "stable_connection_02", spoolDirectory: root})
+  assert.throws(() => connection.createConnection({host: "127.0.0.1", port: 9, identifier: "stable_stream_02", recover: true}), /recovery/i)
+})
+
+test("relay enforces one process-wide retained buffer ceiling", async (t) => {
+  const targets = new Map()
+  const relay = await startMultiplexedTcpRelay({
+    tokens: tokens(),
+    authorizeTarget: () => true,
+    createTargetConnection: (requested) => {
+      const target = new Duplex({read() {}, write(_chunk, _encoding, callback) { callback() }})
+      targets.set(requested.port, target)
+      setImmediate(() => target.emit("connect"))
+      return /** @type {import('node:net').Socket} */ (/** @type {unknown} */ (target))
+    },
+    initialWindowBytes: 64,
+    maxFrameBytes: 32,
+    maxStreamBufferBytes: 64,
+    maxConnectionBufferBytes: 64,
+    maxTotalBufferBytes: 64
+  })
+  t.after(() => relay.close())
+  const options = {relay: {host: "127.0.0.1", port: relay.port, token: "valid-token"}, initialWindowBytes: 64, maxFrameBytes: 32}
+  const firstConnection = new MultiplexedSocketductConnection(options)
+  const secondConnection = new MultiplexedSocketductConnection(options)
+  t.after(() => Promise.all([firstConnection.close(), secondConnection.close()]))
+  const first = firstConnection.createConnection({host: "target.internal", port: 1, readableHighWaterMark: 1})
+  const second = secondConnection.createConnection({host: "target.internal", port: 2, readableHighWaterMark: 1})
+  await Promise.all([onceEvent(first, "connect"), onceEvent(second, "connect")])
+  const secondError = nextError(second)
+  targets.get(1)?.push(Buffer.alloc(40, 0x61))
+  await waitUntil(() => relay.status().bufferedBytes === 40)
+  targets.get(2)?.push(Buffer.alloc(40, 0x62))
+  assert.equal((await secondError).code, "PROCESS_BUFFER_LIMIT")
+  assert.equal(relay.status().bufferedBytes, 40)
+  assert.equal(relay.status().bufferLimitBytes, 64)
+  first.destroy()
+  await waitUntil(() => relay.status().bufferedBytes === 0)
+})
+
+test("authentication timeout covers AUTH_OK and permits a later open", async (t) => {
+  const fixture = await createBlackholeThenReadyServer(1)
+  t.after(() => closeServer(fixture.server))
+  const connection = new MultiplexedSocketductConnection({relay: {host: "127.0.0.1", port: fixture.port, token: "valid-token"}, connectTimeoutMs: 40})
+  t.after(() => connection.close())
+  const first = connection.createConnection({host: "target.internal", port: 1})
+  const error = await Promise.race([
+    nextError(first),
+    new Promise((_, reject) => setTimeout(() => reject(new Error("authentication timeout did not settle")), 250))
+  ])
+  assert.equal(error.code, "SOCKETDUCT_AUTH_TIMEOUT")
+  const second = connection.createConnection({host: "target.internal", port: 1})
+  await onceEvent(second, "connect")
+  assert.equal(fixture.status().accepts, 2)
+})
+
+test("slow spool initialization does not consume the authentication timeout", async (t) => {
+  const originalCreateNew = SessionSpool.prototype.createNew
+  /** @type {() => void} */
+  let releaseCreateNew = () => {}
+  /** @type {Promise<void>} */
+  const createNewGate = new Promise((resolve) => { releaseCreateNew = () => resolve() })
+  SessionSpool.prototype.createNew = async function (/** @type {{sessionId: string, ownerId: string}} */ options) {
+    await createNewGate
+    return await originalCreateNew.call(this, options)
+  }
+  t.after(() => { SessionSpool.prototype.createNew = originalCreateNew })
+  const fixture = await createBlackholeThenReadyServer(0)
+  t.after(() => closeServer(fixture.server))
+  let physicalAttempts = 0
+  const connection = new MultiplexedSocketductConnection({relay: {host: "127.0.0.1", port: fixture.port, token: "valid-token"}, connectTimeoutMs: 20, createPhysicalSocket: (options) => {
+    physicalAttempts += 1
+    return createConnection(options)
+  }})
+  t.after(() => connection.close())
+  const socket = connection.createConnection({host: "target.internal", port: 1})
+  void nextError(socket)
+  await new Promise((resolve) => setTimeout(resolve, 50))
+  const attemptsBeforeSpoolReady = physicalAttempts
+  releaseCreateNew()
+  assert.equal(attemptsBeforeSpoolReady, 0)
+  await onceEvent(socket, "connect")
+  assert.equal(physicalAttempts, 1)
+})
+
+test("cancelling the only opening stream clears physical attempt ownership", async (t) => {
+  const originalCreateNew = SessionSpool.prototype.createNew
+  /** @type {() => void} */
+  let releaseCreateNew = () => {}
+  /** @type {Promise<void>} */
+  const createNewGate = new Promise((resolve) => { releaseCreateNew = () => resolve() })
+  /** @type {() => void} */
+  let markFirstCreateNewDone = () => {}
+  /** @type {Promise<void>} */
+  const firstCreateNewDone = new Promise((resolve) => { markFirstCreateNewDone = () => resolve() })
+  let createNewCalls = 0
+  SessionSpool.prototype.createNew = async function (/** @type {{sessionId: string, ownerId: string}} */ options) {
+    createNewCalls += 1
+    if (createNewCalls !== 1) return await originalCreateNew.call(this, options)
+    await createNewGate
+    const created = await originalCreateNew.call(this, options)
+    markFirstCreateNewDone()
+    return created
+  }
+  t.after(() => { SessionSpool.prototype.createNew = originalCreateNew })
+  const fixture = await createBlackholeThenReadyServer(0)
+  t.after(() => closeServer(fixture.server))
+  let physicalAttempts = 0
+  const connection = new MultiplexedSocketductConnection({relay: {host: "127.0.0.1", port: fixture.port, token: "valid-token"}, connectTimeoutMs: 1_000, createPhysicalSocket: (options) => {
+    physicalAttempts += 1
+    return createConnection(options)
+  }})
+  t.after(() => connection.close())
+  const first = connection.createConnection({host: "target.internal", port: 1})
+  first.destroy()
+  releaseCreateNew()
+  await firstCreateNewDone
+  await new Promise((resolve) => setImmediate(resolve))
+  assert.equal(physicalAttempts, 0)
+  const second = connection.createConnection({host: "target.internal", port: 1})
+  await Promise.race([
+    onceEvent(second, "connect"),
+    new Promise((_, reject) => setTimeout(() => reject(new Error("later open reused a stale connect promise")), 250))
+  ])
+  assert.equal(physicalAttempts, 1)
+  assert.equal(fixture.status().accepts, 1)
+})
+
+test("close-delimited streams release relay capacity after CLOSE delivery", async (t) => {
+  const originalWriteRecoveryState = SessionSpool.prototype.writeRecoveryState
+  /** @type {() => void} */
+  let releaseReceiveAck = () => {}
+  /** @type {Promise<void>} */
+  const receiveAckGate = new Promise((resolve) => { releaseReceiveAck = resolve })
+  /** @type {() => void} */
+  let markReceiveAckStarted = () => {}
+  /** @type {Promise<void>} */
+  const receiveAckStarted = new Promise((resolve) => { markReceiveAckStarted = resolve })
+  SessionSpool.prototype.writeRecoveryState = async function (/** @type {string} */ sessionId, /** @type {Record<string, unknown>} */ state) {
+    if (sessionId === "close_stream_1" && typeof state.receiveAck === "number" && state.receiveAck > 0) {
+      markReceiveAckStarted()
+      await receiveAckGate
+    }
+    return await originalWriteRecoveryState.call(this, sessionId, state)
+  }
+  t.after(() => { SessionSpool.prototype.writeRecoveryState = originalWriteRecoveryState })
+  let targetAccepts = 0
+  const target = createServer((socket) => {
+    targetAccepts += 1
+    socket.end(`response-${targetAccepts}`)
+  })
+  const targetPort = await listen(target)
+  t.after(() => closeServer(target))
+  const relay = await startMultiplexedTcpRelay({
+    tokens: tokens(),
+    authorizeTarget: ({target: requested}) => requested.port === targetPort,
+    maxStreams: 1
+  })
+  t.after(() => relay.close())
+  const observer = await createFaultProxy(relay.port, "observe-client")
+  t.after(() => closeServer(observer.proxy))
+  const connection = new MultiplexedSocketductConnection({relay: {host: "127.0.0.1", port: observer.port, token: "valid-token"}})
+  t.after(() => connection.close())
+  /** @type {number[]} */
+  const streamIds = []
+
+  for (const [index, expected] of ["response-1", "response-2"].entries()) {
+    const socket = connection.createConnection({host: "127.0.0.1", port: targetPort, identifier: `close_stream_${index + 1}`, allowHalfOpen: true})
+    streamIds.push(socket.streamId)
+    /** @type {Buffer[]} */
+    const chunks = []
+    socket.on("data", (chunk) => chunks.push(Buffer.from(chunk)))
+    const closed = onceEvent(socket, "close")
+    const ended = onceEvent(socket, "end")
+    await onceEvent(socket, "connect")
+    await waitUntil(() => observer.status().clientFrames.some((frame) => frame.streamId === socket.streamId && frame.type === V3FrameType.CLOSE))
+    if (index === 0) {
+      await receiveAckStarted
+      releaseReceiveAck()
+    }
+    await ended
+    socket.end()
+    await closed
+    assert.equal(Buffer.concat(chunks).toString(), expected)
+    await waitUntil(() => /** @type {{virtualStreams: number}} */ (relay.status()).virtualStreams === 0)
+  }
+
+  const firstCloseIndex = observer.status().clientFrames.findIndex((frame) => frame.streamId === streamIds[0] && frame.type === V3FrameType.CLOSE)
+  assert.deepEqual(observer.status().clientFrames.slice(firstCloseIndex).filter((frame) => frame.streamId === streamIds[0]).map((frame) => frame.type), [V3FrameType.CLOSE])
+  assert.equal(targetAccepts, 2)
+  assert.equal(/** @type {{physicalAccepts: number}} */ (relay.status()).physicalAccepts, 1)
+})
+
+test("replacement recovery replays target bytes not durably acknowledged", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-v3-receive-recovery-"))
+  const payload = Buffer.from("unread-target-payload")
+  let targetAccepts = 0
+  const target = createServer((socket) => {
+    socket.write(payload)
+  })
+  const targetPort = await listen(target)
+  t.after(() => closeServer(target))
+  // Prove target-open accounting is owned by the relay, not arbitrary clients of the fixture listener.
+  const unrelated = createConnection({host: "127.0.0.1", port: targetPort})
+  const unrelatedData = onceEvent(unrelated, "data")
+  const unrelatedClosed = onceEvent(unrelated, "close")
+  await onceEvent(unrelated, "connect")
+  await unrelatedData
+  unrelated.end()
+  await unrelatedClosed
+  const relay = await startMultiplexedTcpRelay({
+    tokens: tokens(),
+    authorizeTarget: ({target: requested}) => requested.port === targetPort,
+    createTargetConnection: (requested) => {
+      targetAccepts += 1
+      return createConnection(requested)
+    },
+    initialWindowBytes: 32,
+    maxFrameBytes: 32,
+    resumeWindowMs: 2_000
+  })
+  t.after(() => relay.close())
+  const shared = {
+    relay: {host: "127.0.0.1", port: relay.port, token: "valid-token"},
+    connectionId: "stable_connection_receive_01",
+    spoolDirectory: root,
+    initialWindowBytes: 32,
+    maxFrameBytes: 32
+  }
+  const first = new MultiplexedSocketductConnection(shared)
+  const initial = first.createConnection({host: "127.0.0.1", port: targetPort, identifier: "stable_stream_receive_01", readableHighWaterMark: 1})
+  await onceEvent(initial, "connect")
+  await waitUntil(() => initial.bytesRead === payload.length)
+  await waitUntil(() => /** @type {{bufferedBytes: number}} */ (relay.status()).bufferedBytes === payload.length)
+  await first.detach()
+
+  const second = new MultiplexedSocketductConnection(shared)
+  t.after(() => second.close())
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const recovered = second.createConnection({host: "127.0.0.1", port: targetPort, identifier: "stable_stream_receive_01", readableHighWaterMark: 1, recover: true})
+  /** @type {Buffer[]} */
+  const chunks = []
+  recovered.on("data", (chunk) => chunks.push(Buffer.from(chunk)))
+  recovered.resume()
+  await onceEvent(recovered, "connect")
+  await waitUntil(() => Buffer.concat(chunks).length === payload.length)
+  assert.deepEqual(Buffer.concat(chunks), payload)
+  assert.equal(targetAccepts, 1)
+})
+
+test("replacement recovery reconciles a durable opening stream without a duplicate OPEN", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-v3-opening-recovery-"))
+  let targetAttempts = 0
+  /** @type {Duplex | undefined} */
+  let pendingTarget
+  const relay = await startMultiplexedTcpRelay({
+    tokens: tokens(),
+    authorizeTarget: () => true,
+    resumeWindowMs: 2_000,
+    createTargetConnection: () => {
+      targetAttempts += 1
+      pendingTarget = new Duplex({read() {}, write(_chunk, _encoding, callback) { callback() }})
+      return /** @type {import('node:net').Socket} */ (/** @type {unknown} */ (pendingTarget))
+    }
+  })
+  t.after(() => relay.close())
+  const shared = {
+    relay: {host: "127.0.0.1", port: relay.port, token: "valid-token"},
+    connectionId: "stable_connection_opening_01",
+    spoolDirectory: root
+  }
+  const first = new MultiplexedSocketductConnection(shared)
+  first.createConnection({host: "target.internal", port: 443, identifier: "stable_stream_opening_01"})
+  await waitUntil(() => pendingTarget !== undefined)
+  await first.detach()
+
+  const second = new MultiplexedSocketductConnection(shared)
+  t.after(() => second.close())
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const recovered = second.createConnection({host: "target.internal", port: 443, identifier: "stable_stream_opening_01", recover: true})
+  const connected = onceEvent(recovered, "connect")
+  pendingTarget?.emit("connect")
+  await connected
+  assert.equal(targetAttempts, 1)
+  await second.detach()
+})