socketduct 0.1.25 → 0.1.26

package/test/unit/logging/log-retention.test.js

@@ -1,63 +1,68 @@
 /* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-param-type, jsdoc/require-returns */
-import assert from "node:assert/strict"
+import {describe, expect, it, withTestCleanup} from "@velocious/testing"
 import {readlinkSync} from "node:fs"
 import {mkdtemp, readFile, readdir, rm, utimes, writeFile} from "node:fs/promises"
 import {tmpdir} from "node:os"
 import {join} from "node:path"
-import test from "node:test"
 
 import {enforceLogRetention} from "../../../src/logging/log-retention.js"
 
-test("retention removes only oldest sealed segments and preserves active evidence", async (t) => {
-  const directory = await mkdtemp(join(tmpdir(), "socketduct-retention-"))
-  t.after(() => rm(directory, {recursive: true, force: true}))
-  const old = await createSegment(directory, "reverse-hub-AAAAAAAAAAAAAAAAAAAAAA-123e4567-e89b-42d3-a456-426614174000", 700, true)
-  const newer = await createSegment(directory, "reverse-hub-BBBBBBBBBBBBBBBBBBBBBB-123e4567-e89b-42d3-a456-426614174001", 700, true)
-  const active = await createSegment(directory, "reverse-hub-CCCCCCCCCCCCCCCCCCCCCC-123e4567-e89b-42d3-a456-426614174002", 700, false)
-  await utimes(old.data, new Date(1_000), new Date(1_000))
-  await utimes(newer.data, new Date(2_000), new Date(2_000))
-  await utimes(active.data, new Date(3_000), new Date(3_000))
+describe("log retention", () => {
+  it("retention removes only oldest sealed segments and preserves active evidence", async () => withTestCleanup(async (after) => {
+    const directory = await mkdtemp(join(tmpdir(), "socketduct-retention-"))
+    after(() => rm(directory, {recursive: true, force: true}))
+    const old = await createSegment(directory, "reverse-hub-AAAAAAAAAAAAAAAAAAAAAA-123e4567-e89b-42d3-a456-426614174000", 700, true)
+    const newer = await createSegment(directory, "reverse-hub-BBBBBBBBBBBBBBBBBBBBBB-123e4567-e89b-42d3-a456-426614174001", 700, true)
+    const active = await createSegment(directory, "reverse-hub-CCCCCCCCCCCCCCCCCCCCCC-123e4567-e89b-42d3-a456-426614174002", 700, false)
+    await utimes(old.data, new Date(1_000), new Date(1_000))
+    await utimes(newer.data, new Date(2_000), new Date(2_000))
+    await utimes(active.data, new Date(3_000), new Date(3_000))
 
-  const result = await enforceLogRetention({directory, maxAgeMs: 60_000, maxBytes: 1800, now: () => new Date(3_000)})
-  const names = await readdir(directory)
-  assert.equal(names.some((name) => name.startsWith(old.name)), false)
-  assert(names.some((name) => name.startsWith(newer.name)))
-  assert(names.some((name) => name.startsWith(active.name)))
-  assert.equal(result.deletedSegments, 1)
-})
+    const result = await enforceLogRetention({directory, maxAgeMs: 60_000, maxBytes: 1800, now: () => new Date(3_000)})
+    const names = await readdir(directory)
+    expect(names.some((name) => name.startsWith(old.name))).toBe(false)
+    expect(names.some((name) => name.startsWith(newer.name))).toBeTruthy()
+    expect(names.some((name) => name.startsWith(active.name))).toBeTruthy()
+    expect(result.deletedSegments).toBe(1)
+  }))
 
-test("retention fails closed when active or quarantined bytes prevent quota compliance", async (t) => {
-  const directory = await mkdtemp(join(tmpdir(), "socketduct-retention-blocked-"))
-  t.after(() => rm(directory, {recursive: true, force: true}))
-  const active = await createSegment(directory, "reverse-client-DDDDDDDDDDDDDDDDDDDDDD-123e4567-e89b-42d3-a456-426614174003", 1800, false)
-  await writeFile(`${active.data}.quarantine`, "LOG_EVIDENCE_INVALID", {mode: 0o600})
+  it("retention fails closed when active or quarantined bytes prevent quota compliance", async () => withTestCleanup(async (after) => {
+    const directory = await mkdtemp(join(tmpdir(), "socketduct-retention-blocked-"))
+    after(() => rm(directory, {recursive: true, force: true}))
+    const active = await createSegment(directory, "reverse-client-DDDDDDDDDDDDDDDDDDDDDD-123e4567-e89b-42d3-a456-426614174003", 1800, false)
+    await writeFile(`${active.data}.quarantine`, "LOG_EVIDENCE_INVALID", {mode: 0o600})
 
-  await assert.rejects(
-    () => enforceLogRetention({directory, maxAgeMs: 60_000, maxBytes: 1024, now: () => new Date(3_000)}),
-    (error) => error instanceof Error && /** @type {{code?: unknown}} */ (error).code === "LOG_RETENTION_QUOTA_BLOCKED"
-  )
-  assert((await readdir(directory)).some((name) => name.startsWith(active.name)))
-})
+    let error
+    try {
+      await enforceLogRetention({directory, maxAgeMs: 60_000, maxBytes: 1024, now: () => new Date(3_000)})
+    } catch (caught) {
+      error = caught
+    }
+    expect(error).toBeDefined()
+    expect(error instanceof Error && /** @type {{code?: unknown}} */ (error).code === "LOG_RETENTION_QUOTA_BLOCKED").toBeTruthy()
+    expect((await readdir(directory)).some((name) => name.startsWith(active.name))).toBeTruthy()
+  }))
 
-test("retention reclaims stale ownership without displacing a live process instance", async (t) => {
-  const directory = await mkdtemp(join(tmpdir(), "socketduct-retention-owner-"))
-  t.after(() => rm(directory, {recursive: true, force: true}))
-  const lockPath = join(directory, ".socketduct-retention.lock")
-  const processStart = processStartIdentity(await readFile(`/proc/${process.pid}/stat`, "utf8"))
-  const tid = Number(readlinkSync("/proc/thread-self").split("/").at(-1))
-  const threadStart = processStartIdentity(await readFile(`/proc/${process.pid}/task/${tid}/stat`, "utf8"))
-  const staleTemporary = `.socketduct-retention-owner-${process.pid}-${BigInt(processStart) + 1n}-${tid}-${threadStart}-123e4567-e89b-42d3-a456-426614174099.tmp`
-  await writeFile(join(directory, staleTemporary), "incomplete", {mode: 0o600})
+  it("retention reclaims stale ownership without displacing a live process instance", async () => withTestCleanup(async (after) => {
+    const directory = await mkdtemp(join(tmpdir(), "socketduct-retention-owner-"))
+    after(() => rm(directory, {recursive: true, force: true}))
+    const lockPath = join(directory, ".socketduct-retention.lock")
+    const processStart = processStartIdentity(await readFile(`/proc/${process.pid}/stat`, "utf8"))
+    const tid = Number(readlinkSync("/proc/thread-self").split("/").at(-1))
+    const threadStart = processStartIdentity(await readFile(`/proc/${process.pid}/task/${tid}/stat`, "utf8"))
+    const staleTemporary = `.socketduct-retention-owner-${process.pid}-${BigInt(processStart) + 1n}-${tid}-${threadStart}-123e4567-e89b-42d3-a456-426614174099.tmp`
+    await writeFile(join(directory, staleTemporary), "incomplete", {mode: 0o600})
 
-  await writeFile(lockPath, `${JSON.stringify({version: 1, pid: process.pid, processStart: String(BigInt(processStart) + 1n), tid, threadStart})}\n`, {mode: 0o600})
-  assert.equal((await enforceLogRetention({directory, maxAgeMs: 60_000, maxBytes: 1024})).skipped, false)
-  assert.equal((await readdir(directory)).includes(staleTemporary), false)
+    await writeFile(lockPath, `${JSON.stringify({version: 1, pid: process.pid, processStart: String(BigInt(processStart) + 1n), tid, threadStart})}\n`, {mode: 0o600})
+    expect((await enforceLogRetention({directory, maxAgeMs: 60_000, maxBytes: 1024})).skipped).toBe(false)
+    expect((await readdir(directory)).includes(staleTemporary)).toBe(false)
 
-  await writeFile(lockPath, `${JSON.stringify({version: 1, pid: process.pid, processStart, tid: 2_147_483_647, threadStart: "1"})}\n`, {mode: 0o600})
-  assert.equal((await enforceLogRetention({directory, maxAgeMs: 60_000, maxBytes: 1024})).skipped, false)
+    await writeFile(lockPath, `${JSON.stringify({version: 1, pid: process.pid, processStart, tid: 2_147_483_647, threadStart: "1"})}\n`, {mode: 0o600})
+    expect((await enforceLogRetention({directory, maxAgeMs: 60_000, maxBytes: 1024})).skipped).toBe(false)
 
-  await writeFile(lockPath, `${JSON.stringify({version: 1, pid: process.pid, processStart, tid, threadStart})}\n`, {mode: 0o600})
-  assert.equal((await enforceLogRetention({directory, maxAgeMs: 60_000, maxBytes: 1024})).skipped, true)
+    await writeFile(lockPath, `${JSON.stringify({version: 1, pid: process.pid, processStart, tid, threadStart})}\n`, {mode: 0o600})
+    expect((await enforceLogRetention({directory, maxAgeMs: 60_000, maxBytes: 1024})).skipped).toBe(true)
+  }))
 })
 
 /**
@@ -80,7 +85,7 @@ function processStartIdentity(value) {
   const close = value.lastIndexOf(")")
   const fields = value.slice(close + 2).trim().split(/\s+/)
   const start = fields[19]
-  if (start === undefined) assert.fail("process stat omits start time")
-  assert.match(start, /^[0-9]+$/)
+  if (start === undefined) throw new Error("process stat omits start time")
+  expect(start).toMatch(/^[0-9]+$/)
   return start
 }

package/test/unit/logging/log-segment-index.test.js

@@ -1,6 +1,5 @@
-import assert from "node:assert/strict"
+import {describe, expect, it} from "@velocious/testing"
 import {createHash, randomBytes} from "node:crypto"
-import test from "node:test"
 
 import {
   INDEX_ENTRY_BYTES,
@@ -12,93 +11,97 @@ import {
   uuidBytes
 } from "../../../src/logging/log-segment-index.js"
 
-test("index v1 header and entry round-trip in the exact fixed-width format", () => {
-  const segmentUuid = uuidBytes("123e4567-e89b-42d3-a456-426614174000")
-  const writerEpoch = randomBytes(16)
-  const batchId = randomBytes(16)
-  const frameHash = createHash("sha256").update("frame").digest()
-  const header = createIndexHeader({segmentUuid, writerEpoch})
-  const entry = createIndexEntry({
-    segmentUuid,
-    writerEpoch,
-    batchId,
-    firstSequence: 1n,
-    lastSequence: 3n,
-    dataOffset: 0n,
-    compressedLength: 91n,
-    uncompressedLength: 240n,
-    recordCount: 3,
-    minTimestamp: 1_795_000_000_000n,
-    maxTimestamp: 1_795_000_000_010n,
-    frameSha256: frameHash
-  })
+describe("log segment index", () => {
+  it("index v1 header and entry round-trip in the exact fixed-width format", () => {
+    const segmentUuid = uuidBytes("123e4567-e89b-42d3-a456-426614174000")
+    const writerEpoch = randomBytes(16)
+    const batchId = randomBytes(16)
+    const frameHash = createHash("sha256").update("frame").digest()
+    const header = createIndexHeader({segmentUuid, writerEpoch})
+    const entry = createIndexEntry({
+      segmentUuid,
+      writerEpoch,
+      batchId,
+      firstSequence: 1n,
+      lastSequence: 3n,
+      dataOffset: 0n,
+      compressedLength: 91n,
+      uncompressedLength: 240n,
+      recordCount: 3,
+      minTimestamp: 1_795_000_000_000n,
+      maxTimestamp: 1_795_000_000_010n,
+      frameSha256: frameHash
+    })
 
-  assert.equal(header.length, INDEX_HEADER_BYTES)
-  assert.equal(entry.length, INDEX_ENTRY_BYTES)
-  assert.deepEqual(parseIndexHeader(header), {version: 1, segmentUuid, writerEpoch})
-  assert.deepEqual(parseIndexEntry(entry, {segmentUuid, writerEpoch}), {
-    version: 1,
-    flags: 0,
-    segmentUuid,
-    writerEpoch,
-    batchId,
-    firstSequence: 1n,
-    lastSequence: 3n,
-    dataOffset: 0n,
-    compressedLength: 91n,
-    uncompressedLength: 240n,
-    recordCount: 3,
-    minTimestamp: 1_795_000_000_000n,
-    maxTimestamp: 1_795_000_000_010n,
-    frameSha256: frameHash
+    expect(header.length).toBe(INDEX_HEADER_BYTES)
+    expect(entry.length).toBe(INDEX_ENTRY_BYTES)
+    const parsedHeader = parseIndexHeader(header)
+    expect(parsedHeader.version).toBe(1)
+    expect(Buffer.from(parsedHeader.segmentUuid).equals(Buffer.from(segmentUuid))).toBe(true)
+    expect(Buffer.from(parsedHeader.writerEpoch).equals(Buffer.from(writerEpoch))).toBe(true)
+    const parsedEntry = parseIndexEntry(entry, {segmentUuid, writerEpoch})
+    expect(parsedEntry.version).toBe(1)
+    expect(parsedEntry.flags).toBe(0)
+    expect(Buffer.from(parsedEntry.segmentUuid).equals(Buffer.from(segmentUuid))).toBe(true)
+    expect(Buffer.from(parsedEntry.writerEpoch).equals(Buffer.from(writerEpoch))).toBe(true)
+    expect(Buffer.from(parsedEntry.batchId).equals(Buffer.from(batchId))).toBe(true)
+    expect(parsedEntry.firstSequence).toBe(1n)
+    expect(parsedEntry.lastSequence).toBe(3n)
+    expect(parsedEntry.dataOffset).toBe(0n)
+    expect(parsedEntry.compressedLength).toBe(91n)
+    expect(parsedEntry.uncompressedLength).toBe(240n)
+    expect(parsedEntry.recordCount).toBe(3)
+    expect(parsedEntry.minTimestamp).toBe(1_795_000_000_000n)
+    expect(parsedEntry.maxTimestamp).toBe(1_795_000_000_010n)
+    expect(Buffer.from(parsedEntry.frameSha256).equals(Buffer.from(frameHash))).toBe(true)
   })
-})
 
-test("index CRC and identity corruption fail closed", () => {
-  const segmentUuid = randomBytes(16)
-  const writerEpoch = randomBytes(16)
-  const header = createIndexHeader({segmentUuid, writerEpoch})
-  header[20] = /** @type {number} */ (header[20]) ^ 0xff
-  assert.throws(() => parseIndexHeader(header), /CRC32C/)
+  it("index CRC and identity corruption fail closed", () => {
+    const segmentUuid = randomBytes(16)
+    const writerEpoch = randomBytes(16)
+    const header = createIndexHeader({segmentUuid, writerEpoch})
+    header[20] = /** @type {number} */ (header[20]) ^ 0xff
+    expect(() => parseIndexHeader(header)).toThrow(/CRC32C/)
 
-  const entry = createIndexEntry({
-    segmentUuid,
-    writerEpoch,
-    batchId: randomBytes(16),
-    firstSequence: 8n,
-    lastSequence: 8n,
-    dataOffset: 10n,
-    compressedLength: 20n,
-    uncompressedLength: 30n,
-    recordCount: 1,
-    minTimestamp: 4n,
-    maxTimestamp: 4n,
-    frameSha256: randomBytes(32)
-  })
-  entry[151] = /** @type {number} */ (entry[151]) ^ 0xff
-  assert.throws(() => parseIndexEntry(entry, {segmentUuid, writerEpoch}), /CRC32C/)
-})
-
-test("index bytes contain no searchable diagnostic dimensions", () => {
-  const forbidden = ["minisforum-zyxel", "disconnect-incident", "GATEWAY_DISCONNECTED", "docker.internal"]
-  const segmentUuid = randomBytes(16)
-  const writerEpoch = randomBytes(16)
-  const encoded = Buffer.concat([
-    createIndexHeader({segmentUuid, writerEpoch}),
-    createIndexEntry({
+    const entry = createIndexEntry({
       segmentUuid,
       writerEpoch,
       batchId: randomBytes(16),
-      firstSequence: 1n,
-      lastSequence: 1n,
-      dataOffset: 0n,
-      compressedLength: 1n,
-      uncompressedLength: 1n,
+      firstSequence: 8n,
+      lastSequence: 8n,
+      dataOffset: 10n,
+      compressedLength: 20n,
+      uncompressedLength: 30n,
       recordCount: 1,
-      minTimestamp: 1n,
-      maxTimestamp: 1n,
+      minTimestamp: 4n,
+      maxTimestamp: 4n,
       frameSha256: randomBytes(32)
     })
-  ])
-  for (const value of forbidden) assert.equal(encoded.includes(Buffer.from(value)), false)
+    entry[151] = /** @type {number} */ (entry[151]) ^ 0xff
+    expect(() => parseIndexEntry(entry, {segmentUuid, writerEpoch})).toThrow(/CRC32C/)
+  })
+
+  it("index bytes contain no searchable diagnostic dimensions", () => {
+    const forbidden = ["minisforum-zyxel", "disconnect-incident", "GATEWAY_DISCONNECTED", "docker.internal"]
+    const segmentUuid = randomBytes(16)
+    const writerEpoch = randomBytes(16)
+    const encoded = Buffer.concat([
+      createIndexHeader({segmentUuid, writerEpoch}),
+      createIndexEntry({
+        segmentUuid,
+        writerEpoch,
+        batchId: randomBytes(16),
+        firstSequence: 1n,
+        lastSequence: 1n,
+        dataOffset: 0n,
+        compressedLength: 1n,
+        uncompressedLength: 1n,
+        recordCount: 1,
+        minTimestamp: 1n,
+        maxTimestamp: 1n,
+        frameSha256: randomBytes(32)
+      })
+    ])
+    for (const value of forbidden) expect(encoded.includes(Buffer.from(value))).toBe(false)
+  })
 })

package/test/unit/logging/zstd-frame-codec.test.js

@@ -1,24 +1,33 @@
-import assert from "node:assert/strict"
-import test from "node:test"
+import {describe, expect, it} from "@velocious/testing"
 
-import {compressLogFrame, decompressLogFrame} from "../../../src/logging/zstd-frame-codec.js"
+import {DEFAULT_LOG_COMPRESSION_LEVEL, compressLogFrame, decompressLogFrame} from "../../../src/logging/zstd-frame-codec.js"
 
-test("log codec emits independently decodable standard zstd frames with checksums at level 19", async () => {
-  const firstRaw = Buffer.from('{"event":"first"}\n')
-  const secondRaw = Buffer.from('{"event":"second"}\n')
-  const first = await compressLogFrame(firstRaw)
-  const second = await compressLogFrame(secondRaw)
+describe("zstd log frame codec", () => {
+  it("emits independently decodable standard zstd frames with checksums at the default level", async () => {
+    const firstRaw = Buffer.from('{"event":"first"}\n')
+    const secondRaw = Buffer.from('{"event":"second"}\n')
+    const first = await compressLogFrame(firstRaw)
+    const second = await compressLogFrame(secondRaw)
 
-  assert.deepEqual(first.subarray(0, 4), Buffer.from([0x28, 0xb5, 0x2f, 0xfd]))
-  assert.notEqual(/** @type {number} */ (first[4]) & 0x04, 0, "zstd frame checksum flag must be set")
-  assert.deepEqual(await decompressLogFrame(first), firstRaw)
-  assert.deepEqual(await decompressLogFrame(second), secondRaw)
-  assert.notDeepEqual(first, second)
-})
+    expect(first.subarray(0, 4).toString("hex")).toBe("28b52ffd")
+    expect(Number(first[4]) & 0x04).toBeGreaterThan(0)
+    expect((await decompressLogFrame(first)).toString("hex")).toBe(firstRaw.toString("hex"))
+    expect((await decompressLogFrame(second)).toString("hex")).toBe(secondRaw.toString("hex"))
+    expect(first.equals(second)).toBe(false)
+  })
+
+  it("never falls back to plaintext", async () => {
+    const raw = Buffer.from("small\n")
+    const frame = await compressLogFrame(raw)
+
+    expect(frame.equals(raw)).toBe(false)
+    await expect(decompressLogFrame(Buffer.from("small\n"))).rejects.toThrow()
+  })
 
-test("log codec never falls back to plaintext", async () => {
-  const raw = Buffer.from("small\n")
-  const frame = await compressLogFrame(raw)
-  assert.equal(frame.equals(raw), false)
-  await assert.rejects(() => decompressLogFrame(Buffer.from("small\n")))
+  it("default compression level stays memory-bounded", () => {
+    // A fresh zstd context per batch costs ~1-2 MB at level 9, tens of MB at 12
+    // and ~90 MB at 19. Keep the default in the bounded range unless a
+    // deliberate review accepts the resident-memory consequences.
+    expect(DEFAULT_LOG_COMPRESSION_LEVEL).toBeLessThanOrEqual(9)
+  })
 })