@mostra/react 0.0.0-stage → 0.1.0

package/src/runtime/transport.ts

@@ -0,0 +1,342 @@
+/**
+ * How the client runtime reaches Mostra (INTERFACES §4): the browser protocol over the artifact's
+ * own origin, with its session cookie and CSRF token. A delivery target without a gateway (a
+ * static export, an MCP App before its transport, D111) gets another implementation of the same
+ * interface, so hooks never know which they talk to.
+ */
+import {
+  BROWSER_PROTOCOL_REVISION,
+  type CallLine,
+  type CallRequest,
+  type EphemeralMessage,
+  type EventRecord,
+  type FieldsRequest,
+  type LiveRequest,
+  type LiveState,
+  type LiveUpdate,
+  type MutationResult,
+  type PollResult,
+  type RunAttachRequest,
+  type RunDelta,
+  type RunRequest,
+  type RunState,
+  type SignalRequest,
+  type StreamSnapshot,
+  type SubmissionSummary,
+  type SubmitRequest,
+} from "@mostra/protocol";
+import { type DiagnosticLike, MostraError } from "./errors.ts";
+
+/** The connection to the gateway failed before it answered: the page is offline. */
+export class NetworkError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "NetworkError";
+  }
+}
+
+/** What a subscription hears. */
+export interface StreamHandlers {
+  /** Where the page stands, first, and again after a compacted cursor. */
+  onSnapshot(snapshot: StreamSnapshot): void;
+  /** Durable events after the last cursor, in order. */
+  onEvents(events: readonly EventRecord[]): void;
+  /** The stream's health: `live` while connected, `offline` while it retries, `revoked` at the end. */
+  onStatus(status: "live" | "offline" | "revoked"): void;
+  /** Run and live updates (WP-08): lossy, never events, so a page reads again what it missed. */
+  onEphemeral?(message: EphemeralMessage): void;
+}
+
+/** The client runtime's way to Mostra. */
+export interface Transport {
+  /** Where the page stands: its viewer, draft, the artifact state and their cursor. */
+  snapshot(): Promise<StreamSnapshot>;
+  /** One mutation (`fields`); `keepalive` lets it outlive the page (`pagehide`). */
+  mutate(
+    request: FieldsRequest,
+    options?: { readonly keepalive?: boolean },
+  ): Promise<MutationResult>;
+  /** A submit through the artifact channel. */
+  submit(request: SubmitRequest): Promise<SubmissionSummary>;
+  /** A signal. */
+  signal(request: SignalRequest): Promise<{ readonly cursor: string }>;
+  /** Hears the page's events after `cursor`; returns the function that stops. */
+  subscribe(cursor: string | undefined, handlers: StreamHandlers): () => void;
+  /** A plain server-function call (D54): its result's lines as they come. */
+  call?(fnId: string, request: CallRequest, signal?: AbortSignal): AsyncIterable<CallLine>;
+  /** Starts or joins an action run (AC-02, AC-03). */
+  startRun?(request: RunRequest): Promise<RunState>;
+  /** Reads runs and follows them for a minute. */
+  attachRuns?(request: RunAttachRequest): Promise<{ readonly runs: readonly RunState[] }>;
+  /** Cancels a run (AC-04). */
+  cancelRun?(runId: string, viewId: string): Promise<RunState>;
+  /** Reads live sources and keeps them produced for a minute (D56). */
+  live?(request: LiveRequest): Promise<{ readonly sources: readonly LiveState[] }>;
+}
+
+/** The longest body `fetch` sends with `keepalive` (the Fetch standard's 64 KiB budget). */
+export const KEEPALIVE_BODY_MAX: number = 64 * 1024 - 1024;
+
+/** After this many stream failures in a row, the client long-polls instead (FAILURE_MODEL §8). */
+const STREAM_FAILURES_BEFORE_POLL = 2;
+
+/**
+ * The browser protocol over HTTP, on the artifact's origin. The CSRF token comes from
+ * `/_mostra/session`, once; a refusal is a {@link MostraError} with the gateway's diagnostic, and
+ * an unreachable gateway a {@link NetworkError}.
+ */
+export class HttpTransport implements Transport {
+  readonly #viewId: string;
+  readonly #base: string;
+  #csrf: Promise<string> | undefined;
+
+  /**
+   * `csrf` is the session's token when the caller already read it (the bridge does): a save made
+   * as the page closes must not wait for a request the closing page would cancel (IN-02).
+   */
+  constructor(viewId: string, options: { readonly csrf?: string; readonly base?: string } = {}) {
+    this.#viewId = viewId;
+    this.#base = options.base ?? `/_mostra/v/${BROWSER_PROTOCOL_REVISION}`;
+    if (options.csrf) this.#csrf = Promise.resolve(options.csrf);
+  }
+
+  #token(): Promise<string> {
+    this.#csrf ??= (async () => {
+      const session = (await this.#request("/_mostra/session", { method: "GET" })) as {
+        csrf: string;
+      };
+      return session.csrf;
+    })().catch((error: unknown) => {
+      this.#csrf = undefined;
+      throw error;
+    });
+    return this.#csrf;
+  }
+
+  async #request(path: string, init: RequestInit): Promise<unknown> {
+    let response: Response;
+    try {
+      response = await fetch(path, { credentials: "same-origin", cache: "no-store", ...init });
+    } catch (error) {
+      throw new NetworkError((error as Error).message);
+    }
+    let body: unknown;
+    try {
+      body = await response.json();
+    } catch {
+      body = undefined;
+    }
+    if (!response.ok) {
+      const diagnostic = (body ?? {}) as Partial<DiagnosticLike> & Record<string, unknown>;
+      // A proxy or a restarting gateway answers without a diagnostic: that is a network failure.
+      if (typeof diagnostic.code !== "string") {
+        throw new NetworkError(`The gateway answered ${response.status}.`);
+      }
+      throw new MostraError(diagnostic.code, diagnostic.message ?? diagnostic.code, {
+        status: response.status,
+        diagnostic: diagnostic as DiagnosticLike,
+        body: diagnostic,
+      });
+    }
+    return body;
+  }
+
+  async #post(path: string, body: unknown, keepalive = false): Promise<unknown> {
+    const text = JSON.stringify(body);
+    const csrf = await this.#token();
+    return this.#request(`${this.#base}${path}`, {
+      method: "POST",
+      headers: { "content-type": "application/json", "x-mostra-csrf": csrf },
+      body: text,
+      keepalive: keepalive && text.length < KEEPALIVE_BODY_MAX,
+    });
+  }
+
+  async snapshot(): Promise<StreamSnapshot> {
+    const result = (await this.#request(`${this.#base}/events/poll?view=${this.#viewId}&wait=0`, {
+      method: "GET",
+    })) as PollResult;
+    if (!result.snapshot) throw new NetworkError("The gateway sent no snapshot.");
+    return result.snapshot;
+  }
+
+  mutate(
+    request: FieldsRequest,
+    options?: { readonly keepalive?: boolean },
+  ): Promise<MutationResult> {
+    return this.#post("/fields", request, options?.keepalive === true) as Promise<MutationResult>;
+  }
+
+  submit(request: SubmitRequest): Promise<SubmissionSummary> {
+    return this.#post("/submit", request) as Promise<SubmissionSummary>;
+  }
+
+  signal(request: SignalRequest): Promise<{ readonly cursor: string }> {
+    return this.#post("/signal", request) as Promise<{ cursor: string }>;
+  }
+
+  async *call(fnId: string, request: CallRequest, signal?: AbortSignal): AsyncIterable<CallLine> {
+    const csrf = await this.#token();
+    let response: Response;
+    try {
+      response = await fetch(`${this.#base}/call/${encodeURIComponent(fnId)}`, {
+        method: "POST",
+        credentials: "same-origin",
+        cache: "no-store",
+        headers: { "content-type": "application/json", "x-mostra-csrf": csrf },
+        body: JSON.stringify(request),
+        ...(signal ? { signal } : {}),
+      });
+    } catch (error) {
+      throw new NetworkError((error as Error).message);
+    }
+    if (!response.ok || !response.body) {
+      let body: unknown;
+      try {
+        body = await response.json();
+      } catch {
+        body = undefined;
+      }
+      const diagnostic = (body ?? {}) as Partial<DiagnosticLike>;
+      if (typeof diagnostic.code !== "string") {
+        throw new NetworkError(`The gateway answered ${response.status}.`);
+      }
+      throw new MostraError(diagnostic.code, diagnostic.message ?? diagnostic.code, {
+        status: response.status,
+        diagnostic: diagnostic as DiagnosticLike,
+      });
+    }
+    // NDJSON: one line per batch, then the end.
+    const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+    let buffer = "";
+    try {
+      for (;;) {
+        let chunk: ReadableStreamReadResult<string>;
+        try {
+          chunk = await reader.read();
+        } catch (error) {
+          throw new NetworkError((error as Error).message);
+        }
+        if (chunk.done) break;
+        buffer += chunk.value;
+        let newline = buffer.indexOf("\n");
+        while (newline !== -1) {
+          const line = buffer.slice(0, newline);
+          buffer = buffer.slice(newline + 1);
+          if (line.trim() !== "") yield JSON.parse(line) as CallLine;
+          newline = buffer.indexOf("\n");
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    if (buffer.trim() !== "") yield JSON.parse(buffer) as CallLine;
+  }
+
+  startRun(request: RunRequest): Promise<RunState> {
+    return this.#post("/runs", request) as Promise<RunState>;
+  }
+
+  attachRuns(request: RunAttachRequest): Promise<{ readonly runs: readonly RunState[] }> {
+    return this.#post("/runs/attach", request) as Promise<{ runs: RunState[] }>;
+  }
+
+  cancelRun(runId: string, viewId: string): Promise<RunState> {
+    return this.#post(`/runs/${encodeURIComponent(runId)}/cancel`, { viewId }) as Promise<RunState>;
+  }
+
+  live(request: LiveRequest): Promise<{ readonly sources: readonly LiveState[] }> {
+    return this.#post("/live", request) as Promise<{ sources: LiveState[] }>;
+  }
+
+  subscribe(cursor: string | undefined, handlers: StreamHandlers): () => void {
+    let closed = false;
+    let last = cursor;
+    let source: EventSource | undefined;
+    let failures = 0;
+    let polling = false;
+    let retry: ReturnType<typeof setTimeout> | undefined;
+    const query = (): string =>
+      `view=${this.#viewId}${last === undefined ? "" : `&cursor=${last}`}`;
+
+    const poll = async (): Promise<void> => {
+      polling = true;
+      let backoff = 1_000;
+      while (!closed) {
+        try {
+          const result = (await this.#request(`${this.#base}/events/poll?${query()}&wait=25`, {
+            method: "GET",
+          })) as PollResult;
+          backoff = 1_000;
+          handlers.onStatus("live");
+          if (result.snapshot) handlers.onSnapshot(result.snapshot);
+          if (result.events.length > 0) handlers.onEvents(result.events);
+          for (const message of result.ephemeral ?? []) handlers.onEphemeral?.(message);
+          last = result.cursor;
+        } catch (error) {
+          if (error instanceof MostraError && error.code === "MOSTRA_HYGIENE_TOKEN_REVOKED") {
+            handlers.onStatus("revoked");
+            return;
+          }
+          handlers.onStatus("offline");
+          await new Promise((resolve) => {
+            retry = setTimeout(resolve, backoff);
+          });
+          backoff = Math.min(backoff * 2, 30_000);
+        }
+      }
+    };
+
+    const open = (): void => {
+      if (closed) return;
+      if (typeof EventSource === "undefined") {
+        void poll();
+        return;
+      }
+      source = new EventSource(`${this.#base}/events?${query()}`);
+      source.addEventListener("open", () => {
+        failures = 0;
+        handlers.onStatus("live");
+      });
+      source.addEventListener("snapshot", (event) => {
+        failures = 0;
+        const snapshot = JSON.parse((event as MessageEvent<string>).data) as StreamSnapshot;
+        last = snapshot.cursor;
+        handlers.onSnapshot(snapshot);
+      });
+      source.addEventListener("mostra", (event) => {
+        failures = 0;
+        const record = JSON.parse((event as MessageEvent<string>).data) as EventRecord;
+        last = record.cursor;
+        handlers.onEvents([record]);
+      });
+      // Run and live updates carry no `id`, so they never move the stream's cursor.
+      source.addEventListener("run", (event) => {
+        const run = JSON.parse((event as MessageEvent<string>).data) as RunDelta;
+        handlers.onEphemeral?.({ kind: "run", run });
+      });
+      source.addEventListener("live", (event) => {
+        const live = JSON.parse((event as MessageEvent<string>).data) as LiveUpdate;
+        handlers.onEphemeral?.({ kind: "live", live });
+      });
+      source.addEventListener("error", () => {
+        if (closed) return;
+        failures += 1;
+        handlers.onStatus("offline");
+        // A refused stream (revoked link, gateway gone) is CLOSED; a dropped one reconnects by
+        // itself. Either way, after two failures in a row the page long-polls on the same cursor.
+        if (source?.readyState === EventSource.CLOSED || failures >= STREAM_FAILURES_BEFORE_POLL) {
+          source?.close();
+          source = undefined;
+          if (!polling) void poll();
+        }
+      });
+    };
+    open();
+    return () => {
+      closed = true;
+      source?.close();
+      if (retry !== undefined) clearTimeout(retry);
+    };
+  }
+}

package/src/runtime/verify-probe.ts

@@ -0,0 +1,67 @@
+"use client";
+
+/**
+ * `verify`'s field probe (D138 item 3): in the `verify` target only, the page keeps a record of
+ * every field it mounts (the hook, the scope and the type of the initial value) and how much
+ * server work it waits on, and publishes both on `globalThis[VERIFY_PROBE]`, where the verify
+ * runner reads them. Viewers' pages never install it.
+ */
+import { type ProbedField, VERIFY_PROBE } from "@mostra/protocol";
+import type { Registration, Store } from "./store.ts";
+
+/** `typeof`, with arrays and `null` named as such. */
+function typeName(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
+interface Entry {
+  readonly first: { readonly hook: string; readonly scope: string; readonly initialType: string };
+  mounts: number;
+  readonly conflicts: Set<string>;
+}
+
+/** Records the store's field mounts on `globalThis[VERIFY_PROBE]`. */
+export function installVerifyProbe(store: Store): void {
+  const entries = new Map<string, Entry>();
+  store.observeMounts((registration: Registration, mounted: boolean) => {
+    const shape = {
+      hook: registration.hook ?? "useField",
+      scope: registration.scope,
+      initialType: typeName(registration.initial),
+    };
+    let entry = entries.get(registration.id);
+    if (!entry) {
+      entry = { first: shape, mounts: 0, conflicts: new Set() };
+      entries.set(registration.id, entry);
+    }
+    if (mounted) {
+      entry.mounts += 1;
+      if (shape.hook !== entry.first.hook)
+        entry.conflicts.add(`${entry.first.hook} and ${shape.hook}`);
+      if (shape.scope !== entry.first.scope)
+        entry.conflicts.add(`scopes ${entry.first.scope} and ${shape.scope}`);
+      if (shape.initialType !== entry.first.initialType)
+        entry.conflicts.add(
+          `initial values of types ${entry.first.initialType} and ${shape.initialType}`,
+        );
+    } else entry.mounts = Math.max(0, entry.mounts - 1);
+  });
+  const fields = (): ProbedField[] =>
+    [...entries].map(([id, entry]) => ({
+      id,
+      scope: entry.first.scope as ProbedField["scope"],
+      hook: entry.first.hook,
+      initialType: entry.first.initialType,
+      mounts: entry.mounts,
+      conflicts: [...entry.conflicts],
+    }));
+  // `pending`: the server work the page waits on (calls, runs, first live values), which the
+  // runner's quiescence wait includes (Opus review finding 1).
+  const pending = (): number => store.server.pending();
+  Object.defineProperty(globalThis, VERIFY_PROBE, {
+    value: { fields, pending },
+    configurable: true,
+  });
+}