statewire 0.0.0-0 → 0.0.2

package/src/client/connection.ts

@@ -0,0 +1,301 @@
+import { useEffect, useRef, useState } from "react";
+import { flushTapSync } from "@assistant-ui/tap";
+import { reviveOps, reviveResponse, reviveValue } from "../wire/meta";
+import { retryDelay } from "./timing";
+import type { ConnectionState, StatewireRemoteProps } from "../transports/sse";
+import type { StatewireClient } from "../statewire";
+import type { StatewireHost } from "../host";
+
+export type Episode = {
+  cause: "dropped" | "evicted" | "error";
+  message?: string;
+};
+
+export type StatewireResponse = {
+  seq: number;
+  type: "accepted" | "rejected" | "pending" | "crashed" | "result-unavailable";
+  code?: string;
+  message?: string;
+  payload?: unknown;
+  meta?: unknown;
+};
+
+export type StatewireSyn = {
+  lastSeq: number;
+  lease?: string;
+};
+
+export type StatewireEnvelope = {
+  ops?: unknown[];
+  res?: StatewireResponse[];
+  ack?: number;
+  syn?: StatewireSyn;
+  fin?: StatewireHost.Fin;
+};
+
+const createGate = () => {
+  let latched = false;
+  let wake: (() => void) | undefined;
+  return {
+    take: () => {
+      const was = latched;
+      latched = false;
+      return was;
+    },
+    wait: (timeoutMs?: number) => {
+      if (latched) {
+        latched = false;
+        return Promise.resolve();
+      }
+      return new Promise<void>((resolve) => {
+        const timer =
+          timeoutMs === undefined
+            ? undefined
+            : setTimeout(() => {
+                wake = undefined;
+                resolve();
+              }, timeoutMs);
+        wake = () => {
+          clearTimeout(timer);
+          wake = undefined;
+          resolve();
+        };
+      });
+    },
+    open: () => {
+      if (wake) wake();
+      else latched = true;
+    },
+  };
+};
+
+export type Gate = ReturnType<typeof createGate>;
+
+export type Conn = {
+  connection: StatewireClient.Connection;
+  hasSnapshot: boolean;
+  lease: string | null;
+  attempt: number;
+  episode: Episode | null;
+  gate: Gate;
+  abort: AbortController | null;
+  lifetime: AbortController | null;
+  ctx: StatewireRemoteProps;
+  onChange: (connection: StatewireClient.Connection) => void;
+  attemptOnce: (
+    abort: AbortController,
+  ) => Promise<"stop" | "reattach" | "ended">;
+  notify: (connection: StatewireClient.Connection) => void;
+  reconnect: () => void;
+};
+
+const setStatus = (c: Conn, next: ConnectionState) => {
+  const changed = next.status !== c.connection.status;
+  c.connection = { ...next, reconnect: c.reconnect };
+  c.notify(c.connection);
+  if (changed) c.onChange(c.connection);
+};
+
+const deliverEnvelope = (
+  c: Conn,
+  env: Pick<StatewireEnvelope, "ops" | "res" | "ack" | "syn">,
+) => {
+  if (env.syn?.lease !== undefined) c.lease = env.syn.lease;
+  const ctx = c.ctx;
+  const ops = env.ops === undefined ? [] : reviveOps(env.ops);
+  const res = env.res?.map(reviveResponse);
+  if (env.syn !== undefined) {
+    ctx.onSnapshot({ ops, lastSeq: env.syn.lastSeq });
+    c.hasSnapshot = true;
+  } else if (
+    env.ops !== undefined ||
+    env.res !== undefined ||
+    env.ack !== undefined
+  ) {
+    ctx.onOps({
+      ops,
+      ...(res !== undefined && { res }),
+      ...(env.ack !== undefined && { ack: env.ack }),
+    });
+  }
+};
+
+const isTransientFinish = (
+  reason: StatewireHost.Fin["reason"],
+): reason is "evicted" | "error" => reason === "evicted" || reason === "error";
+
+const settleEnvelope = (
+  c: Conn,
+  env: StatewireEnvelope,
+): "stop" | "reattach" | null => {
+  let finish = env.fin;
+  if (finish) {
+    if (finish.meta !== undefined) {
+      const { meta, ...rest } = finish;
+      finish = { ...rest, payload: reviveValue(rest.payload, meta) };
+    }
+    c.ctx.onFinish(finish);
+    if (isTransientFinish(finish.reason)) {
+      c.episode = {
+        cause: finish.reason,
+        ...(finish.message !== undefined && { message: finish.message }),
+      };
+      return "reattach";
+    }
+    setStatus(c, {
+      status: "gone",
+      ...(finish.message !== undefined && { message: finish.message }),
+      ...(finish.payload !== undefined && { payload: finish.payload }),
+    });
+    return "stop";
+  }
+  if (c.connection.status !== "live") {
+    c.attempt = 0;
+    c.episode = null;
+    setStatus(c, { status: "live" });
+  }
+  return null;
+};
+
+export const handleEnvelope = (
+  c: Conn,
+  env: StatewireEnvelope,
+): "stop" | "reattach" | null => {
+  deliverEnvelope(c, env);
+  return settleEnvelope(c, env);
+};
+
+const scheduleRetry = (
+  c: Conn,
+  failure: string | undefined,
+  immediate: boolean,
+  cause?: unknown,
+) => {
+  c.attempt += 1;
+  c.episode ??= { cause: "dropped" };
+  const delay = immediate ? 0 : retryDelay(cause, c.attempt);
+  if (c.hasSnapshot) {
+    setStatus(c, {
+      status: "reconnecting",
+      ...c.episode,
+      attempt: c.attempt,
+      nextRetryAt: Date.now() + delay,
+      ...(failure !== undefined && { lastError: failure }),
+    });
+  }
+  return delay;
+};
+
+const reconnectConn = (c: Conn) => {
+  if (!c.lifetime) return;
+  if (c.connection.status === "gone") {
+    c.attempt = 0;
+    c.episode = { cause: "dropped" };
+    flushTapSync(() => {
+      if (c.hasSnapshot) scheduleRetry(c, undefined, true);
+      else setStatus(c, { status: "connecting" });
+    });
+  }
+  c.gate.open();
+  c.abort?.abort();
+};
+
+const run = async (c: Conn, lifetime: AbortController, gate: Gate) => {
+  const alive = () => c.lifetime === lifetime;
+  while (alive()) {
+    const abort = new AbortController();
+    c.abort = abort;
+    let failure: string | undefined;
+    let cause: unknown;
+    let gone = false;
+    try {
+      gone = (await c.attemptOnce(abort)) === "stop";
+    } catch (error) {
+      if (!abort.signal.aborted) {
+        failure =
+          error instanceof Error && error.message ? error.message : "network";
+        cause = error;
+      }
+    }
+    abort.abort();
+    if (!alive()) return;
+    if (gone) {
+      await gate.wait();
+      continue;
+    }
+    const immediate = gate.take();
+    const delay = flushTapSync(() =>
+      scheduleRetry(c, failure, immediate, cause),
+    );
+    if (delay === 0) continue;
+    await gate.wait(delay);
+  }
+};
+
+export const useStatewireConn = (props: {
+  url: string;
+  onChange?: ((connection: StatewireClient.Connection) => void) | undefined;
+  ctx: StatewireRemoteProps;
+  attemptOnce: (
+    c: Conn,
+    abort: AbortController,
+  ) => Promise<"stop" | "reattach" | "ended">;
+}): Conn => {
+  const latest = useRef(props);
+  latest.current = props;
+  const [, setConnection] = useState<StatewireClient.Connection | null>(null);
+  const [c] = useState((): Conn => {
+    const conn: Conn = {
+      hasSnapshot: false,
+      lease: null,
+      attempt: 0,
+      episode: null,
+      abort: null,
+      gate: createGate(),
+      lifetime: null,
+      ctx: props.ctx,
+      onChange: (connection) => latest.current.onChange?.(connection),
+      attemptOnce: (abort) => latest.current.attemptOnce(conn, abort),
+      notify: setConnection,
+      reconnect: () => reconnectConn(conn),
+      connection: { status: "connecting", reconnect: () => conn.reconnect() },
+    };
+    return conn;
+  });
+
+  useEffect(() => {
+    c.hasSnapshot = false;
+    c.lease = null;
+    c.attempt = 0;
+    c.episode = null;
+    if (c.connection.status !== "connecting") {
+      setStatus(c, { status: "connecting" });
+    }
+    const lifetime = new AbortController();
+    c.lifetime = lifetime;
+    c.gate = createGate();
+    void run(c, lifetime, c.gate);
+    return () => {
+      c.abort?.abort();
+      lifetime.abort();
+      if (c.lifetime === lifetime) c.lifetime = null;
+      c.gate.open();
+    };
+  }, [c, props.url]);
+
+  return c;
+};
+
+export const classify = (timeout: AbortSignal) =>
+  new Error(timeout.aborted ? "timeout" : "network");
+
+export const parseRetryAfter = (header: string | null): number | undefined => {
+  if (!header) return undefined;
+  const value = header.trim();
+  if (/^\d+$/.test(value)) return Number(value) * 1000;
+  const date = Date.parse(value);
+  return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
+};
+
+export const overloadedError = (retryAfterMs?: number) =>
+  Object.assign(new Error("overloaded"), { retryAfterMs });

package/src/client/core.ts

@@ -0,0 +1,312 @@
+import { useEffect, useState } from "react";
+import { createChanges } from "./changes";
+import { getCommandsHost, getEmitHost, getStateHost } from "../host/host";
+import type { CommandsInvocation, CommandsListener } from "../host/host";
+import { recordMutations } from "../util/recordMutations";
+import { createMacrotaskPoster } from "../util/macrotask";
+import { createMethodProxy } from "../util/methodProxy";
+import type { StatewirePath } from "../wire/ops";
+import { StatewireSendError } from "../types";
+import type { Statewire } from "../types";
+import type { StatewireClient } from "../statewire";
+
+export const LIVE_CONNECTION: StatewireClient.Connection = {
+  status: "live",
+  reconnect: () => {},
+};
+
+const failureOf = (error: unknown): StatewireClient.SendFailure =>
+  error instanceof StatewireSendError
+    ? error.failure
+    : {
+        fate: "rejected",
+        cause: "server",
+        message: error instanceof Error ? error.message : String(error),
+      };
+
+type Overlay = { inv: CommandsInvocation; dropped: boolean };
+
+const createCore = (
+  getOptions: () => StatewireClient.Options<any, any, any>,
+) => {
+  let value: Statewire<unknown> | null = null;
+  let source: Statewire.StateSource | null = null;
+  let overlays: Overlay[] = [];
+  let updates: Statewire.CommandUpdate[] = [];
+  let events: unknown[] = [];
+  let pendingChanged: StatewirePath[] = [];
+  let canonical: unknown;
+  let published: unknown;
+  let overlayPaths: readonly StatewirePath[] = [];
+  let notifiedPublished: unknown;
+  let notifiedOverlayPaths: readonly StatewirePath[] = [];
+  let notifiedConnection: StatewireClient.Connection | null = null;
+  let stale = false;
+  let overlaysDirty = false;
+  let flushing = false;
+  const listeners = new Set<() => void>();
+
+  const post = createMacrotaskPoster(() => {
+    scheduled = false;
+    flush();
+  });
+  let scheduled = false;
+  const schedule = () => {
+    if (scheduled) return;
+    scheduled = true;
+    post();
+  };
+
+  const markStale = () => {
+    stale = true;
+    schedule();
+  };
+
+  const drainCanonical = () => {
+    if (source) {
+      pendingChanged.push(...source.takeChanged());
+      canonical = source.snapshot();
+    } else if (value && value.state !== canonical) {
+      pendingChanged.push([]);
+      canonical = value.state;
+    }
+  };
+
+  const recompute = () => {
+    if (!stale || !value) return;
+    stale = false;
+    const prevCanonical = canonical;
+    drainCanonical();
+    if (canonical === prevCanonical && !overlaysDirty) return;
+    overlaysDirty = false;
+    const { optimistic } = getOptions();
+    let next = canonical;
+    let paths: readonly StatewirePath[] = [];
+    if (optimistic && canonical !== undefined) {
+      for (const overlay of overlays) {
+        if (overlay.dropped) continue;
+        const { inv } = overlay;
+        const ctx: StatewireClient.OptimisticContext = {
+          ts: inv.ts,
+          seq: inv.seq,
+          ...(inv.clientId !== undefined && { clientId: inv.clientId }),
+        };
+        try {
+          const recorded = recordMutations(next, (draft) =>
+            optimistic(
+              draft as never,
+              { method: inv.method, params: inv.params } as Statewire.Command,
+              ctx,
+            ),
+          );
+          next = recorded.state;
+          paths = [...paths, ...recorded.changedPaths];
+        } catch (error) {
+          overlay.dropped = true;
+          console.error(
+            `statewire: optimistic reducer threw for "${inv.method}"; dropping its optimistic update`,
+            error,
+          );
+        }
+      }
+    }
+    published = next;
+    overlayPaths = paths;
+  };
+
+  const getConnection = (): StatewireClient.Connection =>
+    value?.connection ?? LIVE_CONNECTION;
+
+  const flush = () => {
+    if (!value) return;
+    if (flushing) {
+      schedule();
+      return;
+    }
+    flushing = true;
+    try {
+      recompute();
+      const options = getOptions();
+      const stateChanged = published !== notifiedPublished;
+      if (stateChanged) {
+        const prev = notifiedPublished;
+        const changed = [
+          ...pendingChanged,
+          ...notifiedOverlayPaths,
+          ...overlayPaths,
+        ];
+        pendingChanged = [];
+        notifiedPublished = published;
+        notifiedOverlayPaths = overlayPaths;
+        options.onStateChange?.(published as never, {
+          changes: createChanges(prev, published, changed),
+        });
+      }
+      if (updates.length > 0 && published !== undefined) {
+        const batch = updates;
+        updates = [];
+        for (const update of batch) {
+          options.onCommandChange?.(update, { state: published as never });
+        }
+      }
+      if (events.length > 0 && published !== undefined) {
+        const batch = events;
+        events = [];
+        for (const event of batch) {
+          options.onEvent?.(event, { state: published as never });
+        }
+      }
+      const connection = getConnection();
+      const connectionChanged = connection !== notifiedConnection;
+      notifiedConnection = connection;
+      if (stateChanged || connectionChanged) {
+        for (const listener of [...listeners]) listener();
+      }
+    } finally {
+      flushing = false;
+    }
+  };
+
+  const note = (
+    inv: CommandsInvocation,
+    status: Statewire.CommandUpdate["status"],
+    extra?: { result?: unknown; failure?: StatewireClient.SendFailure },
+  ) => {
+    if (!getOptions().onCommandChange) return;
+    updates.push({
+      method: inv.method,
+      params: inv.params as never[],
+      seq: inv.seq,
+      status,
+      ...extra,
+    });
+    schedule();
+  };
+
+  const commandsListener: CommandsListener = {
+    onStart: (inv) => {
+      overlays.push({ inv, dropped: false });
+      overlaysDirty = true;
+      markStale();
+      note(inv, "queued");
+    },
+    onPosted: (inv) => note(inv, "posted"),
+    onAck: (inv) => note(inv, "acked"),
+    onCovered: (inv) => {
+      if (!overlays.some((o) => o.inv === inv)) return;
+      overlays = overlays.filter((o) => o.inv !== inv);
+      overlaysDirty = true;
+      markStale();
+    },
+    onSettle: (inv, outcome) => {
+      note(
+        inv,
+        "settled",
+        outcome.type === "accepted"
+          ? { result: outcome.payload }
+          : { failure: failureOf(outcome.error) },
+      );
+      flush();
+    },
+  };
+
+  const eventSink = (event: unknown) => {
+    if (!getOptions().onEvent) return;
+    events.push(event);
+    schedule();
+  };
+
+  const attach = (next: Statewire<unknown>) => {
+    if (next === value) return;
+    const prev = value;
+    value = next;
+    const nextSource =
+      next.source ??
+      (typeof next.state === "object" && next.state !== null
+        ? getStateHost(next.state)
+        : undefined) ??
+      null;
+    if (nextSource !== source) {
+      source?.setOnChange(null);
+      source = nextSource;
+      source?.setOnChange(markStale);
+      markStale();
+    }
+    if (next.commands !== prev?.commands) {
+      if (prev) getCommandsHost(prev.commands)?.setListener(null);
+      getCommandsHost(next.commands)?.setListener(commandsListener);
+      if (overlays.length > 0) {
+        overlays = [];
+        overlaysDirty = true;
+      }
+      markStale();
+    }
+    if (next.emit !== prev?.emit) {
+      if (prev) getEmitHost(prev.emit)?.setSink(null);
+      getEmitHost(next.emit)?.setSink(eventSink);
+    }
+    if (!source) markStale();
+    schedule();
+  };
+
+  const detach = () => {
+    source?.setOnChange(null);
+    source = null;
+    if (value) {
+      getCommandsHost(value.commands)?.setListener(null);
+      getEmitHost(value.emit)?.setSink(null);
+      value = null;
+    }
+  };
+
+  const commands = createMethodProxy<Statewire.CommandsProxy<any>>(
+    (method, params) => {
+      if (!value) {
+        return Promise.reject(
+          new StatewireSendError({ fate: "aborted", cause: "unmount" }),
+        );
+      }
+      const send = (
+        value.commands as Record<
+          string,
+          (...args: unknown[]) => Promise<unknown>
+        >
+      )[method]!;
+      const promise = send(...params);
+      flush();
+      return promise;
+    },
+  );
+
+  return {
+    attach,
+    detach,
+    getState: () => {
+      recompute();
+      return published;
+    },
+    commands,
+    subscribe: (listener: () => void) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+};
+
+export const useStatewireCore = (
+  getOptions: () => StatewireClient.Options<any, any, any>,
+  value: Statewire<unknown>,
+) => {
+  const [core] = useState(() => createCore(getOptions));
+  // Attach during render so the first snapshot reads the transport's state;
+  // re-attaching the same transport is a no-op and the single-slot host
+  // listeners make a swap land on the last writer.
+  core.attach(value);
+  useEffect(() => {
+    core.attach(value);
+  });
+  useEffect(() => () => core.detach(), [core]);
+  return core;
+};