socketduct 0.1.15

package/test/unit/auth/auth.test.js

@@ -0,0 +1,64 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+
+import {
+  createPasswordHash,
+  verifyPassword
+} from "../../../src/auth/passwords.js"
+import {
+  InMemoryUserStore,
+  login,
+  TokenStore
+} from "../../../src/auth/user-store.js"
+
+test("createPasswordHash stores a salted scrypt hash instead of plaintext", async () => {
+  const hash = await createPasswordHash("correct horse battery staple")
+
+  assert.notEqual(hash, "correct horse battery staple")
+  assert.match(hash, /^scrypt\$/)
+  assert.equal(await verifyPassword("correct horse battery staple", hash), true)
+  assert.equal(await verifyPassword("wrong password", hash), false)
+})
+
+test("login returns an opaque token for valid username and password", async () => {
+  const users = new InMemoryUserStore()
+  const tokens = new TokenStore({now: () => 1_000})
+  await users.createUser({username: "kasper", password: "secret-password"})
+
+  const token = await login(users, tokens, {
+    username: "kasper",
+    password: "secret-password"
+  })
+
+  assert.match(token.value, /^[a-zA-Z0-9_-]{32,}$/)
+  assert.equal(tokens.authenticate(token.value)?.username, "kasper")
+})
+
+test("login rejects invalid username or password", async () => {
+  const users = new InMemoryUserStore()
+  const tokens = new TokenStore()
+  await users.createUser({username: "kasper", password: "secret-password"})
+
+  await assert.rejects(
+    login(users, tokens, {username: "missing", password: "secret-password"}),
+    /invalid username or password/i
+  )
+  await assert.rejects(
+    login(users, tokens, {username: "kasper", password: "wrong-password"}),
+    /invalid username or password/i
+  )
+})
+
+test("TokenStore expires and revokes tokens", () => {
+  let now = 1_000
+  const tokens = new TokenStore({now: () => now, tokenTtlMs: 500})
+  const token = tokens.issue({userId: "user-1", username: "kasper"})
+
+  assert.equal(tokens.authenticate(token.value)?.userId, "user-1")
+  now = 1_501
+  assert.equal(tokens.authenticate(token.value), undefined)
+
+  const revoked = tokens.issue({userId: "user-1", username: "kasper"})
+  assert.equal(tokens.revoke(revoked.value), true)
+  assert.equal(tokens.authenticate(revoked.value), undefined)
+})

package/test/unit/auth/static-token-store.test.js

@@ -0,0 +1,14 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+
+import {StaticTokenStore} from "../../../src/auth/static-token-store.js"
+
+test("StaticTokenStore authenticates configured bearer tokens", () => {
+  const tokens = new StaticTokenStore([{username: "edge", token: "secret-token"}])
+
+  const principal = tokens.authenticate("secret-token")
+
+  assert.equal(principal?.username, "edge")
+  assert.equal(principal?.userId.startsWith("static:"), true)
+  assert.equal(tokens.authenticate("wrong-token"), undefined)
+})

package/test/unit/client/connect.test.js

@@ -0,0 +1,58 @@
+import assert from "node:assert/strict"
+import {mkdtemp, rm} from "node:fs/promises"
+import {tmpdir} from "node:os"
+import {join} from "node:path"
+import test from "node:test"
+
+import {createSocketductConnectionFactory} from "../../../src/client/connect.js"
+import {SocketductSocket} from "../../../src/client/socketduct-socket.js"
+
+/**
+ * @returns {Promise<string>} - Temporary spool root.
+ */
+async function createSpoolRoot() {
+  return await mkdtemp(join(tmpdir(), "socketduct-connect-test-"))
+}
+
+test("createSocketductConnectionFactory merges base relay options with per-call targets", async () => {
+  const spoolDirectory = await createSpoolRoot()
+  const createConnection = createSocketductConnectionFactory({
+    relay: {host: "relay.local", port: 3100, token: "token"},
+    spoolDirectory,
+    reconnect: {initialDelayMs: 25},
+    sessionNamePrefix: "docker"
+  })
+
+  const socket = createConnection({host: "docker-api", port: 2375})
+
+  assert.equal(socket instanceof SocketductSocket, true)
+  assert.equal(socket.remoteAddress, "docker-api")
+  assert.equal(socket.remotePort, 2375)
+  assert.equal(socket.connecting, true)
+  socket.destroy()
+  await rm(spoolDirectory, {recursive: true, force: true})
+})
+
+test("createSocketductConnectionFactory accepts explicit target and connect listener", async () => {
+  const spoolDirectory = await createSpoolRoot()
+  const createConnection = createSocketductConnectionFactory({
+    relay: {host: "relay.local", port: 3100, token: "token"},
+    spoolDirectory,
+    sessionNamePrefix: "explicit"
+  })
+  let listenerCalled = false
+
+  const socket = createConnection({
+    target: {host: "docker-socket-shim", port: 2375},
+    sessionName: "custom session"
+  }, () => {
+    listenerCalled = true
+  })
+
+  assert.equal(socket.remoteAddress, "docker-socket-shim")
+  assert.equal(socket.remotePort, 2375)
+  socket.emit("connect")
+  assert.equal(listenerCalled, true)
+  socket.destroy()
+  await rm(spoolDirectory, {recursive: true, force: true})
+})

package/test/unit/client/multiplexed-spool-budget.test.js

@@ -0,0 +1,309 @@
+/* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-param, jsdoc/require-returns */
+import assert from "node:assert/strict"
+import {EventEmitter} from "node:events"
+import {mkdtemp, rm} from "node:fs/promises"
+import {tmpdir} from "node:os"
+import {join} from "node:path"
+import {Duplex} from "node:stream"
+import test from "node:test"
+
+import {MultiplexedSocketductTransportSet} from "../../../src/client/multiplexed-transport-set.js"
+import {decodeV3Control, encodeV3Control, encodeV3Frame, V3FrameDecoder, V3FrameType} from "../../../src/protocol/v3-frame.js"
+import {SessionSpool} from "../../../src/spool/spool-file.js"
+
+class LoopbackController extends EventEmitter {
+  constructor() {
+    super()
+    /** @type {Array<{socket: LoopbackV3Socket, frame: import('../../../src/protocol/v3-frame.js').V3Frame}>} */
+    this.frames = []
+  }
+
+  /** @param {LoopbackV3Socket} socket - Source. @param {import('../../../src/protocol/v3-frame.js').V3Frame} frame - DATA frame. */
+  record(socket, frame) {
+    const entry = {socket, frame}
+    this.frames.push(entry)
+    this.emit("dataFrame", entry)
+  }
+
+  async nextFrame() {
+    const existing = this.frames.shift()
+    if (existing !== undefined) return existing
+    return await new Promise((resolve) => this.once("dataFrame", resolve))
+  }
+}
+
+class LoopbackV3Socket extends Duplex {
+  /** @param {LoopbackController} controller - Recorded DATA frames. */
+  constructor(controller) {
+    super()
+    this.controller = controller
+    this.decoder = new V3FrameDecoder()
+    queueMicrotask(() => this.emit("connect"))
+  }
+
+  /** @override */
+  _read() {}
+
+  /**
+   * @override
+   * @param {Buffer} chunk - Wire bytes.
+   * @param {string} _encoding - Encoding.
+   * @param {(error?: Error | null) => void} callback - Completion.
+   */
+  _write(chunk, _encoding, callback) {
+    for (const frame of this.decoder.push(chunk)) {
+      if (frame.type === V3FrameType.AUTH) {
+        const auth = decodeV3Control(frame.payload)
+        this.respond(V3FrameType.AUTH_OK, 0, frame.sequence, {
+          version: 3,
+          connectionId: auth.connectionId,
+          generation: auth.generation,
+          resumed: false
+        })
+      } else if (frame.type === V3FrameType.OPEN) {
+        const open = decodeV3Control(frame.payload)
+        this.respond(V3FrameType.OPENED, frame.streamId, 0, {identifier: open.identifier, initialWindow: 16})
+      } else if (frame.type === V3FrameType.DATA) {
+        this.controller.record(this, frame)
+      } else if (frame.type === V3FrameType.PING) {
+        this.respond(V3FrameType.PONG, 0, frame.sequence, {})
+      }
+    }
+    callback()
+  }
+
+  /** @param {import('../../../src/protocol/v3-frame.js').V3Frame} frame - DATA to acknowledge. */
+  ack(frame) {
+    queueMicrotask(() => {
+      if (!this.destroyed) this.push(encodeV3Frame({type: V3FrameType.ACK, streamId: frame.streamId, sequence: frame.sequence}))
+    })
+  }
+
+  /** @param {number} type - Frame type. @param {number} streamId - Stream. @param {number} sequence - Sequence. @param {Record<string, unknown>} detail - Control body. */
+  respond(type, streamId, sequence, detail) {
+    queueMicrotask(() => {
+      if (!this.destroyed) this.push(encodeV3Frame({type, streamId, sequence}, encodeV3Control(detail)))
+    })
+  }
+}
+
+/** @returns {{promise: Promise<void>, resolve: () => void, reject: (reason?: unknown) => void}} Deferred controls. */
+function deferred() {
+  let resolve = () => {}
+  /** @type {(reason?: unknown) => void} */
+  let reject = () => {}
+  const promise = new Promise((resolvePromise, rejectPromise) => {
+    resolve = () => resolvePromise(undefined)
+    reject = rejectPromise
+  })
+  return {promise, resolve, reject}
+}
+
+/** @template T @param {T[]} values - Values. @param {number} index - Index. @returns {T} */
+function at(values, index) {
+  const value = values[index]
+  assert(value !== undefined)
+  return value
+}
+
+/** @param {string} root - Spool root. */
+function createFixture(root) {
+  const controllers = [new LoopbackController(), new LoopbackController(), new LoopbackController()]
+  const factories = controllers.map((controller) => () => /** @type {import('node:net').Socket} */ (/** @type {unknown} */ (new LoopbackV3Socket(controller))))
+  const set = new MultiplexedSocketductTransportSet({
+    connectionId: "spool_budget_process_01",
+    spoolDirectory: root,
+    minimumReadyMembers: 3,
+    maxTotalBufferBytes: 16,
+    maxTotalSpoolBytes: 8,
+    maxTotalQueuedBytes: 1024,
+    memberOptions: {initialWindowBytes: 16, maxFrameBytes: 16, maxStreamBufferBytes: 16, maxConnectionBufferBytes: 16},
+    gateways: factories.map((createPhysicalSocket, index) => ({
+      gatewayId: at(["starlink", "zyxel", "o2gateway"], index),
+      endpoint: {relay: {host: "127.0.0.1", port: 3201 + index, token: "secret"}, createPhysicalSocket}
+    }))
+  })
+  return {set, controllers}
+}
+
+/** @param {import('node:events').EventEmitter} emitter - Emitter. @param {string} event - Event. */
+async function onceEvent(emitter, event) {
+  await new Promise((resolve, reject) => {
+    emitter.once("error", reject)
+    emitter.once(event, () => { emitter.off("error", reject); resolve(undefined) })
+  })
+}
+
+/** @param {import('../../../src/client/virtual-socket.js').VirtualSocket} socket - Socket. @param {number} bytes - Write size. @returns {Promise<Error | null>} */
+async function writeResult(socket, bytes) {
+  socket.on("error", () => {})
+  return await new Promise((resolve) => socket.write(Buffer.alloc(bytes), (error) => resolve(error ?? null)))
+}
+
+/** @returns {Promise<void>} Next event-loop turn. */
+async function settle() {
+  await new Promise((resolve) => setImmediate(resolve))
+}
+
+test("destroy keeps shared spool capacity reserved until remove succeeds", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-destroy-spool-budget-"))
+  const originalRemove = SessionSpool.prototype.remove
+  const removeGate = deferred()
+  const removeCalled = deferred()
+  const removeFinished = deferred()
+  SessionSpool.prototype.remove = async function (/** @type {string} */ identifier) {
+    if (identifier === "destroy_stream_01") {
+      removeCalled.resolve()
+      await removeGate.promise
+    }
+    await originalRemove.call(this, identifier)
+    if (identifier === "destroy_stream_01") removeFinished.resolve()
+  }
+  const {set, controllers} = createFixture(root)
+  t.after(async () => {
+    removeGate.resolve()
+    SessionSpool.prototype.remove = originalRemove
+    await set.close().catch(() => {})
+    await rm(root, {recursive: true, force: true})
+  })
+  await set.start()
+  const first = set.createConnection({host: "target.internal", port: 443, identifier: "destroy_stream_01"})
+  await onceEvent(first, "connect")
+  assert.equal(await writeResult(first, 6), null)
+  await at(controllers, 0).nextFrame()
+  first.destroy()
+  await removeCalled.promise
+  await settle()
+  assert.equal(set.status().budgets.dataBytes, 0)
+  assert.equal(set.status().budgets.spoolBytes, 6)
+
+  const sibling = set.createConnection({host: "target.internal", port: 443, identifier: "destroy_stream_02"})
+  await onceEvent(sibling, "connect")
+  const blocked = await writeResult(sibling, 3)
+  let closeSettled = false
+  const closing = set.close().then(() => { closeSettled = true })
+  await settle()
+  assert.equal(closeSettled, false)
+  removeGate.resolve()
+  await removeFinished.promise
+  await closing
+  assert.equal(/** @type {{code?: string}} */ (blocked).code, "SOCKETDUCT_SET_SPOOL_LIMIT")
+  assert.equal(set.status().budgets.spoolBytes, 0)
+})
+
+test("failed destroy removal retains spool accounting and fails the member visibly", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-failed-remove-budget-"))
+  const originalRemove = SessionSpool.prototype.remove
+  const removeCalled = deferred()
+  SessionSpool.prototype.remove = async function (/** @type {string} */ identifier) {
+    if (identifier === "failed_remove_stream_01") {
+      removeCalled.resolve()
+      throw new Error("injected remove failure")
+    }
+    await originalRemove.call(this, identifier)
+  }
+  const {set, controllers} = createFixture(root)
+  t.after(async () => {
+    SessionSpool.prototype.remove = originalRemove
+    await set.close().catch(() => {})
+    await rm(root, {recursive: true, force: true})
+  })
+  await set.start()
+  const socket = set.createConnection({host: "target.internal", port: 443, identifier: "failed_remove_stream_01"})
+  await onceEvent(socket, "connect")
+  assert.equal(await writeResult(socket, 6), null)
+  await at(controllers, 0).nextFrame()
+  socket.destroy()
+  await removeCalled.promise
+  await settle()
+  assert.equal(set.status().budgets.dataBytes, 0)
+  assert.equal(set.status().budgets.spoolBytes, 6)
+  assert.equal(at(set.status().members, 0).spoolCleanupFailures, 1)
+  assert.equal(at(set.status().members, 0).state, "closed")
+})
+
+test("ACK keeps shared spool capacity reserved until truncate succeeds", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-ack-spool-budget-"))
+  const originalTruncate = SessionSpool.prototype.truncateAcked
+  const truncateGate = deferred()
+  const truncateCalled = deferred()
+  const truncateFinished = deferred()
+  SessionSpool.prototype.truncateAcked = async function (/** @type {string} */ identifier, /** @type {number} */ sequence) {
+    if (identifier === "ack_stream_01") {
+      truncateCalled.resolve()
+      await truncateGate.promise
+    }
+    await originalTruncate.call(this, identifier, sequence)
+    if (identifier === "ack_stream_01") truncateFinished.resolve()
+  }
+  const {set, controllers} = createFixture(root)
+  t.after(async () => {
+    truncateGate.resolve()
+    SessionSpool.prototype.truncateAcked = originalTruncate
+    await set.close().catch(() => {})
+    await rm(root, {recursive: true, force: true})
+  })
+  await set.start()
+  const first = set.createConnection({host: "target.internal", port: 443, identifier: "ack_stream_01"})
+  await onceEvent(first, "connect")
+  assert.equal(await writeResult(first, 6), null)
+  const sent = await at(controllers, 0).nextFrame()
+  sent.socket.ack(sent.frame)
+  await truncateCalled.promise
+  await settle()
+  assert.equal(set.status().budgets.dataBytes, 0)
+  assert.equal(set.status().budgets.spoolBytes, 6)
+
+  const sibling = set.createConnection({host: "target.internal", port: 443, identifier: "ack_stream_02"})
+  await onceEvent(sibling, "connect")
+  const blocked = await writeResult(sibling, 3)
+  truncateGate.resolve()
+  await truncateFinished.promise
+  await settle()
+  assert.equal(/** @type {{code?: string}} */ (blocked).code, "SOCKETDUCT_SET_SPOOL_LIMIT")
+  assert.equal(set.status().budgets.spoolBytes, 0)
+})
+
+test("failed ACK truncate and removal retain spool accounting and surface cleanup failure", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-failed-truncate-budget-"))
+  const originalTruncate = SessionSpool.prototype.truncateAcked
+  const originalRemove = SessionSpool.prototype.remove
+  const truncateCalled = deferred()
+  const removeCalled = deferred()
+  SessionSpool.prototype.truncateAcked = async function (/** @type {string} */ identifier, /** @type {number} */ sequence) {
+    if (identifier === "failed_ack_stream_01") {
+      truncateCalled.resolve()
+      throw new Error("injected truncate failure")
+    }
+    await originalTruncate.call(this, identifier, sequence)
+  }
+  SessionSpool.prototype.remove = async function (/** @type {string} */ identifier) {
+    if (identifier === "failed_ack_stream_01") {
+      removeCalled.resolve()
+      throw new Error("injected remove failure")
+    }
+    await originalRemove.call(this, identifier)
+  }
+  const {set, controllers} = createFixture(root)
+  t.after(async () => {
+    SessionSpool.prototype.truncateAcked = originalTruncate
+    SessionSpool.prototype.remove = originalRemove
+    await set.close().catch(() => {})
+    await rm(root, {recursive: true, force: true})
+  })
+  await set.start()
+  const socket = set.createConnection({host: "target.internal", port: 443, identifier: "failed_ack_stream_01"})
+  await onceEvent(socket, "connect")
+  assert.equal(await writeResult(socket, 6), null)
+  const sent = await at(controllers, 0).nextFrame()
+  const streamError = onceEvent(socket, "error").catch((error) => error)
+  sent.socket.ack(sent.frame)
+  await truncateCalled.promise
+  await removeCalled.promise
+  await streamError
+  await settle()
+  assert.equal(set.status().budgets.dataBytes, 0)
+  assert.equal(set.status().budgets.spoolBytes, 6)
+  assert.equal(at(set.status().members, 0).spoolCleanupFailures, 1)
+  assert.equal(at(set.status().members, 0).state, "closed")
+})