@graphorin/client 0.6.1 → 0.7.0

package/src/index.ts

@@ -0,0 +1,49 @@
+/**
+ * `@graphorin/client` - reference TypeScript client for the
+ * Graphorin standalone server.
+ *
+ * Wraps the WebSocket subprotocol `graphorin.protocol.v1` (with an
+ * optional Server-Sent Events fallback for proxy-restricted
+ * environments) behind an ergonomic {@link GraphorinClient} class:
+ * `connect()`, `subscribe({ target, id })` returning an
+ * async-iterable subscription, `cancel(runId, opts)`,
+ * `disconnect()`. Handles the browser ticket flow, exponential-
+ * backoff reconnect with `lastEventId` resume against the server
+ * replay buffer, and Zod-validated frame parsing on both
+ * directions.
+ *
+ * Browser-friendly: zero Node-only dependencies; the only runtime
+ * dependencies are `@graphorin/protocol` and `zod`.
+ *
+ * @packageDocumentation
+ */
+
+/** Canonical version constant, derived from `package.json` at build time. */
+import pkg from '../package.json' with { type: 'json' };
+
+export const VERSION: string = pkg.version;
+
+export * from './errors.js';
+export {
+  GraphorinClient,
+  type GraphorinClientOptions,
+  type Subscription,
+  type SubscriptionMetadata,
+  type SubscriptionTarget,
+  type TransportPreference,
+} from './graphorin-client.js';
+export {
+  type BackoffPolicy,
+  computeBackoffMs,
+  sleep,
+} from './reconnect.js';
+export {
+  openSseTransport,
+  openWebSocketTransport,
+  type Transport,
+  type TransportAuth,
+  type TransportCloseReason,
+  type TransportKind,
+  type TransportListeners,
+  type TransportOptions,
+} from './transport/index.js';

package/src/reconnect.ts

@@ -0,0 +1,91 @@
+/**
+ * Pure-functional reconnect-backoff helper. Encapsulated in its own
+ * module so the `GraphorinClient` stays free of timing
+ * heuristics - and so tests can drive the policy with a deterministic
+ * RNG.
+ *
+ * Algorithm: exponential backoff with full-jitter
+ * (`delay = random(0, min(maxMs, baseMs * 2^attempt))`). The
+ * implementation matches the AWS Architecture Blog "exponential
+ * backoff and jitter" reference but is otherwise an original
+ * formulation.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Stable shape consumed by {@link computeBackoffMs}.
+ *
+ * @stable
+ */
+export interface BackoffPolicy {
+  /** Initial slot in milliseconds. Default `500`. */
+  readonly baseMs?: number;
+  /** Cap on every individual sleep. Default `30_000`. */
+  readonly maxMs?: number;
+  /**
+   * Hard cap on the number of attempts. The client surfaces a
+   * `TransportFailedError` once exceeded. Default `Infinity`.
+   */
+  readonly maxAttempts?: number;
+  /**
+   * Optional injection seam used by tests; defaults to `Math.random`.
+   */
+  readonly random?: () => number;
+}
+
+/**
+ * Compute the number of milliseconds to sleep before the
+ * `attempt`-th reconnect (1-indexed). Returns `null` when the policy
+ * has been exhausted (`attempt > maxAttempts`).
+ *
+ * @stable
+ */
+export function computeBackoffMs(attempt: number, policy: BackoffPolicy = {}): number | null {
+  if (!Number.isFinite(attempt) || attempt < 1) {
+    throw new RangeError('computeBackoffMs: attempt must be a positive integer.');
+  }
+  const baseMs = policy.baseMs ?? 500;
+  const maxMs = policy.maxMs ?? 30_000;
+  const maxAttempts = policy.maxAttempts ?? Number.POSITIVE_INFINITY;
+  const random = policy.random ?? Math.random;
+  if (attempt > maxAttempts) return null;
+  // Exponential growth with full jitter, clamped to maxMs.
+  const exp = Math.min(maxMs, baseMs * 2 ** Math.min(attempt - 1, 30));
+  return Math.floor(random() * exp);
+}
+
+/**
+ * Resolve when the requested number of milliseconds elapsed, or
+ * reject (with a `DOMException`-style abort error) when the
+ * supplied `AbortSignal` fires first.
+ *
+ * @stable
+ */
+export function sleep(durationMs: number, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted) {
+    return Promise.reject(abortError(signal.reason));
+  }
+  return new Promise<void>((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, durationMs);
+    const onAbort = (): void => {
+      cleanup();
+      reject(abortError(signal?.reason));
+    };
+    const cleanup = (): void => {
+      clearTimeout(timeout);
+      signal?.removeEventListener('abort', onAbort);
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+function abortError(reason: unknown): Error {
+  if (reason instanceof Error) return reason;
+  const err = new Error('Aborted.');
+  err.name = 'AbortError';
+  return err;
+}

package/src/transport/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Transport barrel for `@graphorin/client`.
+ *
+ * @packageDocumentation
+ */
+
+export { openSseTransport } from './sse.js';
+export type {
+  Transport,
+  TransportAuth,
+  TransportCloseReason,
+  TransportKind,
+  TransportListeners,
+  TransportOptions,
+} from './types.js';
+export { openWebSocketTransport } from './ws.js';

package/src/transport/sse.ts

@@ -0,0 +1,174 @@
+/**
+ * Server-Sent-Events transport - the read-only fallback for clients
+ * stuck behind proxies that block WebSocket upgrades. The transport
+ * is unidirectional (server → client only); control-plane operations
+ * (subscribe / abort / resume) must go through REST endpoints
+ * exposed by `@graphorin/server`.
+ *
+ * IP-3: implemented on **fetch streaming**, not `EventSource`. The
+ * server writes *named* events (`event: <frame.type>`), which an
+ * `EventSource` delivers only to listeners registered per type - an
+ * unbounded catalogue the old `message`-only listener never saw.
+ * Every frame's full JSON rides in `data:`, so a direct SSE parse
+ * that ignores the event name delivers everything - and `fetch`
+ * sends the `Authorization` header natively (no polyfill seam).
+ *
+ * @packageDocumentation
+ */
+
+import { ServerMessageSchema } from '@graphorin/protocol';
+
+import { InvalidServerFrameError, TransportFailedError } from '../errors.js';
+import type { Transport, TransportListeners, TransportOptions } from './types.js';
+
+/**
+ * Open an SSE transport. Resolves once the server answers with a
+ * streaming response; rejects with a typed
+ * {@link TransportFailedError} on construction / connection failure.
+ *
+ * @stable
+ */
+export async function openSseTransport(
+  options: TransportOptions,
+  listeners: TransportListeners,
+): Promise<Transport> {
+  if (options.auth.kind !== 'bearer') {
+    throw new TransportFailedError(
+      `SSE transport supports only the 'bearer' auth strategy; got '${options.auth.kind}'.`,
+    );
+  }
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== 'function') {
+    throw new TransportFailedError('No fetch implementation available for the SSE transport.');
+  }
+  const controller = new AbortController();
+  let resp: Response;
+  try {
+    resp = await fetchImpl(options.url, {
+      method: 'GET',
+      headers: {
+        Accept: 'text/event-stream',
+        Authorization: `Bearer ${options.auth.token}`,
+        // periphery-03: resume from the replay buffer instead of
+        // re-receiving the entire buffered history on every reconnect.
+        ...(options.lastEventId !== undefined && options.lastEventId.length > 0
+          ? { 'Last-Event-ID': options.lastEventId }
+          : {}),
+      },
+      signal: controller.signal,
+    });
+  } catch (cause) {
+    throw new TransportFailedError(
+      `SSE connection to '${options.url}' failed.`,
+      cause instanceof Error ? { cause } : {},
+    );
+  }
+  if (!resp.ok || resp.body === null) {
+    throw new TransportFailedError(
+      `SSE endpoint '${options.url}' answered ${resp.status}${resp.body === null ? ' with no body' : ''}.`,
+    );
+  }
+
+  let lastEventId: string | undefined;
+  let closeFired = false;
+  const close = (reason: { code: number; reason: string; wasClean: boolean }): void => {
+    if (closeFired) return;
+    closeFired = true;
+    listeners.onClose(reason);
+  };
+
+  // Consume the stream in the background: split on newlines, parse
+  // `id:` / `data:` fields, dispatch on blank lines. The `event:`
+  // name is intentionally ignored - the full frame JSON is in `data:`.
+  void (async () => {
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let dataLines: string[] = [];
+    let pendingId: string | undefined;
+
+    const dispatch = (): void => {
+      if (dataLines.length === 0) {
+        pendingId = undefined;
+        return;
+      }
+      const raw = dataLines.join('\n');
+      dataLines = [];
+      const id = pendingId;
+      pendingId = undefined;
+      let payload: unknown;
+      try {
+        payload = JSON.parse(raw);
+      } catch {
+        // Keep-alive / non-JSON data is not a frame.
+        return;
+      }
+      const parsed = ServerMessageSchema.safeParse(payload);
+      if (!parsed.success) {
+        listeners.onError(
+          new InvalidServerFrameError(
+            'Server SSE frame failed schema validation.',
+            parsed.error.issues.map((i) => ({ path: i.path, message: i.message })),
+          ),
+        );
+        return;
+      }
+      const frame = parsed.data;
+      const eventId = (frame as { eventId?: string }).eventId ?? id;
+      if (typeof eventId === 'string' && eventId.length > 0) lastEventId = eventId;
+      listeners.onFrame(frame);
+    };
+
+    try {
+      for await (const chunk of resp.body as unknown as AsyncIterable<Uint8Array>) {
+        buffer += decoder.decode(chunk, { stream: true });
+        for (;;) {
+          const nl = buffer.indexOf('\n');
+          if (nl === -1) break;
+          const line = buffer.slice(0, nl).replace(/\r$/, '');
+          buffer = buffer.slice(nl + 1);
+          if (line.length === 0) {
+            dispatch();
+            continue;
+          }
+          if (line.startsWith(':')) continue; // comment / keep-alive
+          if (line.startsWith('data:')) {
+            dataLines.push(line.slice(5).replace(/^ /, ''));
+          } else if (line.startsWith('id:')) {
+            pendingId = line.slice(3).trim();
+          }
+          // `event:` / `retry:` fields are intentionally ignored.
+        }
+      }
+      close({ code: 1000, reason: 'stream ended', wasClean: true });
+    } catch (err) {
+      if (controller.signal.aborted) {
+        close({ code: 1000, reason: 'closed by client', wasClean: true });
+        return;
+      }
+      close({
+        code: 1006,
+        reason: err instanceof Error ? err.message : String(err),
+        wasClean: false,
+      });
+    }
+  })();
+
+  listeners.onOpen();
+  const transport: Transport = {
+    kind: 'sse',
+    url: options.url,
+    send: () => {
+      throw new TransportFailedError(
+        'The SSE transport is read-only; control-plane calls go through REST.',
+      );
+    },
+    close: () => {
+      controller.abort();
+      close({ code: 1000, reason: 'closed by client', wasClean: true });
+    },
+    get lastEventId(): string | undefined {
+      return lastEventId;
+    },
+  };
+  return transport;
+}

package/src/transport/types.ts

@@ -0,0 +1,106 @@
+/**
+ * Common transport contract shared by the WebSocket and SSE
+ * back-ends. The {@link GraphorinClient} talks to a transport
+ * exclusively through this interface so the two implementations are
+ * pluggable + replaceable.
+ *
+ * @packageDocumentation
+ */
+
+import type { ClientMessage, ServerMessage } from '@graphorin/protocol';
+
+/**
+ * Discriminator used by the public client API + diagnostics.
+ *
+ * @stable
+ */
+export type TransportKind = 'ws' | 'sse';
+
+/**
+ * Stable shape consumed by every transport implementation.
+ *
+ * @stable
+ */
+export interface TransportOptions {
+  readonly url: string;
+  readonly auth: TransportAuth;
+  readonly fetch?: typeof fetch;
+  readonly WebSocket?: typeof WebSocket;
+  readonly EventSource?: typeof EventSource;
+  /** Per-connection identifier surfaced on diagnostics + reconnects. */
+  readonly clientId?: string;
+  /**
+   * Resume cursor sent as the `Last-Event-ID` header on (re)connect
+   * (periphery-03). The server replays only events AFTER it from the
+   * buffer - without it every SSE reconnect replays the entire
+   * buffered history. Consumed by the SSE transport; ignored by WS
+   * (whose resubscribe carries the cursor in the RPC).
+   */
+  readonly lastEventId?: string;
+}
+
+/**
+ * Authentication strategy passed to a transport. The bearer-token
+ * shape is consumed by both transports (WS via the
+ * `Authorization` header on Node SDK clients; SSE via the
+ * `Authorization` header on every fetch); the ticket-provider shape
+ * is only used by the WS browser path (the WebSocket browser API
+ * does not allow custom headers, so the ticket rides the
+ * `Sec-WebSocket-Protocol` header).
+ *
+ * @stable
+ */
+export type TransportAuth =
+  | { readonly kind: 'bearer'; readonly token: string }
+  | { readonly kind: 'ticket'; readonly ticketProvider: () => Promise<string> };
+
+/**
+ * Minimal listener surface the transport invokes in lifecycle order:
+ * `onOpen` ⇒ `onFrame*` (zero or more) ⇒ `onClose`. `onError` may
+ * fire at any time before `onClose`.
+ *
+ * @stable
+ */
+export interface TransportListeners {
+  onOpen(): void;
+  onFrame(frame: ServerMessage): void;
+  onError(error: Error): void;
+  onClose(reason: TransportCloseReason): void;
+}
+
+/**
+ * Discriminator returned via {@link TransportListeners.onClose}. The
+ * client uses the discriminator to decide whether to reconnect.
+ *
+ * @stable
+ */
+export interface TransportCloseReason {
+  readonly code: number;
+  readonly reason: string;
+  /** True when the close came from a server-side `error` frame. */
+  readonly wasClean: boolean;
+  /** Optional Graphorin reason discriminator, per `@graphorin/protocol`. */
+  readonly graphorinReason?: string;
+}
+
+/**
+ * Active transport handle. The client owns the handle and disposes
+ * it via {@link Transport.close} on every cleanup path.
+ *
+ * @stable
+ */
+export interface Transport {
+  readonly kind: TransportKind;
+  readonly url: string;
+  /**
+   * Send a client → server frame. Throws when the transport is not
+   * in the open state, or when the underlying back-end does not
+   * support send (the SSE transport throws every send via
+   * `TransportFailedError` - clients
+   * should fall back to REST for control-plane operations on SSE).
+   */
+  send(frame: ClientMessage): void;
+  close(code?: number, reason?: string): void;
+  /** Last server-issued event id observed on this connection. */
+  readonly lastEventId: string | undefined;
+}

package/src/transport/ws.ts

@@ -0,0 +1,211 @@
+/**
+ * WebSocket transport for the {@link GraphorinClient}. Speaks the
+ * `graphorin.protocol.v1` subprotocol; honours the browser ticket
+ * flow when the auth strategy is `'ticket'`.
+ *
+ * @packageDocumentation
+ */
+
+import {
+  type ClientMessage,
+  closeCodeReason,
+  formatTicketSubprotocol,
+  isErrorFrame,
+  ServerMessageSchema,
+  SUBPROTOCOL_NAME,
+} from '@graphorin/protocol';
+
+import {
+  AuthFailedError,
+  InvalidServerFrameError,
+  ProtocolViolationError,
+  SubprotocolMismatchError,
+  TransportFailedError,
+} from '../errors.js';
+import type {
+  Transport,
+  TransportCloseReason,
+  TransportListeners,
+  TransportOptions,
+} from './types.js';
+
+const STATE_CONNECTING = 0;
+const STATE_OPEN = 1;
+
+/**
+ * Open a WebSocket transport. Resolves once the underlying socket
+ * fires `open` (i.e. the upgrade succeeded + the subprotocol matches
+ * `SUBPROTOCOL_NAME`); rejects with a typed
+ * {@link TransportFailedError} / {@link SubprotocolMismatchError} /
+ * {@link AuthFailedError} otherwise.
+ *
+ * @stable
+ */
+export async function openWebSocketTransport(
+  options: TransportOptions,
+  listeners: TransportListeners,
+): Promise<Transport> {
+  const WebSocketImpl = options.WebSocket ?? globalThis.WebSocket;
+  if (typeof WebSocketImpl !== 'function') {
+    throw new TransportFailedError(
+      'No WebSocket implementation found. Pass `WebSocket` via the transport options or run on a runtime that ships one (Node 22+, modern browsers).',
+    );
+  }
+
+  const subprotocols: string[] = [SUBPROTOCOL_NAME];
+  if (options.auth.kind === 'ticket') {
+    const ticket = await options.auth.ticketProvider();
+    subprotocols.push(formatTicketSubprotocol(ticket));
+  }
+
+  // Bearer-token auth on Node SDKs is encoded as a custom header on
+  // the upgrade. The browser WebSocket API does not expose headers,
+  // so the SDK fallback path uses the ticket strategy instead. We
+  // try the 3-arg `new WebSocket(url, protocols, opts)` overload
+  // first (supported by `ws` on Node + most polyfills); if the
+  // implementation rejects it, we fall back to the 2-arg signature
+  // and rely on the server to surface auth failures via the close
+  // code (the only viable path on plain browser WebSocket).
+  let socket: WebSocket;
+  if (options.auth.kind === 'bearer') {
+    type WsCtorWithOptions = new (
+      url: string,
+      protocols: ReadonlyArray<string>,
+      options: { readonly headers: Readonly<Record<string, string>> },
+    ) => WebSocket;
+    const Ctor = WebSocketImpl as unknown as WsCtorWithOptions;
+    try {
+      socket = new Ctor(options.url, subprotocols, {
+        headers: { Authorization: `Bearer ${options.auth.token}` },
+      });
+    } catch {
+      try {
+        socket = new WebSocketImpl(options.url, subprotocols);
+      } catch (cause) {
+        throw new TransportFailedError(
+          `Failed to construct WebSocket for '${options.url}'.`,
+          cause instanceof Error ? { cause } : {},
+        );
+      }
+    }
+  } else {
+    try {
+      socket = new WebSocketImpl(options.url, subprotocols);
+    } catch (cause) {
+      throw new TransportFailedError(
+        `Failed to construct WebSocket for '${options.url}'.`,
+        cause instanceof Error ? { cause } : {},
+      );
+    }
+  }
+
+  let lastEventId: string | undefined;
+  let closeFired = false;
+  let openFired = false;
+  return await new Promise<Transport>((resolve, reject) => {
+    const fail = (err: Error): void => {
+      if (!openFired) {
+        cleanup();
+        reject(err);
+      } else {
+        listeners.onError(err);
+      }
+    };
+    const cleanup = (): void => {
+      socket.removeEventListener('open', onOpen);
+      socket.removeEventListener('message', onMessage);
+      socket.removeEventListener('error', onError);
+      socket.removeEventListener('close', onClose);
+    };
+    const onOpen = (): void => {
+      const negotiated = socket.protocol;
+      if (negotiated !== SUBPROTOCOL_NAME) {
+        socket.close(4008, 'protocol.violation');
+        fail(new SubprotocolMismatchError(SUBPROTOCOL_NAME, negotiated || null));
+        return;
+      }
+      openFired = true;
+      listeners.onOpen();
+      resolve({
+        kind: 'ws',
+        url: options.url,
+        send(frame: ClientMessage): void {
+          if (socket.readyState !== STATE_OPEN) {
+            throw new TransportFailedError(
+              `Cannot send: WebSocket is in state ${socket.readyState}.`,
+            );
+          }
+          socket.send(JSON.stringify(frame));
+        },
+        close(code?: number, reason?: string): void {
+          if (socket.readyState !== STATE_CONNECTING && socket.readyState !== STATE_OPEN) {
+            return;
+          }
+          socket.close(code, reason);
+        },
+        get lastEventId(): string | undefined {
+          return lastEventId;
+        },
+      });
+    };
+    const onMessage = (event: MessageEvent): void => {
+      const raw = typeof event.data === 'string' ? event.data : '';
+      let payload: unknown;
+      try {
+        payload = JSON.parse(raw);
+      } catch {
+        fail(new ProtocolViolationError('Server sent a non-JSON frame.'));
+        return;
+      }
+      const parsed = ServerMessageSchema.safeParse(payload);
+      if (!parsed.success) {
+        fail(
+          new InvalidServerFrameError(
+            'Server frame failed schema validation.',
+            parsed.error.issues.map((i) => ({ path: i.path, message: i.message })),
+          ),
+        );
+        return;
+      }
+      const frame = parsed.data;
+      if ('kind' in frame && frame.kind === 'event') {
+        lastEventId = frame.eventId;
+      }
+      if (isErrorFrame(frame) && frame.fatal === true) {
+        listeners.onFrame(frame);
+        if (frame.code.startsWith('auth.')) fail(new AuthFailedError(frame.message));
+        return;
+      }
+      listeners.onFrame(frame);
+    };
+    const onError = (): void => {
+      fail(new TransportFailedError('WebSocket error event fired.'));
+    };
+    const onClose = (event: CloseEvent): void => {
+      if (closeFired) return;
+      closeFired = true;
+      cleanup();
+      const graphorinReason = closeCodeReason(event.code);
+      const reasonRecord: TransportCloseReason = {
+        code: event.code,
+        reason: event.reason,
+        wasClean: event.wasClean,
+        ...(graphorinReason !== undefined ? { graphorinReason } : {}),
+      };
+      if (!openFired) {
+        const codeReason = closeCodeReason(event.code);
+        if (codeReason?.startsWith('auth.') === true) {
+          fail(new AuthFailedError(event.reason || codeReason));
+          return;
+        }
+        fail(new TransportFailedError(event.reason || 'WebSocket closed before open.'));
+        return;
+      }
+      listeners.onClose(reasonRecord);
+    };
+    socket.addEventListener('open', onOpen);
+    socket.addEventListener('message', onMessage);
+    socket.addEventListener('error', onError);
+    socket.addEventListener('close', onClose);
+  });
+}