@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/worker-protocol/uplink/mux.ts

@@ -0,0 +1,646 @@
+// Many independent streams over one ordered, reliable byte stream. In
+// production that byte stream is the plaintext side of a Noise transport;
+// here it is anything shaped like `ByteDuplex`.
+//
+// The mux owns framing, per-stream receive windows, the session caps and
+// PING/PONG. It owns no schedule: ping cadence, pong deadline and idle
+// deadline all belong to the session layer above it.
+
+import {
+  CONTROL_STREAM_ID,
+  DEFAULT_LIMITS,
+  MAX_PAYLOAD_BYTES,
+  MAX_RESET_REASON_CHARS,
+  PING_PAYLOAD_BYTES,
+  WINDOW_PAYLOAD_BYTES,
+} from "./constants.ts";
+import { SessionClosed, StreamReset, UplinkProtocolError } from "./errors.ts";
+import {
+  decodeU32,
+  decodeUtf8,
+  EMPTY_PAYLOAD,
+  encodeFrame,
+  encodeU32,
+  encodeUtf8,
+  type Frame,
+  FrameParser,
+  FrameType,
+  frameTypeName,
+} from "./frame.ts";
+
+/** The abstract transport: ordered and reliable in each direction. */
+export interface ByteDuplex {
+  readable: ReadableStream<Uint8Array>;
+  writable: WritableStream<Uint8Array>;
+}
+
+export interface Limits {
+  /** Largest DATA payload this side emits. */
+  fragmentSize: number;
+  /** Per-stream receive window, each direction. */
+  initialWindow: number;
+  /** Concurrent streams this side may have open. */
+  maxStreams: number;
+  /** Un-credited DATA bytes in flight across all of this side's sends. */
+  maxInFlight: number;
+}
+
+export type MuxSide = "initiator" | "responder";
+
+export interface Stream {
+  readonly id: number;
+  /** The peer's DATA. Closes on END, errors with `StreamReset` on RESET. */
+  readonly readable: ReadableStream<Uint8Array>;
+  /** Our DATA. `close()` sends END, `abort(reason)` sends RESET. */
+  readonly writable: WritableStream<Uint8Array>;
+  reset(reason: string): void;
+}
+
+interface SendEntry {
+  bytes: Uint8Array;
+  streamId: number;
+  resolve: () => void;
+  reject: (error: Error) => void;
+}
+
+interface StreamState {
+  id: number;
+  /** True when this side opened it, which is also what the id's parity says. */
+  local: boolean;
+  stream: Stream;
+  retired: boolean;
+  error: Error | undefined;
+  // Send side.
+  sendCredit: number;
+  sendOutstanding: number;
+  writeEnded: boolean;
+  writeController: WritableStreamDefaultController | undefined;
+  // Receive side.
+  recvRemaining: number;
+  recvUncredited: number;
+  consumed: number;
+  recvQueue: Uint8Array[];
+  recvEnded: boolean;
+  readSettled: boolean;
+  readController: ReadableStreamDefaultController<Uint8Array> | undefined;
+  pullResolve: (() => void) | undefined;
+}
+
+/** One-shot notification a waiter re-checks its own condition against. */
+class Gate {
+  #promise: Promise<void> | undefined;
+  #resolve: (() => void) | undefined;
+
+  wait(): Promise<void> {
+    this.#promise ??= new Promise<void>((resolve) => {
+      this.#resolve = resolve;
+    });
+    return this.#promise;
+  }
+
+  wake(): void {
+    const resolve = this.#resolve;
+    this.#promise = undefined;
+    this.#resolve = undefined;
+    resolve?.();
+  }
+}
+
+export class Mux {
+  readonly #limits: Limits;
+  readonly #grantThreshold: number;
+  readonly #localOdd: boolean;
+  readonly #writer: WritableStreamDefaultWriter<Uint8Array>;
+  readonly #reader: ReadableStreamDefaultReader<Uint8Array>;
+  readonly #parser = new FrameParser();
+  readonly #streams = new Map<number, StreamState>();
+  readonly #controlQueue: SendEntry[] = [];
+  readonly #dataQueue: SendEntry[] = [];
+  readonly #creditGate = new Gate();
+  readonly #slotGate = new Gate();
+  readonly #pings = new Map<number, { resolve: () => void; reject: (error: Error) => void }>();
+  readonly #closedPromise: Promise<string>;
+  readonly #closedResolve: (reason: string) => void;
+
+  #onOpen: ((stream: Stream, header: Uint8Array) => void) | undefined;
+  #pendingOpens: Array<{ stream: Stream; header: Uint8Array }> = [];
+  #nextId: number;
+  #localMaxId = 0;
+  #peerMaxId = 0;
+  #localOpen = 0;
+  #remoteOpen = 0;
+  #inFlight = 0;
+  #peerInFlight = 0;
+  #pingSeq = 0;
+  #pumping = false;
+  #closeError: Error | undefined;
+
+  constructor(transport: ByteDuplex, opts: { side: MuxSide } & Partial<Limits>) {
+    const limits: Limits = {
+      fragmentSize: opts.fragmentSize ?? DEFAULT_LIMITS.fragmentSize,
+      initialWindow: opts.initialWindow ?? DEFAULT_LIMITS.initialWindow,
+      maxStreams: opts.maxStreams ?? DEFAULT_LIMITS.maxStreams,
+      maxInFlight: opts.maxInFlight ?? DEFAULT_LIMITS.maxInFlight,
+    };
+    // A fragment is sent atomically, so anything it cannot fit inside would
+    // stall forever rather than fail.
+    if (limits.fragmentSize < 1 || limits.fragmentSize > MAX_PAYLOAD_BYTES) {
+      throw new RangeError(`fragmentSize must be 1..${MAX_PAYLOAD_BYTES}`);
+    }
+    if (limits.initialWindow < limits.fragmentSize) {
+      throw new RangeError("initialWindow must be at least fragmentSize");
+    }
+    if (limits.maxInFlight < limits.fragmentSize) {
+      throw new RangeError("maxInFlight must be at least fragmentSize");
+    }
+    if (limits.maxStreams < 1) throw new RangeError("maxStreams must be at least 1");
+
+    this.#limits = limits;
+    this.#grantThreshold = Math.max(1, Math.floor(limits.initialWindow / 2));
+    this.#localOdd = opts.side === "initiator";
+    this.#nextId = this.#localOdd ? 1 : 2;
+    this.#writer = transport.writable.getWriter();
+    this.#reader = transport.readable.getReader();
+
+    let resolveClosed: (reason: string) => void = () => {};
+    this.#closedPromise = new Promise<string>((resolve) => {
+      resolveClosed = resolve;
+    });
+    this.#closedResolve = resolveClosed;
+
+    void this.#readLoop();
+  }
+
+  /** The close reason, whichever side closed. Never rejects. */
+  get closed(): Promise<string> {
+    return this.#closedPromise;
+  }
+
+  /**
+   * Opens a stream. Costs no round trip — the first DATA may follow at once.
+   * Waits only for a local slot when `maxStreams` are already open.
+   */
+  async open(header: Uint8Array): Promise<Stream> {
+    if (header.length > MAX_PAYLOAD_BYTES) {
+      throw new RangeError(`OPEN header ${header.length} exceeds ${MAX_PAYLOAD_BYTES} bytes`);
+    }
+    while (this.#closeError === undefined && this.#localOpen >= this.#limits.maxStreams) {
+      await this.#slotGate.wait();
+    }
+    if (this.#closeError !== undefined) throw this.#closeError;
+    if (this.#nextId > 0xffffffff) throw new RangeError("stream id space exhausted");
+    const id = this.#nextId;
+    this.#nextId += 2;
+    this.#localMaxId = id;
+    const state = this.#createStream(id, true);
+    this.#localOpen++;
+    this.#sendControl(encodeFrame(FrameType.OPEN, id, header), id);
+    return state.stream;
+  }
+
+  /** Registers the incoming-stream handler. Opens seen before this are replayed. */
+  onOpen(handler: (stream: Stream, header: Uint8Array) => void): void {
+    this.#onOpen = handler;
+    const pending = this.#pendingOpens;
+    this.#pendingOpens = [];
+    for (const entry of pending) handler(entry.stream, entry.header);
+  }
+
+  /** Resolves on the matching PONG. The caller owns the deadline. */
+  ping(): Promise<void> {
+    if (this.#closeError !== undefined) return Promise.reject(this.#closeError);
+    const seq = ++this.#pingSeq;
+    const payload = new Uint8Array(PING_PAYLOAD_BYTES);
+    new DataView(payload.buffer).setUint32(4, seq);
+    const waited = new Promise<void>((resolve, reject) => {
+      this.#pings.set(seq, { resolve, reject });
+    });
+    this.#sendControl(encodeFrame(FrameType.PING, CONTROL_STREAM_ID, payload));
+    return waited;
+  }
+
+  /** Local close. Idempotent. */
+  close(reason: string): void {
+    this.#shutdown(new SessionClosed(reason), reason);
+  }
+
+  // --- send path -------------------------------------------------------
+
+  // Control outranks DATA so a kick never queues behind a body. END cannot
+  // overtake its own stream's DATA even so: the writable's `close` runs only
+  // after every `write` has resolved, which is after its frames are written.
+  #sendControl(bytes: Uint8Array, streamId = CONTROL_STREAM_ID): void {
+    if (this.#closeError !== undefined) return;
+    this.#controlQueue.push({ bytes, streamId, resolve: noop, reject: noop });
+    void this.#pump();
+  }
+
+  #sendData(streamId: number, bytes: Uint8Array): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      this.#dataQueue.push({ bytes, streamId, resolve, reject });
+      void this.#pump();
+    });
+  }
+
+  // One writer on the transport, awaited, so the sink's backpressure
+  // reaches the stream that produced the bytes.
+  async #pump(): Promise<void> {
+    if (this.#pumping) return;
+    this.#pumping = true;
+    try {
+      for (;;) {
+        const entry = this.#controlQueue.shift() ?? this.#dataQueue.shift();
+        if (entry === undefined) return;
+        try {
+          await this.#writer.write(entry.bytes);
+        } catch (e) {
+          const error = asError(e);
+          entry.reject(error);
+          this.#shutdown(new SessionClosed(error.message), error.message);
+          return;
+        }
+        entry.resolve();
+      }
+    } finally {
+      this.#pumping = false;
+    }
+  }
+
+  async #write(state: StreamState, chunk: Uint8Array): Promise<void> {
+    const size = this.#limits.fragmentSize;
+    for (let offset = 0; offset < chunk.length; offset += size) {
+      const part = chunk.subarray(offset, Math.min(offset + size, chunk.length));
+      await this.#reserve(state, part.length);
+      await this.#sendData(state.id, encodeFrame(FrameType.DATA, state.id, part));
+    }
+  }
+
+  // Stalls until the stream window and the session in-flight cap both have
+  // room for one whole fragment.
+  async #reserve(state: StreamState, size: number): Promise<void> {
+    for (;;) {
+      if (this.#closeError !== undefined) throw this.#closeError;
+      if (state.retired) throw state.error ?? new StreamReset("stream closed");
+      const sessionRoom = this.#limits.maxInFlight - this.#inFlight;
+      if (state.sendCredit >= size && sessionRoom >= size) {
+        state.sendCredit -= size;
+        state.sendOutstanding += size;
+        this.#inFlight += size;
+        return;
+      }
+      await this.#creditGate.wait();
+    }
+  }
+
+  #endWrite(state: StreamState): void {
+    if (state.writeEnded || state.retired) return;
+    state.writeEnded = true;
+    this.#sendControl(encodeFrame(FrameType.END, state.id, EMPTY_PAYLOAD), state.id);
+    this.#maybeRetire(state);
+  }
+
+  #resetStream(state: StreamState, reason: string): void {
+    if (state.retired) return;
+    const text = reason.slice(0, MAX_RESET_REASON_CHARS);
+    this.#sendControl(encodeFrame(FrameType.RESET, state.id, encodeUtf8(text)), state.id);
+    this.#failStream(state, new StreamReset(text));
+  }
+
+  // --- receive path ----------------------------------------------------
+
+  async #readLoop(): Promise<void> {
+    try {
+      for (;;) {
+        const { value, done } = await this.#reader.read();
+        if (done) {
+          this.#shutdown(new SessionClosed("transport closed"), "transport closed");
+          return;
+        }
+        for (const frame of this.#parser.push(value)) this.#handle(frame);
+      }
+    } catch (e) {
+      if (e instanceof UplinkProtocolError) this.#shutdown(e, e.message);
+      else {
+        const error = asError(e);
+        this.#shutdown(new SessionClosed(error.message), error.message);
+      }
+    }
+  }
+
+  #handle(frame: Frame): void {
+    switch (frame.type) {
+      case FrameType.PING:
+      case FrameType.PONG: {
+        if (frame.streamId !== CONTROL_STREAM_ID) {
+          throw new UplinkProtocolError(`${frameTypeName(frame.type)} on stream ${frame.streamId}`);
+        }
+        if (frame.payload.length !== PING_PAYLOAD_BYTES) {
+          throw new UplinkProtocolError(
+            `${frameTypeName(frame.type)} payload must be ${PING_PAYLOAD_BYTES} bytes`,
+          );
+        }
+        if (frame.type === FrameType.PING) {
+          this.#sendControl(encodeFrame(FrameType.PONG, CONTROL_STREAM_ID, frame.payload));
+          return;
+        }
+        const view = new DataView(
+          frame.payload.buffer,
+          frame.payload.byteOffset,
+          frame.payload.byteLength,
+        );
+        const seq = view.getUint32(4);
+        const waiter = this.#pings.get(seq);
+        // An unsolicited PONG is noise, not a violation.
+        if (waiter !== undefined) {
+          this.#pings.delete(seq);
+          waiter.resolve();
+        }
+        return;
+      }
+      case FrameType.OPEN:
+        return this.#handleOpen(frame);
+      default:
+        return this.#handleStreamFrame(frame);
+    }
+  }
+
+  #handleOpen(frame: Frame): void {
+    const id = frame.streamId;
+    if (id === CONTROL_STREAM_ID || (id % 2 === 1) === this.#localOdd) {
+      throw new UplinkProtocolError(`OPEN on wrong-parity stream ${id}`);
+    }
+    // Ids only grow, which is what lets late frames on a torn-down stream be
+    // told apart from frames on a stream that was never opened.
+    if (id <= this.#peerMaxId) throw new UplinkProtocolError(`OPEN reuses stream ${id}`);
+    this.#peerMaxId = id;
+    if (this.#remoteOpen >= this.#limits.maxStreams) {
+      // The peer's own bookkeeping is broken, not the framing: refuse the
+      // one stream rather than take the whole session down.
+      this.#sendControl(encodeFrame(FrameType.RESET, id, encodeUtf8("too many streams")), id);
+      return;
+    }
+    const state = this.#createStream(id, false);
+    this.#remoteOpen++;
+    const handler = this.#onOpen;
+    if (handler === undefined) {
+      this.#pendingOpens.push({ stream: state.stream, header: frame.payload });
+      return;
+    }
+    try {
+      handler(state.stream, frame.payload);
+    } catch (e) {
+      this.#resetStream(state, asError(e).message);
+    }
+  }
+
+  #handleStreamFrame(frame: Frame): void {
+    const id = frame.streamId;
+    const name = frameTypeName(frame.type);
+    if (id === CONTROL_STREAM_ID) throw new UplinkProtocolError(`${name} on stream 0`);
+    const state = this.#streams.get(id);
+    if (state === undefined) {
+      const mine = (id % 2 === 1) === this.#localOdd;
+      const everOpened = mine ? id <= this.#localMaxId : id <= this.#peerMaxId;
+      if (!everOpened) throw new UplinkProtocolError(`${name} on unopened stream ${id}`);
+      return; // Torn down here; the peer had frames in flight.
+    }
+    switch (frame.type) {
+      case FrameType.DATA:
+        return this.#handleData(state, frame.payload);
+      case FrameType.END: {
+        if (frame.payload.length !== 0) throw new UplinkProtocolError("END carries a payload");
+        if (state.recvEnded) throw new UplinkProtocolError(`duplicate END on stream ${id}`);
+        state.recvEnded = true;
+        const pull = state.pullResolve;
+        if (pull !== undefined) {
+          state.pullResolve = undefined;
+          this.#settleRead(state, undefined);
+          pull();
+        }
+        this.#maybeRetire(state);
+        return;
+      }
+      case FrameType.RESET:
+        return this.#failStream(state, new StreamReset(decodeUtf8(frame.payload)));
+      case FrameType.WINDOW: {
+        if (frame.payload.length !== WINDOW_PAYLOAD_BYTES) {
+          throw new UplinkProtocolError(`WINDOW payload must be ${WINDOW_PAYLOAD_BYTES} bytes`);
+        }
+        const credit = decodeU32(frame.payload);
+        // Credit is granted against bytes consumed, so it can never exceed
+        // what this side still has outstanding.
+        if (credit === 0 || credit > state.sendOutstanding) {
+          throw new UplinkProtocolError(
+            `stream ${id} credited ${credit} against ${state.sendOutstanding} outstanding bytes`,
+          );
+        }
+        state.sendCredit += credit;
+        state.sendOutstanding -= credit;
+        this.#inFlight -= credit;
+        this.#creditGate.wake();
+        return;
+      }
+      default:
+        throw new UplinkProtocolError(`${name} is not a stream frame`);
+    }
+  }
+
+  #handleData(state: StreamState, payload: Uint8Array): void {
+    if (state.recvEnded) throw new UplinkProtocolError(`DATA after END on stream ${state.id}`);
+    const size = payload.length;
+    if (size > state.recvRemaining) {
+      throw new UplinkProtocolError(`stream ${state.id} exceeded its receive window`);
+    }
+    if (this.#peerInFlight + size > this.#limits.maxInFlight) {
+      throw new UplinkProtocolError("peer exceeded the session in-flight cap");
+    }
+    state.recvRemaining -= size;
+    state.recvUncredited += size;
+    this.#peerInFlight += size;
+    if (size === 0) return;
+    const pull = state.pullResolve;
+    if (pull === undefined) {
+      state.recvQueue.push(payload);
+      return;
+    }
+    state.pullResolve = undefined;
+    this.#deliver(state, payload);
+    pull();
+  }
+
+  // --- stream plumbing -------------------------------------------------
+
+  #createStream(id: number, local: boolean): StreamState {
+    const state: StreamState = {
+      id,
+      local,
+      stream: undefined as unknown as Stream,
+      retired: false,
+      error: undefined,
+      sendCredit: this.#limits.initialWindow,
+      sendOutstanding: 0,
+      writeEnded: false,
+      writeController: undefined,
+      recvRemaining: this.#limits.initialWindow,
+      recvUncredited: 0,
+      consumed: 0,
+      recvQueue: [],
+      recvEnded: false,
+      readSettled: false,
+      readController: undefined,
+      pullResolve: undefined,
+    };
+    // A zero high-water mark is what ties credit to consumption: `pull` runs
+    // only when the application actually has a read outstanding.
+    const readable = new ReadableStream<Uint8Array>(
+      {
+        start: (controller) => {
+          state.readController = controller;
+        },
+        pull: () => this.#pull(state),
+        cancel: (reason) => {
+          // Nothing else can tell the peer to stop sending.
+          this.#resetStream(state, reasonText(reason));
+        },
+      },
+      { highWaterMark: 0 },
+    );
+    const writable = new WritableStream<Uint8Array>({
+      start: (controller) => {
+        state.writeController = controller;
+      },
+      write: (chunk) => this.#write(state, chunk),
+      close: () => {
+        this.#endWrite(state);
+      },
+      abort: (reason) => {
+        this.#resetStream(state, reasonText(reason));
+      },
+    });
+    state.stream = {
+      id,
+      readable,
+      writable,
+      reset: (reason: string) => {
+        this.#resetStream(state, reason);
+      },
+    };
+    this.#streams.set(id, state);
+    return state;
+  }
+
+  #pull(state: StreamState): Promise<void> | undefined {
+    const chunk = state.recvQueue.shift();
+    if (chunk !== undefined) {
+      this.#deliver(state, chunk);
+      return undefined;
+    }
+    if (state.error !== undefined) {
+      this.#settleRead(state, state.error);
+      return undefined;
+    }
+    if (state.recvEnded) {
+      this.#settleRead(state, undefined);
+      return undefined;
+    }
+    return new Promise<void>((resolve) => {
+      state.pullResolve = resolve;
+    });
+  }
+
+  #deliver(state: StreamState, chunk: Uint8Array): void {
+    if (state.readSettled) return;
+    state.readController?.enqueue(chunk);
+    this.#grant(state, chunk.length);
+  }
+
+  // Credit follows what the application read, not what arrived.
+  #grant(state: StreamState, size: number): void {
+    state.consumed += size;
+    if (state.retired || state.consumed < this.#grantThreshold) return;
+    const credit = state.consumed;
+    state.consumed = 0;
+    state.recvRemaining += credit;
+    state.recvUncredited -= credit;
+    this.#peerInFlight -= credit;
+    this.#sendControl(encodeFrame(FrameType.WINDOW, state.id, encodeU32(credit)), state.id);
+  }
+
+  #settleRead(state: StreamState, error: Error | undefined): void {
+    if (state.readSettled) return;
+    state.readSettled = true;
+    if (error === undefined) state.readController?.close();
+    else state.readController?.error(error);
+  }
+
+  #failStream(state: StreamState, error: Error): void {
+    if (state.retired) return;
+    state.error = error;
+    state.writeEnded = true;
+    state.recvEnded = true;
+    // Queued DATA for a stream the peer has abandoned is dead weight; the
+    // RESET has already overtaken it.
+    for (let i = this.#dataQueue.length - 1; i >= 0; i--) {
+      const entry = this.#dataQueue[i];
+      if (entry !== undefined && entry.streamId === state.id) {
+        this.#dataQueue.splice(i, 1);
+        entry.reject(error);
+      }
+    }
+    this.#settleRead(state, error);
+    const pull = state.pullResolve;
+    state.pullResolve = undefined;
+    pull?.();
+    state.writeController?.error(error);
+    this.#retire(state);
+  }
+
+  #maybeRetire(state: StreamState): void {
+    if (state.writeEnded && state.recvEnded) this.#retire(state);
+  }
+
+  // Frees the slot and the credit the stream held. The readable may still
+  // have buffered bytes to hand out; that is the application's business.
+  #retire(state: StreamState): void {
+    if (state.retired) return;
+    state.retired = true;
+    this.#inFlight -= state.sendOutstanding;
+    state.sendOutstanding = 0;
+    this.#peerInFlight -= state.recvUncredited;
+    state.recvUncredited = 0;
+    this.#streams.delete(state.id);
+    if (state.local) this.#localOpen--;
+    else this.#remoteOpen--;
+    this.#slotGate.wake();
+    this.#creditGate.wake();
+  }
+
+  // --- teardown --------------------------------------------------------
+
+  #shutdown(error: Error, reason: string): void {
+    if (this.#closeError !== undefined) return;
+    this.#closeError = error;
+    for (const entry of this.#controlQueue.splice(0)) entry.reject(error);
+    for (const entry of this.#dataQueue.splice(0)) entry.reject(error);
+    // Snapshot: failing a stream retires it out of the map.
+    for (const state of Array.from(this.#streams.values())) this.#failStream(state, error);
+    for (const waiter of this.#pings.values()) waiter.reject(error);
+    this.#pings.clear();
+    this.#creditGate.wake();
+    this.#slotGate.wake();
+    this.#closedResolve(reason);
+    void this.#writer.abort(reason).catch(noop);
+    void this.#reader.cancel(reason).catch(noop);
+  }
+}
+
+function noop(): void {}
+
+function asError(value: unknown): Error {
+  return value instanceof Error ? value : new Error(String(value));
+}
+
+function reasonText(reason: unknown): string {
+  if (reason === undefined || reason === null) return "";
+  return reason instanceof Error ? reason.message : String(reason);
+}

package/src/worker-protocol/uplink/protocol.ts

@@ -0,0 +1,11 @@
+/**
+ * The version of the RPC catalogue in `methods.ts`, as both peers announce it
+ * in `hello`. Bump it whenever any method OTHER than `hello` changes shape -
+ * params or result, tightened or loosened. `protocol.test.ts` snapshots the
+ * catalogue under this number and fails when the two disagree.
+ *
+ * `hello` itself is outside this number on purpose: it is the door, and a
+ * door both sides can always open is what lets a mismatched pair be told to
+ * update instead of being stranded.
+ */
+export const PROTOCOL_VERSION = 1;