@iislee/opencodex 2.11.0

package/src/adapters/cursor/framing.ts

@@ -0,0 +1,211 @@
+export const CONNECT_FRAME_HEADER_BYTES = 5;
+export const CONNECT_FLAG_COMPRESSED = 0x01;
+export const CONNECT_FLAG_END_STREAM = 0x02;
+export const MAX_CONNECT_FRAME_PAYLOAD_BYTES = 0xffffffff;
+
+export type ConnectFrameErrorCode =
+  | "invalid_offset"
+  | "invalid_flags"
+  | "payload_too_large"
+  | "frame_incomplete";
+
+export interface ConnectFrame {
+  flags: number;
+  payload: Uint8Array;
+  compressed: boolean;
+  endStream: boolean;
+}
+
+export interface DecodedConnectFrame {
+  frame: ConnectFrame;
+  readBytes: number;
+}
+
+export interface DecodedConnectFrames {
+  frames: ConnectFrame[];
+  remainder: Uint8Array;
+}
+
+interface CopyReservation {
+  commitRetained(): void;
+  release(): void;
+}
+
+interface InspectedConnectFrame {
+  flags: number;
+  length: number;
+  payloadStart: number;
+  readBytes: number;
+}
+
+export class ConnectFrameError extends Error {
+  constructor(
+    public readonly code: ConnectFrameErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = "ConnectFrameError";
+  }
+}
+
+export function isConnectFrameCompressed(flags: number): boolean {
+  return (flags & CONNECT_FLAG_COMPRESSED) === CONNECT_FLAG_COMPRESSED;
+}
+
+export function isConnectFrameEndStream(flags: number): boolean {
+  return (flags & CONNECT_FLAG_END_STREAM) === CONNECT_FLAG_END_STREAM;
+}
+
+export function encodeConnectFrame(
+  payload: Uint8Array,
+  options: { flags?: number; compressed?: boolean; endStream?: boolean } = {},
+): Uint8Array {
+  if (payload.length > MAX_CONNECT_FRAME_PAYLOAD_BYTES) {
+    throw new ConnectFrameError("payload_too_large", `Connect frame payload too large: ${payload.length}`);
+  }
+
+  let flags = options.flags ?? 0;
+  assertByte(flags, "invalid_flags", `Connect frame flags must be a byte: ${flags}`);
+  if (options.compressed) flags |= CONNECT_FLAG_COMPRESSED;
+  if (options.endStream) flags |= CONNECT_FLAG_END_STREAM;
+
+  const frame = new Uint8Array(CONNECT_FRAME_HEADER_BYTES + payload.length);
+  frame[0] = flags;
+  new DataView(frame.buffer, frame.byteOffset, frame.byteLength)
+    .setUint32(1, payload.length, false);
+  frame.set(payload, CONNECT_FRAME_HEADER_BYTES);
+  return frame;
+}
+
+export function tryDecodeConnectFrame(
+  input: Uint8Array,
+  offset = 0,
+  maxPayloadBytes = MAX_CONNECT_FRAME_PAYLOAD_BYTES,
+  reservePayloadCopy?: (bytes: number) => CopyReservation | undefined,
+): DecodedConnectFrame | null {
+  assertOffset(input, offset);
+  const inspected = inspectConnectFrame(input, offset, maxPayloadBytes);
+  if (!inspected) return null;
+  const payloadEnd = inspected.payloadStart + inspected.length;
+  const reservation = reservePayloadCopy?.(inspected.length);
+  let payload: Uint8Array;
+  try {
+    payload = input.slice(inspected.payloadStart, payloadEnd);
+    reservation?.commitRetained();
+  } catch (error) {
+    reservation?.release();
+    throw error;
+  }
+  return {
+    frame: {
+      flags: inspected.flags,
+      payload,
+      compressed: isConnectFrameCompressed(inspected.flags),
+      endStream: isConnectFrameEndStream(inspected.flags),
+    },
+    readBytes: inspected.readBytes,
+  };
+}
+
+export function decodeConnectFrame(input: Uint8Array, offset = 0): DecodedConnectFrame {
+  const decoded = tryDecodeConnectFrame(input, offset);
+  if (!decoded) {
+    throw new ConnectFrameError("frame_incomplete", "Incomplete Connect frame");
+  }
+  return decoded;
+}
+
+export function decodeConnectFrames(input: Uint8Array): ConnectFrame[] {
+  const frames: ConnectFrame[] = [];
+  let offset = 0;
+  while (offset < input.length) {
+    const decoded = decodeConnectFrame(input, offset);
+    frames.push(decoded.frame);
+    offset += decoded.readBytes;
+  }
+  return frames;
+}
+
+export function decodeAvailableConnectFrames(
+  input: Uint8Array,
+  maxPayloadBytes = MAX_CONNECT_FRAME_PAYLOAD_BYTES,
+  availableFrameSlots = Number.POSITIVE_INFINITY,
+  reservePayloadCopy?: (bytes: number) => CopyReservation | undefined,
+): DecodedConnectFrames {
+  const planned: Array<InspectedConnectFrame & { reservation?: CopyReservation }> = [];
+  let offset = 0;
+  let remainderReservation: CopyReservation | undefined;
+  try {
+    while (offset < input.length && planned.length < availableFrameSlots) {
+      const inspected = inspectConnectFrame(input, offset, maxPayloadBytes);
+      if (!inspected) break;
+      const reservation = reservePayloadCopy?.(inspected.length);
+      planned.push({ ...inspected, reservation });
+      offset += inspected.readBytes;
+    }
+    const remainderBytes = offset === input.length ? 0 : bufferedPayloadBytes(input, offset);
+    remainderReservation = reservePayloadCopy?.(remainderBytes);
+
+    // Keep every reservation transient until every batch allocation succeeds. A later admission
+    // failure can then roll the entire batch back without needing ownership of unreturned frames.
+    const frames = planned.map(({ flags, length, payloadStart }) => {
+      const payload = input.slice(payloadStart, payloadStart + length);
+      return {
+        flags,
+        payload,
+        compressed: isConnectFrameCompressed(flags),
+        endStream: isConnectFrameEndStream(flags),
+      };
+    });
+    const remainder = offset === input.length ? new Uint8Array() : input.slice(offset);
+    for (const entry of planned) entry.reservation?.commitRetained();
+    remainderReservation?.commitRetained();
+    return { frames, remainder };
+  } catch (error) {
+    for (const entry of planned) entry.reservation?.release();
+    remainderReservation?.release();
+    throw error;
+  }
+}
+
+function inspectConnectFrame(
+  input: Uint8Array,
+  offset: number,
+  maxPayloadBytes: number,
+): InspectedConnectFrame | null {
+  if (input.length - offset < CONNECT_FRAME_HEADER_BYTES) return null;
+  const view = new DataView(input.buffer, input.byteOffset + offset, input.byteLength - offset);
+  const flags = view.getUint8(0);
+  const length = view.getUint32(1, false);
+  if (length > maxPayloadBytes) {
+    throw new ConnectFrameError("payload_too_large", `Connect frame payload too large: ${length}`);
+  }
+  const readBytes = CONNECT_FRAME_HEADER_BYTES + length;
+  if (input.length - offset < readBytes) return null;
+  return { flags, length, payloadStart: offset + CONNECT_FRAME_HEADER_BYTES, readBytes };
+}
+
+function bufferedPayloadBytes(input: Uint8Array, start: number): number {
+  let offset = start;
+  let payloadBytes = 0;
+  while (input.byteLength - offset >= CONNECT_FRAME_HEADER_BYTES) {
+    const length = new DataView(input.buffer, input.byteOffset + offset, input.byteLength - offset).getUint32(1, false);
+    const available = Math.min(length, input.byteLength - offset - CONNECT_FRAME_HEADER_BYTES);
+    payloadBytes += available;
+    if (available < length) break;
+    offset += CONNECT_FRAME_HEADER_BYTES + length;
+  }
+  return payloadBytes;
+}
+
+function assertOffset(input: Uint8Array, offset: number): void {
+  if (!Number.isInteger(offset) || offset < 0 || offset > input.length) {
+    throw new ConnectFrameError("invalid_offset", `Invalid Connect frame offset: ${offset}`);
+  }
+}
+
+function assertByte(value: number, code: ConnectFrameErrorCode, message: string): void {
+  if (!Number.isInteger(value) || value < 0 || value > 0xff) {
+    throw new ConnectFrameError(code, message);
+  }
+}