socketduct 0.1.15

package/src/protocol/compression.js

@@ -0,0 +1,325 @@
+import zlib from "node:zlib"
+
+/**
+ * Frame-local compression for `stream.data` payloads.
+ *
+ * Every compressed frame is an independent zstd frame: it carries its own
+ * uncompressed length (`dataLength`) and shares no dictionary or window with
+ * any other frame. That keeps reconnect/resume/replay correct, because a
+ * spooled raw chunk can be re-encoded at any time under whatever codec the
+ * current connection negotiated (including none).
+ *
+ * Sequence numbers, acknowledgements, spool offsets, byte limits and
+ * backpressure all stay in uncompressed bytes. Compression happens when a
+ * frame is built and decompression happens as soon as it is parsed; no other
+ * subsystem ever sees a compressed byte.
+ * @typedef {import('./frame.js').FrameHeader} FrameHeader
+ * @typedef {object} CompressionLimits
+ * @property {number} [minCompressBytes] - Payloads smaller than this are sent raw. Default 256.
+ * @property {number} [maxCompressedBytes] - Maximum accepted compressed payload size. Default 16 MiB.
+ * @property {number} [maxDecompressedBytes] - Maximum accepted decompressed size. Default 16 MiB.
+ * @property {number} [maxExpansionRatio] - Maximum accepted dataLength/compressed size ratio. Default 1000.
+ * @typedef {object} EncodedPayload
+ * @property {Buffer} payload - Bytes to place on the wire.
+ * @property {string} [encoding] - Codec name, omitted when the payload is raw.
+ * @property {number} [dataLength] - Uncompressed length, present only with an encoding.
+ */
+
+export const ZSTD_CODEC = "zstd"
+
+const DEFAULT_MIN_COMPRESS_BYTES = 256
+const DEFAULT_MAX_COMPRESSED_BYTES = 16 * 1024 * 1024
+const DEFAULT_MAX_DECOMPRESSED_BYTES = 16 * 1024 * 1024
+const DEFAULT_MAX_EXPANSION_RATIO = 1000
+const COMPRESSION_MARGIN_BYTES = 16
+const ZSTD_LEVEL = 1
+
+/**
+ * `node:zlib` only exposes zstd from Node 22.15 onward, but `engines` accepts
+ * Node >=22.0, so the binding is probed at runtime rather than imported by name.
+ * @typedef {object} ZstdBinding
+ * @property {((input: Buffer, options: object, callback: (err: Error | null, result: Buffer) => void) => void) | undefined} zstdCompress - Async zstd compressor callback.
+ * @property {((input: Buffer, options: object, callback: (err: Error | null, result: Buffer) => void) => void) | undefined} zstdDecompress - Async zstd decompressor callback.
+ * @property {Record<string, number>} constants - zlib constants.
+ */
+const zstd = /** @type {ZstdBinding} */ (/** @type {unknown} */ (zlib))
+
+/** Raised when a peer sends metadata or a payload that violates the compression contract. */
+export class CompressionProtocolError extends Error {
+  /** @param {string} message - Violation detail. */
+  constructor(message) {
+    super(message)
+    this.name = "CompressionProtocolError"
+  }
+}
+
+/**
+ * Resolves the maximum raw payload size used by the framing and compression
+ * paths. This value is also used as a chunk-splitting divisor, so accepting
+ * zero, fractions, or unsafe integers would make the send loops unsafe.
+ * @param {CompressionLimits} [limits] - Compression size limits.
+ * @returns {number} - Maximum permitted decompressed payload size.
+ */
+export function getMaxDecompressedBytes(limits = {}) {
+  const maxDecompressedBytes = limits.maxDecompressedBytes ?? DEFAULT_MAX_DECOMPRESSED_BYTES
+  if (!Number.isSafeInteger(maxDecompressedBytes) || maxDecompressedBytes < 1) {
+    throw new TypeError("compressionLimits.maxDecompressedBytes must be a positive safe integer")
+  }
+  return maxDecompressedBytes
+}
+
+/** @returns {boolean} - True when this runtime can compress and decompress zstd asynchronously. */
+export function zstdAvailable() {
+  return typeof zstd.zstdCompress === "function"
+    && typeof zstd.zstdDecompress === "function"
+    && typeof zstd.constants?.ZSTD_c_compressionLevel === "number"
+}
+
+/** @returns {string[]} - Codecs this runtime can actually use, in preference order. */
+export function availableCodecs() {
+  return zstdAvailable() ? [ZSTD_CODEC] : []
+}
+
+/**
+ * Picks the first mutually supported codec. Any malformed or unknown offer
+ * yields no codec, which keeps compact stream records uncompressed.
+ * @param {unknown} offer - Codec list advertised by the peer.
+ * @param {string[]} supported - Codecs this side supports, in preference order.
+ * @returns {string | undefined} - Negotiated codec, or undefined for uncompressed data.
+ */
+export function negotiateCodec(offer, supported) {
+  if (!Array.isArray(offer)) {
+    return undefined
+  }
+  for (const codec of supported) {
+    if (offer.includes(codec)) {
+      return codec
+    }
+  }
+  return undefined
+}
+
+/**
+ * @param {Buffer} input - Raw bytes to compress.
+ * @param {object} options - zstd compress options.
+ * @returns {Promise<Buffer>} - Compressed buffer.
+ */
+function zstdCompressAsync(input, options) {
+  const compress = /** @type {NonNullable<ZstdBinding['zstdCompress']>} */ (zstd.zstdCompress)
+  return new Promise((resolve, reject) => {
+    compress(input, options, (err, result) => {
+      if (err) {
+        reject(err)
+        return
+      }
+      resolve(result)
+    })
+  })
+}
+
+/**
+ * @param {Buffer} input - Compressed bytes.
+ * @param {object} options - zstd decompress options.
+ * @returns {Promise<Buffer>} - Decompressed buffer.
+ */
+function zstdDecompressAsync(input, options) {
+  const decompress = /** @type {NonNullable<ZstdBinding['zstdDecompress']>} */ (zstd.zstdDecompress)
+  return new Promise((resolve, reject) => {
+    decompress(input, options, (err, result) => {
+      if (err) {
+        reject(err)
+        return
+      }
+      resolve(result)
+    })
+  })
+}
+
+/**
+ * Encodes one `stream.data` payload, falling back to raw whenever compression
+ * would not pay for itself. The returned frame is never larger than the raw one.
+ * @param {Buffer} chunk - Raw payload bytes.
+ * @param {string | undefined} codec - Negotiated codec, or undefined for raw.
+ * @param {AdaptiveCompressor} [adaptive] - Per-direction adaptive state.
+ * @param {CompressionLimits} [limits] - Compression limits.
+ * @returns {Promise<EncodedPayload>} - Wire payload plus optional metadata.
+ */
+export async function encodeStreamPayload(chunk, codec, adaptive, limits = {}) {
+  const minCompressBytes = limits.minCompressBytes ?? DEFAULT_MIN_COMPRESS_BYTES
+  const maxCompressedBytes = limits.maxCompressedBytes ?? DEFAULT_MAX_COMPRESSED_BYTES
+  const maxDecompressedBytes = getMaxDecompressedBytes(limits)
+
+  // A chunk over the uncompressed limit is rejected by the peer either way, so
+  // there is no point spending CPU compressing it.
+  if (codec !== ZSTD_CODEC || !zstdAvailable() || chunk.length < minCompressBytes || chunk.length > maxDecompressedBytes) {
+    return {payload: chunk}
+  }
+
+  if (adaptive !== undefined && !adaptive.shouldCompress()) {
+    return {payload: chunk}
+  }
+
+  const levelParam = /** @type {number} */ (zstd.constants.ZSTD_c_compressionLevel)
+  /** @type {Buffer} */
+  let compressed
+  try {
+    compressed = await zstdCompressAsync(chunk, {params: {[levelParam]: ZSTD_LEVEL}})
+  } catch {
+    adaptive?.record(1)
+    return {payload: chunk}
+  }
+
+  adaptive?.record(compressed.length / chunk.length)
+
+  // Expansion defense: only keep the compressed form when it actually wins.
+  if (compressed.length + COMPRESSION_MARGIN_BYTES >= chunk.length || compressed.length > maxCompressedBytes) {
+    return {payload: chunk}
+  }
+
+  return {payload: compressed, encoding: ZSTD_CODEC, dataLength: chunk.length}
+}
+
+/**
+ * Validates compression metadata and returns the raw payload bytes.
+ *
+ * Fails closed: any malformed metadata, unnegotiated codec, out-of-bounds
+ * length, excessive expansion ratio or corrupt payload throws. There is no
+ * fallback to treating a compressed payload as raw.
+ * @param {FrameHeader} header - Incoming `stream.data` header.
+ * @param {Buffer} payload - Incoming wire payload.
+ * @param {string | undefined} codec - Codec negotiated on this connection.
+ * @param {CompressionLimits} [limits] - Decompression bounds.
+ * @returns {Promise<Buffer>} - Uncompressed payload bytes.
+ */
+export async function decodeStreamPayload(header, payload, codec, limits = {}) {
+  const encoding = header.encoding
+  const dataLength = header.dataLength
+  const maxUncompressedBytes = getMaxDecompressedBytes(limits)
+
+  if (encoding === undefined || encoding === null) {
+    if (dataLength !== undefined) {
+      throw new CompressionProtocolError("stream.data dataLength requires an encoding.")
+    }
+    // The uncompressed-size limit is a property of the stream, not of the codec:
+    // an uncompressed record that exceeds it is just as much a violation as a compressed one.
+    if (payload.length > maxUncompressedBytes) {
+      throw new CompressionProtocolError(`stream.data payload ${payload.length} exceeds the maximum of ${maxUncompressedBytes} bytes.`)
+    }
+    return payload
+  }
+
+  if (typeof encoding !== "string") {
+    throw new CompressionProtocolError("stream.data encoding must be a string.")
+  }
+
+  if (codec === undefined) {
+    throw new CompressionProtocolError(`stream.data encoding "${encoding}" was not negotiated for this connection.`)
+  }
+
+  if (encoding !== codec) {
+    throw new CompressionProtocolError(`stream.data encoding "${encoding}" does not match negotiated codec "${codec}".`)
+  }
+
+  if (!zstdAvailable()) {
+    throw new CompressionProtocolError(`stream.data encoding "${encoding}" is not supported by this runtime.`)
+  }
+
+  const maxCompressedBytes = limits.maxCompressedBytes ?? DEFAULT_MAX_COMPRESSED_BYTES
+  const maxExpansionRatio = limits.maxExpansionRatio ?? DEFAULT_MAX_EXPANSION_RATIO
+
+  if (typeof dataLength !== "number" || !Number.isSafeInteger(dataLength) || dataLength <= 0) {
+    throw new CompressionProtocolError("stream.data dataLength must be a positive safe integer.")
+  }
+
+  if (dataLength > maxUncompressedBytes) {
+    throw new CompressionProtocolError(`stream.data dataLength ${dataLength} exceeds the maximum of ${maxUncompressedBytes} bytes.`)
+  }
+
+  if (payload.length === 0) {
+    throw new CompressionProtocolError("stream.data compressed payload must not be empty.")
+  }
+
+  if (payload.length > maxCompressedBytes) {
+    throw new CompressionProtocolError(`stream.data compressed payload ${payload.length} exceeds the maximum of ${maxCompressedBytes} bytes.`)
+  }
+
+  if (dataLength / payload.length > maxExpansionRatio) {
+    throw new CompressionProtocolError(`stream.data expansion ratio exceeds the maximum of ${maxExpansionRatio}.`)
+  }
+
+  /** @type {Buffer} */
+  let decompressed
+  try {
+    // The advertised length is also the hard output bound, so a bomb can never
+    // produce more bytes than the sender promised.
+    decompressed = await zstdDecompressAsync(payload, {maxOutputLength: dataLength})
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error)
+    throw new CompressionProtocolError(`stream.data payload failed to decompress: ${detail}`)
+  }
+
+  if (decompressed.length !== dataLength) {
+    throw new CompressionProtocolError(`stream.data decompressed length ${decompressed.length} does not match the advertised dataLength ${dataLength}.`)
+  }
+
+  return decompressed
+}
+
+/**
+ * Send-side only: stops paying CPU on streams that do not compress (TLS, media,
+ * already-compressed payloads) and periodically re-probes in case the stream
+ * changes character. Receivers need no knowledge of this, because every frame
+ * declares its own encoding.
+ */
+export class AdaptiveCompressor {
+  /** @type {number} */
+  #ratio = 0
+
+  /** @type {number} */
+  #skipRemaining = 0
+
+  /** @type {number} */
+  #backoff = 0
+
+  /** @type {number} */
+  #incompressibleRatio
+
+  /** @type {number} */
+  #maxSkipChunks
+
+  /**
+   * @param {object} [options] - Adaptive options.
+   * @param {number} [options.incompressibleRatio] - Ratio at or above which a stream counts as incompressible. Default 0.95.
+   * @param {number} [options.maxSkipChunks] - Upper bound on consecutive skipped chunks. Default 64.
+   */
+  constructor(options = {}) {
+    this.#incompressibleRatio = options.incompressibleRatio ?? 0.95
+    this.#maxSkipChunks = options.maxSkipChunks ?? 64
+  }
+
+  /** @returns {boolean} - True when the next eligible chunk should be compressed. */
+  shouldCompress() {
+    if (this.#skipRemaining > 0) {
+      this.#skipRemaining -= 1
+      return false
+    }
+    return true
+  }
+
+  /**
+   * @param {number} ratio - Achieved compressed/uncompressed ratio.
+   * @returns {void}
+   */
+  record(ratio) {
+    this.#ratio = this.#ratio === 0 ? ratio : (this.#ratio * 0.7) + (ratio * 0.3)
+
+    if (this.#ratio >= this.#incompressibleRatio) {
+      this.#backoff = this.#backoff === 0 ? 1 : Math.min(this.#backoff * 2, this.#maxSkipChunks)
+      this.#skipRemaining = this.#backoff
+      return
+    }
+
+    this.#backoff = 0
+    this.#skipRemaining = 0
+  }
+}

package/src/protocol/frame.js

@@ -0,0 +1,341 @@
+/**
+ * @typedef {Record<string, unknown> & {type: string}} FrameHeader
+ * @typedef {{header: FrameHeader, payload: Buffer, wireFormat: "compact" | "envelope"}} Frame
+ * @typedef {{maxHeaderBytes?: number, maxPayloadBytes?: number, maxInputBytes?: number, compactDirection?: "client-to-target" | "target-to-client"}} FrameDecoderOptions
+ */
+
+const DEFAULT_MAX_HEADER_BYTES = 64 * 1024
+const DEFAULT_MAX_PAYLOAD_BYTES = 16 * 1024 * 1024
+const UINT32_BYTES = 4
+const COMPACT_DATA_RAW = 0x80
+const COMPACT_DATA_ZSTD = 0x81
+const COMPACT_ACK = 0x82
+
+/**
+ * @param {number} value - Safe non-negative integer.
+ * @returns {Buffer} Canonical unsigned LEB128.
+ */
+function encodeVarint(value) {
+  if (!Number.isSafeInteger(value) || value < 0) throw new RangeError("Compact varint value must be a non-negative safe integer")
+  const bytes = []
+  do {
+    const low = value % 128
+    value = Math.floor(value / 128)
+    bytes.push(low | (value > 0 ? 0x80 : 0))
+  } while (value > 0)
+  return Buffer.from(bytes)
+}
+
+/**
+ * @param {{sequence: number, payload: Uint8Array, dataLength?: number}} record - Compact stream record.
+ * @returns {Buffer} Encoded record.
+ */
+export function encodeCompactData(record) {
+  const payload = Buffer.from(record.payload)
+  const parts = [Buffer.from([record.dataLength === undefined ? COMPACT_DATA_RAW : COMPACT_DATA_ZSTD]), encodeVarint(record.sequence)]
+  if (record.dataLength !== undefined) parts.push(encodeVarint(record.dataLength))
+  parts.push(encodeVarint(payload.length), payload)
+  return Buffer.concat(parts)
+}
+
+/**
+ * @param {number} sequence - Acknowledged byte sequence.
+ * @returns {Buffer} Encoded record.
+ */
+export function encodeCompactAck(sequence) {
+  return Buffer.concat([Buffer.from([COMPACT_ACK]), encodeVarint(sequence)])
+}
+
+/**
+ * @param {FrameHeader} header - header value.
+ * @param {Uint8Array} [payload] - payload value.
+ * @returns {Buffer} - Result value.
+ */
+export function encodeFrame(header, payload = Buffer.alloc(0)) {
+  const headerBytes = Buffer.from(JSON.stringify(header), "utf8")
+  const payloadBytes = Buffer.from(payload)
+  const frame = Buffer.allocUnsafe(UINT32_BYTES + headerBytes.length + UINT32_BYTES + payloadBytes.length)
+
+  frame.writeUInt32BE(headerBytes.length, 0)
+  headerBytes.copy(frame, UINT32_BYTES)
+  frame.writeUInt32BE(payloadBytes.length, UINT32_BYTES + headerBytes.length)
+  payloadBytes.copy(frame, UINT32_BYTES + headerBytes.length + UINT32_BYTES)
+
+  return frame
+}
+
+export class FrameDecoder {
+  /** @type {number} */
+  #maxHeaderBytes
+
+  /** @type {number} */
+  #maxPayloadBytes
+
+  /** @type {number} */
+  #maxInputBytes
+
+  /** @type {number} */
+  #inputBytes = 0
+
+  /** @type {"client-to-target" | "target-to-client" | undefined} */
+  #compactDirection
+
+  /** @type {Buffer} */
+  #buffer = Buffer.alloc(0)
+
+  /** @type {number} */
+  #readPos = 0
+
+  /** @type {number} */
+  #writePos = 0
+
+  /** @param {FrameDecoderOptions} [options] - Decoder limits. */
+  constructor(options = {}) {
+    this.#maxHeaderBytes = options.maxHeaderBytes ?? DEFAULT_MAX_HEADER_BYTES
+    this.#maxPayloadBytes = options.maxPayloadBytes ?? DEFAULT_MAX_PAYLOAD_BYTES
+    this.#maxInputBytes = options.maxInputBytes ?? 0
+    this.#compactDirection = options.compactDirection
+  }
+
+  /**
+   * @param {Uint8Array} chunk - chunk value.
+   * @returns {Frame[]} - Result value.
+   */
+  push(chunk) {
+    const chunkLen = chunk.length
+    if (chunkLen === 0) {
+      return []
+    }
+
+    this.#inputBytes += chunkLen
+    if (this.#maxInputBytes > 0 && this.#inputBytes > this.#maxInputBytes) {
+      throw new Error(`Input byte budget exceeded: ${this.#inputBytes} > ${this.#maxInputBytes}`)
+    }
+
+    this.#maybeGrow(chunkLen)
+    this.#copyChunk(chunk, chunkLen)
+
+    return this.#extractFrames()
+  }
+
+  /**
+   * @returns {void}
+   */
+  disableInputBudget() {
+    this.#maxInputBytes = 0
+    this.#inputBytes = 0
+  }
+
+  /**
+   * @param {number} needed - Additional bytes needed.
+   */
+  #maybeGrow(needed) {
+    let writePos = this.#writePos
+    const buffer = this.#buffer
+    let minCapacity = writePos + needed
+
+    if (minCapacity <= buffer.length) {
+      return
+    }
+
+    const readPos = this.#readPos
+    const used = writePos - readPos
+
+    if (readPos > 0) {
+      buffer.copyWithin(0, readPos, writePos)
+      this.#readPos = 0
+      this.#writePos = used
+      writePos = used
+      minCapacity = writePos + needed
+    }
+
+    if (minCapacity <= this.#buffer.length) {
+      return
+    }
+
+    let newCapacity = this.#buffer.length * 2
+    if (newCapacity < 256) {
+      newCapacity = 256
+    }
+    while (newCapacity < minCapacity) {
+      newCapacity = Math.floor(newCapacity * 1.5)
+    }
+
+    const newBuf = Buffer.allocUnsafe(newCapacity)
+    if (used > 0) {
+      newBuf.set(this.#buffer.subarray(0, used), 0)
+    }
+    this.#buffer = newBuf
+  }
+
+  /**
+   * @param {Uint8Array} chunk - chunk value.
+   * @param {number} chunkLen - chunk length.
+   */
+  #copyChunk(chunk, chunkLen) {
+    const writePos = this.#writePos
+    const buf = this.#buffer
+
+    if (chunk instanceof Buffer) {
+      buf.set(chunk, writePos)
+    } else {
+      buf.set(Buffer.from(chunk), writePos)
+    }
+    this.#writePos = writePos + chunkLen
+  }
+
+  /**
+   * @returns {Frame[]} - Result value.
+   */
+  #extractFrames() {
+    /** @type {Frame[]} */
+    const frames = []
+    const buffer = this.#buffer
+    let readPos = this.#readPos
+    const writePos = this.#writePos
+
+    while (true) {
+      const remaining = writePos - readPos
+      if (remaining === 0) {
+        break
+      }
+
+      const firstByte = buffer[readPos]
+      if (this.#compactDirection !== undefined && (firstByte === COMPACT_DATA_RAW || firstByte === COMPACT_DATA_ZSTD || firstByte === COMPACT_ACK)) {
+        const compact = this.#parseCompact(readPos, writePos)
+        if (compact === undefined) break
+        frames.push(compact.frame)
+        readPos = compact.end
+        continue
+      }
+
+      if (remaining < UINT32_BYTES) break
+
+      const headerLength = buffer.readUInt32BE(readPos)
+      if (headerLength <= 0 || headerLength > this.#maxHeaderBytes) {
+        throw new Error(`Invalid frame header length: ${headerLength}`)
+      }
+
+      const payloadLengthOffset = readPos + UINT32_BYTES + headerLength
+      if (remaining < payloadLengthOffset + UINT32_BYTES - readPos) {
+        break
+      }
+
+      const payloadLength = buffer.readUInt32BE(payloadLengthOffset)
+      if (payloadLength > this.#maxPayloadBytes) {
+        throw new Error(`Invalid frame payload length: ${payloadLength}`)
+      }
+
+      const frameEnd = payloadLengthOffset + UINT32_BYTES + payloadLength
+      if (remaining < frameEnd - readPos) {
+        break
+      }
+
+      const headerStart = readPos + UINT32_BYTES
+      const headerBytes = buffer.subarray(headerStart, payloadLengthOffset)
+      const payload = buffer.subarray(payloadLengthOffset + UINT32_BYTES, frameEnd)
+      const header = parseHeader(headerBytes)
+
+      frames.push({header, payload: Buffer.from(payload), wireFormat: "envelope"})
+
+      readPos = frameEnd
+    }
+
+    this.#readPos = readPos
+
+    if (readPos > 0 && readPos >= writePos) {
+      this.#readPos = 0
+      this.#writePos = 0
+    }
+
+    return frames
+  }
+
+  /**
+   * @param {number} start - Record start.
+   * @param {number} end - Available end.
+   * @returns {{frame: Frame, end: number} | undefined} Parsed record or undefined when incomplete.
+   */
+  #parseCompact(start, end) {
+    const tag = this.#buffer[start]
+    if (tag !== COMPACT_DATA_RAW && tag !== COMPACT_DATA_ZSTD && tag !== COMPACT_ACK) throw new Error(`Invalid compact frame tag: ${tag}`)
+    let offset = start + 1
+    const sequenceResult = this.#readVarint(offset, end)
+    if (sequenceResult === undefined) return undefined
+    const sequence = sequenceResult.value
+    offset = sequenceResult.end
+    const dataDirection = /** @type {"client-to-target" | "target-to-client"} */ (this.#compactDirection)
+    const ackDirection = dataDirection === "client-to-target" ? "target-to-client" : "client-to-target"
+    if (tag === COMPACT_ACK) {
+      return {frame: {header: {type: "stream.ack", direction: ackDirection, ackSequence: sequence, compact: true}, payload: Buffer.alloc(0), wireFormat: "compact"}, end: offset}
+    }
+    let dataLength
+    if (tag === COMPACT_DATA_ZSTD) {
+      const lengthResult = this.#readVarint(offset, end)
+      if (lengthResult === undefined) return undefined
+      dataLength = lengthResult.value
+      offset = lengthResult.end
+    }
+    const payloadResult = this.#readVarint(offset, end)
+    if (payloadResult === undefined) return undefined
+    const payloadLength = payloadResult.value
+    offset = payloadResult.end
+    if (payloadLength > this.#maxPayloadBytes) throw new Error(`Invalid frame payload length: ${payloadLength}`)
+    if (end - offset < payloadLength) return undefined
+    /** @type {FrameHeader} */
+    const header = {type: "stream.data", direction: dataDirection, sequence, compact: true}
+    if (tag === COMPACT_DATA_ZSTD) {
+      header.encoding = "zstd"
+      header.dataLength = dataLength
+    }
+    return {frame: {header, payload: Buffer.from(this.#buffer.subarray(offset, offset + payloadLength)), wireFormat: "compact"}, end: offset + payloadLength}
+  }
+
+  /**
+   * @param {number} start - Varint start.
+   * @param {number} end - Available end.
+   * @returns {{value: number, end: number} | undefined} Parsed value or undefined when incomplete.
+   */
+  #readVarint(start, end) {
+    let value = 0
+    let multiplier = 1
+    for (let offset = start; offset < end && offset < start + 8; offset += 1) {
+      const byte = /** @type {number} */ (this.#buffer[offset])
+      const digit = byte & 0x7f
+      if (digit > Math.floor((Number.MAX_SAFE_INTEGER - value) / multiplier)) throw new Error("Compact varint exceeds safe integer range")
+      value += digit * multiplier
+      if ((byte & 0x80) === 0) {
+        if (offset > start && digit === 0) throw new Error("Compact varint is not canonical")
+        return {value, end: offset + 1}
+      }
+      multiplier *= 128
+    }
+    if (end - start >= 8) throw new Error("Compact varint exceeds safe integer range")
+    return undefined
+  }
+}
+
+/**
+ * @param {Buffer} headerBytes - headerBytes value.
+ * @returns {FrameHeader} - Result value.
+ */
+function parseHeader(headerBytes) {
+  const parsed = JSON.parse(headerBytes.toString("utf8"))
+
+  if (!isFrameHeader(parsed)) {
+    throw new Error("Invalid frame header: expected object with string type")
+  }
+
+  return parsed
+}
+
+/**
+ * @param {unknown} value - value value.
+ * @returns {value is FrameHeader} - Result value.
+ */
+function isFrameHeader(value) {
+  return typeof value === "object"
+    && value !== null
+    && !Array.isArray(value)
+    && typeof /** @type {{type?: unknown}} */ (value).type === "string"
+}