@cortexkit/subc-client 0.3.4 → 0.4.1

package/src/route-handle.ts

@@ -0,0 +1,60 @@
+const connectionToken = new WeakMap<RouteHandle, object>();
+
+/**
+ * Immutable identity for one route binding on one live socket. Only channel and
+ * epoch cross the wire; the connection token remains private to this SDK.
+ */
+export class RouteHandle {
+  readonly channel: number;
+  readonly epoch: number;
+
+  private constructor(channel: number, epoch: number, token: object) {
+    if (!Number.isInteger(channel) || channel <= 0 || channel > 0xffff) {
+      throw new RangeError(`route channel must be an integer in 1..65535, got ${channel}`);
+    }
+    if (!Number.isInteger(epoch) || epoch <= 0 || epoch > 0xffff_ffff) {
+      throw new RangeError(`route epoch must be an integer in 1..4294967295, got ${epoch}`);
+    }
+    this.channel = channel;
+    this.epoch = epoch;
+    connectionToken.set(this, token);
+    Object.freeze(this);
+  }
+
+  private static create(channel: number, epoch: number, token: object): RouteHandle {
+    return new RouteHandle(channel, epoch, token);
+  }
+}
+
+/** @internal SDK factory; not re-exported from the package surface. */
+export function createRouteHandle(channel: number, epoch: number, token: object): RouteHandle {
+  const factory = RouteHandle as unknown as {
+    create(channel: number, epoch: number, token: object): RouteHandle;
+  };
+  return factory.create(channel, epoch, token);
+}
+
+/** A route handle belongs to another connection or is no longer installed. */
+export class StaleRouteHandleError extends Error {
+  readonly code = "stale_route_handle";
+
+  constructor(readonly handle: RouteHandle) {
+    super(`route handle (${handle.channel}, ${handle.epoch}) is not live on the current connection`);
+    this.name = "StaleRouteHandleError";
+  }
+}
+
+/** @internal */
+export function newConnectionToken(): object {
+  return Object.freeze({});
+}
+
+/** @internal */
+export function belongsToConnection(handle: RouteHandle, token: object): boolean {
+  return connectionToken.get(handle) === token;
+}
+
+/** @internal */
+export function sameRouteHandle(left: RouteHandle, right: RouteHandle): boolean {
+  return left === right;
+}

package/src/socket.ts

@@ -6,6 +6,16 @@
 
 import net from "node:net";
 
+import {
+  decodeHeader,
+  DecodeError,
+  FROZEN_PREFIX_LEN,
+  HEADER_LEN,
+  MAX_FRAME_BODY_LEN,
+  PROTOCOL_VERSION,
+  type Frame,
+} from "./envelope.js";
+
 export class SocketClosedError extends Error {}
 export class SocketTimeoutError extends Error {}
 
@@ -99,6 +109,44 @@ export class SubcSocket {
     });
   }
 
+  /**
+   * Read one envelope frame. The frozen five-byte prefix is validated before
+   * waiting for the rest of the header, so a stale 17-byte v1 sender fails
+   * promptly instead of leaving this reader blocked for four bytes.
+   *
+   * `bodyDeadline` is either an absolute epoch-ms deadline (a single total
+   * budget shared with the header read — the bounded handshake read) or
+   * `{ afterHeaderMs }` to start the body budget from header arrival. A
+   * background frame loop waits for the header with an infinite deadline, so it
+   * MUST use `afterHeaderMs`: anchoring the body budget before that idle wait
+   * makes a frame arriving after a quiet stretch longer than the body timeout
+   * instant-reject ("timed out waiting for N bytes") even though its body is
+   * arriving normally.
+   */
+  async readFrame(
+    headerDeadlineMs: number,
+    bodyDeadline: number | { afterHeaderMs: number },
+    onHeader?: () => void,
+  ): Promise<Frame> {
+    const prefix = await this.readExact(FROZEN_PREFIX_LEN, headerDeadlineMs);
+    const version = prefix[4]!;
+    if (version !== PROTOCOL_VERSION) throw new DecodeError(`unsupported envelope version ${version}`, "unsupported_version");
+
+    const remainder = await this.readExact(HEADER_LEN - FROZEN_PREFIX_LEN, headerDeadlineMs);
+    const headerBytes = new Uint8Array(HEADER_LEN);
+    headerBytes.set(prefix);
+    headerBytes.set(remainder, FROZEN_PREFIX_LEN);
+    const header = decodeHeader(headerBytes);
+    if (header.len > MAX_FRAME_BODY_LEN) {
+      throw new DecodeError(`frame body ${header.len} exceeds max ${MAX_FRAME_BODY_LEN}`, "frame_body_too_large");
+    }
+    onHeader?.();
+    const bodyDeadlineMs =
+      typeof bodyDeadline === "number" ? bodyDeadline : Date.now() + bodyDeadline.afterHeaderMs;
+    const body = header.len === 0 ? new Uint8Array(0) : await this.readExact(header.len, bodyDeadlineMs);
+    return { header, body };
+  }
+
   /** Read exactly `n` bytes, rejecting if `deadlineMs` (epoch ms) passes first. */
   readExact(n: number, deadlineMs: number): Promise<Uint8Array> {
     if (this.waiter) {