statewire 0.0.1 → 0.0.3

package/src/transports/sse.ts

@@ -1,3 +1,4 @@
+import { useRef, useState } from "react";
 import { flushTapSync, resource } from "@assistant-ui/tap";
 import type { ResourceElement } from "@assistant-ui/tap";
 import { encodeParams, reviveResponse } from "../wire/meta";
@@ -5,24 +6,22 @@ import { createSseParser } from "./sse-parser";
 import { timing } from "../client/timing";
 import {
   classify,
-  createGate,
   handleEnvelope,
   overloadedError,
   parseRetryAfter,
-  reconnectConn,
+  useStatewireConn,
 } from "../client/connection";
 import type {
-  ConnBase,
+  Conn,
   StatewireEnvelope,
-  StatewireFinish,
   StatewireResponse,
 } from "../client/connection";
-import type { StatewireTransport } from "../types";
+import type { Statewire } from "../types";
+import type { StatewireClient } from "../statewire";
+import type { StatewireHost } from "../host";
 import { useStatewireRemote } from "./remote";
-import type { StatewireSessionStore } from "../client/sessionStore";
-import type { StatewireCommands } from "../types";
 
-export type StatewireTransportProps = {
+export type StatewireRemoteProps = {
   clientId: string;
   onSnapshot: (args: { ops: unknown[]; lastSeq: number }) => void;
   onOps: (args: {
@@ -30,17 +29,31 @@ export type StatewireTransportProps = {
     res?: StatewireResponse[];
     ack?: number;
   }) => void;
-  onFinish: (args: StatewireFinish) => void;
+  onFinish: (args: StatewireHost.Fin) => void;
 };
 
-export type StatewireWireCommand = {
-  method: string;
-  params: readonly unknown[];
-};
+export type StatewireWireCommand =
+  | { method: string; params: readonly unknown[]; context?: never }
+  | { method?: never; params?: never; context: Record<string, unknown> };
+
+/** The wire shape of a client context submission: one root replace op. */
+export const contextOps = (value: Record<string, unknown>) => [
+  { op: "replace", path: [], value },
+];
+
+export const encodeWireCommand = (command: StatewireWireCommand) => ({
+  ...(command.method !== undefined && {
+    method: command.method,
+    ...encodeParams(command.params),
+  }),
+  ...(command.context !== undefined && {
+    context: contextOps(command.context),
+  }),
+});
 
 export type StatewireSubmitResult =
   | { type: "receipt"; response?: StatewireResponse }
-  | { type: "rejected"; message: string; payload?: unknown }
+  | { type: "rejected"; message: string }
   | { type: "seq-gap" }
   | { type: "unknown-client" }
   | { type: "stale-lease" };
@@ -50,7 +63,7 @@ export type ConnectionState =
   | { status: "live" }
   | {
       status: "reconnecting";
-      cause: "dropped" | "ended" | "error";
+      cause: "dropped" | "evicted" | "error";
       attempt: number;
       nextRetryAt: number;
       lastError?: string;
@@ -58,61 +71,23 @@ export type ConnectionState =
     }
   | { status: "gone"; message?: string; payload?: unknown };
 
-export type StatewireConnection = ConnectionState & { reconnect: () => void };
-
 /** The live wire a remote session drives: connection status plus command POST. */
 export type RemoteLink = {
-  connection: StatewireConnection;
+  connection: StatewireClient.Connection;
   send: (args: {
     seq: number;
     command: StatewireWireCommand;
   }) => Promise<StatewireSubmitResult>;
 };
 
-export type StatewireSSEOptions = {
-  url: string;
-  headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
-  fetch?: typeof globalThis.fetch;
-  onChange?: (connection: StatewireConnection) => void;
-  sessionStore?: StatewireSessionStore;
-};
-
-type Latest = {
-  options: StatewireSSEOptions;
-  ctx: StatewireTransportProps;
-};
+const baseUrl = (options: StatewireClient.SSEOptions) =>
+  options.url.replace(/\/$/, "");
 
-type Conn = ConnBase & {
-  latest: { readonly current: Latest };
-  send: RemoteLink["send"];
-};
-
-const createConn = (
-  latest: { readonly current: Latest },
-  notify: (connection: StatewireConnection) => void,
-): Conn => {
-  const c: Conn = {
-    hasSnapshot: false,
-    lease: null,
-    attempt: 0,
-    episode: null,
-    abort: null,
-    gate: createGate(),
-    lifetime: null,
-    latest,
-    notify,
-    reconnect: () => reconnectConn(c),
-    attemptOnce: (abort) => attemptStream(c, abort),
-    send: (args) => sendCommand(c, args),
-    connection: { status: "connecting", reconnect: () => c.reconnect() },
-  };
-  return c;
-};
-
-const baseUrl = (c: Conn) => c.latest.current.options.url.replace(/\/$/, "");
-
-const requestHeaders = async (c: Conn, extra: Record<string, string>) => {
-  const { headers } = c.latest.current.options;
+const requestHeaders = async (
+  options: StatewireClient.SSEOptions,
+  extra: Record<string, string>,
+) => {
+  const { headers } = options;
   const merged = new Headers(
     typeof headers === "function" ? await headers() : headers,
   );
@@ -121,16 +96,13 @@ const requestHeaders = async (c: Conn, extra: Record<string, string>) => {
 };
 
 const timedFetch = async (
-  c: Conn,
+  options: StatewireClient.SSEOptions,
   input: string,
   init: RequestInit & { signal: AbortSignal },
   timeout: AbortSignal,
 ): Promise<Response> => {
   try {
-    return await (c.latest.current.options.fetch ?? globalThis.fetch)(
-      input,
-      init,
-    );
+    return await (options.fetch ?? globalThis.fetch)(input, init);
   } catch {
     throw classify(timeout);
   }
@@ -144,7 +116,6 @@ const consume = async (
 ): Promise<"stop" | "reattach" | "ended"> => {
   const decoder = new TextDecoder();
   const parse = createSseParser();
-  let attached = false;
   for (;;) {
     const timer = setTimeout(
       () => heartbeat.abort(),
@@ -162,8 +133,7 @@ const consume = async (
     for (const data of parse(decoder.decode(result.value, { stream: true }))) {
       if (dead()) return "ended";
       const env = JSON.parse(data) as StatewireEnvelope;
-      const done = flushTapSync(() => handleEnvelope(c, env, attached));
-      attached = true;
+      const done = flushTapSync(() => handleEnvelope(c, env));
       if (done) return done;
     }
   }
@@ -171,10 +141,11 @@ const consume = async (
 
 const attemptStream = async (
   c: Conn,
+  options: StatewireClient.SSEOptions,
   abort: AbortController,
 ): Promise<"stop" | "reattach" | "ended"> => {
-  const headers = await requestHeaders(c, {
-    "Statewire-Client-Id": c.latest.current.ctx.clientId,
+  const headers = await requestHeaders(options, {
+    "Statewire-Client-Id": c.ctx.clientId,
     accept: "text/event-stream",
   });
   const heartbeat = new AbortController();
@@ -185,8 +156,8 @@ const attemptStream = async (
   let res: Response;
   try {
     res = await timedFetch(
-      c,
-      `${baseUrl(c)}/stream`,
+      options,
+      `${baseUrl(options)}/stream`,
       {
         headers,
         cache: "no-store",
@@ -212,24 +183,22 @@ const overloaded = (res: Response) =>
 
 const sendCommand = async (
   c: Conn,
+  options: StatewireClient.SSEOptions,
   { seq, command }: { seq: number; command: StatewireWireCommand },
 ): Promise<StatewireSubmitResult> => {
   const timeout = AbortSignal.timeout(timing.heartbeatTimeoutMs);
   const res = await timedFetch(
-    c,
-    `${baseUrl(c)}/commands`,
+    options,
+    `${baseUrl(options)}/commands`,
     {
       method: "POST",
-      headers: await requestHeaders(c, {
+      headers: await requestHeaders(options, {
         "content-type": "application/json",
-        "Statewire-Client-Id": c.latest.current.ctx.clientId,
+        "Statewire-Client-Id": c.ctx.clientId,
         "Statewire-Command-Seq": String(seq),
         ...(c.lease !== null && { "Statewire-Lease": c.lease }),
       }),
-      body: JSON.stringify({
-        method: command.method,
-        ...encodeParams(command.params),
-      }),
+      body: JSON.stringify(encodeWireCommand(command)),
       signal: AbortSignal.any([
         c.lifetime?.signal ?? AbortSignal.abort(),
         timeout,
@@ -238,9 +207,15 @@ const sendCommand = async (
     timeout,
   );
   if (res.ok) {
-    const body = (await res.json().catch(() => null)) as {
-      res?: StatewireResponse;
-    } | null;
+    let body: { res?: StatewireResponse } | null;
+    try {
+      body = (await res.json()) as { res?: StatewireResponse } | null;
+    } catch {
+      return {
+        type: "rejected",
+        message: "statewire: protocol error: malformed /commands receipt body",
+      };
+    }
     return body?.res !== undefined
       ? { type: "receipt", response: reviveResponse(body.res) }
       : { type: "receipt" };
@@ -267,14 +242,37 @@ const sendCommand = async (
   throw new Error(`HTTP ${res.status}`);
 };
 
+const useSseLink = (
+  options: StatewireClient.SSEOptions,
+  ctx: StatewireRemoteProps,
+): RemoteLink => {
+  const latest = useRef(options);
+  latest.current = options;
+  const c = useStatewireConn({
+    url: options.url,
+    onChange: options.onChange,
+    ctx,
+    attemptOnce: (c, abort) => attemptStream(c, options, abort),
+  });
+  const [link] = useState(
+    (): RemoteLink => ({
+      get connection() {
+        return c.connection;
+      },
+      send: (args) => sendCommand(c, latest.current, args),
+    }),
+  );
+  return link;
+};
+
 const useStatewireSSE = (
-  options: StatewireSSEOptions,
-): StatewireTransport<any, any, any> => useStatewireRemote(options, createConn);
+  options: StatewireClient.SSEOptions,
+): Statewire<any, any, any> => useStatewireRemote(options, useSseLink);
 
 export const StatewireSSE = resource(useStatewireSSE) as <
   TState = any,
-  TCommands extends StatewireCommands = StatewireCommands,
+  TCommands extends Statewire.Commands = Statewire.Commands,
   TEvent = any,
 >(
-  options: StatewireSSEOptions,
-) => ResourceElement<StatewireTransport<TState | undefined, TCommands, TEvent>>;
+  options: StatewireClient.SSEOptions,
+) => ResourceElement<Statewire<TState | undefined, TCommands, TEvent>>;

package/src/transports/testing.ts

@@ -1,8 +1,12 @@
 import type { ResourceElement } from "@assistant-ui/tap";
 import type { StatewireEnvelope } from "../client/connection";
-import { recordMutations } from "../client/optimistic";
+import { recordMutations } from "../util/recordMutations";
 import { StatewireSSE } from "./sse";
-import type { StatewireTransport } from "../types";
+import type { Statewire } from "../types";
+import { openSSEStream, sseFrame } from "./fake-sse";
+import type { FakeStreamHandle } from "./fake-sse";
+
+export * from "./fixtures";
 
 /** Let queued microtasks and op batches drain through the statewire client. */
 export const tick = () => new Promise<void>((r) => setTimeout(r, 0));
@@ -13,17 +17,11 @@ export const applyOptimistic = <TState>(
   mutate: (draft: TState) => void,
 ): TState => recordMutations(state, mutate).state;
 
-type StreamHandle = {
-  clientId: string;
-  send: (text: string) => void;
-  close: () => void;
-};
-
 export type MockTransport<TState> = {
   /** Pass as the `transport:` option of useStatewire / Harness. */
-  transport: ResourceElement<StatewireTransport<TState | undefined, any, any>>;
-  /** Captured `{ method, params }` command bodies, in POST order. */
-  commands: { method: string; params: unknown[] }[];
+  transport: ResourceElement<Statewire<TState | undefined, any, any>>;
+  /** Captured `/commands` POST bodies, in POST order. */
+  commands: { method?: string; params?: unknown[]; context?: unknown }[];
   /** Replace the replicated state and broadcast it as a root snapshot op. */
   setState: (state: TState) => Promise<void>;
   /** Deliver an ack watermark on the stream. */
@@ -50,60 +48,14 @@ export const createMockTransport = <TState>(
   let clientId = "";
   let finished = false;
   const clients = new Map<string, number>();
-  const streams = new Set<StreamHandle>();
-  const commands: { method: string; params: unknown[] }[] = [];
+  const streams = new Set<FakeStreamHandle>();
+  const commands: MockTransport<unknown>["commands"] = [];
 
   const sendEnvelope = (envelope: StatewireEnvelope) => {
-    for (const stream of streams) {
-      stream.send(`data: ${JSON.stringify(envelope)}\n\n`);
-    }
+    for (const stream of streams) stream.send(sseFrame(envelope));
     return tick();
   };
 
-  const handleStream = (id: string, signal: AbortSignal | undefined) => {
-    clientId = id;
-    const lastSeq = clients.get(id) ?? 0;
-    clients.set(id, lastSeq);
-    const encoder = new TextEncoder();
-    let handle: StreamHandle;
-    const body = new ReadableStream<Uint8Array>({
-      start: (controller) => {
-        let open = true;
-        handle = {
-          clientId: id,
-          send: (text) => {
-            if (open) controller.enqueue(encoder.encode(text));
-          },
-          close: () => {
-            if (!open) return;
-            open = false;
-            streams.delete(handle);
-            controller.close();
-          },
-        };
-        streams.add(handle);
-        handle.send(
-          `data: ${JSON.stringify({
-            ops: [{ op: "replace", path: [], value: state }],
-            syn: { lastSeq, lease: "mock-lease" },
-          })}\n\n`,
-        );
-      },
-      cancel: () => {
-        streams.delete(handle);
-      },
-    });
-    signal?.addEventListener("abort", () => {
-      for (const stream of [...streams]) {
-        if (stream.clientId === id) stream.close();
-      }
-    });
-    return new Response(body, {
-      status: 200,
-      headers: { "content-type": "text/event-stream" },
-    });
-  };
-
   const fakeFetch = (async (
     input: RequestInfo | URL,
     init?: RequestInit,
@@ -112,13 +64,31 @@ export const createMockTransport = <TState>(
     const url = String(input);
     const headers = new Headers(init?.headers);
     const id = headers.get("Statewire-Client-Id") ?? "";
-    if (url.endsWith("/stream"))
-      return handleStream(id, init?.signal ?? undefined);
+    if (url.endsWith("/stream")) {
+      clientId = id;
+      const lastSeq = clients.get(id) ?? 0;
+      clients.set(id, lastSeq);
+      return openSSEStream(
+        streams,
+        id,
+        (handle) => {
+          handle.send(
+            sseFrame({
+              ops: [{ op: "replace", path: [], value: state }],
+              syn: { lastSeq, lease: "mock-lease" },
+            }),
+          );
+        },
+        init?.signal ?? undefined,
+      );
+    }
     if (url.endsWith("/commands")) {
       const seq = Number(headers.get("Statewire-Command-Seq"));
       clients.set(id, Math.max(clients.get(id) ?? 0, seq));
       commands.push(
-        JSON.parse(String(init?.body)) as { method: string; params: unknown[] },
+        JSON.parse(
+          String(init?.body),
+        ) as MockTransport<unknown>["commands"][number],
       );
       return Response.json({});
     }