@structured-id/ui-core 2.0.0 → 3.0.0

package/src/transport/adaptive.ts

@@ -1,308 +0,0 @@
-/**
- * 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

@@ -1,227 +0,0 @@
-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

@@ -1,98 +0,0 @@
-/**
- * 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);
-}