socketduct 0.1.15

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

@@ -0,0 +1,295 @@
+import assert from "node:assert/strict"
+import {access, mkdtemp, readFile, rm, stat, writeFile} from "node:fs/promises"
+import {tmpdir} from "node:os"
+import {join} from "node:path"
+import test from "node:test"
+
+import {
+  SessionSpool,
+  SpoolQuotaError
+} from "../../../src/spool/spool-file.js"
+
+/**
+ * @template T
+ * @param {(dir: string) => Promise<T>} fn
+ * @returns {Promise<T>} Promise resolving with the callback result.
+ */
+async function withTempDir(fn) {
+  const dir = await mkdtemp(join(tmpdir(), "socketduct-spool-test-"))
+  try {
+    return await fn(dir)
+  } finally {
+    await rm(dir, {recursive: true, force: true})
+  }
+}
+
+test("SessionSpool creates private per-session temp storage with metadata", async () => {
+  await withTempDir(async (root) => {
+    const spool = new SessionSpool({rootDir: root})
+    const session = await spool.create({sessionId: "session_1234567890", ownerId: "user-1"})
+    const mode = (await stat(session.directory)).mode & 0o777
+
+    assert.equal(mode, 0o700)
+    assert.equal(session.metadata.sessionId, "session_1234567890")
+    assert.equal(session.metadata.ownerId, "user-1")
+  })
+})
+
+test("SessionSpool writes chunks and reads only chunks after a requested sequence", async () => {
+  await withTempDir(async (root) => {
+    const spool = new SessionSpool({rootDir: root})
+    await spool.create({sessionId: "session_1234567890", ownerId: "user-1"})
+    await spool.appendChunk({sessionId: "session_1234567890", sequence: 1, data: Buffer.from("one")})
+    await spool.appendChunk({sessionId: "session_1234567890", sequence: 2, data: Buffer.from([0, 255])})
+    await spool.appendChunk({sessionId: "session_1234567890", sequence: 3, data: Buffer.from("three")})
+
+    const chunks = await spool.readChunksAfter("session_1234567890", 1)
+
+    assert.deepEqual(chunks.map((chunk) => chunk.sequence), [2, 3])
+    assert.deepEqual(chunks[0]?.data, Buffer.from([0, 255]))
+    assert.equal(chunks[1]?.data.toString("utf8"), "three")
+  })
+})
+
+test("SessionSpool truncates acknowledged chunks", async () => {
+  await withTempDir(async (root) => {
+    const spool = new SessionSpool({rootDir: root})
+    await spool.create({sessionId: "session_1234567890", ownerId: "user-1"})
+    await spool.appendChunk({sessionId: "session_1234567890", sequence: 1, data: Buffer.from("one")})
+    await spool.appendChunk({sessionId: "session_1234567890", sequence: 2, data: Buffer.from("two")})
+    await spool.truncateAcked("session_1234567890", 1)
+
+    assert.deepEqual((await spool.readChunksAfter("session_1234567890", 0)).map((chunk) => chunk.sequence), [2])
+  })
+})
+
+test("SessionSpool rejects path traversal and mismatched metadata", async () => {
+  await withTempDir(async (root) => {
+    const spool = new SessionSpool({rootDir: root})
+
+    await assert.rejects(
+      spool.create({sessionId: "../escape", ownerId: "user-1"}),
+      /invalid session identifier/i
+    )
+
+    await spool.create({sessionId: "session_1234567890", ownerId: "user-1"})
+    await assert.rejects(
+      spool.appendChunk({sessionId: "session_1234567890", ownerId: "other-user", sequence: 1, data: Buffer.from("nope")}),
+      /does not match spool metadata/i
+    )
+  })
+})
+
+test("SessionSpool.remove removes all session spool data and rejects subsequent operations", async () => {
+  await withTempDir(async (root) => {
+    const spool = new SessionSpool({rootDir: root})
+    const sessionId = "session_1234567890"
+    await spool.create({sessionId, ownerId: "user-1"})
+    await spool.appendChunk({sessionId, sequence: 1, data: Buffer.from("hello")})
+
+    const dir = join(root, sessionId)
+    await access(dir)
+
+    await spool.remove(sessionId)
+
+    await assert.rejects(
+      access(dir),
+      /ENOENT|no such file/i
+    )
+
+    await assert.rejects(
+      spool.readChunksAfter(sessionId, 0),
+      /ENOENT|no such file/i
+    )
+  })
+})
+
+test("SessionSpool.remove is safe when session does not exist", async () => {
+  await withTempDir(async (root) => {
+    const spool = new SessionSpool({rootDir: root})
+
+    // does not throw
+    await spool.remove("nonexistent_session")
+  })
+})
+
+test("SessionSpool enforces maxBytes quota on appendChunk", async () => {
+  await withTempDir(async (root) => {
+    const spool = new SessionSpool({rootDir: root, maxBytes: 100})
+    const sessionId = "session_1234567890"
+    await spool.create({sessionId, ownerId: "user-1"})
+
+    await spool.appendChunk({sessionId, sequence: 1, data: Buffer.alloc(50)})
+    await spool.appendChunk({sessionId, sequence: 2, data: Buffer.alloc(40)})
+
+    await assert.rejects(
+      spool.appendChunk({sessionId, sequence: 3, data: Buffer.alloc(30)}),
+      (err) => {
+        if (!(err instanceof SpoolQuotaError)) {
+          return false
+        }
+        assert.equal(err.code, "SPOOL_QUOTA_EXCEEDED")
+        assert.ok(err.message.includes("100"))
+        return true
+      }
+    )
+  })
+})
+
+test("SessionSpool maxBytes quota does not block under-limit appends", async () => {
+  await withTempDir(async (root) => {
+    const spool = new SessionSpool({rootDir: root, maxBytes: 200})
+    const sessionId = "session_1234567890"
+    await spool.create({sessionId, ownerId: "user-1"})
+
+    // exactly at limit
+    await spool.appendChunk({sessionId, sequence: 1, data: Buffer.alloc(200)})
+
+    const chunks = await spool.readChunksAfter(sessionId, 0)
+    assert.equal(chunks.length, 1)
+  })
+})
+
+test("SessionSpool enforces maxAgeMs quota for aged-out sessions", async () => {
+  await withTempDir(async (root) => {
+    let now = 1_000_000
+    const maxAgeMs = 60_000
+    const spool = new SessionSpool({rootDir: root, maxAgeMs, now: () => now})
+
+    const session = await spool.create({sessionId: "session_1234567890", ownerId: "user-1"})
+
+    now = 1_000_000 + maxAgeMs - 1
+    await spool.appendChunk({sessionId: session.metadata.sessionId, sequence: 1, data: Buffer.from("ok")})
+
+    now = 1_000_000 + maxAgeMs + 1
+    await assert.rejects(
+      spool.appendChunk({sessionId: session.metadata.sessionId, sequence: 2, data: Buffer.from("x")}),
+      (err) => {
+        if (!(err instanceof SpoolQuotaError)) {
+          return false
+        }
+        assert.equal(err.code, "SPOOL_AGE_EXCEEDED")
+        return true
+      }
+    )
+  })
+})
+
+test("SessionSpool synchronously rejects expired durable recovery state", async () => {
+  await withTempDir(async (root) => {
+    let now = 1_000_000
+    const spool = new SessionSpool({rootDir: root, maxAgeMs: 60_000, now: () => now})
+    const sessionId = "session_recovery_expired"
+    await spool.createNew({sessionId, ownerId: "edge-v3"})
+    await spool.writeRecoveryState(sessionId, {version: 3})
+
+    now += 60_001
+    assert.throws(
+      () => spool.readRecoveryStateSync(sessionId, "edge-v3"),
+      (error) => error instanceof SpoolQuotaError && error.code === "SPOOL_AGE_EXCEEDED"
+    )
+  })
+})
+
+test("SessionSpool cleans expired abandoned entries so their stable IDs can be reused", async () => {
+  await withTempDir(async (root) => {
+    let now = 1_000_000
+    const sessionId = "session_abandoned_expired"
+    const first = new SessionSpool({rootDir: root, maxAgeMs: 60_000, now: () => now})
+    await first.createNew({sessionId, ownerId: "edge-v3"})
+
+    now += 60_001
+    const replacement = new SessionSpool({rootDir: root, maxAgeMs: 60_000, now: () => now})
+    await replacement.createNew({sessionId, ownerId: "edge-v3"})
+    await access(join(root, sessionId))
+  })
+})
+
+test("SessionSpool appendChunk appends lines without rewriting whole file", async () => {
+  await withTempDir(async (root) => {
+    const spool = new SessionSpool({rootDir: root})
+    const sessionId = "session_1234567890"
+    await spool.create({sessionId, ownerId: "user-1"})
+
+    await spool.appendChunk({sessionId, sequence: 1, data: Buffer.from("first")})
+    await spool.appendChunk({sessionId, sequence: 2, data: Buffer.from("second")})
+    await spool.appendChunk({sessionId, sequence: 3, data: Buffer.from("third")})
+
+    const raw = await readFile(join(root, sessionId, "chunks.jsonl"), "utf8")
+    const lines = raw.trimEnd().split("\n")
+
+    assert.ok(lines.length >= 3)
+    const chunk1 = JSON.parse(/** @type {string} */ (lines[0]))
+    const chunk2 = JSON.parse(/** @type {string} */ (lines[1]))
+    const chunk3 = JSON.parse(/** @type {string} */ (lines[2]))
+    assert.equal(chunk1.sequence, 1)
+    assert.equal(chunk2.sequence, 2)
+    assert.equal(chunk3.sequence, 3)
+  })
+})
+
+test("SessionSpool getUsedBytes tracks per-session spool byte usage", async () => {
+  await withTempDir(async (root) => {
+    const spool = new SessionSpool({rootDir: root, maxBytes: 1000})
+    const sessionId = "session_1234567890"
+    await spool.create({sessionId, ownerId: "user-1"})
+
+    assert.equal(spool.getUsedBytes(sessionId), 0)
+
+    await spool.appendChunk({sessionId, sequence: 1, data: Buffer.alloc(50)})
+    assert.equal(spool.getUsedBytes(sessionId), 50)
+
+    await spool.appendChunk({sessionId, sequence: 2, data: Buffer.alloc(30)})
+    assert.equal(spool.getUsedBytes(sessionId), 80)
+
+    await spool.truncateAcked(sessionId, 1)
+    assert.equal(spool.getUsedBytes(sessionId), 30)
+  })
+})
+
+test("SessionSpool getUsedBytes returns undefined for non-existent session", () => {
+  const spool = new SessionSpool({rootDir: "/tmp"})
+  assert.equal(spool.getUsedBytes("nonexistent_session"), undefined)
+})
+
+test("SessionSpool reopened with existing data enforces maxBytes quota from durable usage", async () => {
+  await withTempDir(async (root) => {
+    const sessionId = "session_1234567890"
+
+    const spool1 = new SessionSpool({rootDir: root, maxBytes: 100})
+    await spool1.create({sessionId, ownerId: "user-1"})
+    await spool1.appendChunk({sessionId, sequence: 1, data: Buffer.alloc(60)})
+
+    const spool2 = new SessionSpool({rootDir: root, maxBytes: 100})
+    await spool2.appendChunk({sessionId, sequence: 2, data: Buffer.alloc(30)})
+
+    await assert.rejects(
+      spool2.appendChunk({sessionId, sequence: 3, data: Buffer.alloc(20)}),
+      (err) => err instanceof SpoolQuotaError && err.code === "SPOOL_QUOTA_EXCEEDED"
+    )
+
+    const chunks = await spool2.readChunksAfter(sessionId, 0)
+    assert.equal(chunks.length, 2)
+    assert.equal(chunks[0]?.sequence, 1)
+    assert.equal(chunks[1]?.sequence, 2)
+  })
+})
+
+test("SessionSpool reconciles a stale usage sidecar from durable chunks when reopened", async () => {
+  await withTempDir(async (root) => {
+    const sessionId = "session_1234567890"
+    const spool1 = new SessionSpool({rootDir: root, maxBytes: 20})
+    await spool1.create({sessionId, ownerId: "user-1"})
+    await spool1.appendChunk({sessionId, sequence: 1, data: Buffer.alloc(10)})
+    await writeFile(join(root, sessionId, "usage.json"), JSON.stringify({totalBytes: 20}) + "\n")
+
+    const spool2 = new SessionSpool({rootDir: root, maxBytes: 20})
+    await spool2.appendChunk({sessionId, sequence: 2, data: Buffer.alloc(10)})
+
+    await assert.rejects(
+      spool2.appendChunk({sessionId, sequence: 3, data: Buffer.alloc(1)}),
+      (err) => err instanceof SpoolQuotaError && err.code === "SPOOL_QUOTA_EXCEEDED"
+    )
+    assert.deepEqual((await spool2.readChunksAfter(sessionId, 0)).map((chunk) => chunk.data.length), [10, 10])
+  })
+})

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "allowJs": true,
+    "checkJs": true,
+    "noEmit": true,
+    "lib": ["ES2023"],
+    "types": ["node"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.js", "test/**/*.js"]
+}