socketduct 0.1.20 → 0.1.22

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

@@ -8,7 +8,7 @@ import {VirtualSocket} from "../../../src/client/virtual-socket.js"
  *
  */
 function fakeConnection() {
-  const calls = {destroyed: 0, ended: 0, resumed: 0, refs: 0, unrefs: 0}
+  const calls = {destroyed: 0, ended: 0, resumed: 0, refs: 0, unrefs: 0, delivered: 0, acknowledged: 0, durableWrites: /** @type {Buffer[]} */ ([])}
   return {
     calls,
     connection: /** @type {import('../../../src/client/multiplexed-connection.js').MultiplexedSocketductConnection} */ (/** @type {unknown} */ ({
@@ -25,6 +25,16 @@ function fakeConnection() {
       _endStream: (_id, callback) => { calls.ended += 1; callback() },
       _destroyStream: () => { calls.destroyed += 1 },
       _resumeReadable: () => { calls.resumed += 1 },
+      _deliverReadable: (/** @type {number} */ _id, /** @type {number} */ bytes) => { calls.delivered += bytes },
+      _acknowledgeReadable: (/** @type {number} */ _id, /** @type {number} */ bytes) => {
+        assert(bytes <= calls.delivered - calls.acknowledged)
+        calls.acknowledged += bytes
+        return Promise.resolve(calls.acknowledged)
+      },
+      _writeDurableStream: (/** @type {number} */ _id, /** @type {Buffer} */ data, /** @type {(error?: Error | null) => void} */ callback) => {
+        calls.durableWrites.push(Buffer.from(data))
+        callback()
+      },
       physicalAddress: () => ({address: "127.0.0.1", port: 43210}),
       ref: () => { calls.refs += 1 },
       unref: () => { calls.unrefs += 1 }
@@ -96,3 +106,115 @@ test("VirtualSocket pause/resume, timeout, data and half-close remain stream-loc
   assert(fake.calls.resumed > 0)
   socket.destroy()
 })
+
+test("VirtualSocket exposes opt-in manual receive ACK and durable write contracts", async () => {
+  const fake = fakeConnection()
+  const socket = new VirtualSocket(fake.connection, 7, {
+    host: "127.0.0.1",
+    port: 80,
+    manualReceiveAck: true
+  })
+  socket._markConnected()
+
+  const acknowledged = new Promise((resolve, reject) => {
+    socket.once("data", (chunk) => {
+      socket.acknowledgeReceive(chunk.length).then(resolve, reject)
+    })
+  })
+  socket._receive(Buffer.from("response"))
+  assert.equal(await acknowledged, 8)
+  assert.equal(fake.calls.delivered, 8)
+  assert.equal(fake.calls.acknowledged, 8)
+
+  await socket.writeDurable(new Uint8Array(Buffer.from("request")))
+  assert.deepEqual(fake.calls.durableWrites, [Buffer.from("request")])
+  assert.equal(socket.bytesWritten, 7)
+  assert.throws(
+    () => socket.acknowledgeReceive(1),
+    (error) => /** @type {{code?: string}} */ (error).code === "SOCKETDUCT_INVALID_RECEIVE_ACK"
+  )
+  const closed = new Promise((resolve) => socket.once("close", resolve))
+  socket.destroy()
+  await closed
+  await assert.rejects(
+    socket.acknowledgeReceive(1),
+    (error) => /** @type {{code?: string}} */ (error).code === "ERR_STREAM_DESTROYED"
+  )
+})
+
+test("VirtualSocket orders durable writes behind queued ordinary writes", async () => {
+  const fake = fakeConnection()
+  /** @type {string[]} */
+  const delivered = []
+  /** @type {(() => void) | undefined} */
+  let releaseFirst
+  const connection = /** @type {{_writeStream: (id: number, data: Buffer, callback: (error?: Error | null) => void) => void, _writeDurableStream: (id: number, data: Buffer, callback: (error?: Error | null) => void) => void}} */ (/** @type {unknown} */ (fake.connection))
+  connection._writeStream = (_id, data, callback) => {
+    delivered.push(data.toString())
+    if (data.toString() === "A") releaseFirst = callback
+    else callback()
+  }
+  connection._writeDurableStream = (_id, data, callback) => {
+    delivered.push(data.toString())
+    callback()
+  }
+  const socket = new VirtualSocket(fake.connection, 9, {host: "127.0.0.1", port: 80})
+
+  const first = new Promise((resolve, reject) => socket.write("A", (error) => error ? reject(error) : resolve(undefined)))
+  const second = new Promise((resolve, reject) => socket.write("B", (error) => error ? reject(error) : resolve(undefined)))
+  const durable = socket.writeDurable("C")
+  assert(releaseFirst !== undefined)
+  releaseFirst()
+  await Promise.all([first, second, durable])
+
+  assert.deepEqual(delivered, ["A", "B", "C"])
+  assert.equal(socket.bytesWritten, 3)
+  socket.destroy()
+})
+
+test("VirtualSocket rejects durable writes after end while ordinary writes remain queued", async () => {
+  const fake = fakeConnection()
+  /** @type {string[]} */
+  const delivered = []
+  /** @type {(() => void) | undefined} */
+  let releaseFirst
+  const connection = /** @type {{_writeStream: (id: number, data: Buffer, callback: (error?: Error | null) => void) => void}} */ (/** @type {unknown} */ (fake.connection))
+  connection._writeStream = (_id, data, callback) => {
+    delivered.push(data.toString())
+    if (data.toString() === "A") releaseFirst = callback
+    else callback()
+  }
+  const socket = new VirtualSocket(fake.connection, 11, {host: "127.0.0.1", port: 80})
+
+  const first = new Promise((resolve, reject) => socket.write("A", (error) => error ? reject(error) : resolve(undefined)))
+  const second = new Promise((resolve, reject) => socket.write("B", (error) => error ? reject(error) : resolve(undefined)))
+  const finished = new Promise((resolve) => socket.once("finish", resolve))
+  socket.end()
+  const rejected = assert.rejects(
+    socket.writeDurable("late"),
+    (error) => /** @type {{code?: string}} */ (error).code === "ERR_STREAM_WRITE_AFTER_END"
+  )
+
+  assert(releaseFirst !== undefined)
+  releaseFirst()
+  await Promise.all([first, second, finished, rejected])
+  assert.deepEqual(delivered, ["A", "B"])
+  assert.deepEqual(fake.calls.durableWrites, [])
+  socket.destroy()
+})
+
+test("VirtualSocket keeps manual ACK opt-in and reports unsupported durable admission", async () => {
+  const fake = fakeConnection()
+  delete /** @type {{_writeDurableStream?: unknown}} */ (fake.connection)._writeDurableStream
+  const socket = new VirtualSocket(fake.connection, 9, {host: "127.0.0.1", port: 80})
+
+  assert.throws(
+    () => socket.acknowledgeReceive(1),
+    (error) => /** @type {{code?: string}} */ (error).code === "SOCKETDUCT_MANUAL_ACK_DISABLED"
+  )
+  await assert.rejects(
+    socket.writeDurable("request"),
+    (error) => /** @type {{code?: string}} */ (error).code === "SOCKETDUCT_DURABLE_WRITE_UNSUPPORTED"
+  )
+  socket.destroy()
+})

package/test/unit/config/environment.test.js

@@ -337,6 +337,31 @@ test("loadEnvironmentConfig parses outbound reverse gateway verified TLS setting
   assert.deepEqual(config.reverseHubTls, {caFile: "/certs/ca.crt", certFile: "/certs/client.crt", keyFile: "/certs/client.key", servername: "server3.example.test"})
 })
 
+test("loadEnvironmentConfig parses the reverse-gateway spool directory", () => {
+  const config = loadEnvironmentConfig({
+    SOCKETDUCT_MODE: "reverse-gateway",
+    SOCKETDUCT_REVERSE_GATEWAY_ID: "starlink",
+    SOCKETDUCT_REVERSE_CONNECTION_ID: "home_starlink_01",
+    SOCKETDUCT_REVERSE_HUB_HOST: "server3.example.test",
+    SOCKETDUCT_REVERSE_TOKEN: "gateway-token",
+    SOCKETDUCT_TARGET_ALLOWLIST: "docker-server:2375",
+    SOCKETDUCT_SPOOL_DIRECTORY: " /spool/reverse-gateway "
+  })
+  assert.equal(config.spoolDirectory, "/spool/reverse-gateway")
+  assert.equal("spoolDirectory" in loadEnvironmentConfig({
+    SOCKETDUCT_MODE: "reverse-gateway",
+    SOCKETDUCT_REVERSE_GATEWAY_ID: "starlink",
+    SOCKETDUCT_REVERSE_CONNECTION_ID: "home_starlink_01",
+    SOCKETDUCT_REVERSE_HUB_HOST: "server3.example.test",
+    SOCKETDUCT_REVERSE_TOKEN: "gateway-token",
+    SOCKETDUCT_TARGET_ALLOWLIST: "docker-server:2375",
+    SOCKETDUCT_SPOOL_DIRECTORY: "   "
+  }), false)
+  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "relay", SOCKETDUCT_SPOOL_DIRECTORY: "/spool"}), /reverse-gateway-only/)
+  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "reverse-hub", SOCKETDUCT_SPOOL_DIRECTORY: "/spool"}), /reverse-gateway-only/)
+  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_SPOOL_DIRECTORY: "/spool"}), /reverse-gateway-only/)
+})
+
 test("loadEnvironmentConfig rejects malformed reverse mode policy and credentials", () => {
   assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "unknown"}), /Unsupported SOCKETDUCT_MODE/)
   assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "reverse-hub", SOCKETDUCT_REVERSE_GATEWAY_BINDINGS: "missing-user"}), /gatewayId:username/)

package/test/unit/index.test.js

@@ -13,6 +13,7 @@ import {
   MultiplexedSocketductTransportSet,
   OutboundReverseGateway,
   ReverseGatewayConnection,
+  SocketductRecoveryLookupError,
   SocketductHttpAgent,
   SocketductSocket
 } from "../../src/index.js"
@@ -57,6 +58,7 @@ test("package exports the protocol-v3 pooled connection and relay entrypoints",
 
   assert.equal(multiplexed.MultiplexedSocketductConnection, MultiplexedSocketductConnection)
   assert.equal(multiplexed.MultiplexedSocketductTransportSet, MultiplexedSocketductTransportSet)
+  assert.equal(multiplexed.SocketductRecoveryLookupError, SocketductRecoveryLookupError)
   assert.equal(createMultiplexedSocketductConnection({
     relay: {host: "127.0.0.1", port: 3100, token: "test-token"}
   }) instanceof MultiplexedSocketductConnection, true)

package/test/unit/logging/compressed-log-writer.test.js

@@ -61,11 +61,13 @@ test("compressed logger durably acknowledges ordered records and closes asynchro
 test("compressed logger enforces one shared bounded queue with a critical reserve", async (t) => {
   const root = await mkdtemp(join(tmpdir(), "socketduct-compressed-pressure-"))
   const directory = join(root, "logs")
+  // The reserve must cover the critical event's conservative charge (line bytes × 3 + 128);
+  // an accepted-but-undelivered sequence can never be evicted without tearing the durable journal.
   const logger = createCompressedJsonlFileLogger({
     directory,
     role: "reverse-client",
     maxQueueBytes: 4096,
-    criticalReserveBytes: 1024,
+    criticalReserveBytes: 2048,
     frameMaxBytes: 1024,
     flushIntervalMs: 60_000,
     criticalFlushIntervalMs: 60_000

package/test/unit/spool/spool-file.test.js

@@ -63,6 +63,64 @@ test("SessionSpool truncates acknowledged chunks", async () => {
   })
 })
 
+test("SessionSpool truncates an acknowledgement inside a chunk in application bytes", async () => {
+  await withTempDir(async (root) => {
+    const spool = new SessionSpool({rootDir: root})
+    const sessionId = "session_partial_ack"
+    await spool.create({sessionId, ownerId: "user-1"})
+    await spool.appendChunk({sessionId, sequence: 8, data: Buffer.from("abcdefgh")})
+
+    await spool.truncateAcked(sessionId, 3)
+
+    const chunks = await spool.readChunksAfter(sessionId, 3)
+    assert.deepEqual(chunks, [{sequence: 8, data: Buffer.from("defgh")}])
+    assert.equal(spool.getUsedBytes(sessionId), 5)
+  })
+})
+
+test("SessionSpool atomically admits a complete chunk batch before recovery commit", async () => {
+  await withTempDir(async (root) => {
+    const spool = new SessionSpool({rootDir: root, maxBytes: 32})
+    const sessionId = "session_durable_batch"
+    await spool.createNew({sessionId, ownerId: "reverse-client-v3"})
+    await spool.appendChunk({sessionId, ownerId: "reverse-client-v3", sequence: 4, data: Buffer.from("base")})
+    await spool.writeRecoveryState(sessionId, {version: 3, sendSequence: 4})
+
+    await spool.appendChunksAndRecoveryState({
+      sessionId,
+      ownerId: "reverse-client-v3",
+      previousSequence: 4,
+      chunks: [
+        {sequence: 7, data: Buffer.from("one")},
+        {sequence: 10, data: Buffer.from("two")}
+      ],
+      recoveryState: {version: 3, sendSequence: 10}
+    })
+
+    assert.deepEqual((await spool.readChunksAfter(sessionId, 0)).map(({sequence, data}) => [sequence, data.toString()]), [
+      [4, "base"],
+      [7, "one"],
+      [10, "two"]
+    ])
+    assert.deepEqual(spool.readRecoveryStateSync(sessionId, "reverse-client-v3"), {version: 3, sendSequence: 10})
+    assert.equal(spool.getUsedBytes(sessionId), 10)
+  })
+})
+
+test("SessionSpool recovery lookup distinguishes missing state from invalid state", async () => {
+  await withTempDir(async (root) => {
+    const spool = new SessionSpool({rootDir: root})
+    assert.equal(spool.findRecoveryStateSync("missing_session", "edge-v3"), undefined)
+
+    await spool.createNew({sessionId: "present_session", ownerId: "edge-v3"})
+    await spool.writeRecoveryState("present_session", {version: 3})
+    assert.deepEqual(spool.findRecoveryStateSync("present_session", "edge-v3"), {version: 3})
+
+    await writeFile(join(root, "present_session", "recovery.json"), "{invalid\n")
+    assert.throws(() => spool.findRecoveryStateSync("present_session", "edge-v3"), /Invalid Socketduct recovery state/)
+  })
+})
+
 test("SessionSpool rejects path traversal and mismatched metadata", async () => {
   await withTempDir(async (root) => {
     const spool = new SessionSpool({rootDir: root})