okengine 0.15.2 → 0.17.0

package/src/client/live.ts

@@ -0,0 +1,389 @@
+/**
+ * Client live subscribe — fetch SSE, callback + unsubscribe.
+ */
+
+import type { ClientFetch, ClientOptions, ClientRouteMap, FlowContract } from "./types.ts";
+import type { LiveHandlers, LiveUnsubscribe } from "./types.ts";
+
+/** One HTTP exposure of a live signal. */
+export interface LiveExposure {
+  readonly flow: string;
+  readonly method: string;
+  readonly path: string;
+  readonly matchKey: readonly string[];
+}
+
+/** Signal name → exposures (multiple audiences). */
+export type LiveRouteTable = Readonly<Record<string, readonly LiveExposure[]>>;
+
+/** Flow id (`unit.flow`) → exposure. */
+export type LiveByFlow = Readonly<Record<string, LiveExposure>>;
+
+/**
+ * Build live route tables from `app.$routes`.
+ *
+ * @param $routes - Runtime route map
+ */
+export function flattenLiveRoutes($routes: ClientRouteMap | undefined): {
+  readonly bySignal: LiveRouteTable;
+  readonly byFlow: LiveByFlow;
+} {
+  const bySignal: Record<string, LiveExposure[]> = {};
+  const byFlow: Record<string, LiveExposure> = {};
+  if (!$routes) return { bySignal, byFlow };
+  for (const [unit, flows] of Object.entries($routes)) {
+    if (!flows || typeof flows !== "object") continue;
+    for (const [flow, contract] of Object.entries(flows)) {
+      if (!contract || typeof contract !== "object") continue;
+      const live = liveName(contract);
+      const method = "method" in contract ? contract.method : undefined;
+      const path = "path" in contract ? contract.path : undefined;
+      if (typeof live !== "string" || typeof method !== "string" || typeof path !== "string") {
+        continue;
+      }
+      const matchKey = matchKeyOf(contract);
+      const id = `${unit}.${flow}`;
+      const exposure: LiveExposure = { flow: id, method, path, matchKey };
+      (bySignal[live] ??= []).push(exposure);
+      byFlow[id] = exposure;
+    }
+  }
+  return { bySignal, byFlow };
+}
+
+function liveName(contract: FlowContract): string | undefined {
+  return "live" in contract && typeof contract.live === "string" ? contract.live : undefined;
+}
+
+function matchKeyOf(contract: FlowContract): readonly string[] {
+  if ("matchKey" in contract && Array.isArray(contract.matchKey)) {
+    return contract.matchKey.filter((k): k is string => typeof k === "string");
+  }
+  return [];
+}
+
+/** True when `value` is a handlers bag (`onEvent` present). */
+export function isLiveHandlers(value: unknown): value is LiveHandlers<unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as LiveHandlers<unknown>).onEvent === "function"
+  );
+}
+
+/**
+ * Pick the unique exposure whose `matchKey` is a subset of `input` keys.
+ * Prefer the largest matchKey. Ties require `via`.
+ *
+ * @param exposures - All exposures for one signal
+ * @param input - Filter fields
+ * @param via - `unit.flow` disambiguator
+ */
+export function pickLiveExposure(
+  exposures: readonly LiveExposure[],
+  input: unknown,
+  via?: string,
+): LiveExposure {
+  if (via) {
+    const hit = exposures.find((e) => e.flow === via);
+    if (!hit) {
+      throw new Error(
+        `Unknown live via "${via}". Known: ${exposures.map((e) => e.flow).join(", ")}`,
+      );
+    }
+    return hit;
+  }
+  const keys =
+    input !== null && typeof input === "object"
+      ? Object.keys(input as Record<string, unknown>)
+      : [];
+  const candidates = exposures.filter((e) => e.matchKey.every((k) => keys.includes(k)));
+  if (candidates.length === 0) {
+    throw new Error(
+      `No live exposure matches input keys [${keys.join(", ")}]. Flows: ${exposures.map((e) => e.flow).join(", ")}`,
+    );
+  }
+  let max = -1;
+  for (const e of candidates) {
+    if (e.matchKey.length > max) max = e.matchKey.length;
+  }
+  const top = candidates.filter((e) => e.matchKey.length === max);
+  if (top.length !== 1) {
+    throw new Error(
+      `Multiple live exposures match: ${top.map((e) => e.flow).join(", ")}. Pass via: "unit.flow".`,
+    );
+  }
+  return top[0]!;
+}
+
+/** First wait after a drop when {@link LiveHandlers.autoResubscribe} is true. */
+export const LIVE_RESUBSCRIBE_INITIAL_MS = 500;
+
+/** Cap for autoResubscribe exponential backoff. */
+export const LIVE_RESUBSCRIBE_MAX_MS = 30_000;
+
+/**
+ * Next backoff after `delayMs` (`initial * 2^n`, capped).
+ *
+ * @param delayMs - Current delay
+ */
+export function nextResubscribeDelay(delayMs: number): number {
+  return Math.min(Math.max(delayMs, LIVE_RESUBSCRIBE_INITIAL_MS) * 2, LIVE_RESUBSCRIBE_MAX_MS);
+}
+
+/**
+ * Open an SSE subscription. `unsubscribe` aborts and drops in-flight frames.
+ *
+ * @param base - Origin
+ * @param exposure - Route
+ * @param input - Path/query fields
+ * @param handlers - Callbacks
+ * @param opts - Client options (auth, headers, fetch)
+ */
+export function subscribeLive(
+  base: string,
+  exposure: LiveExposure,
+  input: unknown,
+  handlers: LiveHandlers<unknown>,
+  opts: ClientOptions,
+): LiveUnsubscribe {
+  const ctrl = new AbortController();
+  const onAbort = (): void => {
+    ctrl.abort();
+  };
+  handlers.signal?.addEventListener("abort", onAbort, { once: true });
+  const run = pump(base, exposure, input, handlers, opts, ctrl.signal);
+  void run;
+  return () => {
+    handlers.signal?.removeEventListener("abort", onAbort);
+    ctrl.abort();
+  };
+}
+
+async function pump(
+  base: string,
+  exposure: LiveExposure,
+  input: unknown,
+  handlers: LiveHandlers<unknown>,
+  opts: ClientOptions,
+  signal: AbortSignal,
+): Promise<void> {
+  const auto = handlers.autoResubscribe === true;
+  let delayMs = LIVE_RESUBSCRIBE_INITIAL_MS;
+  let attempt = 0;
+  let lastSeenId: string | undefined;
+  for (;;) {
+    if (signal.aborted) return;
+    if (attempt > 0 && auto) {
+      await sleep(delayMs, signal);
+      if (signal.aborted) return;
+      delayMs = nextResubscribeDelay(delayMs);
+    }
+    attempt += 1;
+    try {
+      const res = await openSse(base, exposure, input, opts, signal, lastSeenId);
+      if (signal.aborted) return;
+      if (res.status === 401 && opts.auth?.refresh) {
+        await opts.auth.refresh();
+        const retry = await openSse(base, exposure, input, opts, signal, lastSeenId);
+        if (signal.aborted) return;
+        lastSeenId = await consumeSse(retry, handlers, signal, lastSeenId);
+        if (signal.aborted) return;
+        const closed = new Error("live connection closed");
+        if (auto) {
+          handlers.onError?.(closed);
+          continue;
+        }
+        handlers.onError?.(closed);
+        return;
+      }
+      if (res.status === 410) {
+        const err = await liveResumeGapError(res);
+        lastSeenId = undefined;
+        handlers.onError?.(err);
+        if (!auto) return;
+        continue;
+      }
+      lastSeenId = await consumeSse(res, handlers, signal, lastSeenId);
+      if (signal.aborted) return;
+      const closed = new Error("live connection closed");
+      if (auto) {
+        handlers.onError?.(closed);
+        continue;
+      }
+      handlers.onError?.(closed);
+      return;
+    } catch (err) {
+      if (signal.aborted) return;
+      if (auto) {
+        handlers.onError?.(err);
+        continue;
+      }
+      handlers.onError?.(err);
+      return;
+    }
+  }
+}
+
+async function consumeSse(
+  res: Response,
+  handlers: LiveHandlers<unknown>,
+  signal: AbortSignal,
+  lastSeenId: string | undefined,
+): Promise<string | undefined> {
+  let cursor = lastSeenId;
+  await readSse(
+    res,
+    (event, id) => {
+      handlers.onEvent(event);
+      if (id !== undefined && id.length > 0) cursor = id;
+    },
+    signal,
+    handlers.onOpen,
+  );
+  return cursor;
+}
+
+async function liveResumeGapError(res: Response): Promise<Error> {
+  const text = await res.text().catch(() => "");
+  return sseError(410, text);
+}
+
+/**
+ * Abortable delay. Resolves immediately when `signal` is already aborted.
+ *
+ * @param ms - Duration
+ * @param signal - Unsubscribe / caller abort
+ */
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  if (signal.aborted || ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => {
+    function finish(): void {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", finish);
+      resolve();
+    }
+    const timer = setTimeout(finish, ms);
+    signal.addEventListener("abort", finish, { once: true });
+    if (signal.aborted) finish();
+  });
+}
+
+async function openSse(
+  base: string,
+  exposure: LiveExposure,
+  input: unknown,
+  opts: ClientOptions,
+  signal: AbortSignal,
+  lastSeenId?: string,
+): Promise<Response> {
+  const { url, method } = restGet(base, exposure.path, input);
+  const headers = new Headers({ accept: "text/event-stream" });
+  const extra = typeof opts.headers === "function" ? await opts.headers() : opts.headers;
+  if (Array.isArray(extra)) {
+    for (const [k, v] of extra) headers.set(k, v);
+  } else if (extra) {
+    for (const [k, v] of Object.entries(extra)) headers.set(k, v);
+  }
+  const token = opts.auth ? await opts.auth.getToken() : undefined;
+  if (token && !headers.has("authorization")) {
+    headers.set("authorization", `Bearer ${token}`);
+  }
+  if (lastSeenId) headers.set("last-event-id", lastSeenId);
+  const fetchFn: ClientFetch = opts.fetch ?? globalThis.fetch.bind(globalThis);
+  return fetchFn(url, { method, headers, signal });
+}
+
+function restGet(base: string, path: string, input: unknown): { url: string; method: string } {
+  const params =
+    input !== null && typeof input === "object" ? (input as Record<string, unknown>) : {};
+  let pathOut = path;
+  const query: string[] = [];
+  for (const [k, v] of Object.entries(params)) {
+    const token = `:${k}`;
+    if (pathOut.includes(token)) {
+      pathOut = pathOut.replaceAll(token, encodeURIComponent(String(v)));
+    } else if (v !== undefined) {
+      query.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+    }
+  }
+  const qs = query.length ? `?${query.join("&")}` : "";
+  return { url: `${base}${pathOut}${qs}`, method: "GET" };
+}
+
+async function readSse(
+  res: Response,
+  onEvent: (event: unknown, id: string | undefined) => void,
+  signal: AbortSignal,
+  onOpen?: () => void,
+): Promise<void> {
+  if (signal.aborted) return;
+  const ct = res.headers.get("content-type") ?? "";
+  if (!res.ok || !res.body) {
+    const text = await res.text().catch(() => "");
+    throw sseError(res.status, text);
+  }
+  if (!ct.includes("text/event-stream")) {
+    const text = await res.text().catch(() => "");
+    throw sseError(res.status, text || `Expected text/event-stream, got ${ct || "none"}`);
+  }
+  onOpen?.();
+  const reader = res.body.getReader();
+  const dec = new TextDecoder();
+  let buf = "";
+  try {
+    for (;;) {
+      if (signal.aborted) return;
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += dec.decode(value, { stream: true });
+      let sep = buf.indexOf("\n\n");
+      while (sep >= 0) {
+        const raw = buf.slice(0, sep);
+        buf = buf.slice(sep + 2);
+        const stop = dispatchFrame(raw, onEvent, signal);
+        if (stop || signal.aborted) return;
+        sep = buf.indexOf("\n\n");
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function dispatchFrame(
+  raw: string,
+  onEvent: (event: unknown, id: string | undefined) => void,
+  signal: AbortSignal,
+): boolean {
+  const dataLines: string[] = [];
+  let id: string | undefined;
+  for (const line of raw.split("\n")) {
+    if (line.startsWith("id:")) id = line.slice(3).replace(/^ /, "");
+    if (line.startsWith("data:")) dataLines.push(line.slice(5).replace(/^ /, ""));
+  }
+  if (dataLines.length === 0) return false;
+  const data = dataLines.join("\n");
+  if (data === "[DONE]") return true;
+  if (signal.aborted) return true;
+  onEvent(JSON.parse(data) as unknown, id);
+  return false;
+}
+
+function sseError(status: number, body: string): Error {
+  let message = `HTTP ${status}`;
+  if (body) {
+    try {
+      const json: unknown = JSON.parse(body);
+      if (json !== null && typeof json === "object" && "error" in json) {
+        const err = (json as { error?: { code?: string; data?: { message?: string } } }).error;
+        message = err?.data?.message ?? err?.code ?? message;
+      }
+    } catch {
+      message = body.slice(0, 200);
+    }
+  }
+  const e = new Error(message);
+  (e as Error & { status?: number }).status = status;
+  return e;
+}

package/src/client/notes-contract.test.ts

@@ -11,12 +11,14 @@ import { oke } from "../kernel/app.ts";
 import { flow, resetFlowSeq } from "../kernel/flow.ts";
 import { on, resetBindings } from "../kernel/on.ts";
 import { http } from "../kernel/triggers.ts";
+import { resetSignals, signal } from "../elements/signal/declare.ts";
 import { createClient } from "./create.ts";
 import type { Client } from "./types.ts";
 
 beforeEach(() => {
   resetBindings();
   resetFlowSeq();
+  resetSignals();
 });
 
 /** Compile-time equality. */
@@ -276,4 +278,43 @@ describe("Notes — typeof app carries contracts", () => {
     expect(method).toBe("POST");
     expect(url).toBe("http://app.test/_oke/notes/stats");
   });
+
+  test("typeof app live exposure is subscribe, not JSON RPC", () => {
+    const orderStatus = signal("order-status", {
+      delivery: "live",
+      optional: true,
+      schema: z.object({ orderId: z.string(), status: z.string() }),
+    });
+    const events = on(http.get("/orders/:orderId/events").live(orderStatus));
+    const app = oke({ name: "shop", autoBoot: false, registry: "ignore" }).adopt({
+      orders: { events },
+    });
+
+    type LiveFlag = typeof app.$routes.orders.events extends { readonly live: string }
+      ? true
+      : false;
+    type StreamFlag = typeof app.$routes.orders.events extends { readonly stream: true }
+      ? true
+      : false;
+    type _Live = Assert<Eq<LiveFlag, true>>;
+    type _Stream = Assert<Eq<StreamFlag, true>>;
+    const flags: [_Live, _Stream] = [true, true];
+    expect(flags).toEqual([true, true]);
+    expect(app.$routes.orders.events.live).toBe("order-status");
+    expect(app.$routes.orders.events.stream).toBe(true);
+
+    const api = createClient(app, "http://app.test", {
+      fetch: async () =>
+        new Response("data: [DONE]\n\n", {
+          status: 200,
+          headers: { "content-type": "text/event-stream" },
+        }),
+    });
+    const stop = api.orders.events({ orderId: "ord_1" }, { onEvent: () => undefined });
+    type _Unsub = Assert<Eq<typeof stop, () => void>>;
+    const unsub: _Unsub = true;
+    expect(unsub).toBe(true);
+    expect(typeof stop).toBe("function");
+    stop();
+  });
 });

package/src/client/types.ts

@@ -27,6 +27,14 @@ export interface FlowContract<
   readonly method?: string;
   /** Optional HTTP path template (`/notes/:id`). */
   readonly path?: string;
+  /** Live signal name when this flow is an SSE exposure. */
+  readonly live?: string;
+  /** Auto-match path-param names (empty = firehose). */
+  readonly matchKey?: readonly string[];
+  /** Flattened gate names on the HTTP trigger. */
+  readonly gates?: readonly string[];
+  /** True when this flow returns `text/event-stream`. */
+  readonly stream?: true;
 }
 
 /**
@@ -248,6 +256,75 @@ type ClientCallFn<I, O, E extends Record<string, unknown>> = [I] extends [void]
  */
 export type ClientCall<I, O, E extends Record<string, unknown>> = ClientCallFn<I, O, E>;
 
+/** Unsubscribe a live SSE subscription. */
+export type LiveUnsubscribe = () => void;
+
+/**
+ * Callbacks for {@link ClientLive} / live-exposing flow calls.
+ *
+ * @typeParam T - Signal payload
+ */
+export interface LiveHandlers<T> {
+  readonly onEvent: (event: T) => void;
+  readonly onError?: (error: unknown) => void;
+  /** Fired after a successful SSE open (HTTP 200), including reconnects. */
+  readonly onOpen?: () => void;
+  /**
+   * Re-open the SSE request after a drop. Default false.
+   * Reconnects send `Last-Event-ID` when a cursor was received.
+   * A 410 LiveResumeGap clears the cursor and replays the remaining tape.
+   * Backoff starts at 500ms and doubles to 30s so a closed stream cannot
+   * tight-loop reconnects.
+   */
+  readonly autoResubscribe?: boolean;
+  /** Disambiguate when two exposures share a match shape. `unit.flow`. */
+  readonly via?: string;
+  readonly signal?: AbortSignal;
+}
+
+/** Named live signal handle (`signal()`). */
+export type LiveSignalHandle<T = unknown> = {
+  readonly name: string;
+  readonly _payload?: T;
+};
+
+/** Filter fields for a live subscribe (path params / payload keys). */
+export type LiveInput<T> = T extends object
+  ? Partial<T> & Record<string, unknown>
+  : Record<string, unknown>;
+
+/**
+ * Root `api.live(signal, …)` — callback subscribe, not `for await`.
+ *
+ * @typeParam App - App brand (reserved; runtime uses `$routes`)
+ */
+export type ClientLive<App = never> = [App] extends [never]
+  ? ClientLiveOverloads
+  : ClientLiveOverloads;
+
+type ClientLiveOverloads = {
+  <T>(signal: LiveSignalHandle<T>, input: LiveInput<T>, handlers: LiveHandlers<T>): LiveUnsubscribe;
+  <T>(signal: LiveSignalHandle<T>, handlers: LiveHandlers<T>): LiveUnsubscribe;
+  <T>(name: string, input: unknown, handlers: LiveHandlers<T>): LiveUnsubscribe;
+  <T>(name: string, handlers: LiveHandlers<T>): LiveUnsubscribe;
+};
+
+type IsLiveContract<C> = C extends { readonly live: string } ? true : false;
+
+type ClientLiveFlowCall<I, O> = [I] extends [void]
+  ? (handlers: LiveHandlers<O>) => LiveUnsubscribe
+  : Partial<I> extends I
+    ? {
+        (handlers: LiveHandlers<O>): LiveUnsubscribe;
+        (input?: I, handlers?: LiveHandlers<O>): LiveUnsubscribe;
+      }
+    : (input: I, handlers: LiveHandlers<O>) => LiveUnsubscribe;
+
+type ClientCallFor<C> =
+  IsLiveContract<C> extends true
+    ? ClientLiveFlowCall<ContractIn<C>, ContractOut<C>>
+    : ClientCall<ContractIn<C>, ContractOut<C>, ContractErrors<C>>;
+
 /**
  * Pull input from a contract shape (supports required or phantom-optional `in`).
  */
@@ -274,20 +351,22 @@ type ContractErrors<C> = "errors" extends keyof C
  */
 export type ClientFromRoutes<R extends ClientRouteMap> = {
   readonly [U in keyof R]: {
-    readonly [F in keyof R[U]]: ClientCall<
-      ContractIn<R[U][F]>,
-      ContractOut<R[U][F]>,
-      ContractErrors<R[U][F]>
-    >;
+    readonly [F in keyof R[U]]: ClientCallFor<R[U][F]>;
   };
 };
 
 /**
  * Fully typed client for an App.
  *
+ * `live` is always on the instance. Pass `typeof app` / `$routes` so unit
+ * bags exist on the type — an empty-`$routes` client cannot be asserted onto
+ * `{ console: … }` (TS2352).
+ *
  * @typeParam App - App or route map
  */
-export type Client<App = never> = ClientFromRoutes<RoutesOf<ResolveApp<App>>>;
+export type Client<App = never> = ClientFromRoutes<RoutesOf<ResolveApp<App>>> & {
+  readonly live: ClientLive<ResolveApp<App>>;
+};
 
 /**
  * Convenience: brand a route map as an App (`export type App = AppOf<…>`).

package/src/client-react/index.ts

@@ -1,11 +1,12 @@
 /**
- * React helpers for okengine clients — `useSession` over {@link createClient}.
+ * React helpers for okengine clients — `useSession` / `useLive` over {@link createClient}.
  *
  * @module
  */
 
 import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
 import type { MemorySession } from "../client/auth.ts";
+import type { ClientLive, LiveInput, LiveSignalHandle } from "../client/types.ts";
 
 /** Minimal client surface for session reading. */
 export interface SessionClient {
@@ -91,3 +92,86 @@ export function useSession(api: SessionClient, session?: MemorySession): Session
     signOut,
   };
 }
+
+/** Options for {@link useLive}. */
+export interface UseLiveOptions {
+  readonly autoResubscribe?: boolean;
+  readonly via?: string;
+}
+
+/** Hook state from {@link useLive}. */
+export interface LiveState<T> {
+  readonly events: T[];
+  readonly latest: T | null;
+  readonly error: unknown;
+  readonly isConnected: boolean;
+}
+
+/** Client surface that exposes `api.live`. */
+export interface LiveClient {
+  readonly live: ClientLive;
+}
+
+/**
+ * Subscribe to a `delivery: "live"` signal for the component lifetime.
+ *
+ * Cleanup calls `stop()`. Changing `signal` / `input` / `via` resets `events`.
+ *
+ * @param api - Typed client from `createClient`
+ * @param signal - Signal handle or name
+ * @param input - Path / match fields
+ * @param options - Resubscribe and `via`
+ */
+export function useLive<T>(
+  api: LiveClient,
+  signal: LiveSignalHandle<T> | string,
+  input?: LiveInput<T>,
+  options?: UseLiveOptions,
+): LiveState<T> {
+  const signalName = typeof signal === "string" ? signal : signal.name;
+  const inputKey = JSON.stringify(input ?? null);
+  const autoResubscribe = options?.autoResubscribe;
+  const via = options?.via;
+
+  const [events, setEvents] = useState<T[]>([]);
+  const [latest, setLatest] = useState<T | null>(null);
+  const [error, setError] = useState<unknown>(undefined);
+  const [isConnected, setConnected] = useState(false);
+
+  useEffect(() => {
+    setEvents([]);
+    setLatest(null);
+    setError(undefined);
+    setConnected(false);
+    let stopped = false;
+    const handlers = {
+      autoResubscribe,
+      ...(via !== undefined ? { via } : {}),
+      onOpen: () => {
+        if (!stopped) setConnected(true);
+      },
+      onEvent: (event: T) => {
+        if (stopped) return;
+        setConnected(true);
+        setEvents((prev) => [...prev, event]);
+        setLatest(event);
+      },
+      onError: (err: unknown) => {
+        if (stopped) return;
+        setError(err);
+        setConnected(false);
+      },
+    };
+    const parsedInput = inputKey === "null" ? undefined : (JSON.parse(inputKey) as LiveInput<T>);
+    const stop =
+      parsedInput === undefined
+        ? api.live(signalName, handlers)
+        : api.live(signalName, parsedInput, handlers);
+    return () => {
+      stopped = true;
+      stop();
+    };
+  }, [api, signalName, inputKey, autoResubscribe, via]);
+
+  return { events, latest, error, isConnected };
+}