@cortexkit/subc-client 0.3.4 → 0.4.0

package/src/envelope.ts

@@ -1,10 +1,9 @@
-// Byte-for-byte port of subc-protocol's 17-byte envelope header.
-// Source of truth: crates/subc-protocol/src/lib.rs. Keep field offsets, the
-// little-endian encoding, and the frame-type/flag numbering in lock-step with
-// the Rust; a one-byte drift here desynchronizes every frame on the wire.
+// Byte-for-byte port of subc-protocol's fixed envelope header.
+// Source of truth: crates/subc-protocol/src/lib.rs. Keep field offsets, little-
+// endian encoding, and frame/flag numbering in lock-step with Rust.
 
-export const PROTOCOL_VERSION = 1;
-export const HEADER_LEN = 17;
+export const PROTOCOL_VERSION = 2;
+export const HEADER_LEN = 21;
 export const FROZEN_PREFIX_LEN = 5;
 export const MAX_FRAME_BODY_LEN = 64 * 1024 * 1024;
 
@@ -28,12 +27,7 @@ const FRAME_TYPE_MAX = FrameType.Goodbye;
 
 /** Cancel/Ping/Pong/Goodbye carry only a header (`len` must be 0). */
 export function isPureHeader(ty: FrameType): boolean {
-  return (
-    ty === FrameType.Cancel ||
-    ty === FrameType.Ping ||
-    ty === FrameType.Pong ||
-    ty === FrameType.Goodbye
-  );
+  return ty === FrameType.Cancel || ty === FrameType.Ping || ty === FrameType.Pong || ty === FrameType.Goodbye;
 }
 
 /** Scheduling priority carried in flags bits 1-2. */
@@ -43,19 +37,38 @@ export enum Priority {
   Background = 2,
 }
 
-const FLAG_BINARY = 0b0000_0001; // bit 0
-const FLAG_PRIORITY_MASK = 0b0000_0110; // bits 1-2
+/** Admission behavior carried in flags bits 4-5. */
+export enum AdmissionClass {
+  Normal = 0,
+  Expedite = 1,
+  Sheddable = 2,
+}
+
+const FLAG_BINARY = 0b0000_0001;
+const FLAG_PRIORITY_MASK = 0b0000_0110;
 const FLAG_PRIORITY_SHIFT = 1;
-const FLAG_LAST = 0b0000_1000; // bit 3
-const FLAG_RESERVED_MASK = 0b1111_0000; // bits 4-7 must be zero
-
-/** Build the flags byte from typed components (mirrors Flags::new). */
-export function buildFlags(binary: boolean, priority: Priority, last: boolean): number {
-  let b = 0;
-  if (binary) b |= FLAG_BINARY;
-  b |= priority << FLAG_PRIORITY_SHIFT;
-  if (last) b |= FLAG_LAST;
-  return b;
+const FLAG_LAST = 0b0000_1000;
+const FLAG_ADMISSION_MASK = 0b0011_0000;
+const FLAG_ADMISSION_SHIFT = 4;
+const FLAG_RESERVED_MASK = 0b1100_0000;
+
+/** Build flags from typed components. Admission defaults to NORMAL. */
+export function buildFlags(
+  binary: boolean,
+  priority: Priority,
+  last: boolean,
+  admissionClass: AdmissionClass = AdmissionClass.Normal,
+): number {
+  let flags = 0;
+  if (binary) flags |= FLAG_BINARY;
+  flags |= priority << FLAG_PRIORITY_SHIFT;
+  if (last) flags |= FLAG_LAST;
+  flags |= admissionClass << FLAG_ADMISSION_SHIFT;
+  return flags;
+}
+
+export function admissionClass(flags: number): AdmissionClass {
+  return ((flags & FLAG_ADMISSION_MASK) >> FLAG_ADMISSION_SHIFT) as AdmissionClass;
 }
 
 export interface EnvelopeHeader {
@@ -64,6 +77,7 @@ export interface EnvelopeHeader {
   ty: FrameType;
   flags: number;
   channel: number;
+  epoch: number;
   corr: bigint;
 }
 
@@ -72,97 +86,145 @@ export interface Frame {
   body: Uint8Array;
 }
 
-/** Serialize a header to its fixed 17-byte little-endian form. */
-export function encodeHeader(h: EnvelopeHeader): Uint8Array {
-  const buf = new Uint8Array(HEADER_LEN);
-  const view = new DataView(buf.buffer);
-  view.setUint32(0, h.len, true);
-  buf[4] = h.ver;
-  buf[5] = h.ty;
-  buf[6] = h.flags;
-  view.setUint16(7, h.channel, true);
-  view.setBigUint64(9, h.corr, true);
-  return buf;
+/** Serialize a header to its fixed 21-byte little-endian form. */
+export function encodeHeader(header: EnvelopeHeader): Uint8Array {
+  const buffer = new Uint8Array(HEADER_LEN);
+  const view = new DataView(buffer.buffer);
+  view.setUint32(0, header.len, true);
+  buffer[4] = header.ver;
+  buffer[5] = header.ty;
+  buffer[6] = header.flags;
+  view.setUint16(7, header.channel, true);
+  view.setUint32(9, header.epoch, true);
+  view.setBigUint64(13, header.corr, true);
+  return buffer;
 }
 
-export class DecodeError extends Error {}
+export type DecodeErrorCode =
+  | "too_short_for_prefix"
+  | "unsupported_version"
+  | "too_short_for_header"
+  | "unknown_frame_type"
+  | "reserved_flag_bits"
+  | "reserved_priority_bits"
+  | "reserved_admission_class"
+  | "sheddable_illegal_frame_type"
+  | "nonzero_epoch_on_control_channel"
+  | "pure_header_frame_with_body"
+  | "frame_body_too_large"
+  | "frame_length_mismatch";
 
-/**
- * Decode a header from the front of `bytes`, following the frozen-prefix
- * discipline: need 5 bytes for len+ver, dispatch full header length on ver,
- * then validate. Mirrors decode_header — never throws on a structurally short
- * buffer beyond the typed DecodeError.
- */
+/** Typed envelope decode failure mirroring the Rust wire taxonomy. */
+export class DecodeError extends Error {
+  constructor(message: string, readonly code: DecodeErrorCode) {
+    super(message);
+    this.name = "DecodeError";
+  }
+}
+
+/** Decode and validate a header from the front of `bytes`. */
 export function decodeHeader(bytes: Uint8Array): EnvelopeHeader {
   if (bytes.length < FROZEN_PREFIX_LEN) {
-    throw new DecodeError(`header shorter than frozen prefix: have ${bytes.length} bytes`);
+    throw new DecodeError(`header shorter than frozen prefix: have ${bytes.length} bytes`, "too_short_for_prefix");
   }
   const ver = bytes[4]!;
-  if (ver !== PROTOCOL_VERSION) {
-    throw new DecodeError(`unsupported envelope version ${ver}`);
-  }
+  if (ver !== PROTOCOL_VERSION) throw new DecodeError(`unsupported envelope version ${ver}`, "unsupported_version");
   if (bytes.length < HEADER_LEN) {
-    throw new DecodeError(`header too short for version: have ${bytes.length} bytes, need ${HEADER_LEN}`);
+    throw new DecodeError(
+      `header too short for version: have ${bytes.length} bytes, need ${HEADER_LEN}`,
+      "too_short_for_header",
+    );
   }
+
   const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
   const len = view.getUint32(0, true);
-  const tyByte = bytes[5]!;
-  if (tyByte > FRAME_TYPE_MAX) {
-    throw new DecodeError(`unknown frame type byte ${tyByte}`);
-  }
-  const ty = tyByte as FrameType;
+  const typeByte = bytes[5]!;
+  if (typeByte > FRAME_TYPE_MAX) throw new DecodeError(`unknown frame type byte ${typeByte}`, "unknown_frame_type");
+  const ty = typeByte as FrameType;
   const flags = bytes[6]!;
   if ((flags & FLAG_RESERVED_MASK) !== 0) {
-    throw new DecodeError(`reserved flag bits set in flags 0b${flags.toString(2)}`);
+    throw new DecodeError(
+      `reserved flag bits set in flags 0b${flags.toString(2).padStart(8, "0")}`,
+      "reserved_flag_bits",
+    );
   }
   if (((flags & FLAG_PRIORITY_MASK) >> FLAG_PRIORITY_SHIFT) === 0b11) {
-    throw new DecodeError(`reserved priority bits set in flags 0b${flags.toString(2)}`);
+    throw new DecodeError(
+      `reserved priority bits set in flags 0b${flags.toString(2).padStart(8, "0")}`,
+      "reserved_priority_bits",
+    );
   }
-  if (isPureHeader(ty) && len !== 0) {
-    throw new DecodeError(`pure-header frame ${FrameType[ty]} declared non-zero body length ${len}`);
+  const admission = (flags & FLAG_ADMISSION_MASK) >> FLAG_ADMISSION_SHIFT;
+  if (admission === 0b11) {
+    throw new DecodeError(
+      `reserved admission class set in flags 0b${flags.toString(2).padStart(8, "0")}`,
+      "reserved_admission_class",
+    );
+  }
+  if (admission === AdmissionClass.Sheddable && ty !== FrameType.Push && ty !== FrameType.StreamData) {
+    throw new DecodeError(
+      `SHEDDABLE admission class is illegal on ${FrameType[ty]} in flags 0b${flags.toString(2).padStart(8, "0")}`,
+      "sheddable_illegal_frame_type",
+    );
   }
   const channel = view.getUint16(7, true);
-  const corr = view.getBigUint64(9, true);
-  return { len, ver, ty, flags, channel, corr };
+  const epoch = view.getUint32(9, true);
+  if (channel === 0 && epoch !== 0) {
+    throw new DecodeError(
+      `control channel carried nonzero epoch ${epoch}`,
+      "nonzero_epoch_on_control_channel",
+    );
+  }
+  if (isPureHeader(ty) && len !== 0) {
+    throw new DecodeError(
+      `pure-header frame ${FrameType[ty]} declared non-zero body length ${len}`,
+      "pure_header_frame_with_body",
+    );
+  }
+  return { len, ver, ty, flags, channel, epoch, corr: view.getBigUint64(13, true) };
 }
 
-/** Build a full current-version frame, enforcing the body-length cap and the pure-header rule. */
+/** Build a current-version frame and validate its complete header. */
 export function buildFrame(
   ty: FrameType,
   flags: number,
   channel: number,
+  epoch: number,
   corr: bigint,
   body: Uint8Array,
 ): Frame {
-  return buildFrameWithVersion(PROTOCOL_VERSION, ty, flags, channel, corr, body);
+  return buildFrameWithVersion(PROTOCOL_VERSION, ty, flags, channel, epoch, corr, body);
 }
 
-/** Build a full frame while preserving a peer-negotiated envelope version. */
+/** Build a frame while preserving the peer's exact supported version. */
 export function buildFrameWithVersion(
   ver: number,
   ty: FrameType,
   flags: number,
   channel: number,
+  epoch: number,
   corr: bigint,
   body: Uint8Array,
 ): Frame {
   if (body.length > MAX_FRAME_BODY_LEN) {
-    throw new DecodeError(`frame body ${body.length} exceeds max ${MAX_FRAME_BODY_LEN}`);
+    throw new DecodeError(`frame body ${body.length} exceeds max ${MAX_FRAME_BODY_LEN}`, "frame_body_too_large");
   }
-  if (isPureHeader(ty) && body.length !== 0) {
-    throw new DecodeError(`pure-header frame ${FrameType[ty]} cannot carry a body`);
-  }
-  return {
-    header: { len: body.length, ver, ty, flags, channel, corr },
-    body,
-  };
+  const header = { len: body.length, ver, ty, flags, channel, epoch, corr };
+  decodeHeader(encodeHeader(header));
+  return { header, body };
 }
 
-/** Encode a frame to wire bytes: 17-byte header followed by `len` body bytes. */
+/** Encode a frame to wire bytes: header followed by exactly `len` body bytes. */
 export function encodeFrame(frame: Frame): Uint8Array {
+  if (frame.header.len !== frame.body.length) {
+    throw new DecodeError(
+      `frame header length ${frame.header.len} does not match body length ${frame.body.length}`,
+      "frame_length_mismatch",
+    );
+  }
   const header = encodeHeader(frame.header);
-  const out = new Uint8Array(header.length + frame.body.length);
-  out.set(header, 0);
-  out.set(frame.body, header.length);
-  return out;
+  const output = new Uint8Array(header.length + frame.body.length);
+  output.set(header, 0);
+  output.set(frame.body, header.length);
+  return output;
 }

package/src/index.ts

@@ -21,7 +21,11 @@ export {
   type SubscribeOptions,
   type Subscription,
   type CloseRouteOptions,
+  type ManagedCloseRouteOptions,
+  type RoutePollKind,
+  type RoutePollResult,
 } from "./client.js";
+export { RouteHandle, StaleRouteHandleError } from "./route-handle.js";
 export {
   readConnectionFile,
   ConnectionFileError,
@@ -31,6 +35,7 @@ export {
 export {
   FrameType,
   Priority,
+  AdmissionClass,
   PROTOCOL_VERSION,
   HEADER_LEN,
   buildFrame,
@@ -40,6 +45,7 @@ export {
   decodeHeader,
   encodeHeader,
   DecodeError,
+  type DecodeErrorCode,
   type Frame,
   type EnvelopeHeader,
 } from "./envelope.js";
@@ -60,6 +66,7 @@ export {
   managementSurfaceManifest,
   jsonProviderHandler,
   type ProviderRequestContext,
+  type ProviderEmitOptions,
   type BindDecision,
   type Principal,
   type BindingsInput,