statewire 0.0.0-0 → 0.0.2

package/src/statewire.ts

@@ -0,0 +1,200 @@
+import { useMemo, useRef, useState, useSyncExternalStore } from "react";
+import {
+  createTapRoot,
+  flushTapSync,
+  resource,
+  useResource,
+} from "@assistant-ui/tap";
+import type { ResourceElement } from "@assistant-ui/tap";
+import { LIVE_CONNECTION, useStatewireCore } from "./client/core";
+import type { Statewire } from "./types";
+import type { ConnectionState } from "./transports/sse";
+import type { StatewireSessionStoreOptions } from "./client/sessionStore";
+
+export const useStatewire = <
+  TState,
+  TCommands extends Statewire.Commands = Statewire.Commands,
+  TEvent = any,
+>(
+  options: StatewireClient.Options<TState, TCommands, TEvent>,
+): StatewireClient.Helpers<TState, TCommands> => {
+  const latest = useRef(options);
+  latest.current = options;
+
+  const value = useResource(options.transport) as Statewire<unknown>;
+  const core = useStatewireCore(() => latest.current, value);
+  const [subscribe] = useState(
+    () => (listener: () => void) =>
+      core.subscribe(() => flushTapSync(listener)),
+  );
+
+  const state = useSyncExternalStore(
+    subscribe,
+    core.getState,
+    core.getState,
+  ) as TState;
+  const connection = value.connection ?? LIVE_CONNECTION;
+
+  return useMemo(
+    () => ({
+      state,
+      getState: core.getState as () => TState,
+      connection,
+      commands: core.commands as Statewire.CommandsProxy<TCommands>,
+    }),
+    [state, connection, core],
+  );
+};
+
+export const StatewireResource = <
+  TState,
+  TCommands extends Statewire.Commands = Statewire.Commands,
+  TEvent = any,
+>(
+  options: StatewireClient.Options<TState, TCommands, TEvent>,
+): ResourceElement<StatewireClient.Helpers<TState, TCommands>> =>
+  resource(useStatewire<TState, TCommands, TEvent>)(options);
+
+export class StatewireClient<
+  TState,
+  TCommands extends Statewire.Commands = Statewire.Commands,
+  TEvent = any,
+> {
+  private readonly root;
+  private disposed = false;
+
+  constructor(options: StatewireClient.Options<TState, TCommands, TEvent>) {
+    const ClientRoot = () => useStatewire<TState, TCommands, TEvent>(options);
+    this.root = createTapRoot(ClientRoot);
+  }
+
+  get state(): TState {
+    return this.root.getValue().getState();
+  }
+
+  get connection(): StatewireClient.Connection {
+    return this.root.getValue().connection;
+  }
+
+  get commands(): Statewire.CommandsProxy<TCommands> {
+    return this.root.getValue().commands;
+  }
+
+  subscribe(listener: () => void): () => void {
+    return this.root.subscribe(listener);
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.root.unmount();
+  }
+}
+
+export namespace StatewireClient {
+  export type Options<
+    TState,
+    TCommands extends Statewire.Commands = Statewire.Commands,
+    TEvent = any,
+  > = {
+    transport: ResourceElement<Statewire<TState, TCommands, TEvent>>;
+    optimistic?: Optimistic<NonNullable<TState>, TCommands>;
+    onEvent?: (event: TEvent, ctx: { state: NonNullable<TState> }) => void;
+    onStateChange?: (
+      state: NonNullable<TState>,
+      ctx: { changes: Statewire.Changes },
+    ) => void;
+    onCommandChange?: (
+      update: Statewire.CommandUpdate<TCommands>,
+      ctx: { state: NonNullable<TState> },
+    ) => void;
+  };
+
+  export type Helpers<
+    TState,
+    TCommands extends Statewire.Commands = Statewire.Commands,
+  > = {
+    /** The statewire's state type — remote statewires include `undefined` until the first attach snapshot applies. */
+    state: TState;
+    /** Identity-stable across renders; reads the current canonical state without subscribing the caller. */
+    getState: () => TState;
+    connection: Connection;
+    commands: Statewire.CommandsProxy<TCommands>;
+  };
+
+  export type Connection = ConnectionState & { reconnect: () => void };
+  export type ConnectionStatus = Connection["status"];
+
+  /**
+   * Mutate the draft in place; the client records the next state plus the exact
+   * changed paths. Re-run against the new base on every rebase.
+   */
+  export type Optimistic<
+    TState,
+    TCommands extends Statewire.Commands = Statewire.Commands,
+  > = (
+    draft: TState,
+    command: Statewire.Command<TCommands>,
+    ctx: OptimisticContext,
+  ) => void;
+
+  export type OptimisticContext = {
+    ts: number;
+    seq: number;
+    clientId?: string;
+  };
+
+  /**
+   * fate: "aborted" = never sent, "rejected" = the handler refused,
+   * "unknown-command" = no such command, "invalid-params" = the args did not
+   * match the command's schema, "lost" = sent but never covered by an ack,
+   * "crashed" = acked but the processing died, "result-unavailable" = acked
+   * but the result is gone.
+   * cause is which channel settled it: "server" = the server's answer;
+   * the rest are channel deaths the client settled locally.
+   */
+  export type SendFailure =
+    | { fate: "rejected"; cause: "server"; message: string; payload?: unknown }
+    | { fate: "unknown-command"; cause: "server" }
+    | { fate: "invalid-params"; cause: "server"; message: string }
+    | { fate: "crashed"; cause: "server" }
+    | {
+        fate: "result-unavailable";
+        cause:
+          | "server"
+          | "unmount"
+          | "stream-gone"
+          | "session-lost"
+          | "superseded";
+      }
+    | {
+        fate: "aborted";
+        cause:
+          | "cascade"
+          | "unmount"
+          | "stream-gone"
+          | "session-lost"
+          | "superseded";
+      }
+    | {
+        fate: "lost";
+        cause: "unmount" | "stream-gone" | "session-lost" | "superseded";
+      };
+
+  export type SSEOptions = StatewireSessionStoreOptions & {
+    url: string;
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    fetch?: typeof globalThis.fetch;
+    onChange?: (connection: Connection) => void;
+  };
+
+  export type WSOptions = StatewireSessionStoreOptions & {
+    url: string;
+    protocols?: string | string[];
+    query?:
+      | Record<string, string>
+      | (() => Record<string, string> | Promise<Record<string, string>>);
+    webSocket?: new (url: string, protocols?: string | string[]) => WebSocket;
+    onChange?: (connection: Connection) => void;
+  };
+}

package/src/transports/fake-sse.ts

@@ -0,0 +1,51 @@
+import type { StatewireEnvelope } from "../client/connection";
+
+export type FakeStreamHandle = {
+  clientId: string;
+  send: (text: string) => void;
+  close: () => void;
+};
+
+export const sseFrame = (envelope: StatewireEnvelope) =>
+  `data: ${JSON.stringify(envelope)}\n\n`;
+
+export const openSSEStream = (
+  streams: Set<FakeStreamHandle>,
+  clientId: string,
+  onOpen: (handle: FakeStreamHandle) => void,
+  signal?: AbortSignal,
+): Response => {
+  const encoder = new TextEncoder();
+  let handle: FakeStreamHandle;
+  const body = new ReadableStream<Uint8Array>({
+    start: (controller) => {
+      let open = true;
+      handle = {
+        clientId,
+        send: (text) => {
+          if (open) controller.enqueue(encoder.encode(text));
+        },
+        close: () => {
+          if (!open) return;
+          open = false;
+          streams.delete(handle);
+          controller.close();
+        },
+      };
+      streams.add(handle);
+      onOpen(handle);
+    },
+    cancel: () => {
+      streams.delete(handle);
+    },
+  });
+  signal?.addEventListener("abort", () => {
+    for (const stream of [...streams]) {
+      if (stream.clientId === clientId) stream.close();
+    }
+  });
+  return new Response(body, {
+    status: 200,
+    headers: { "content-type": "text/event-stream" },
+  });
+};

package/src/transports/fixtures.ts

@@ -0,0 +1,60 @@
+import { resource } from "@assistant-ui/tap";
+import {
+  useStatewireCommands,
+  useStatewireEmit,
+  useStatewireState,
+} from "../host";
+import { tick } from "./testing";
+
+/** Let several rounds of queued microtasks and op batches drain. */
+export const settle = async () => {
+  for (let i = 0; i < 3; i++) await tick();
+};
+
+/** A minimal statewire host element: `{ count }` state with an `increment` command. */
+export const createCounterElement = () =>
+  resource(() => {
+    const [state] = useStatewireState(() => ({ count: 0 }));
+    const emit = useStatewireEmit();
+    const commands = useStatewireCommands({
+      increment: () => {
+        state.count += 1;
+      },
+    });
+    return { state, commands, emit };
+  })();
+
+/** Serialize a command frame as a client would send it over a socket. */
+export const commandFrame = (
+  method: string,
+  seq: number,
+  params: unknown[] = [],
+) => JSON.stringify({ method, params, seq });
+
+export type SocketRecorder = {
+  sent: string[];
+  closes: { code?: number; reason?: string }[];
+  last: () => any;
+  send: (data: string) => void;
+  close: (code?: number, reason?: string) => void;
+};
+
+/** Record sent frames and close calls; `last()` parses the latest frame. */
+export const createSocketRecorder = (): SocketRecorder => {
+  const sent: string[] = [];
+  const closes: { code?: number; reason?: string }[] = [];
+  return {
+    sent,
+    closes,
+    last: () => JSON.parse(sent.at(-1)!),
+    send: (data) => {
+      sent.push(data);
+    },
+    close: (code, reason) => {
+      closes.push({
+        ...(code !== undefined && { code }),
+        ...(reason !== undefined && { reason }),
+      });
+    },
+  };
+};

package/src/transports/remote.ts

@@ -0,0 +1,30 @@
+import { useEffect } from "react";
+import { useStatewireEmit } from "../host/host";
+import type { Statewire } from "../types";
+import { setTransport, useStatewireSession } from "../client/session";
+import type { StatewireSessionStoreOptions } from "../client/sessionStore";
+import type { StatewireClient } from "../statewire";
+import type { RemoteLink, StatewireRemoteProps } from "./sse";
+
+export const useStatewireRemote = <
+  TOptions extends {
+    url: string;
+    onChange?: (connection: StatewireClient.Connection) => void;
+  } & StatewireSessionStoreOptions,
+>(
+  options: TOptions,
+  useLink: (options: TOptions, ctx: StatewireRemoteProps) => RemoteLink,
+): Statewire<any, any, any> => {
+  const emit = useStatewireEmit<any>();
+  const s = useStatewireSession({ sessionStore: options.sessionStore }, emit);
+  const conn = useLink(options, s.ctx);
+  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,267 @@
+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";
+import { createSseParser } from "./sse-parser";
+import { timing } from "../client/timing";
+import {
+  classify,
+  handleEnvelope,
+  overloadedError,
+  parseRetryAfter,
+  useStatewireConn,
+} from "../client/connection";
+import type {
+  Conn,
+  StatewireEnvelope,
+  StatewireResponse,
+} from "../client/connection";
+import type { Statewire } from "../types";
+import type { StatewireClient } from "../statewire";
+import type { StatewireHost } from "../host";
+import { useStatewireRemote } from "./remote";
+
+export type StatewireRemoteProps = {
+  clientId: string;
+  onSnapshot: (args: { ops: unknown[]; lastSeq: number }) => void;
+  onOps: (args: {
+    ops: unknown[];
+    res?: StatewireResponse[];
+    ack?: number;
+  }) => void;
+  onFinish: (args: StatewireHost.Fin) => void;
+};
+
+export type StatewireWireCommand = {
+  method: string;
+  params: readonly unknown[];
+};
+
+export type StatewireSubmitResult =
+  | { type: "receipt"; response?: StatewireResponse }
+  | { type: "rejected"; message: string }
+  | { type: "seq-gap" }
+  | { type: "unknown-client" }
+  | { type: "stale-lease" };
+
+export type ConnectionState =
+  | { status: "connecting" }
+  | { status: "live" }
+  | {
+      status: "reconnecting";
+      cause: "dropped" | "evicted" | "error";
+      attempt: number;
+      nextRetryAt: number;
+      lastError?: string;
+      message?: string;
+    }
+  | { status: "gone"; message?: string; payload?: unknown };
+
+/** The live wire a remote session drives: connection status plus command POST. */
+export type RemoteLink = {
+  connection: StatewireClient.Connection;
+  send: (args: {
+    seq: number;
+    command: StatewireWireCommand;
+  }) => Promise<StatewireSubmitResult>;
+};
+
+const baseUrl = (options: StatewireClient.SSEOptions) =>
+  options.url.replace(/\/$/, "");
+
+const requestHeaders = async (
+  options: StatewireClient.SSEOptions,
+  extra: Record<string, string>,
+) => {
+  const { headers } = 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 (
+  options: StatewireClient.SSEOptions,
+  input: string,
+  init: RequestInit & { signal: AbortSignal },
+  timeout: AbortSignal,
+): Promise<Response> => {
+  try {
+    return await (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();
+  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));
+      if (done) return done;
+    }
+  }
+};
+
+const attemptStream = async (
+  c: Conn,
+  options: StatewireClient.SSEOptions,
+  abort: AbortController,
+): Promise<"stop" | "reattach" | "ended"> => {
+  const headers = await requestHeaders(options, {
+    "Statewire-Client-Id": c.ctx.clientId,
+    accept: "text/event-stream",
+  });
+  const heartbeat = new AbortController();
+  const headerTimer = setTimeout(
+    () => heartbeat.abort(),
+    timing.heartbeatTimeoutMs,
+  );
+  let res: Response;
+  try {
+    res = await timedFetch(
+      options,
+      `${baseUrl(options)}/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,
+  options: StatewireClient.SSEOptions,
+  { seq, command }: { seq: number; command: StatewireWireCommand },
+): Promise<StatewireSubmitResult> => {
+  const timeout = AbortSignal.timeout(timing.heartbeatTimeoutMs);
+  const res = await timedFetch(
+    options,
+    `${baseUrl(options)}/commands`,
+    {
+      method: "POST",
+      headers: await requestHeaders(options, {
+        "content-type": "application/json",
+        "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),
+      }),
+      signal: AbortSignal.any([
+        c.lifetime?.signal ?? AbortSignal.abort(),
+        timeout,
+      ]),
+    },
+    timeout,
+  );
+  if (res.ok) {
+    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" };
+  }
+  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 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: StatewireClient.SSEOptions,
+): Statewire<any, any, any> => useStatewireRemote(options, useSseLink);
+
+export const StatewireSSE = resource(useStatewireSSE) as <
+  TState = any,
+  TCommands extends Statewire.Commands = Statewire.Commands,
+  TEvent = any,
+>(
+  options: StatewireClient.SSEOptions,
+) => ResourceElement<Statewire<TState | undefined, TCommands, TEvent>>;