statewire 0.17.2 → 0.18.1

package/src/storage.ts

@@ -0,0 +1,601 @@
+import { useEffect, useMemo, useRef } from "react";
+import { wrapStorageError } from "./client/storageError";
+import { resource } from "@assistant-ui/tap";
+import type { StatewireClient } from "./statewire";
+import type { StatewireProtocol } from "./wire/protocol";
+import { negotiationHeaders, protocolToken } from "./wire/protocol";
+import { applyDocumentOps } from "./wire/documents";
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isOptionalString = (value: unknown): boolean =>
+  value === undefined || typeof value === "string";
+
+const isPositiveSafeInteger = (value: unknown): value is number =>
+  typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+
+const isSessionCommand = (
+  value: unknown,
+): value is StatewireClient.SessionCommand =>
+  isRecord(value) &&
+  isPositiveSafeInteger(value["seq"]) &&
+  isProtocol(value["protocol"]) &&
+  isProducer(value["produced"]) &&
+  typeof value["method"] === "string" &&
+  Array.isArray(value["params"]);
+
+const isSessionVerdict = (
+  value: unknown,
+): value is StatewireClient.SessionVerdict =>
+  isRecord(value) &&
+  isPositiveSafeInteger(value["seq"]) &&
+  (value["type"] === "result" ||
+    value["type"] === "rejected" ||
+    value["type"] === "failed" ||
+    value["type"] === "crashed" ||
+    value["type"] === "expired") &&
+  isOptionalString(value["code"]) &&
+  isOptionalString(value["message"]);
+
+const isSendFailure = (
+  value: unknown,
+): value is StatewireClient.SendFailure => {
+  if (!isRecord(value)) return false;
+  switch (value["fate"]) {
+    case "rejected":
+      return (
+        value["cause"] === "server" &&
+        isOptionalString(value["code"]) &&
+        isOptionalString(value["message"])
+      );
+    case "failed":
+      return value["cause"] === "server" && isOptionalString(value["message"]);
+    case "crashed":
+    case "expired":
+      return value["cause"] === "server";
+    case "aborted":
+      return (
+        (value["cause"] === "unmount" ||
+          value["cause"] === "stream-gone" ||
+          value["cause"] === "session-lost") &&
+        (value["predecessorLost"] === undefined ||
+          value["predecessorLost"] === true)
+      );
+    case "lost":
+      return (
+        value["cause"] === "unmount" ||
+        value["cause"] === "stream-gone" ||
+        value["cause"] === "session-lost"
+      );
+    default:
+      return false;
+  }
+};
+
+const isFailedCommand = (
+  value: unknown,
+): value is StatewireClient.FailedCommand =>
+  isRecord(value) &&
+  isProtocol(value["protocol"]) &&
+  isProducer(value["produced"]) &&
+  typeof value["command"] === "string" &&
+  Array.isArray(value["params"]) &&
+  isSendFailure(value["failure"]) &&
+  typeof value["ts"] === "number" &&
+  Number.isFinite(value["ts"]) &&
+  isPositiveSafeInteger(value["seq"]);
+
+const isSessionRecord = (
+  value: unknown,
+): value is StatewireClient.SessionRecord =>
+  isRecord(value) &&
+  typeof value["clientId"] === "string" &&
+  value["clientId"].length > 0 &&
+  isContext(value["context"]) &&
+  isPositiveSafeInteger(value["nextSeq"]) &&
+  isPositiveSafeInteger(value["ctxNextSeq"]) &&
+  Array.isArray(value["commands"]) &&
+  value["commands"].every(isSessionCommand) &&
+  (value["verdicts"] === undefined ||
+    (Array.isArray(value["verdicts"]) &&
+      value["verdicts"].every(isSessionVerdict))) &&
+  (value["failed"] === undefined ||
+    (Array.isArray(value["failed"]) && value["failed"].every(isFailedCommand)));
+
+const isProtocol = (value: unknown) =>
+  value === undefined ||
+  (typeof value === "string" && value !== "*" && protocolToken.test(value));
+
+const isProducer = (value: unknown) => {
+  if (value === undefined) return true;
+  if (!isRecord(value) || !isRecord(value["wire"])) return false;
+  try {
+    negotiationHeaders({
+      wireVersion: value["wire"] as StatewireProtocol.Range,
+      applicationProtocols: value["protocols"] as
+        | readonly StatewireProtocol.Offer[]
+        | "*",
+    });
+    return value["protocols"] !== undefined;
+  } catch {
+    return false;
+  }
+};
+
+const isContextOperation = (value: unknown) => {
+  if (!isRecord(value)) return false;
+  if (
+    value["doc"] !== undefined &&
+    (typeof value["doc"] !== "number" ||
+      !Number.isSafeInteger(value["doc"]) ||
+      value["doc"] < 0)
+  )
+    return false;
+  if (value["op"] === "mount") {
+    try {
+      applyDocumentOps(
+        { mode: "mounted", documents: new Map() },
+        [value],
+        undefined,
+        true,
+      );
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  if (value["op"] === "unmount") return true;
+  if (!["add", "replace", "remove"].includes(value["op"] as string))
+    return false;
+  return (
+    Array.isArray(value["path"]) &&
+    value["path"].every(
+      (part) =>
+        typeof part === "string" ||
+        (typeof part === "number" && Number.isSafeInteger(part) && part >= 0),
+    ) &&
+    (value["op"] === "remove" || "value" in value)
+  );
+};
+
+const isContext = (value: unknown) => {
+  if (value === undefined) return true;
+  if (
+    !isRecord(value) ||
+    !Array.isArray(value["ops"]) ||
+    !Array.isArray(value["pending"])
+  )
+    return false;
+  if (value["recover"] !== undefined && value["recover"] !== "version-1")
+    return false;
+  try {
+    const documents = applyDocumentOps(
+      { mode: "mounted", documents: new Map() },
+      value["ops"],
+      undefined,
+      true,
+    );
+    for (const entry of value["pending"]) {
+      if (
+        !isRecord(entry) ||
+        !isPositiveSafeInteger(entry["seq"]) ||
+        !Array.isArray(entry["ops"])
+      )
+        return false;
+      if (!entry["ops"].every(isContextOperation)) return false;
+    }
+    return documents.mode === "mounted";
+  } catch {
+    return false;
+  }
+};
+
+const decode = (
+  raw: string | null,
+  legacyProtocol: KeyValueSessionStorage.Options["legacyProtocol"],
+): StatewireClient.SessionRecord | null => {
+  if (raw === null) return null;
+  const parsed: unknown = JSON.parse(raw);
+  if (!isSessionRecord(parsed))
+    throw new Error("statewire: invalid stored session record");
+  const {
+    statewireStorageVersion: format,
+    savedAt: _savedAt,
+    ...value
+  } = parsed as StatewireClient.SessionRecord & {
+    statewireStorageVersion?: unknown;
+    savedAt?: unknown;
+  };
+  if (!isSessionRecord(value))
+    throw new Error("statewire: invalid stored session record");
+  if (format !== undefined && format !== 1)
+    throw new Error("statewire: unsupported session storage version");
+  if (legacyProtocol === undefined || format !== undefined) return value;
+  const produced = {
+    wire: { version: "2026-09-07" },
+    protocols: [legacyProtocol],
+  };
+  return {
+    ...value,
+    ...(value.context === undefined && value.ctxNextSeq > 1
+      ? {
+          context: {
+            ops: [
+              {
+                op: "mount",
+                protocol: legacyProtocol.name,
+                main: true,
+                value: {},
+              },
+            ],
+            pending: [],
+            recover: "version-1",
+          },
+        }
+      : {}),
+    commands: value.commands.map((command) =>
+      command.produced === undefined
+        ? {
+            ...command,
+            protocol: command.protocol ?? legacyProtocol.name,
+            produced,
+          }
+        : command,
+    ),
+    ...(value.failed === undefined
+      ? {}
+      : {
+          failed: value.failed.map((entry) => ({
+            ...entry,
+            protocol: entry.protocol ?? legacyProtocol.name,
+            produced: entry.produced ?? produced,
+          })),
+        }),
+  };
+};
+
+const active = new WeakMap<
+  KeyValueSessionStorage.Backend,
+  Map<string, number>
+>();
+
+const sweep = async (
+  options: KeyValueSessionStorage.Options,
+  currentKey: string,
+  quota = false,
+) => {
+  const { backend, retention, namespace = "" } = options;
+  if (!retention || !backend.getAllKeys) return;
+  const entries: { key: string; savedAt: number }[] = [];
+  const candidate = (raw: string | null) => {
+    if (raw === null) return undefined;
+    let value: unknown;
+    try {
+      value = JSON.parse(raw);
+    } catch {
+      return undefined;
+    }
+    const format = isRecord(value)
+      ? value["statewireStorageVersion"]
+      : undefined;
+    if (format !== undefined && format !== 1) return undefined;
+    if (
+      !isSessionRecord(value) ||
+      value.commands.length ||
+      value.failed?.length ||
+      value.context?.pending.length
+    )
+      return undefined;
+    const savedAt =
+      (value as Record<string, unknown>)["savedAt"] ??
+      (value as Record<string, unknown>)["updatedAt"];
+    return typeof savedAt === "number" && Number.isFinite(savedAt)
+      ? savedAt
+      : undefined;
+  };
+  for (const key of await backend.getAllKeys()) {
+    if (
+      !key.startsWith(namespace) ||
+      key === currentKey ||
+      active.get(backend)?.has(key)
+    )
+      continue;
+    const savedAt = candidate(await backend.getItem(key));
+    if (savedAt !== undefined) entries.push({ key, savedAt });
+  }
+  entries.sort((a, b) => b.savedAt - a.savedAt);
+  const now = Date.now();
+  let retained = 1;
+  const quotaStart = Math.floor(entries.length / 2);
+  for (const [index, entry] of entries.entries()) {
+    const expired =
+      retention.maxAgeMs !== undefined &&
+      now - entry.savedAt > retention.maxAgeMs;
+    const overflow =
+      retention.maxEntries !== undefined && retained >= retention.maxEntries;
+    if (expired || overflow || (quota && index >= quotaStart)) {
+      const remove = async () => {
+        if (active.get(backend)?.has(entry.key)) return;
+        if (candidate(await backend.getItem(entry.key)) !== entry.savedAt)
+          return;
+        if (active.get(backend)?.has(entry.key)) return;
+        await backend.removeItem(entry.key);
+      };
+      if (backend.withUnused) await backend.withUnused(entry.key, remove);
+      else await remove();
+    } else retained++;
+  }
+};
+
+const isQuotaError = (error: unknown) =>
+  error instanceof Error && error.name === "QuotaExceededError";
+
+const useKeyValueSessionStorage = (
+  options: KeyValueSessionStorage.Options,
+): StatewireClient.SessionStorage => {
+  const {
+    backend,
+    key,
+    namespace = "",
+    legacyProtocol: suppliedLegacyProtocol,
+    migrate,
+    retention: suppliedRetention,
+    onError,
+  } = options;
+  const latestErrorHandler = useRef(onError);
+  latestErrorHandler.current = onError;
+  const reportError = useMemo(
+    () => (error: unknown) => latestErrorHandler.current?.(error),
+    [],
+  );
+  const legacyName = suppliedLegacyProtocol?.name;
+  const legacyVersion = suppliedLegacyProtocol?.version;
+  const legacyProtocol = useMemo(
+    () =>
+      legacyName === undefined
+        ? undefined
+        : { name: legacyName, version: legacyVersion! },
+    [legacyName, legacyVersion],
+  );
+  const retain = suppliedRetention !== undefined;
+  const maxAgeMs = suppliedRetention?.maxAgeMs;
+  const maxEntries = suppliedRetention?.maxEntries;
+  const retention = useMemo(
+    () =>
+      retain
+        ? {
+            ...(maxAgeMs === undefined ? {} : { maxAgeMs }),
+            ...(maxEntries === undefined ? {} : { maxEntries }),
+          }
+        : undefined,
+    [retain, maxAgeMs, maxEntries],
+  );
+  const configured = useMemo(
+    () => ({
+      backend,
+      key,
+      namespace,
+      ...(retention === undefined ? {} : { retention }),
+    }),
+    [backend, key, namespace, retention],
+  );
+  const storageKey = namespace + key;
+  if (legacyProtocol !== undefined)
+    negotiationHeaders({ applicationProtocols: [legacyProtocol] });
+  if (retention !== undefined) {
+    if (!namespace)
+      throw new Error("statewire: session retention requires a namespace");
+    if (!backend.getAllKeys)
+      throw new Error("statewire: session retention requires getAllKeys");
+    if (
+      retention.maxAgeMs !== undefined &&
+      (!Number.isFinite(retention.maxAgeMs) || retention.maxAgeMs < 0)
+    )
+      throw new Error("statewire: invalid session retention maxAgeMs");
+    if (
+      retention.maxEntries !== undefined &&
+      (!Number.isSafeInteger(retention.maxEntries) || retention.maxEntries < 1)
+    )
+      throw new Error("statewire: invalid session retention maxEntries");
+  }
+  const state = useMemo(() => {
+    let raw: string | null | Promise<string | null>;
+    try {
+      raw = backend.getItem(storageKey);
+    } catch (cause) {
+      const error = wrapStorageError(cause);
+      reportError(error);
+      throw error;
+    }
+    const state = {
+      record: null as StatewireClient.SessionRecord | null,
+      ready: undefined as Promise<void> | undefined,
+      queue: Promise.resolve(),
+      pending: 0,
+      failure: undefined as unknown,
+      asynchronous: typeof raw !== "string" && raw !== null,
+      hydrated: typeof raw === "string" || raw === null,
+    };
+    if (state.asynchronous) {
+      state.ready = Promise.resolve(raw)
+        .then((value) => {
+          state.record = decode(value, legacyProtocol);
+          state.hydrated = true;
+        })
+        .catch((cause: unknown) => {
+          const error = wrapStorageError(cause);
+          if (state.failure !== error) reportError(error);
+          state.failure = error;
+          throw error;
+        });
+      state.ready.catch(() => {});
+    } else {
+      try {
+        state.record = decode(raw as string | null, legacyProtocol);
+      } catch (cause) {
+        const error = wrapStorageError(cause);
+        reportError(error);
+        throw error;
+      }
+    }
+    return state;
+  }, [backend, storageKey, legacyProtocol, reportError]);
+
+  useEffect(() => {
+    const entries = active.get(backend) ?? new Map<string, number>();
+    active.set(backend, entries);
+    entries.set(storageKey, (entries.get(storageKey) ?? 0) + 1);
+    return () => {
+      const count = entries.get(storageKey)! - 1;
+      if (count === 0) entries.delete(storageKey);
+      else entries.set(storageKey, count);
+    };
+  }, [backend, storageKey]);
+
+  useEffect(() => {
+    if (retention !== undefined)
+      void sweep(configured, storageKey).catch((cause: unknown) => {
+        const error = wrapStorageError(cause);
+        state.failure = error;
+        reportError(error);
+      });
+  }, [state, configured, storageKey, retention, reportError]);
+
+  return useMemo(
+    () => ({
+      ...(state.ready === undefined ? {} : { ready: state.ready }),
+      load: () => {
+        if (state.failure !== undefined) throw state.failure;
+        if (!state.hydrated)
+          throw new Error(
+            "statewire: await session storage readiness before loading",
+          );
+        if (state.asynchronous || state.pending > 0) return state.record;
+        let raw: string | null | Promise<string | null>;
+        try {
+          raw = backend.getItem(storageKey);
+        } catch (cause) {
+          const error = wrapStorageError(cause);
+          reportError(error);
+          throw error;
+        }
+        if (typeof raw !== "string" && raw !== null)
+          throw new Error(
+            "statewire: storage backend changed from synchronous to asynchronous",
+          );
+        try {
+          return decode(raw, legacyProtocol);
+        } catch (cause) {
+          const error = wrapStorageError(cause);
+          reportError(error);
+          throw error;
+        }
+      },
+      save: (record: StatewireClient.SessionRecord) => {
+        if (state.failure !== undefined) throw state.failure;
+        if (!state.hydrated)
+          throw new Error(
+            "statewire: await session storage readiness before saving",
+          );
+        if (!isSessionRecord(record))
+          throw new Error("statewire: invalid session record");
+        const encoded = JSON.stringify({
+          ...record,
+          statewireStorageVersion: 1,
+          savedAt: Date.now(),
+        });
+        state.record = record;
+        const recoverQuota = async (error: unknown) => {
+          if (!isQuotaError(error) || retention === undefined) throw error;
+          await sweep(configured, storageKey, true);
+          await backend.setItem(storageKey, encoded);
+        };
+        const write = async () => {
+          try {
+            await backend.setItem(storageKey, encoded);
+          } catch (error) {
+            await recoverQuota(error);
+          }
+        };
+        if (!state.asynchronous && state.pending === 0) {
+          let result: void | Promise<void>;
+          try {
+            result = backend.setItem(storageKey, encoded);
+          } catch (error) {
+            if (!isQuotaError(error) || retention === undefined) {
+              state.failure = wrapStorageError(error);
+              reportError(state.failure);
+              throw state.failure;
+            }
+            result = recoverQuota(error);
+          }
+          if (result === undefined) return;
+          state.pending++;
+          state.queue = result;
+        } else {
+          state.pending++;
+          state.queue = state.queue.then(() => state.ready).then(write);
+        }
+        state.queue = state.queue
+          .catch((cause: unknown) => {
+            const error = wrapStorageError(cause);
+            if (state.failure !== error) reportError(error);
+            state.failure = error;
+            throw error;
+          })
+          .finally(() => {
+            state.pending--;
+          });
+        state.queue.catch(() => {});
+      },
+      flush: () => {
+        if (state.failure !== undefined) throw state.failure;
+        if (!state.asynchronous && state.pending === 0) return;
+        return (async () => {
+          await state.ready;
+          for (;;) {
+            const queue = state.queue;
+            await queue;
+            if (queue === state.queue) return;
+          }
+        })();
+      },
+      ...(migrate === undefined ? {} : { migrate }),
+    }),
+    [
+      state,
+      backend,
+      storageKey,
+      legacyProtocol,
+      migrate,
+      retention,
+      configured,
+      reportError,
+    ],
+  );
+};
+
+/** Persist sessions through a synchronous or asynchronous string storage backend. */
+export const KeyValueSessionStorage = resource(useKeyValueSessionStorage);
+
+export namespace KeyValueSessionStorage {
+  export type Backend = {
+    getItem: (key: string) => string | null | Promise<string | null>;
+    setItem: (key: string, value: string) => void | Promise<void>;
+    removeItem: (key: string) => void | Promise<void>;
+    getAllKeys?: () => readonly string[] | Promise<readonly string[]>;
+    /** Runs cleanup under exclusive access, skipping keys in use by another runtime. */
+    withUnused?: (key: string, action: () => Promise<void>) => Promise<void>;
+  };
+  export type Options = {
+    backend: Backend;
+    key: string;
+    namespace?: string;
+    /** The application format used by sessions saved before version negotiation. */
+    legacyProtocol?: { name: string; version: string };
+    migrate?: StatewireClient.SessionStorage["migrate"];
+    retention?: { maxAgeMs?: number; maxEntries?: number };
+    onError?: (error: unknown) => void;
+  };
+}

package/src/transports/sse.ts

@@ -30,6 +30,7 @@ export type StatewireFrame = {
 };
 
 export type StatewireRemoteProps = {
+  beforeAttach?: () => void | Promise<void>;
   clientId: string;
   /** Lanes to ride the attach frame (no-lease supersession only); records the included seqs. */
   takeAttachLanes: () => StatewireFrame | null;
@@ -52,6 +53,7 @@ export type ConnectionState = StatewireClient.ConnectionState;
 
 /** The live wire a remote session drives: connection status plus frame submission. */
 export type RemoteLink = {
+  storageFailed: (error: Error) => void;
   connection: StatewireClient.Connection;
   /** A deferred first attach still waiting; `reconnect()` releases it. */
   parked: boolean;
@@ -118,6 +120,9 @@ const attemptStream = async (
   options: StatewireClient.HttpOptions,
   abort: AbortController,
 ): Promise<AttemptOutcome> => {
+  const persistence = c.ctx.beforeAttach?.();
+  if (persistence) await persistence;
+  if (abort.signal.aborted) return "ended";
   c.lease = null;
   const headers = await resolveHeaders(options.headers, c.authStale);
   for (const [name, value] of Object.entries(negotiationHeaders(options))) {