socketduct 0.1.15

package/test/unit/protocol/frame.test.js

@@ -0,0 +1,336 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+
+import {FrameDecoder, encodeCompactAck, encodeCompactData, encodeFrame} from "../../../src/protocol/frame.js"
+
+test("encodeFrame and FrameDecoder preserve header fields and payload bytes", () => {
+  const payload = Buffer.from([0, 1, 2, 253, 254, 255])
+  const encoded = encodeFrame({type: "stream.data", sessionId: "session-1", sequence: 42}, payload)
+
+  const decoder = new FrameDecoder()
+  const frames = decoder.push(encoded)
+
+  assert.equal(frames.length, 1)
+  assert.deepEqual(frames[0]?.header, {
+    type: "stream.data",
+    sessionId: "session-1",
+    sequence: 42
+  })
+  assert.deepEqual(frames[0]?.payload, payload)
+  assert.equal(frames[0]?.wireFormat, "envelope")
+})
+
+test("FrameDecoder decodes frames split across multiple TCP chunks", () => {
+  const first = encodeFrame({type: "auth.request", requestId: "a"}, Buffer.from("one"))
+  const second = encodeFrame({type: "session.create", requestId: "b"}, Buffer.from("two"))
+  const combined = Buffer.concat([first, second])
+  const decoder = new FrameDecoder()
+
+  assert.deepEqual(decoder.push(combined.subarray(0, 2)), [])
+  assert.deepEqual(decoder.push(combined.subarray(2, 9)), [])
+  const frames = decoder.push(combined.subarray(9))
+
+  assert.equal(frames.length, 2)
+  assert.equal(frames[0]?.header.type, "auth.request")
+  assert.equal(frames[0]?.payload.toString("utf8"), "one")
+  assert.equal(frames[1]?.header.type, "session.create")
+  assert.equal(frames[1]?.payload.toString("utf8"), "two")
+})
+
+test("FrameDecoder rejects invalid header lengths before allocating payload buffers", () => {
+  const decoder = new FrameDecoder({maxHeaderBytes: 8})
+  const invalid = Buffer.alloc(4)
+  invalid.writeUInt32BE(9, 0)
+
+  assert.throws(() => decoder.push(invalid), /header length/i)
+})
+
+test("FrameDecoder rejects payloads larger than the configured limit", () => {
+  const decoder = new FrameDecoder({maxPayloadBytes: 2})
+  const encoded = encodeFrame({type: "stream.data"}, Buffer.from("too-large"))
+
+  assert.throws(() => decoder.push(encoded), /payload length/i)
+})
+
+test("FrameDecoder handles empty chunk without error", () => {
+  const decoder = new FrameDecoder()
+  const frames = decoder.push(Buffer.alloc(0))
+  assert.deepEqual(frames, [])
+})
+
+test("compact v2 uncompressed data and ACK records round-trip beside envelope controls", () => {
+  const decoder = new FrameDecoder({compactDirection: "target-to-client"})
+  const frames = decoder.push(Buffer.concat([
+    encodeFrame({type: "session.resumed", identifier: "s1", framing: 2}),
+    encodeCompactData({sequence: 300, payload: Buffer.from("raw")}),
+    encodeCompactAck(257),
+    encodeFrame({type: "session.close", direction: "target-to-client"})
+  ]))
+  assert.deepEqual(frames.map(({header, payload}) => ({header, payload: payload.toString()})), [
+    {header: {type: "session.resumed", identifier: "s1", framing: 2}, payload: ""},
+    {header: {type: "stream.data", direction: "target-to-client", sequence: 300, compact: true}, payload: "raw"},
+    {header: {type: "stream.ack", direction: "client-to-target", ackSequence: 257, compact: true}, payload: ""},
+    {header: {type: "session.close", direction: "target-to-client"}, payload: ""}
+  ])
+})
+
+test("compact v2 zstd records normalize compression metadata", () => {
+  const decoder = new FrameDecoder({compactDirection: "client-to-target"})
+  const [frame] = decoder.push(encodeCompactData({sequence: Number.MAX_SAFE_INTEGER, dataLength: 4096, payload: Buffer.from([1, 2, 3])}))
+  assert.deepEqual(frame?.header, {type: "stream.data", direction: "client-to-target", sequence: Number.MAX_SAFE_INTEGER, compact: true, encoding: "zstd", dataLength: 4096})
+  assert.deepEqual(frame?.payload, Buffer.from([1, 2, 3]))
+  assert.equal(frame?.wireFormat, "compact")
+})
+
+test("compact decoder waits for fragmented records", () => {
+  const encoded = encodeCompactData({sequence: 129, payload: Buffer.from("fragmented")})
+  const decoder = new FrameDecoder({compactDirection: "client-to-target"})
+  assert.deepEqual(decoder.push(encoded.subarray(0, 3)), [])
+  assert.equal(decoder.push(encoded.subarray(3))[0]?.payload.toString(), "fragmented")
+})
+
+test("compact decoder rejects non-canonical, overflowing, and oversized varints", () => {
+  const options = /** @type {const} */ ({compactDirection: "client-to-target"})
+  assert.throws(() => new FrameDecoder(options).push(Buffer.from([0x82, 0x80, 0x00])), /canonical/)
+  assert.throws(() => new FrameDecoder(options).push(Buffer.from([0x82, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x7f])), /safe integer/)
+  assert.throws(() => new FrameDecoder({...options, maxPayloadBytes: 2}).push(encodeCompactData({sequence: 3, payload: Buffer.from("abc")})), /payload length/)
+})
+
+test("FrameDecoder handles partial uint32 header length", () => {
+  const decoder = new FrameDecoder()
+  const partial = Buffer.alloc(2)
+  partial.writeUInt16BE(42, 0)
+
+  assert.deepEqual(decoder.push(partial), [])
+})
+
+test("FrameDecoder handles partial header bytes after header length", () => {
+  const decoder = new FrameDecoder()
+  const buf = Buffer.alloc(6)
+  buf.writeUInt32BE(10, 0)
+
+  assert.deepEqual(decoder.push(buf), [])
+})
+
+test("FrameDecoder handles partial payload length uint32 after header", () => {
+  const header = JSON.stringify({type: "test"})
+  const buf = Buffer.alloc(4 + header.length + 2)
+  buf.writeUInt32BE(header.length, 0)
+  buf.write(header, 4, "utf8")
+
+  const decoder = new FrameDecoder()
+  assert.deepEqual(decoder.push(buf), [])
+})
+
+test("FrameDecoder handles partial payload bytes after full header and payload length", () => {
+  const header = JSON.stringify({type: "test"})
+  const buf = Buffer.alloc(4 + header.length + 4 + 3)
+  buf.writeUInt32BE(header.length, 0)
+  buf.write(header, 4, "utf8")
+  buf.writeUInt32BE(10, 4 + header.length)
+
+  const decoder = new FrameDecoder()
+  assert.deepEqual(decoder.push(buf), [])
+})
+
+test("FrameDecoder decodes one frame from a chunk that arrives byte-by-byte (uint32 split)", () => {
+  const payload = Buffer.from("hello")
+  const encoded = encodeFrame({type: "ping"}, payload)
+  const decoder = new FrameDecoder()
+
+  for (let i = 0; i < encoded.length; i++) {
+    const result = decoder.push(encoded.subarray(i, i + 1))
+    if (i < encoded.length - 1) {
+      assert.deepEqual(result, [])
+    } else {
+      assert.equal(result.length, 1)
+      assert.equal(result[0]?.header.type, "ping")
+      assert.deepEqual(result[0]?.payload, payload)
+    }
+  }
+})
+
+test("FrameDecoder decodes multiple complete frames from a single push", () => {
+  const frame1 = encodeFrame({type: "alpha"}, Buffer.from("a"))
+  const frame2 = encodeFrame({type: "beta"}, Buffer.from("bb"))
+  const frame3 = encodeFrame({type: "gamma"}, Buffer.from("ccc"))
+  const combined = Buffer.concat([frame1, frame2, frame3])
+
+  const decoder = new FrameDecoder()
+  const frames = decoder.push(combined)
+
+  assert.equal(frames.length, 3)
+  assert.equal(frames[0]?.header.type, "alpha")
+  assert.equal(frames[0]?.payload.toString(), "a")
+  assert.equal(frames[1]?.header.type, "beta")
+  assert.equal(frames[1]?.payload.toString(), "bb")
+  assert.equal(frames[2]?.header.type, "gamma")
+  assert.equal(frames[2]?.payload.toString(), "ccc")
+})
+
+test("FrameDecoder with maxInputBytes rejects over-budget input", () => {
+  const decoder = new FrameDecoder({maxInputBytes: 10})
+  const frame = encodeFrame({type: "test"}, Buffer.from("hello"))
+
+  assert.throws(() => decoder.push(frame), /input byte budget/i)
+})
+
+test("FrameDecoder with maxInputBytes allows input within budget and rejects on overflow", () => {
+  const decoder = new FrameDecoder({maxInputBytes: 100})
+
+  const header = JSON.stringify({type: "small"})
+  const smallFrame = Buffer.alloc(4 + header.length + 4 + 5)
+  smallFrame.writeUInt32BE(header.length, 0)
+  smallFrame.write(header, 4, "utf8")
+  smallFrame.writeUInt32BE(5, 4 + header.length)
+  smallFrame.write("hello", 4 + header.length + 4, "utf8")
+
+  const frames = decoder.push(smallFrame.subarray(0, 7))
+  assert.deepEqual(frames, [])
+
+  const frames2 = decoder.push(smallFrame.subarray(7))
+  assert.equal(frames2.length, 1)
+  assert.equal(frames2[0]?.header.type, "small")
+
+  const big = Buffer.alloc(2000)
+  big.writeUInt32BE(5, 0)
+  assert.throws(() => decoder.push(big), /input byte budget/i)
+})
+
+test("FrameDecoder with zero maxInputBytes disables budget check", () => {
+  const decoder = new FrameDecoder({maxInputBytes: 0, maxHeaderBytes: 200_000})
+
+  const smallChunk = Buffer.alloc(100_001)
+  smallChunk.writeUInt32BE(100_000, 0)
+
+  assert.deepEqual(decoder.push(smallChunk), [])
+})
+
+test("FrameDecoder byte-by-byte input exercises cursor path: one frame", () => {
+  const payload = Buffer.from("cursor")
+  const encoded = encodeFrame({type: "cursor-test"}, payload)
+  const decoder = new FrameDecoder()
+
+  for (let i = 0; i < encoded.length; i++) {
+    const result = decoder.push(encoded.subarray(i, i + 1))
+    if (i < encoded.length - 1) {
+      assert.deepEqual(result, [])
+    }
+  }
+
+  const frames = decoder.push(Buffer.alloc(0))
+
+  assert.deepEqual(frames, [])
+})
+
+test("FrameDecoder byte-by-byte input exercises cursor path: multiple queued frames", () => {
+  const frame1 = encodeFrame({type: "alpha"}, Buffer.from("a"))
+  const frame2 = encodeFrame({type: "beta"}, Buffer.from("bb"))
+  const frame3 = encodeFrame({type: "gamma"}, Buffer.from("ccc"))
+  const combined = Buffer.concat([frame1, frame2, frame3])
+  const decoder = new FrameDecoder()
+
+  /** @type {import('../../../src/protocol/frame.js').Frame[]} */
+  const allFrames = []
+  for (let i = 0; i < combined.length; i++) {
+    const result = decoder.push(combined.subarray(i, i + 1))
+    for (const f of result) {
+      allFrames.push(f)
+    }
+  }
+
+  for (const f of decoder.push(Buffer.alloc(0))) {
+    allFrames.push(f)
+  }
+
+  assert.equal(allFrames.length, 3)
+  assert.equal(allFrames[0]?.header.type, "alpha")
+  assert.equal(allFrames[0]?.payload.toString(), "a")
+  assert.equal(allFrames[1]?.header.type, "beta")
+  assert.equal(allFrames[1]?.payload.toString(), "bb")
+  assert.equal(allFrames[2]?.header.type, "gamma")
+  assert.equal(allFrames[2]?.payload.toString(), "ccc")
+})
+
+test("FrameDecoder discards header read from garbage bytes and throws on oversized header", () => {
+  const decoder = new FrameDecoder()
+
+  const garbage = Buffer.alloc(5000, 0xFF)
+  assert.throws(() => decoder.push(garbage), /header length/i)
+})
+
+test("FrameDecoder compaction path: readPos shifts after partial consumption triggers compact", () => {
+  const frame1 = encodeFrame({type: "first"}, Buffer.from("data1"))
+  const frame2 = encodeFrame({type: "second"}, Buffer.from("data2"))
+  const combined = Buffer.concat([frame1, frame2])
+  const decoder = new FrameDecoder()
+
+  /** @type {import('../../../src/protocol/frame.js').Frame[]} */
+  const allFrames = []
+  for (const f of decoder.push(combined.subarray(0, frame1.length + 2))) {
+    allFrames.push(f)
+  }
+
+  for (const f of decoder.push(combined.subarray(frame1.length + 2))) {
+    allFrames.push(f)
+  }
+
+  for (const f of decoder.push(Buffer.alloc(0))) {
+    allFrames.push(f)
+  }
+
+  assert.equal(allFrames.length, 2)
+  assert.equal(allFrames[0]?.header.type, "first")
+  assert.equal(allFrames[1]?.header.type, "second")
+})
+
+test("FrameDecoder verifies the decoder is reusable across many byte-by-byte deliveries", () => {
+  const payload = Buffer.from("large-frame")
+  const encoded = encodeFrame({type: "reuse"}, payload)
+  const decoder = new FrameDecoder()
+
+  let totalFrames = 0
+  for (let round = 0; round < 5; round++) {
+    for (let i = 0; i < encoded.length; i++) {
+      const result = decoder.push(encoded.subarray(i, i + 1))
+      totalFrames += result.length
+    }
+  }
+
+  totalFrames += decoder.push(Buffer.alloc(0)).length
+
+  assert.equal(totalFrames, 5)
+})
+
+test("FrameDecoder disableInputBudget allows exceeding original budget", () => {
+  const decoder = new FrameDecoder({maxInputBytes: 100})
+  const smallFrame = encodeFrame({type: "small"}, Buffer.from("hello"))
+  decoder.push(smallFrame)
+
+  decoder.disableInputBudget()
+
+  const largeFrame = encodeFrame({type: "large"}, Buffer.allocUnsafe(200_000))
+  const after = decoder.push(largeFrame)
+  assert.equal(after.length, 1)
+  assert.equal(after[0]?.header.type, "large")
+})
+
+test("FrameDecoder compaction reuses existing capacity instead of unbounded growth", () => {
+  const decoder = new FrameDecoder()
+
+  const manyBytes = Buffer.alloc(1000, 0x41)
+  const bigFrame = encodeFrame({type: "big"}, manyBytes)
+
+  const part1 = bigFrame.subarray(0, 800)
+  const part2 = bigFrame.subarray(800)
+  decoder.push(part1)
+  const extracted = decoder.push(part2)
+  assert.equal(extracted.length, 1)
+
+  for (let round = 0; round < 20; round++) {
+    const inner = encodeFrame({type: "small"}, Buffer.from("x"))
+    const result = decoder.push(inner)
+    assert.equal(result.length, 1)
+    assert.equal(result[0]?.header.type, "small")
+  }
+})

package/test/unit/protocol/v3-compression.test.js

@@ -0,0 +1,31 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+
+import {ZSTD_CODEC, zstdAvailable} from "../../../src/protocol/compression.js"
+import {AdaptiveCompressor, decodeV3Data, encodeV3Data} from "../../../src/protocol/v3-compression.js"
+import {V3FrameFlag} from "../../../src/protocol/v3-frame.js"
+
+test("v3 reverse DATA compression is independent, bounded, and negotiated", async (t) => {
+  if (!zstdAvailable()) {
+    t.skip("Node runtime has no zstd binding")
+    return
+  }
+  const raw = Buffer.from(Array.from({length: 4096}, (_, index) => `{"dockerEvent":${index},"status":"running"}\n`).join(""))
+  const encoded = await encodeV3Data(raw, ZSTD_CODEC, new AdaptiveCompressor())
+  assert.equal(encoded.flags, V3FrameFlag.DATA_COMPRESSED)
+  assert(encoded.wireBytes < encoded.rawBytes)
+  assert.deepEqual(await decodeV3Data(encoded, ZSTD_CODEC), raw)
+  await assert.rejects(decodeV3Data(encoded, undefined), /not negotiated/i)
+
+  const corrupt = {...encoded, payload: Buffer.from(encoded.payload)}
+  const last = corrupt.payload.length - 1
+  corrupt.payload[last] = /** @type {number} */ (corrupt.payload[last]) ^ 0xff
+  await assert.rejects(decodeV3Data(corrupt, ZSTD_CODEC), /decompress/i)
+})
+
+test("v3 reverse DATA remains raw when adaptive compression cannot save bytes", async () => {
+  const raw = Buffer.from("small")
+  const encoded = await encodeV3Data(raw, ZSTD_CODEC, new AdaptiveCompressor())
+  assert.equal(encoded.flags, 0)
+  assert.deepEqual(await decodeV3Data(encoded, ZSTD_CODEC), raw)
+})

package/test/unit/protocol/v3-frame.test.js

@@ -0,0 +1,57 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+
+import {
+  decodeV3Control,
+  encodeV3Control,
+  encodeV3Frame,
+  V3FrameFlag,
+  V3FrameDecoder,
+  V3FrameType
+} from "../../../src/protocol/v3-frame.js"
+
+test("v3 decoder parses fragmented and coalesced binary frames", () => {
+  const first = encodeV3Frame({type: V3FrameType.PING, streamId: 0, sequence: 7})
+  const second = encodeV3Frame({type: V3FrameType.DATA, streamId: 1, sequence: 3}, Buffer.from("abc"))
+  const wire = Buffer.concat([first, second])
+  const decoder = new V3FrameDecoder({maxFrameBytes: 64})
+
+  assert.deepEqual(decoder.push(wire.subarray(0, 9)), [])
+  const frames = decoder.push(wire.subarray(9))
+  assert.deepEqual(frames, [
+    {type: V3FrameType.PING, flags: 0, streamId: 0, sequence: 7, payload: Buffer.alloc(0)},
+    {type: V3FrameType.DATA, flags: 0, streamId: 1, sequence: 3, payload: Buffer.from("abc")}
+  ])
+})
+
+test("v3 framing rejects control/data stream confusion and oversized payloads", () => {
+  assert.throws(
+    () => encodeV3Frame({type: V3FrameType.DATA, streamId: 0, sequence: 1}, Buffer.from("x")),
+    /stream ID zero/i
+  )
+  assert.throws(
+    () => encodeV3Frame({type: V3FrameType.AUTH, streamId: 1, sequence: 0}, Buffer.from("x")),
+    /connection control/i
+  )
+  assert.throws(() => encodeV3Frame({type: V3FrameType.PING, streamId: 0, sequence: 0, flags: 1}), /flags/i)
+
+  const decoder = new V3FrameDecoder({maxFrameBytes: 2, maxBufferedBytes: 64})
+  assert.throws(
+    () => decoder.push(encodeV3Frame({type: V3FrameType.DATA, streamId: 1, sequence: 3}, Buffer.from("abc"))),
+    /payload length/i
+  )
+})
+
+test("v3 control payloads are bounded strict JSON objects", () => {
+  const encoded = encodeV3Control({token: "secret", versions: [3]}, 128)
+  assert.deepEqual(decodeV3Control(encoded, 128), {token: "secret", versions: [3]})
+  assert.throws(() => encodeV3Control(["not-an-object"], 128), /object/i)
+  assert.throws(() => decodeV3Control(Buffer.from("[]"), 128), /object/i)
+  assert.throws(() => encodeV3Control({padding: "x".repeat(129)}, 128), /limit/i)
+})
+
+test("v3 reserves one negotiated compression flag for DATA only", () => {
+  const wire = encodeV3Frame({type: V3FrameType.DATA, streamId: 2, sequence: 10, flags: V3FrameFlag.DATA_COMPRESSED}, Buffer.from("payload"))
+  assert.equal(new V3FrameDecoder().push(wire)[0]?.flags, V3FrameFlag.DATA_COMPRESSED)
+  assert.throws(() => encodeV3Frame({type: V3FrameType.GATEWAY_REGISTER, streamId: 0, sequence: 1, flags: V3FrameFlag.DATA_COMPRESSED}), /flags/i)
+})

package/test/unit/release-configuration.test.js

@@ -0,0 +1,21 @@
+// @ts-check
+
+import assert from "node:assert/strict"
+import {readFile} from "node:fs/promises"
+import {fileURLToPath} from "node:url"
+import test from "node:test"
+
+const packageJsonPath = fileURLToPath(new URL("../../package.json", import.meta.url))
+
+test("patch releases use release-patch", async () => {
+  const packageJson = /** @type {{devDependencies: Record<string, string>, private?: boolean, scripts: Record<string, string>}} */ (JSON.parse(await readFile(packageJsonPath, "utf8")))
+
+  assert.equal(packageJson.private, undefined)
+  assert.equal(packageJson.devDependencies["release-patch"], "^1.0.8")
+  const check = packageJson.scripts.check
+  const releasePatch = packageJson.scripts["release:patch"]
+  assert.ok(check)
+  assert.ok(releasePatch)
+  assert.deepEqual(check.split(" && "), ["npm run lint", "npm run typecheck", "npm test"])
+  assert.deepEqual(releasePatch.split(" && "), ["npm run check", "release-patch"])
+})