@structured-id/ui-core 0.1.5

package/src/transport/adaptive.ts

@@ -0,0 +1,308 @@
+/**
+ * AdaptiveRpcTransport — per-call failover between WebTransport and gRPC-web.
+ *
+ * Strategy:
+ * 1. Try primary (WebTransport) for every call
+ * 2. On transport-level failure (UNAVAILABLE), immediately retry on fallback (gRPC-web)
+ * 3. Background reconnect to primary after failover
+ * 4. Once primary is back — switch future calls to primary again
+ *
+ * This is NOT a one-time negotiation. Each call can roam independently.
+ */
+
+import {
+  Deferred,
+  RpcError,
+  mergeRpcOptions,
+  UnaryCall,
+} from "@protobuf-ts/runtime-rpc";
+import type {
+  RpcTransport,
+  MethodInfo,
+  RpcOptions,
+  RpcMetadata,
+  RpcStatus,
+  ServerStreamingCall,
+  ClientStreamingCall,
+  DuplexStreamingCall,
+} from "@protobuf-ts/runtime-rpc";
+import { GrpcWebFetchTransport } from "@protobuf-ts/grpcweb-transport";
+import {
+  WebTransportConnection,
+  WebTransportRpcTransport,
+} from "./webtransport";
+
+export type TransportType = "webtransport" | "grpc-web";
+
+export interface AdaptiveTransportOptions {
+  /** gRPC-web base URL (required, always available as fallback) */
+  grpcWebUrl: string;
+  /** WebTransport URL (optional — if absent, always uses gRPC-web) */
+  webTransportUrl?: string;
+  /** SHA-256 cert hash for dev WebTransport certs */
+  webTransportCertHash?: string;
+  /** Delay before attempting to reconnect primary after failover (ms) */
+  reconnectDelay?: number;
+  /** Callback when active transport changes */
+  onTransportChange?: (transport: TransportType) => void;
+  /**
+   * Fetch init options for the gRPC-web fallback transport.
+   * Use `{ credentials: "include" }` to send BFF session cookies.
+   */
+  fetchInit?: RequestInit;
+}
+
+/**
+ * Adaptive RPC transport with per-call failover and background reconnect.
+ */
+export class AdaptiveRpcTransport implements RpcTransport {
+  private readonly defaultOptions: RpcOptions;
+  private readonly fallback: GrpcWebFetchTransport;
+  private readonly wtConnection: WebTransportConnection | null;
+  private readonly wtTransport: WebTransportRpcTransport | null;
+  private readonly reconnectDelay: number;
+  private readonly onTransportChange?: (transport: TransportType) => void;
+
+  private primaryAvailable = false;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(opts: AdaptiveTransportOptions, defaultOptions?: RpcOptions) {
+    this.defaultOptions = defaultOptions ?? {};
+    this.reconnectDelay = opts.reconnectDelay ?? 5000;
+    this.onTransportChange = opts.onTransportChange;
+
+    this.fallback = new GrpcWebFetchTransport({
+      baseUrl: opts.grpcWebUrl,
+      fetchInit: opts.fetchInit,
+    });
+
+    if (opts.webTransportUrl && typeof WebTransport !== "undefined") {
+      this.wtConnection = new WebTransportConnection({
+        url: opts.webTransportUrl,
+        certHash: opts.webTransportCertHash,
+      });
+      this.wtTransport = new WebTransportRpcTransport(this.wtConnection);
+    } else {
+      this.wtConnection = null;
+      this.wtTransport = null;
+    }
+  }
+
+  /** Current active transport type. */
+  get activeTransport(): TransportType {
+    return this.primaryAvailable ? "webtransport" : "grpc-web";
+  }
+
+  /**
+   * Attempt initial WebTransport connection.
+   * Call this during app boot — non-blocking, falls back silently.
+   */
+  async init(): Promise<void> {
+    if (!this.wtConnection) {
+      this.notifyTransport("grpc-web");
+      return;
+    }
+
+    try {
+      await this.wtConnection.connect();
+      this.primaryAvailable = true;
+      this.notifyTransport("webtransport");
+    } catch {
+      this.primaryAvailable = false;
+      this.notifyTransport("grpc-web");
+      this.scheduleReconnect();
+    }
+  }
+
+  /** Shut down all connections. */
+  close(): void {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    this.wtConnection?.close();
+  }
+
+  mergeOptions(options?: Partial<RpcOptions>): RpcOptions {
+    return mergeRpcOptions(this.defaultOptions, options);
+  }
+
+  unary<I extends object, O extends object>(
+    method: MethodInfo<I, O>,
+    input: I,
+    options: RpcOptions,
+  ): UnaryCall<I, O> {
+    // If primary available — try it first with fallback on failure
+    if (this.primaryAvailable && this.wtTransport) {
+      return this.unaryWithFallback(method, input, options);
+    }
+
+    // Otherwise — go directly to fallback
+    return this.fallback.unary(method, input, options);
+  }
+
+  serverStreaming<I extends object, O extends object>(
+    method: MethodInfo<I, O>,
+    input: I,
+    options: RpcOptions,
+  ): ServerStreamingCall<I, O> {
+    // Streaming only via gRPC-web (WebTransport doesn't support it yet)
+    return this.fallback.serverStreaming(method, input, options);
+  }
+
+  clientStreaming<I extends object, O extends object>(
+    _method: MethodInfo<I, O>,
+    _options: RpcOptions,
+  ): ClientStreamingCall<I, O> {
+    throw new RpcError("Client streaming not supported");
+  }
+
+  duplex<I extends object, O extends object>(
+    _method: MethodInfo<I, O>,
+    _options: RpcOptions,
+  ): DuplexStreamingCall<I, O> {
+    throw new RpcError("Duplex streaming not supported");
+  }
+
+  /**
+   * Try primary, on transport-level error retry with fallback.
+   *
+   * The tricky part: UnaryCall is returned synchronously (with deferred promises).
+   * We wrap both attempts and resolve/reject the outer deferreds.
+   */
+  private unaryWithFallback<I extends object, O extends object>(
+    method: MethodInfo<I, O>,
+    input: I,
+    options: RpcOptions,
+  ): UnaryCall<I, O> {
+    const defHeader = new Deferred<RpcMetadata>();
+    const defMessage = new Deferred<O>();
+    const defStatus = new Deferred<RpcStatus>();
+    const defTrailer = new Deferred<RpcMetadata>();
+
+    const call = new UnaryCall(
+      method,
+      options.meta ?? {},
+      input,
+      defHeader.promise,
+      defMessage.promise,
+      defStatus.promise,
+      defTrailer.promise,
+    );
+
+    this.tryPrimaryThenFallback(
+      method,
+      input,
+      options,
+      defHeader,
+      defMessage,
+      defStatus,
+      defTrailer,
+    );
+
+    return call;
+  }
+
+  private async tryPrimaryThenFallback<I extends object, O extends object>(
+    method: MethodInfo<I, O>,
+    input: I,
+    options: RpcOptions,
+    defHeader: Deferred<RpcMetadata>,
+    defMessage: Deferred<O>,
+    defStatus: Deferred<RpcStatus>,
+    defTrailer: Deferred<RpcMetadata>,
+  ): Promise<void> {
+    try {
+      // Attempt primary (WebTransport)
+      const primaryCall = this.wtTransport!.unary(method, input, options);
+      const [header, message, status, trailer] = await Promise.all([
+        primaryCall.headers,
+        primaryCall.response,
+        primaryCall.status,
+        primaryCall.trailers,
+      ]);
+
+      defHeader.resolve(header);
+      defMessage.resolve(message);
+      defStatus.resolve(status);
+      defTrailer.resolve(trailer);
+    } catch (err) {
+      // Transport-level failure — failover to gRPC-web
+      if (isTransportError(err)) {
+        this.primaryAvailable = false;
+        this.notifyTransport("grpc-web");
+        this.scheduleReconnect();
+
+        try {
+          const fallbackCall = this.fallback.unary(method, input, options);
+          const [header, message, status, trailer] = await Promise.all([
+            fallbackCall.headers,
+            fallbackCall.response,
+            fallbackCall.status,
+            fallbackCall.trailers,
+          ]);
+
+          defHeader.resolvePending(header);
+          defMessage.resolvePending(message);
+          defStatus.resolvePending(status);
+          defTrailer.resolvePending(trailer);
+        } catch (fallbackErr) {
+          rejectAll(fallbackErr, defHeader, defMessage, defStatus, defTrailer);
+        }
+      } else {
+        // Application-level error (e.g. NOT_FOUND, PERMISSION_DENIED)
+        // — don't failover, propagate as-is
+        rejectAll(err, defHeader, defMessage, defStatus, defTrailer);
+      }
+    }
+  }
+
+  private scheduleReconnect(): void {
+    if (this.reconnectTimer || !this.wtConnection) return;
+
+    this.reconnectTimer = setTimeout(async () => {
+      this.reconnectTimer = null;
+      try {
+        this.wtConnection!.close();
+        await this.wtConnection!.connect();
+        this.primaryAvailable = true;
+        this.notifyTransport("webtransport");
+      } catch {
+        // Still down — try again later
+        this.scheduleReconnect();
+      }
+    }, this.reconnectDelay);
+  }
+
+  private notifyTransport(type: TransportType): void {
+    this.onTransportChange?.(type);
+  }
+}
+
+/**
+ * Check if the error is a transport-level failure (connection lost,
+ * stream reset, etc.) vs an application-level gRPC error.
+ *
+ * Transport errors trigger failover. Application errors do not.
+ */
+function isTransportError(err: unknown): boolean {
+  if (!(err instanceof RpcError)) return true;
+
+  // gRPC UNAVAILABLE = server unreachable (transport issue)
+  // gRPC CANCELLED = connection dropped mid-call
+  const transportCodes = ["UNAVAILABLE", "CANCELLED", "UNKNOWN"];
+  return transportCodes.includes(err.code);
+}
+
+function rejectAll(err: unknown, ...deferreds: Deferred<unknown>[]): void {
+  const rpcErr =
+    err instanceof RpcError
+      ? err
+      : new RpcError(
+          err instanceof Error ? err.message : String(err),
+          "INTERNAL",
+        );
+  for (const d of deferreds) {
+    d.rejectPending(rpcErr);
+  }
+}

package/src/transport/framing.test.ts

@@ -0,0 +1,227 @@
+import { describe, it, expect } from "vitest";
+import { readFrame, writeFrame, FrameReader } from "./framing";
+
+// ---------------------------------------------------------------------------
+// Helpers — mock ReadableStream / WritableStream
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a ReadableStreamDefaultReader that yields chunks sequentially.
+ */
+function makeReader(
+  chunks: Uint8Array[],
+): ReadableStreamDefaultReader<Uint8Array> {
+  let i = 0;
+  return {
+    read: async () => {
+      if (i < chunks.length) {
+        return { value: chunks[i++], done: false };
+      }
+      return { value: undefined, done: true };
+    },
+    releaseLock: () => {},
+    cancel: async () => {},
+    closed: Promise.resolve(undefined),
+  } as unknown as ReadableStreamDefaultReader<Uint8Array>;
+}
+
+/**
+ * Create a WritableStreamDefaultWriter that collects all written bytes.
+ * The `chunks` array is populated on each write() call.
+ */
+function makeWriter(
+  chunks: Uint8Array[],
+): WritableStreamDefaultWriter<Uint8Array> {
+  return {
+    write: async (chunk: Uint8Array) => {
+      chunks.push(chunk);
+    },
+    releaseLock: () => {},
+    close: async () => {},
+    abort: async () => {},
+    closed: Promise.resolve(undefined),
+    desiredSize: 1,
+    ready: Promise.resolve(undefined),
+  } as unknown as WritableStreamDefaultWriter<Uint8Array>;
+}
+
+/**
+ * Concatenate all chunks into a single Uint8Array.
+ */
+function concat(chunks: Uint8Array[]): Uint8Array {
+  const total = chunks.reduce((n, c) => n + c.length, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    out.set(c, offset);
+    offset += c.length;
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("writeFrame", () => {
+  it("writes 4-byte big-endian length prefix followed by payload", async () => {
+    const payload = new Uint8Array([0xde, 0xad, 0xbe, 0xef]);
+    const chunks: Uint8Array[] = [];
+    const writer = makeWriter(chunks);
+
+    await writeFrame(writer, payload);
+
+    // Should write exactly 2 chunks: length prefix + payload
+    expect(chunks).toHaveLength(2);
+
+    const lenBytes = chunks[0];
+    expect(lenBytes).toHaveLength(4);
+    const view = new DataView(lenBytes.buffer);
+    expect(view.getUint32(0, false)).toBe(4); // big-endian length = 4
+
+    expect(chunks[1]).toEqual(payload);
+  });
+
+  it("writes zero-length frame for empty payload", async () => {
+    const payload = new Uint8Array(0);
+    const chunks: Uint8Array[] = [];
+    await writeFrame(makeWriter(chunks), payload);
+
+    const view = new DataView(chunks[0].buffer);
+    expect(view.getUint32(0, false)).toBe(0);
+    expect(chunks[1]).toHaveLength(0);
+  });
+
+  it("encodes length in big-endian (MSB first)", async () => {
+    // 0x0102_0304 = 16909060 bytes would OOM — use a smaller payload and verify byte order
+    const smallPayload = new Uint8Array(258); // 0x0000_0102
+    const chunks: Uint8Array[] = [];
+    await writeFrame(makeWriter(chunks), smallPayload);
+
+    const lenBytes = chunks[0];
+    expect(lenBytes[0]).toBe(0x00);
+    expect(lenBytes[1]).toBe(0x00);
+    expect(lenBytes[2]).toBe(0x01);
+    expect(lenBytes[3]).toBe(0x02);
+  });
+});
+
+describe("readFrame", () => {
+  it("reads a frame written by writeFrame (roundtrip)", async () => {
+    const payload = new Uint8Array([1, 2, 3, 4, 5]);
+
+    // Write a frame to get the raw bytes
+    const chunks: Uint8Array[] = [];
+    await writeFrame(makeWriter(chunks), payload);
+    const raw = concat(chunks);
+
+    // Split into multiple chunks to test buffering (reader delivers byte-by-byte)
+    const byteChunks = Array.from(raw).map((b) => new Uint8Array([b]));
+    const reader = makeReader(byteChunks);
+
+    const result = await readFrame(reader);
+    expect(result).toEqual(payload);
+  });
+
+  it("reads frame when header and payload each arrive in one read", async () => {
+    // WebTransport delivers frame-aligned chunks: writeFrame writes 2 chunks
+    // (4-byte length prefix, then payload). readFrame receives them as 2 reads.
+    const payload = new Uint8Array([0xca, 0xfe]);
+    const chunks: Uint8Array[] = [];
+    await writeFrame(makeWriter(chunks), payload);
+    // chunks[0] = 4-byte length prefix, chunks[1] = payload
+    const reader = makeReader([chunks[0], chunks[1]]);
+    const result = await readFrame(reader);
+    expect(result).toEqual(payload);
+  });
+
+  it("reads frame when bytes arrive in two chunks (header separate from body)", async () => {
+    const payload = new Uint8Array([10, 20, 30]);
+    const chunks: Uint8Array[] = [];
+    await writeFrame(makeWriter(chunks), payload);
+    // chunks[0] = 4-byte header, chunks[1] = payload
+    const reader = makeReader([chunks[0], chunks[1]]);
+
+    const result = await readFrame(reader);
+    expect(result).toEqual(payload);
+  });
+
+  it("reads zero-length frame", async () => {
+    const payload = new Uint8Array(0);
+    const chunks: Uint8Array[] = [];
+    await writeFrame(makeWriter(chunks), payload);
+    const raw = concat(chunks);
+
+    const reader = makeReader([raw]);
+    const result = await readFrame(reader);
+    expect(result).toHaveLength(0);
+  });
+
+  it("throws when stream closes before frame complete", async () => {
+    // Only deliver the length prefix, no payload
+    const lenBuf = new Uint8Array(4);
+    new DataView(lenBuf.buffer).setUint32(0, 10, false); // says 10 bytes
+    const reader = makeReader([lenBuf]); // but no payload follows
+
+    await expect(readFrame(reader)).rejects.toThrow(
+      "Stream closed before frame complete",
+    );
+  });
+
+  it("throws when frame exceeds 4 MiB limit", async () => {
+    const lenBuf = new Uint8Array(4);
+    new DataView(lenBuf.buffer).setUint32(0, 4 * 1024 * 1024 + 1, false); // 4 MiB + 1
+    const reader = makeReader([lenBuf]);
+
+    await expect(readFrame(reader)).rejects.toThrow("Frame too large");
+  });
+});
+
+describe("FrameReader", () => {
+  it("reads two consecutive frames when each arrives in separate reads", async () => {
+    const p1 = new Uint8Array([1, 2, 3]);
+    const p2 = new Uint8Array([4, 5, 6, 7]);
+    const w1: Uint8Array[] = [];
+    const w2: Uint8Array[] = [];
+    await writeFrame(makeWriter(w1), p1);
+    await writeFrame(makeWriter(w2), p2);
+    // Deliver as separate chunks: [len1, p1, len2, p2]
+    const reader = makeReader([w1[0], w1[1], w2[0], w2[1]]);
+    const fr = new FrameReader(reader);
+
+    expect(await fr.readFrame()).toEqual(p1);
+    expect(await fr.readFrame()).toEqual(p2);
+  });
+
+  it("reads two consecutive frames when both arrive in a single chunk (QUIC coalescing)", async () => {
+    const p1 = new Uint8Array([0xaa, 0xbb]);
+    const p2 = new Uint8Array([0xcc, 0xdd, 0xee]);
+    const w1: Uint8Array[] = [];
+    const w2: Uint8Array[] = [];
+    await writeFrame(makeWriter(w1), p1);
+    await writeFrame(makeWriter(w2), p2);
+    // Deliver all bytes as a single chunk — simulates QUIC frame coalescing
+    const combined = concat([w1[0], w1[1], w2[0], w2[1]]);
+    const reader = makeReader([combined]);
+    const fr = new FrameReader(reader);
+
+    expect(await fr.readFrame()).toEqual(p1);
+    expect(await fr.readFrame()).toEqual(p2);
+  });
+
+  it("reads frames when first frame is split mid-payload across two chunks", async () => {
+    const p1 = new Uint8Array([10, 20, 30, 40]);
+    const p2 = new Uint8Array([50, 60]);
+    const w1: Uint8Array[] = [];
+    const w2: Uint8Array[] = [];
+    await writeFrame(makeWriter(w1), p1);
+    await writeFrame(makeWriter(w2), p2);
+    const full = concat([w1[0], w1[1], w2[0], w2[1]]);
+    // Split at mid-point of first frame
+    const reader = makeReader([full.slice(0, 5), full.slice(5)]);
+    const fr = new FrameReader(reader);
+
+    expect(await fr.readFrame()).toEqual(p1);
+    expect(await fr.readFrame()).toEqual(p2);
+  });
+});

package/src/transport/framing.ts

@@ -0,0 +1,98 @@
+/**
+ * Length-prefixed frame helpers for WebTransport streams.
+ *
+ * Wire format (per frame): [4 bytes big-endian length][payload]
+ */
+
+const MAX_FRAME_SIZE = 4 * 1024 * 1024; // 4 MiB
+
+/**
+ * Stateful frame reader that correctly buffers excess bytes between reads.
+ *
+ * WebTransport delivers QUIC stream data in arbitrary chunk boundaries — a
+ * single reader.read() may contain parts of multiple frames, or a frame may
+ * span multiple reads. FrameReader handles both cases correctly.
+ *
+ * Use FrameReader when reading multiple frames from the same stream.
+ */
+export class FrameReader {
+  private leftover = new Uint8Array(0);
+
+  constructor(
+    private readonly reader: ReadableStreamDefaultReader<Uint8Array>,
+  ) {}
+
+  async readFrame(): Promise<Uint8Array> {
+    const lenBuf = await this.readExact(4);
+    const view = new DataView(lenBuf.buffer, lenBuf.byteOffset, 4);
+    const len = view.getUint32(0, false); // big-endian
+
+    if (len > MAX_FRAME_SIZE) {
+      throw new Error(`Frame too large: ${len} bytes (max ${MAX_FRAME_SIZE})`);
+    }
+
+    return this.readExact(len);
+  }
+
+  private async readExact(n: number): Promise<Uint8Array> {
+    const result = new Uint8Array(n);
+    let offset = 0;
+
+    // First drain leftover from previous read
+    if (this.leftover.length > 0) {
+      const take = Math.min(this.leftover.length, n);
+      result.set(this.leftover.subarray(0, take), offset);
+      offset += take;
+      this.leftover =
+        this.leftover.length > take
+          ? this.leftover.slice(take)
+          : new Uint8Array(0);
+    }
+
+    while (offset < n) {
+      const { value, done } = await this.reader.read();
+      if (done || !value) {
+        throw new Error("Stream closed before frame complete");
+      }
+
+      const remaining = n - offset;
+      if (value.length <= remaining) {
+        result.set(value, offset);
+        offset += value.length;
+      } else {
+        // Chunk contains more bytes than needed — save the tail for next call
+        result.set(value.subarray(0, remaining), offset);
+        offset += remaining;
+        this.leftover = value.slice(remaining);
+      }
+    }
+
+    return result;
+  }
+}
+
+/**
+ * Read one length-prefixed frame from a ReadableStreamDefaultReader.
+ *
+ * Convenience wrapper for reading a single frame from a fresh stream.
+ * When reading multiple consecutive frames from the same stream, use
+ * FrameReader directly so excess bytes are not lost between reads.
+ */
+export async function readFrame(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+): Promise<Uint8Array> {
+  return new FrameReader(reader).readFrame();
+}
+
+/**
+ * Write one length-prefixed frame to a WritableStreamDefaultWriter.
+ */
+export async function writeFrame(
+  writer: WritableStreamDefaultWriter<Uint8Array>,
+  payload: Uint8Array,
+): Promise<void> {
+  const lenBuf = new Uint8Array(4);
+  new DataView(lenBuf.buffer).setUint32(0, payload.length, false);
+  await writer.write(lenBuf);
+  await writer.write(payload);
+}