socketduct 0.1.15

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

@@ -0,0 +1,421 @@
+import assert from "node:assert/strict"
+import {randomBytes} from "node:crypto"
+import test from "node:test"
+import zlib from "node:zlib"
+
+import {
+  AdaptiveCompressor,
+  availableCodecs,
+  CompressionProtocolError,
+  decodeStreamPayload,
+  encodeStreamPayload,
+  negotiateCodec,
+  zstdAvailable,
+  ZSTD_CODEC
+} from "../../../src/protocol/compression.js"
+
+/**
+ * @param {Buffer} input - Raw bytes.
+ * @param {object} [options] - zstd options.
+ * @returns {Promise<Buffer>} - Compressed bytes.
+ */
+function zstdCompress(input, options = {}) {
+  return new Promise((resolve, reject) => {
+    zlib.zstdCompress(input, options, (err, result) => {
+      if (err) { reject(err); return }
+      resolve(result)
+    })
+  })
+}
+
+/**
+ * @param {number} size - Requested size in bytes.
+ * @returns {Buffer} - Highly compressible text payload.
+ */
+function compressibleChunk(size) {
+  return Buffer.from("GET /api/v1/users HTTP/1.1\r\nHost: example.com\r\nAccept: application/json\r\n\r\n".repeat(200)).subarray(0, size)
+}
+
+/**
+ * @param {number} size - Requested size in bytes.
+ * @returns {Buffer} - Incompressible random payload.
+ */
+function incompressibleChunk(size) {
+  return randomBytes(size)
+}
+
+test("availableCodecs advertises zstd only when the runtime supports it", () => {
+  assert.deepEqual(availableCodecs(), zstdAvailable() ? [ZSTD_CODEC] : [])
+})
+
+test("negotiateCodec selects the first mutually supported codec", () => {
+  assert.equal(negotiateCodec(["zstd"], ["zstd"]), "zstd")
+  assert.equal(negotiateCodec(["brotli", "zstd"], ["zstd"]), "zstd")
+})
+
+test("negotiateCodec returns undefined for absent, empty, unknown or malformed offers", () => {
+  assert.equal(negotiateCodec(undefined, ["zstd"]), undefined)
+  assert.equal(negotiateCodec([], ["zstd"]), undefined)
+  assert.equal(negotiateCodec(["brotli"], ["zstd"]), undefined)
+  assert.equal(negotiateCodec("zstd", ["zstd"]), undefined)
+  assert.equal(negotiateCodec({codec: "zstd"}, ["zstd"]), undefined)
+  assert.equal(negotiateCodec(["zstd"], []), undefined)
+})
+
+test("encodeStreamPayload round-trips a compressible payload and shrinks it", {skip: !zstdAvailable()}, async () => {
+  const chunk = compressibleChunk(8192)
+  const encoded = await encodeStreamPayload(chunk, ZSTD_CODEC)
+
+  assert.equal(encoded.encoding, ZSTD_CODEC)
+  assert.equal(encoded.dataLength, chunk.length)
+  assert.ok(encoded.payload.length < chunk.length)
+
+  const decoded = await decodeStreamPayload(
+    {type: "stream.data", encoding: encoded.encoding, dataLength: encoded.dataLength},
+    encoded.payload,
+    ZSTD_CODEC
+  )
+  assert.deepEqual(decoded, chunk)
+})
+
+test("encodeStreamPayload sends raw when no codec is negotiated", async () => {
+  const chunk = compressibleChunk(8192)
+  const encoded = await encodeStreamPayload(chunk, undefined)
+
+  assert.equal(encoded.encoding, undefined)
+  assert.equal(encoded.dataLength, undefined)
+  assert.deepEqual(encoded.payload, chunk)
+})
+
+test("encodeStreamPayload sends payloads below the minimum size raw", {skip: !zstdAvailable()}, async () => {
+  const chunk = compressibleChunk(64)
+  const encoded = await encodeStreamPayload(chunk, ZSTD_CODEC)
+
+  assert.equal(encoded.encoding, undefined)
+  assert.deepEqual(encoded.payload, chunk)
+})
+
+test("encodeStreamPayload never grows a frame for incompressible data", {skip: !zstdAvailable()}, async () => {
+  const chunk = incompressibleChunk(16384)
+  const encoded = await encodeStreamPayload(chunk, ZSTD_CODEC)
+
+  assert.equal(encoded.encoding, undefined)
+  assert.ok(encoded.payload.length <= chunk.length)
+  assert.deepEqual(encoded.payload, chunk)
+})
+
+test("decodeStreamPayload passes raw payloads through untouched", async () => {
+  const chunk = compressibleChunk(1024)
+  assert.deepEqual(await decodeStreamPayload({type: "stream.data"}, chunk, ZSTD_CODEC), chunk)
+  assert.deepEqual(await decodeStreamPayload({type: "stream.data"}, chunk, undefined), chunk)
+})
+
+test("decodeStreamPayload enforces the uncompressed maximum on raw payloads too", async () => {
+  const chunk = compressibleChunk(4096)
+
+  await assert.rejects(
+    () => decodeStreamPayload({type: "stream.data"}, chunk, undefined, {maxDecompressedBytes: 1024}),
+    CompressionProtocolError
+  )
+  await assert.rejects(
+    () => decodeStreamPayload({type: "stream.data"}, chunk, ZSTD_CODEC, {maxDecompressedBytes: 1024}),
+    CompressionProtocolError
+  )
+})
+
+test("decodeStreamPayload still passes a raw payload within the uncompressed maximum", async () => {
+  const chunk = compressibleChunk(1024)
+
+  assert.deepEqual(await decodeStreamPayload({type: "stream.data"}, chunk, undefined, {maxDecompressedBytes: 1024}), chunk)
+})
+
+test("decodeStreamPayload rejects dataLength without an encoding", async () => {
+  await assert.rejects(
+    () => decodeStreamPayload({type: "stream.data", dataLength: 10}, Buffer.alloc(4), ZSTD_CODEC),
+    CompressionProtocolError
+  )
+})
+
+test("decodeStreamPayload rejects an encoding that was never negotiated", {skip: !zstdAvailable()}, async () => {
+  const chunk = compressibleChunk(4096)
+  const encoded = await encodeStreamPayload(chunk, ZSTD_CODEC)
+
+  await assert.rejects(
+    () => decodeStreamPayload({type: "stream.data", encoding: "zstd", dataLength: chunk.length}, encoded.payload, undefined),
+    CompressionProtocolError
+  )
+})
+
+test("decodeStreamPayload rejects an unknown or non-string encoding", async () => {
+  await assert.rejects(
+    () => decodeStreamPayload({type: "stream.data", encoding: "brotli", dataLength: 32}, Buffer.alloc(8), ZSTD_CODEC),
+    CompressionProtocolError
+  )
+  await assert.rejects(
+    () => decodeStreamPayload({type: "stream.data", encoding: 7, dataLength: 32}, Buffer.alloc(8), ZSTD_CODEC),
+    CompressionProtocolError
+  )
+})
+
+test("decodeStreamPayload rejects malformed dataLength values", {skip: !zstdAvailable()}, async () => {
+  const chunk = compressibleChunk(4096)
+  const encoded = await encodeStreamPayload(chunk, ZSTD_CODEC)
+
+  for (const dataLength of [undefined, 0, -1, 1.5, "4096", Number.MAX_SAFE_INTEGER + 2]) {
+    await assert.rejects(
+      () => decodeStreamPayload({type: "stream.data", encoding: ZSTD_CODEC, dataLength}, encoded.payload, ZSTD_CODEC),
+      CompressionProtocolError
+    )
+  }
+})
+
+test("decodeStreamPayload rejects a dataLength above the configured maximum", {skip: !zstdAvailable()}, async () => {
+  const chunk = compressibleChunk(4096)
+  const encoded = await encodeStreamPayload(chunk, ZSTD_CODEC)
+
+  await assert.rejects(
+    () => decodeStreamPayload(
+      {type: "stream.data", encoding: ZSTD_CODEC, dataLength: chunk.length},
+      encoded.payload,
+      ZSTD_CODEC,
+      {maxDecompressedBytes: 1024}
+    ),
+    CompressionProtocolError
+  )
+})
+
+test("decodeStreamPayload rejects a compressed payload above the configured maximum", {skip: !zstdAvailable()}, async () => {
+  const chunk = compressibleChunk(4096)
+  const encoded = await encodeStreamPayload(chunk, ZSTD_CODEC)
+
+  await assert.rejects(
+    () => decodeStreamPayload(
+      {type: "stream.data", encoding: ZSTD_CODEC, dataLength: chunk.length},
+      encoded.payload,
+      ZSTD_CODEC,
+      {maxCompressedBytes: 8}
+    ),
+    CompressionProtocolError
+  )
+})
+
+test("decodeStreamPayload rejects an empty compressed payload", async () => {
+  await assert.rejects(
+    () => decodeStreamPayload({type: "stream.data", encoding: ZSTD_CODEC, dataLength: 16}, Buffer.alloc(0), ZSTD_CODEC),
+    CompressionProtocolError
+  )
+})
+
+test("decodeStreamPayload rejects payloads whose expansion ratio is too high", {skip: !zstdAvailable()}, async () => {
+  const bomb = Buffer.alloc(4 * 1024 * 1024, 0)
+  const compressed = await zstdCompress(bomb)
+
+  await assert.rejects(
+    () => decodeStreamPayload(
+      {type: "stream.data", encoding: ZSTD_CODEC, dataLength: bomb.length},
+      compressed,
+      ZSTD_CODEC
+    ),
+    CompressionProtocolError
+  )
+})
+
+test("decodeStreamPayload refuses to expand a bomb beyond its advertised dataLength", {skip: !zstdAvailable()}, async () => {
+  const bomb = Buffer.alloc(4 * 1024 * 1024, 0)
+  const compressed = await zstdCompress(bomb)
+
+  // Understates the true size: decompression must be bounded, not allocate 4 MiB.
+  await assert.rejects(
+    () => decodeStreamPayload(
+      {type: "stream.data", encoding: ZSTD_CODEC, dataLength: 1024},
+      compressed,
+      ZSTD_CODEC,
+      {maxExpansionRatio: Number.MAX_SAFE_INTEGER}
+    ),
+    CompressionProtocolError
+  )
+})
+
+test("decodeStreamPayload rejects a dataLength larger than the true decompressed size", {skip: !zstdAvailable()}, async () => {
+  const chunk = compressibleChunk(4096)
+  const encoded = await encodeStreamPayload(chunk, ZSTD_CODEC)
+
+  await assert.rejects(
+    () => decodeStreamPayload(
+      {type: "stream.data", encoding: ZSTD_CODEC, dataLength: chunk.length + 1},
+      encoded.payload,
+      ZSTD_CODEC
+    ),
+    CompressionProtocolError
+  )
+})
+
+test("decodeStreamPayload rejects a corrupt compressed payload", {skip: !zstdAvailable()}, async () => {
+  const chunk = compressibleChunk(4096)
+  const encoded = await encodeStreamPayload(chunk, ZSTD_CODEC)
+  const corrupted = Buffer.from(encoded.payload)
+  corrupted.writeUInt8(corrupted.readUInt8(corrupted.length - 1) ^ 0xff, corrupted.length - 1)
+  corrupted.writeUInt8(corrupted.readUInt8(10) ^ 0xff, 10)
+
+  await assert.rejects(
+    () => decodeStreamPayload(
+      {type: "stream.data", encoding: ZSTD_CODEC, dataLength: chunk.length},
+      corrupted,
+      ZSTD_CODEC
+    ),
+    CompressionProtocolError
+  )
+})
+
+test("decodeStreamPayload rejects a truncated compressed payload", {skip: !zstdAvailable()}, async () => {
+  const chunk = compressibleChunk(4096)
+  const encoded = await encodeStreamPayload(chunk, ZSTD_CODEC)
+
+  await assert.rejects(
+    () => decodeStreamPayload(
+      {type: "stream.data", encoding: ZSTD_CODEC, dataLength: chunk.length},
+      encoded.payload.subarray(0, encoded.payload.length - 4),
+      ZSTD_CODEC
+    ),
+    CompressionProtocolError
+  )
+})
+
+test("AdaptiveCompressor backs off on incompressible streams and re-probes", () => {
+  const adaptive = new AdaptiveCompressor()
+
+  assert.equal(adaptive.shouldCompress(), true)
+  adaptive.record(1.0)
+
+  // Backs off for at least one chunk after an incompressible probe.
+  assert.equal(adaptive.shouldCompress(), false)
+  // Then re-probes.
+  assert.equal(adaptive.shouldCompress(), true)
+})
+
+test("AdaptiveCompressor keeps compressing while the stream compresses well", () => {
+  const adaptive = new AdaptiveCompressor()
+
+  for (let index = 0; index < 5; index += 1) {
+    assert.equal(adaptive.shouldCompress(), true)
+    adaptive.record(0.3)
+  }
+})
+
+test("AdaptiveCompressor widens the skip window as incompressible chunks continue", () => {
+  const adaptive = new AdaptiveCompressor()
+  let skipped = 0
+
+  for (let round = 0; round < 4; round += 1) {
+    while (!adaptive.shouldCompress()) {
+      skipped += 1
+    }
+    adaptive.record(1.0)
+  }
+
+  // 1 + 2 + 4 skipped chunks across the three back-off rounds that follow a probe.
+  assert.equal(skipped, 7)
+})
+
+test("encodeStreamPayload skips compression while the adaptive window is closed", {skip: !zstdAvailable()}, async () => {
+  const adaptive = new AdaptiveCompressor()
+  const incompressible = incompressibleChunk(8192)
+  const compressible = compressibleChunk(8192)
+
+  // First probe is incompressible, which closes the window.
+  assert.equal((await encodeStreamPayload(incompressible, ZSTD_CODEC, adaptive)).encoding, undefined)
+  // Next chunk is skipped without spending CPU, even though it would compress well.
+  assert.equal((await encodeStreamPayload(compressible, ZSTD_CODEC, adaptive)).encoding, undefined)
+  // The re-probe compresses it.
+  assert.equal((await encodeStreamPayload(compressible, ZSTD_CODEC, adaptive)).encoding, ZSTD_CODEC)
+})
+
+test("encodeStreamPayload yields to the event loop and does not block synchronously", {skip: !zstdAvailable()}, async () => {
+  const chunk = compressibleChunk(16384)
+
+  // Two concurrent encode calls must both complete with correct results.
+  // The second call must not be blocked by the first.
+  const [encoded1, encoded2] = await Promise.all([
+    encodeStreamPayload(chunk, ZSTD_CODEC),
+    encodeStreamPayload(chunk, ZSTD_CODEC)
+  ])
+
+  assert.equal(encoded1.encoding, ZSTD_CODEC)
+  assert.ok(encoded1.payload.length < chunk.length)
+  assert.equal(encoded2.encoding, ZSTD_CODEC)
+  assert.ok(encoded2.payload.length < chunk.length)
+  // Independent frames produce independent compressed representations.
+  assert.deepEqual(Buffer.concat([encoded1.payload, encoded2.payload]).length < chunk.length * 2, true)
+})
+
+test("decodeStreamPayload yields to the event loop and does not block synchronously", {skip: !zstdAvailable()}, async () => {
+  const chunk = compressibleChunk(8192)
+  const encoded = await encodeStreamPayload(chunk, ZSTD_CODEC)
+  const header = {type: "stream.data", encoding: ZSTD_CODEC, dataLength: chunk.length}
+
+  // Two concurrent decode calls must both complete without blocking each other.
+  const [decoded1, decoded2] = await Promise.all([
+    decodeStreamPayload(header, encoded.payload, ZSTD_CODEC),
+    decodeStreamPayload(header, encoded.payload, ZSTD_CODEC)
+  ])
+
+  assert.deepEqual(decoded1, chunk)
+  assert.deepEqual(decoded2, chunk)
+})
+
+test("async zstd encoding preserves frame ordering when serialized", {skip: !zstdAvailable()}, async () => {
+  const chunks = [
+    compressibleChunk(4096),
+    compressibleChunk(8192),
+    compressibleChunk(16384)
+  ]
+
+  // Sequential encoding: each completes fully before the next starts.
+  // The test proves the async API returns in order when awaited in sequence.
+  const frames = []
+  for (const chunk of chunks) {
+    frames.push({chunk, encoded: await encodeStreamPayload(chunk, ZSTD_CODEC)})
+  }
+
+  assert.equal(frames.length, 3)
+  for (const frame of frames) {
+    assert.equal(frame.encoded.encoding, ZSTD_CODEC)
+    assert.equal(frame.encoded.dataLength, frame.chunk.length)
+  }
+  // Decode each back and verify data integrity.
+  for (const frame of frames) {
+    const decoded = await decodeStreamPayload(
+      {type: "stream.data", encoding: ZSTD_CODEC, dataLength: frame.chunk.length},
+      frame.encoded.payload,
+      ZSTD_CODEC
+    )
+    assert.deepEqual(decoded, frame.chunk)
+  }
+})
+
+test("async zstd encode-decode round-trips independent payloads without leaking state between calls", {skip: !zstdAvailable()}, async () => {
+  // Interleave encoding and decoding to prove each zstd frame is independent.
+  const payloadA = compressibleChunk(12_000)
+  const payloadB = incompressibleChunk(12_000)
+
+  const encA = await encodeStreamPayload(payloadA, ZSTD_CODEC)
+  const encB = await encodeStreamPayload(payloadB, ZSTD_CODEC)
+
+  // A is compressible, B is not — distinct encodings.
+  assert.equal(encA.encoding, ZSTD_CODEC)
+  assert.equal(encB.encoding, undefined) // raw fallback
+
+  const decA = await decodeStreamPayload(
+    {type: "stream.data", encoding: ZSTD_CODEC, dataLength: payloadA.length},
+    encA.payload,
+    ZSTD_CODEC
+  )
+  const decB = await decodeStreamPayload(
+    {type: "stream.data"},
+    encB.payload,
+    ZSTD_CODEC
+  )
+
+  assert.deepEqual(decA, payloadA)
+  assert.deepEqual(decB, payloadB)
+})