statewire 0.0.0-0 → 0.0.1

package/src/server.ts

@@ -0,0 +1,32 @@
+import type {
+  CommandExecution,
+  CommandExecutionResolvers,
+  StatewireHandledCommands,
+  StatewireStateCtl,
+} from "./host/host";
+import type {
+  StatewireCommands,
+  StatewireStateSource,
+  StatewireTransport,
+} from "./types";
+
+export { StatewireReject } from "./host/engine";
+export {
+  CommandExecution,
+  useStatewireState,
+  useStatewireCommands,
+  useStatewireEmit,
+} from "./host/host";
+export namespace StatewireServer {
+  export type StateCtl = StatewireStateCtl;
+  export type StateSource = StatewireStateSource;
+  export type Execution<T = void> = CommandExecution<T>;
+  export type ExecutionResolvers<T = void> = CommandExecutionResolvers<T>;
+  export type HandledCommands<THandlers extends StatewireCommands> =
+    StatewireHandledCommands<THandlers>;
+  export type Transport<
+    TState = any,
+    TCommands extends StatewireCommands = StatewireCommands,
+    TEvent = any,
+  > = StatewireTransport<TState, TCommands, TEvent>;
+}

package/src/statewire.ts

@@ -0,0 +1,107 @@
+import { useEffect, useRef, useState } from "react";
+import {
+  createTapRoot,
+  flushTapSync,
+  resource,
+  useResource,
+} from "@assistant-ui/tap";
+import type { ResourceElement } from "@assistant-ui/tap";
+import { createStatewireCore, LIVE_CONNECTION } from "./client/core";
+import type { StatewireTransport } from "./types";
+import type {
+  StatewireCommands,
+  StatewireCommandsProxy,
+  StatewireHelpers,
+  StatewireOptions,
+} from "./types";
+import type { StatewireConnection } from "./transports/sse";
+
+export const useStatewire = <
+  TState,
+  TCommands extends StatewireCommands = StatewireCommands,
+  TEvent = any,
+>(
+  options: StatewireOptions<TState, TCommands, TEvent>,
+): StatewireHelpers<TState, TCommands> => {
+  const latest = useRef(options);
+  latest.current = options;
+  const [, setVersion] = useState(0);
+  const [core] = useState(() => createStatewireCore(() => latest.current));
+
+  const value = useResource(options.transport) as StatewireTransport<unknown>;
+  core.attach(value);
+
+  useEffect(() => {
+    core.attach(value);
+  });
+  useEffect(() => {
+    const unsubscribe = core.subscribe(() =>
+      flushTapSync(() => setVersion((v) => v + 1)),
+    );
+    return () => {
+      unsubscribe();
+      core.detach();
+    };
+  }, [core]);
+
+  return {
+    state: core.getState() as TState,
+    connection: value.connection ?? LIVE_CONNECTION,
+    commands: core.commands as StatewireCommandsProxy<TCommands>,
+  };
+};
+
+export const StatewireResource = <
+  TState,
+  TCommands extends StatewireCommands = StatewireCommands,
+  TEvent = any,
+>(
+  options: StatewireOptions<TState, TCommands, TEvent>,
+): ResourceElement<StatewireHelpers<TState, TCommands>> =>
+  resource(useStatewire<TState, TCommands, TEvent>)(options);
+
+export class Statewire<
+  TState,
+  TCommands extends StatewireCommands = StatewireCommands,
+  TEvent = any,
+> {
+  private readonly core;
+  private readonly root;
+  private disposed = false;
+
+  constructor(options: StatewireOptions<TState, TCommands, TEvent>) {
+    this.core = createStatewireCore(() => options);
+    const core = this.core;
+    this.root = createTapRoot(() => {
+      const value = useResource(
+        options.transport,
+      ) as StatewireTransport<unknown>;
+      core.attach(value);
+      return value;
+    });
+    flushTapSync(() => {});
+  }
+
+  get state(): TState {
+    return this.core.getState() as TState;
+  }
+
+  get connection(): StatewireConnection {
+    return this.root.getValue().connection ?? LIVE_CONNECTION;
+  }
+
+  get commands(): StatewireCommandsProxy<TCommands> {
+    return this.core.commands as StatewireCommandsProxy<TCommands>;
+  }
+
+  subscribe(listener: () => void): () => void {
+    return this.core.subscribe(listener);
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.root.unmount();
+    this.core.dispose();
+  }
+}

package/src/transports/remote.ts

@@ -0,0 +1,72 @@
+import { useEffect, useState } from "react";
+import { useStatewireConn } from "../client/connection";
+import type { ConnBase } from "../client/connection";
+import { useStatewireEmit } from "../host/host";
+import type { StatewireTransport } from "../types";
+import {
+  createSession,
+  handleFinish,
+  handleOps,
+  handleSnapshot,
+  setTransport,
+  start,
+  stop,
+} from "../client/session";
+import type { SessionOptions } from "../client/session";
+import type {
+  RemoteLink,
+  StatewireConnection,
+  StatewireTransportProps,
+} from "./sse";
+
+export const useStatewireRemote = <
+  TOptions extends {
+    url: string;
+    onChange?: (connection: StatewireConnection) => void;
+  } & SessionOptions,
+>(
+  options: TOptions,
+  create: (
+    latest: {
+      readonly current: { options: TOptions; ctx: StatewireTransportProps };
+    },
+    notify: (connection: StatewireConnection) => void,
+  ) => ConnBase & { send: RemoteLink["send"] },
+): StatewireTransport<any, any, any> => {
+  const emit = useStatewireEmit<any>();
+  const [s] = useState(() =>
+    createSession({ sessionStore: options.sessionStore }),
+  );
+
+  useEffect(() => {
+    s.emitEvent = emit;
+    return () => {
+      s.emitEvent = () => {};
+    };
+  }, [s, emit]);
+  useEffect(() => {
+    start(s);
+    return () => stop(s);
+  }, [s]);
+
+  const [ctx] = useState(
+    (): StatewireTransportProps => ({
+      get clientId() {
+        return s.record.clientId;
+      },
+      onSnapshot: (args) => handleSnapshot(s, args),
+      onOps: (args) => handleOps(s, args),
+      onFinish: (args) => handleFinish(s, args),
+    }),
+  );
+  const conn = useStatewireConn(options, ctx, create);
+  useEffect(() => setTransport(s, conn), [s, conn]);
+
+  return {
+    state: s.canonical,
+    commands: s.commands,
+    emit,
+    connection: conn.connection,
+    source: s.source,
+  };
+};

package/src/transports/sse-parser.ts

@@ -0,0 +1,24 @@
+export const createSseParser = (): ((chunk: string) => string[]) => {
+  let buffer = "";
+  let dataLines: string[] = [];
+
+  return (chunk: string) => {
+    const events: string[] = [];
+    buffer += chunk;
+    const held = buffer.endsWith("\r") ? "\r" : "";
+    const lines = buffer
+      .slice(0, buffer.length - held.length)
+      .split(/\r\n|\r|\n/);
+    buffer = lines.pop()! + held;
+    for (const line of lines) {
+      if (line === "") {
+        if (dataLines.length > 0) events.push(dataLines.join("\n"));
+        dataLines = [];
+        continue;
+      }
+      const match = /^data(?:: ?(.*))?$/.exec(line);
+      if (match) dataLines.push(match[1] ?? "");
+    }
+    return events;
+  };
+};

package/src/transports/sse.ts

@@ -0,0 +1,280 @@
+import { flushTapSync, resource } from "@assistant-ui/tap";
+import type { ResourceElement } from "@assistant-ui/tap";
+import { encodeParams, reviveResponse } from "../wire/meta";
+import { createSseParser } from "./sse-parser";
+import { timing } from "../client/timing";
+import {
+  classify,
+  createGate,
+  handleEnvelope,
+  overloadedError,
+  parseRetryAfter,
+  reconnectConn,
+} from "../client/connection";
+import type {
+  ConnBase,
+  StatewireEnvelope,
+  StatewireFinish,
+  StatewireResponse,
+} from "../client/connection";
+import type { StatewireTransport } from "../types";
+import { useStatewireRemote } from "./remote";
+import type { StatewireSessionStore } from "../client/sessionStore";
+import type { StatewireCommands } from "../types";
+
+export type StatewireTransportProps = {
+  clientId: string;
+  onSnapshot: (args: { ops: unknown[]; lastSeq: number }) => void;
+  onOps: (args: {
+    ops: unknown[];
+    res?: StatewireResponse[];
+    ack?: number;
+  }) => void;
+  onFinish: (args: StatewireFinish) => void;
+};
+
+export type StatewireWireCommand = {
+  method: string;
+  params: readonly unknown[];
+};
+
+export type StatewireSubmitResult =
+  | { type: "receipt"; response?: StatewireResponse }
+  | { type: "rejected"; message: string; payload?: unknown }
+  | { type: "seq-gap" }
+  | { type: "unknown-client" }
+  | { type: "stale-lease" };
+
+export type ConnectionState =
+  | { status: "connecting" }
+  | { status: "live" }
+  | {
+      status: "reconnecting";
+      cause: "dropped" | "ended" | "error";
+      attempt: number;
+      nextRetryAt: number;
+      lastError?: string;
+      message?: string;
+    }
+  | { 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;
+  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;
+};
+
+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 merged = new Headers(
+    typeof headers === "function" ? await headers() : headers,
+  );
+  for (const [name, value] of Object.entries(extra)) merged.set(name, value);
+  return merged;
+};
+
+const timedFetch = async (
+  c: Conn,
+  input: string,
+  init: RequestInit & { signal: AbortSignal },
+  timeout: AbortSignal,
+): Promise<Response> => {
+  try {
+    return await (c.latest.current.options.fetch ?? globalThis.fetch)(
+      input,
+      init,
+    );
+  } catch {
+    throw classify(timeout);
+  }
+};
+
+const consume = async (
+  c: Conn,
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  heartbeat: AbortController,
+  dead: () => boolean,
+): Promise<"stop" | "reattach" | "ended"> => {
+  const decoder = new TextDecoder();
+  const parse = createSseParser();
+  let attached = false;
+  for (;;) {
+    const timer = setTimeout(
+      () => heartbeat.abort(),
+      timing.heartbeatTimeoutMs,
+    );
+    let result: ReadableStreamReadResult<Uint8Array>;
+    try {
+      result = await reader.read();
+    } catch {
+      throw classify(heartbeat.signal);
+    } finally {
+      clearTimeout(timer);
+    }
+    if (result.done) return "ended";
+    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;
+      if (done) return done;
+    }
+  }
+};
+
+const attemptStream = async (
+  c: Conn,
+  abort: AbortController,
+): Promise<"stop" | "reattach" | "ended"> => {
+  const headers = await requestHeaders(c, {
+    "Statewire-Client-Id": c.latest.current.ctx.clientId,
+    accept: "text/event-stream",
+  });
+  const heartbeat = new AbortController();
+  const headerTimer = setTimeout(
+    () => heartbeat.abort(),
+    timing.heartbeatTimeoutMs,
+  );
+  let res: Response;
+  try {
+    res = await timedFetch(
+      c,
+      `${baseUrl(c)}/stream`,
+      {
+        headers,
+        cache: "no-store",
+        signal: AbortSignal.any([abort.signal, heartbeat.signal]),
+      },
+      heartbeat.signal,
+    );
+  } finally {
+    clearTimeout(headerTimer);
+  }
+  if (res.status === 429 || res.status === 503) throw overloaded(res);
+  if (!res.ok || !res.body) throw new Error(`HTTP ${res.status}`);
+  const reader = res.body.getReader();
+  try {
+    return await consume(c, reader, heartbeat, () => abort.signal.aborted);
+  } finally {
+    reader.cancel().catch(() => {});
+  }
+};
+
+const overloaded = (res: Response) =>
+  overloadedError(parseRetryAfter(res.headers.get("Retry-After")));
+
+const sendCommand = async (
+  c: Conn,
+  { seq, command }: { seq: number; command: StatewireWireCommand },
+): Promise<StatewireSubmitResult> => {
+  const timeout = AbortSignal.timeout(timing.heartbeatTimeoutMs);
+  const res = await timedFetch(
+    c,
+    `${baseUrl(c)}/commands`,
+    {
+      method: "POST",
+      headers: await requestHeaders(c, {
+        "content-type": "application/json",
+        "Statewire-Client-Id": c.latest.current.ctx.clientId,
+        "Statewire-Command-Seq": String(seq),
+        ...(c.lease !== null && { "Statewire-Lease": c.lease }),
+      }),
+      body: JSON.stringify({
+        method: command.method,
+        ...encodeParams(command.params),
+      }),
+      signal: AbortSignal.any([
+        c.lifetime?.signal ?? AbortSignal.abort(),
+        timeout,
+      ]),
+    },
+    timeout,
+  );
+  if (res.ok) {
+    const body = (await res.json().catch(() => null)) as {
+      res?: StatewireResponse;
+    } | null;
+    return body?.res !== undefined
+      ? { type: "receipt", response: reviveResponse(body.res) }
+      : { type: "receipt" };
+  }
+  if (res.status === 409 || res.status === 412 || res.status === 423) {
+    // Only a body naming the same verdict as the status is statewire's own;
+    // a bare status is middleware noise — a transport fault, retried.
+    const verdict =
+      res.status === 409
+        ? ("seq-gap" as const)
+        : res.status === 412
+          ? ("unknown-client" as const)
+          : ("stale-lease" as const);
+    const body = (await res.json().catch(() => null)) as {
+      error?: string;
+    } | null;
+    if (body?.error === verdict) return { type: verdict };
+    throw new Error(`HTTP ${res.status}`);
+  }
+  if (res.status === 429 || res.status === 503) throw overloaded(res);
+  if (res.status >= 400 && res.status < 500) {
+    return { type: "rejected", message: `HTTP ${res.status}` };
+  }
+  throw new Error(`HTTP ${res.status}`);
+};
+
+const useStatewireSSE = (
+  options: StatewireSSEOptions,
+): StatewireTransport<any, any, any> => useStatewireRemote(options, createConn);
+
+export const StatewireSSE = resource(useStatewireSSE) as <
+  TState = any,
+  TCommands extends StatewireCommands = StatewireCommands,
+  TEvent = any,
+>(
+  options: StatewireSSEOptions,
+) => ResourceElement<StatewireTransport<TState | undefined, TCommands, TEvent>>;

package/src/transports/testing.ts

@@ -0,0 +1,155 @@
+import type { ResourceElement } from "@assistant-ui/tap";
+import type { StatewireEnvelope } from "../client/connection";
+import { recordMutations } from "../client/optimistic";
+import { StatewireSSE } from "./sse";
+import type { StatewireTransport } from "../types";
+
+/** Let queued microtasks and op batches drain through the statewire client. */
+export const tick = () => new Promise<void>((r) => setTimeout(r, 0));
+
+/** Run a mutator against a recording draft, as the client does for `optimistic`. */
+export const applyOptimistic = <TState>(
+  state: 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[] }[];
+  /** Replace the replicated state and broadcast it as a root snapshot op. */
+  setState: (state: TState) => Promise<void>;
+  /** Deliver an ack watermark on the stream. */
+  ack: (seq: number) => Promise<void>;
+  /** Deliver an arbitrary envelope on the stream. */
+  sendEnvelope: (envelope: StatewireEnvelope) => Promise<void>;
+  /** End the stream with a fin; further attaches fail like a dead server. */
+  finish: (reason: string, message?: string) => Promise<void>;
+  readonly clientId: string;
+  readonly attached: boolean;
+};
+
+/**
+ * A mock statewire backend: serves `initialState` as the attach snapshot,
+ * records command POSTs (receipt only — acks and results are delivered from
+ * test code), and exposes the wire as a transport ResourceElement.
+ */
+let mockCount = 0;
+
+export const createMockTransport = <TState>(
+  initialState: TState,
+): MockTransport<TState> => {
+  let state: unknown = initialState;
+  let clientId = "";
+  let finished = false;
+  const clients = new Map<string, number>();
+  const streams = new Set<StreamHandle>();
+  const commands: { method: string; params: unknown[] }[] = [];
+
+  const sendEnvelope = (envelope: StatewireEnvelope) => {
+    for (const stream of streams) {
+      stream.send(`data: ${JSON.stringify(envelope)}\n\n`);
+    }
+    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,
+  ): Promise<Response> => {
+    if (finished) throw new TypeError("fetch failed (finished)");
+    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("/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[] },
+      );
+      return Response.json({});
+    }
+    return new Response(null, { status: 404 });
+  }) as typeof fetch;
+
+  return {
+    transport: StatewireSSE({
+      url: `http://mock-${++mockCount}/api`,
+      fetch: fakeFetch,
+    }),
+    commands,
+    setState: (next) => {
+      state = next;
+      return sendEnvelope({ ops: [{ op: "replace", path: [], value: next }] });
+    },
+    ack: (seq) => sendEnvelope({ ack: seq }),
+    sendEnvelope,
+    finish: async (reason, message) => {
+      await sendEnvelope({
+        fin: { reason, ...(message !== undefined && { message }) },
+      });
+      finished = true;
+      for (const stream of [...streams]) stream.close();
+      await tick();
+    },
+    get clientId() {
+      return clientId;
+    },
+    get attached() {
+      return streams.size > 0;
+    },
+  };
+};