socketduct 0.1.15

package/src/protocol/v3-compression.js

@@ -0,0 +1,44 @@
+import {AdaptiveCompressor, decodeStreamPayload, encodeStreamPayload, ZSTD_CODEC} from "./compression.js"
+import {V3FrameFlag} from "./v3-frame.js"
+
+const LENGTH_BYTES = 4
+
+/**
+ * Encodes one independently decompressible v3 DATA payload.
+ * @param {Buffer} data - Raw stream bytes.
+ * @param {string | undefined} codec - Negotiated codec.
+ * @param {AdaptiveCompressor} adaptive - Per-direction adaptive state.
+ * @param {import('./compression.js').CompressionLimits} [limits] - Codec limits.
+ * @returns {Promise<{payload: Buffer, flags: number, rawBytes: number, wireBytes: number}>} Encoded v3 payload.
+ */
+export async function encodeV3Data(data, codec, adaptive, limits = {}) {
+  const encoded = await encodeStreamPayload(data, codec, adaptive, limits)
+  if (encoded.encoding === undefined) return {payload: encoded.payload, flags: 0, rawBytes: data.length, wireBytes: data.length}
+  const payload = Buffer.allocUnsafe(LENGTH_BYTES + encoded.payload.length)
+  payload.writeUInt32BE(data.length, 0)
+  encoded.payload.copy(payload, LENGTH_BYTES)
+  return {payload, flags: V3FrameFlag.DATA_COMPRESSED, rawBytes: data.length, wireBytes: payload.length}
+}
+
+/**
+ * Decodes one v3 DATA payload and rejects unnegotiated compression.
+ * @param {{flags: number, payload: Buffer}} frame - Incoming DATA frame.
+ * @param {string | undefined} codec - Negotiated codec.
+ * @param {import('./compression.js').CompressionLimits} [limits] - Codec limits.
+ * @returns {Promise<Buffer>} Raw stream bytes.
+ */
+export async function decodeV3Data(frame, codec, limits = {}) {
+  if (frame.flags === 0) return await decodeStreamPayload({type: "stream.data"}, frame.payload, codec, limits)
+  if (frame.flags !== V3FrameFlag.DATA_COMPRESSED) throw new Error("Unsupported V3 DATA flags")
+  if (codec !== ZSTD_CODEC) throw new Error("Compressed V3 DATA was not negotiated")
+  if (frame.payload.length <= LENGTH_BYTES) throw new Error("Compressed V3 DATA payload is truncated")
+  const dataLength = frame.payload.readUInt32BE(0)
+  return await decodeStreamPayload(
+    {type: "stream.data", encoding: ZSTD_CODEC, dataLength},
+    frame.payload.subarray(LENGTH_BYTES),
+    codec,
+    limits
+  )
+}
+
+export {AdaptiveCompressor}

package/src/protocol/v3-frame.js

@@ -0,0 +1,209 @@
+const MAGIC = Buffer.from("SDV3")
+const VERSION = 3
+const HEADER_BYTES = 24
+const DEFAULT_MAX_FRAME_BYTES = 64 * 1024
+const DEFAULT_MAX_CONTROL_BYTES = 64 * 1024
+const UINT64_MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER)
+
+export const V3FrameType = Object.freeze({
+  AUTH: 1,
+  AUTH_OK: 2,
+  AUTH_ERROR: 3,
+  PING: 4,
+  PONG: 5,
+  GOAWAY: 6,
+  RESUME: 7,
+  RESUMED: 8,
+  GATEWAY_REGISTER: 9,
+  GATEWAY_REGISTERED: 10,
+  GATEWAY_SELECT: 11,
+  GATEWAY_SELECTED: 12,
+  OPEN: 16,
+  OPENED: 17,
+  DATA: 18,
+  ACK: 19,
+  WINDOW: 20,
+  END: 21,
+  CLOSE: 22,
+  RESET: 23
+})
+
+export const V3FrameFlag = Object.freeze({
+  DATA_COMPRESSED: 1
+})
+
+/** @type {Set<number>} */
+const CONNECTION_TYPES = new Set([
+  V3FrameType.AUTH,
+  V3FrameType.AUTH_OK,
+  V3FrameType.AUTH_ERROR,
+  V3FrameType.PING,
+  V3FrameType.PONG,
+  V3FrameType.GOAWAY,
+  V3FrameType.RESUME,
+  V3FrameType.RESUMED,
+  V3FrameType.GATEWAY_REGISTER,
+  V3FrameType.GATEWAY_REGISTERED,
+  V3FrameType.GATEWAY_SELECT,
+  V3FrameType.GATEWAY_SELECTED
+])
+/** @type {Set<number>} */
+const STREAM_TYPES = new Set([
+  V3FrameType.OPEN,
+  V3FrameType.OPENED,
+  V3FrameType.DATA,
+  V3FrameType.ACK,
+  V3FrameType.WINDOW,
+  V3FrameType.END,
+  V3FrameType.CLOSE,
+  V3FrameType.RESET
+])
+
+/**
+ * @typedef {object} V3FrameHeader
+ * @property {number} type - V3FrameType value.
+ * @property {number} streamId - Zero for connection control, otherwise a virtual stream ID.
+ * @property {number} sequence - Cumulative byte position or control sequence.
+ * @property {number} [flags] - Protocol flags.
+ * @typedef {V3FrameHeader & {payload: Buffer, flags: number}} V3Frame
+ */
+
+/**
+ * Encodes one protocol-v3 binary frame.
+ * @param {V3FrameHeader} header - Validated frame header.
+ * @param {Uint8Array} [payload] - Frame payload.
+ * @returns {Buffer} Wire bytes.
+ */
+export function encodeV3Frame(header, payload = Buffer.alloc(0)) {
+  validateHeader(header)
+  const body = Buffer.from(payload)
+  if (body.length > 0xffff_ffff) throw new RangeError("V3 frame payload length exceeds uint32")
+  const wire = Buffer.allocUnsafe(HEADER_BYTES + body.length)
+  MAGIC.copy(wire, 0)
+  wire[4] = VERSION
+  wire[5] = header.type
+  wire.writeUInt16BE(header.flags ?? 0, 6)
+  wire.writeUInt32BE(header.streamId, 8)
+  wire.writeBigUInt64BE(BigInt(header.sequence), 12)
+  wire.writeUInt32BE(body.length, 20)
+  body.copy(wire, HEADER_BYTES)
+  return wire
+}
+
+/**
+ * Encodes a bounded JSON control object.
+ * @param {unknown} value - Plain JSON object.
+ * @param {number} [maxBytes] - Encoded size limit.
+ * @returns {Buffer} UTF-8 JSON bytes.
+ */
+export function encodeV3Control(value, maxBytes = DEFAULT_MAX_CONTROL_BYTES) {
+  positiveInteger(maxBytes, "maxBytes")
+  if (!isObject(value)) throw new TypeError("V3 control payload must be an object")
+  const encoded = Buffer.from(JSON.stringify(value), "utf8")
+  if (encoded.length > maxBytes) throw new RangeError(`V3 control payload exceeds ${maxBytes} byte limit`)
+  return encoded
+}
+
+/**
+ * Decodes a bounded JSON control object.
+ * @param {Uint8Array} bytes - UTF-8 JSON bytes.
+ * @param {number} [maxBytes] - Encoded size limit.
+ * @returns {Record<string, unknown>} Parsed object.
+ */
+export function decodeV3Control(bytes, maxBytes = DEFAULT_MAX_CONTROL_BYTES) {
+  positiveInteger(maxBytes, "maxBytes")
+  if (bytes.length > maxBytes) throw new RangeError(`V3 control payload exceeds ${maxBytes} byte limit`)
+  let value
+  try {
+    value = JSON.parse(Buffer.from(bytes).toString("utf8"))
+  } catch {
+    throw new Error("V3 control payload is not valid JSON")
+  }
+  if (!isObject(value)) throw new TypeError("V3 control payload must be an object")
+  return value
+}
+
+export class V3FrameDecoder {
+  /** @type {number} */
+  #maxFrameBytes
+
+  /** @type {number} */
+  #maxBufferedBytes
+
+  /** @type {Buffer} */
+  #buffer = Buffer.alloc(0)
+
+  /** @param {{maxFrameBytes?: number, maxBufferedBytes?: number}} [options] - Decoder bounds. */
+  constructor(options = {}) {
+    this.#maxFrameBytes = positiveInteger(options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES, "maxFrameBytes")
+    this.#maxBufferedBytes = positiveInteger(options.maxBufferedBytes ?? (this.#maxFrameBytes + HEADER_BYTES), "maxBufferedBytes")
+    if (this.#maxBufferedBytes < HEADER_BYTES) throw new RangeError("maxBufferedBytes must fit a V3 header")
+  }
+
+  /**
+   * @param {Uint8Array} chunk - Next transport bytes.
+   * @returns {V3Frame[]} Complete frames.
+   */
+  push(chunk) {
+    if (chunk.length === 0) return []
+    if (this.#buffer.length + chunk.length > this.#maxBufferedBytes) {
+      throw new RangeError("V3 decoder buffered byte limit exceeded")
+    }
+    this.#buffer = this.#buffer.length === 0
+      ? Buffer.from(chunk)
+      : Buffer.concat([this.#buffer, Buffer.from(chunk)])
+    /** @type {V3Frame[]} */
+    const frames = []
+    let offset = 0
+    while (this.#buffer.length - offset >= HEADER_BYTES) {
+      const header = this.#buffer.subarray(offset, offset + HEADER_BYTES)
+      if (!header.subarray(0, 4).equals(MAGIC)) throw new Error("Invalid V3 frame magic")
+      if (header[4] !== VERSION) throw new Error(`Unsupported protocol version: ${header[4]}`)
+      const type = /** @type {number} */ (header[5])
+      const flags = header.readUInt16BE(6)
+      const streamId = header.readUInt32BE(8)
+      const sequenceValue = header.readBigUInt64BE(12)
+      if (sequenceValue > UINT64_MAX_SAFE) throw new RangeError("V3 sequence exceeds JavaScript safe integer range")
+      const sequence = Number(sequenceValue)
+      const payloadLength = header.readUInt32BE(20)
+      if (payloadLength > this.#maxFrameBytes) throw new RangeError(`Invalid V3 frame payload length: ${payloadLength}`)
+      const end = offset + HEADER_BYTES + payloadLength
+      if (end > this.#buffer.length) break
+      validateHeader({type, flags, streamId, sequence})
+      frames.push({type, flags, streamId, sequence, payload: Buffer.from(this.#buffer.subarray(offset + HEADER_BYTES, end))})
+      offset = end
+    }
+    if (offset > 0) this.#buffer = Buffer.from(this.#buffer.subarray(offset))
+    return frames
+  }
+}
+
+/** @param {V3FrameHeader} header - Candidate header. */
+function validateHeader(header) {
+  if (!CONNECTION_TYPES.has(header.type) && !STREAM_TYPES.has(header.type)) throw new RangeError(`Unknown V3 frame type: ${header.type}`)
+  if (!Number.isInteger(header.streamId) || header.streamId < 0 || header.streamId > 0xffff_ffff) throw new RangeError("V3 stream ID must be uint32")
+  if (!Number.isSafeInteger(header.sequence) || header.sequence < 0) throw new RangeError("V3 sequence must be a non-negative safe integer")
+  const flags = header.flags ?? 0
+  if (!Number.isInteger(flags) || flags < 0 || flags > 0xffff) throw new RangeError("V3 flags must be uint16")
+  if (flags !== 0 && !(header.type === V3FrameType.DATA && flags === V3FrameFlag.DATA_COMPRESSED)) throw new Error("Unsupported V3 frame flags")
+  if (CONNECTION_TYPES.has(header.type) && header.streamId !== 0) throw new Error("V3 connection control frames require stream ID zero")
+  if (STREAM_TYPES.has(header.type) && header.streamId === 0) throw new Error("V3 stream ID zero is reserved for connection control")
+}
+
+/**
+ * @param {unknown} value - Candidate plain object.
+ * @returns {value is Record<string, unknown>} Whether the value is an object.
+ */
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+/**
+ * @param {number} value - Candidate.
+ * @param {string} name - Option name.
+ * @returns {number} Validated value.
+ */
+function positiveInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value <= 0) throw new RangeError(`${name} must be a positive integer`)
+  return value
+}