statewire 0.9.2 → 0.11.0

package/src/client/session.ts

@@ -1,17 +1,20 @@
-import { useEffect, useState } from "react";
+import { useContext, useEffect, useState } from "react";
 import { applyOps } from "../wire/ops";
 import type { StatewirePath } from "../wire/ops";
 import type { StatewireCmd, StatewireSyn } from "./connection";
-import { encodeParams, encodeValue, reviveResponse } from "../wire/meta";
+import {
+  encodeParams,
+  encodeValue,
+  reviveResponse,
+  reviveValue,
+} from "../wire/meta";
 import { bindCommandsHost } from "../host/host";
 import type { CommandsInvocation, CommandsListener } from "../host/host";
 import type { Statewire } from "../types";
 import type { StatewireClient } from "../statewire";
-import { createMemorySessionStore } from "./sessionStore";
-import type {
-  StatewireSessionRecord,
-  StatewireSessionStore,
-  StatewireSessionStoreOptions,
+import {
+  SessionStorageContext,
+  createMemorySessionStore,
 } from "./sessionStore";
 import { backoff } from "./timing";
 import { createMethodProxy } from "../util/methodProxy";
@@ -65,16 +68,26 @@ const rejectedSend = (
 
 type AttachState = "detached" | "attached" | "finished";
 
-export type StatewireSessionOptions = StatewireSessionStoreOptions & {
+export type StatewireSessionOptions = {
+  sessionStore?: StatewireClient.SessionStorage | undefined;
   onDone?: (() => void) | undefined;
 };
 
+type Shared = {
+  txq: Promise<void>;
+  parked: StatewireClient.SessionVerdict[];
+  unsubscribe: (() => void) | null;
+};
+
 type Session = {
-  record: StatewireSessionRecord;
+  record: StatewireClient.SessionRecord;
   ctx: StatewireRemoteProps;
   recordPersisted: boolean;
-  store: StatewireSessionStore;
+  store: StatewireClient.SessionStorage;
+  shared: Shared | false;
   ephemeral: boolean;
+  /** An ephemeral record died with its attach: the storage is off for good. */
+  deactivated: boolean;
   sessionKnown: boolean;
   durableSeq: number;
   resumeAt: number;
@@ -128,9 +141,78 @@ const sleepUntilWake = (s: Session, delayMs: number) =>
     s.waiters.push(waiter);
   });
 
-const setRecord = (s: Session, record: StatewireSessionRecord) => {
+const setRecord = (s: Session, record: StatewireClient.SessionRecord) => {
   s.record = record;
-  if (!s.ephemeral) s.store.save(record);
+  if (!s.deactivated) s.store.save(record);
+};
+
+const backlog = (s: Session): StatewireClient.SessionCommand[] =>
+  s.pending
+    .filter((p) => p.seq > s.durableSeq)
+    .map((p) => ({ seq: p.seq, ...p.command }));
+
+const mergeBacklog = (s: Session): StatewireClient.SessionCommand[] => {
+  const own = backlog(s);
+  if (!s.shared) return own;
+  const known = new Set(s.pending.map((p) => p.seq));
+  const foreign = s.record.commands.filter(
+    (c) => !known.has(c.seq) && c.seq > s.durableSeq,
+  );
+  return [...foreign, ...own].sort((a, b) => a.seq - b.seq);
+};
+
+const MAX_PARKED_VERDICTS = 64;
+
+// Storage holds what a reload must resend: a command leaves at its dur, at a
+// server verdict, or at a record reset — never at a local channel death.
+const syncBacklogInner = (s: Session) => {
+  const parked = s.shared ? s.shared.parked.splice(0) : [];
+  const parkedSeqs = new Set(parked.map((v) => v.seq));
+  const commands = mergeBacklog(s).filter((c) => !parkedSeqs.has(c.seq));
+  const verdicts =
+    parked.length > 0
+      ? [...(s.record.verdicts ?? []), ...parked].slice(-MAX_PARKED_VERDICTS)
+      : s.record.verdicts;
+  const unchanged =
+    verdicts === s.record.verdicts &&
+    commands.length === s.record.commands.length &&
+    commands.every((c, i) => c.seq === s.record.commands[i]!.seq);
+  if (unchanged) return;
+  setRecord(s, {
+    ...s.record,
+    commands,
+    ...(verdicts !== undefined && { verdicts }),
+  });
+};
+
+const syncBacklog = (s: Session) => {
+  if (!s.shared) return syncBacklogInner(s);
+  void transact(s, () => syncBacklogInner(s));
+};
+
+// Every record mutation over shared storage is a locked read-modify-write.
+const transact = (s: Session, fn: () => void): Promise<void> => {
+  if (!s.shared || s.deactivated) {
+    fn();
+    return Promise.resolve();
+  }
+  const shared = s.shared;
+  const run = shared.txq.then(() =>
+    s.store.lock!(async () => {
+      const stored = s.store.load();
+      if (stored !== null && stored.clientId !== s.record.clientId) {
+        adoptReset(s, stored);
+      } else if (stored !== null) {
+        s.record = stored;
+      }
+      fn();
+    }),
+  );
+  shared.txq = run.then(
+    () => {},
+    () => {},
+  );
+  return run;
 };
 
 const setIdle = (s: Session, level: boolean) => {
@@ -223,14 +305,43 @@ const resetRecord = (s: Session, clientId: string) => {
   }
   s.pending = [];
   s.durableSeq = 0;
-  setRecord(s, { clientId, nextSeq: 1, ctxNextSeq: 1 });
+  setRecord(s, { clientId, nextSeq: 1, ctxNextSeq: 1, commands: [] });
+  for (const old of survivors) {
+    s.lifecycle?.onCovered?.(old.inv);
+    enqueueInner(s, old.command, old.inv.params, old.resolve, old.reject);
+  }
+  restateContext(s);
+  publish(s);
+  wake(s);
+  void pump(s);
+};
+
+// Another sharer replaced the record's identity: their reset settles our
+// attempted history and our survivors re-stamp on the stored clocks.
+const adoptReset = (s: Session, stored: StatewireClient.SessionRecord) => {
+  const survivors: Pending[] = [];
+  for (const entry of [...s.pending]) {
+    if (entry.attempted || entry.applied) {
+      s.lifecycle?.onCovered?.(entry.inv);
+      settleEntry(s, entry, {
+        ok: false,
+        failure: { fate: "lost", cause: "session-lost" },
+      });
+    } else {
+      survivors.push(entry);
+    }
+  }
+  s.pending = [];
+  s.durableSeq = 0;
+  s.record = stored;
   for (const old of survivors) {
     s.lifecycle?.onCovered?.(old.inv);
-    enqueue(s, old.command, old.inv.params, old.resolve, old.reject);
+    enqueueInner(s, old.command, old.inv.params, old.resolve, old.reject);
   }
   restateContext(s);
   publish(s);
   wake(s);
+  void pump(s);
 };
 
 // The record died with the attach: mint a fresh id for the next one.
@@ -250,6 +361,59 @@ const rejectedFailure = (cmd: StatewireCmd): StatewireClient.SendFailure => {
   };
 };
 
+const outcomeOf = (
+  cmd: StatewireCmd,
+):
+  | { ok: true; payload: unknown }
+  | { ok: false; failure: StatewireClient.SendFailure } =>
+  cmd.type === "result"
+    ? { ok: true as const, payload: reviveResponse(cmd).payload }
+    : cmd.type === "rejected"
+      ? { ok: false as const, failure: rejectedFailure(reviveResponse(cmd)) }
+      : cmd.type === "failed"
+        ? {
+            ok: false as const,
+            failure: {
+              fate: "failed" as const,
+              cause: "server" as const,
+              ...(cmd.message !== undefined && { message: cmd.message }),
+            },
+          }
+        : cmd.type === "crashed"
+          ? {
+              ok: false as const,
+              failure: { fate: "crashed" as const, cause: "server" as const },
+            }
+          : cmd.type === "expired"
+            ? {
+                ok: false as const,
+                failure: {
+                  fate: "expired" as const,
+                  cause: "server" as const,
+                },
+              }
+            : protocolError(`unknown cmd type: ${String(cmd.type)}`);
+
+const TERMINAL_CMD_TYPES = new Set([
+  "result",
+  "rejected",
+  "failed",
+  "crashed",
+  "expired",
+]);
+
+const parkVerdict = (s: Session, cmd: StatewireCmd) => {
+  if (!s.shared || !TERMINAL_CMD_TYPES.has(cmd.type!)) return;
+  s.shared.parked.push({
+    seq: cmd.seq,
+    type: cmd.type as StatewireClient.SessionVerdict["type"],
+    ...(cmd.code !== undefined && { code: cmd.code }),
+    ...(cmd.message !== undefined && { message: cmd.message }),
+    ...(cmd.payload !== undefined && { payload: cmd.payload }),
+    ...(cmd.meta !== undefined && { meta: cmd.meta }),
+  });
+};
+
 const handleCmd = (s: Session, cmd: StatewireCmd) => {
   if (!Number.isSafeInteger(cmd.seq) || cmd.seq <= 0) {
     protocolError("cmd.seq must be a positive safe integer");
@@ -266,41 +430,35 @@ const handleCmd = (s: Session, cmd: StatewireCmd) => {
     if (entry) cover(s, entry);
     return;
   }
+  parkVerdict(s, cmd);
   if (!entry) return;
   cover(s, entry);
-  const outcome =
-    cmd.type === "result"
-      ? { ok: true as const, payload: reviveResponse(cmd).payload }
-      : cmd.type === "rejected"
-        ? { ok: false as const, failure: rejectedFailure(reviveResponse(cmd)) }
-        : cmd.type === "failed"
-          ? {
-              ok: false as const,
-              failure: {
-                fate: "failed" as const,
-                cause: "server" as const,
-                ...(cmd.message !== undefined && { message: cmd.message }),
-              },
-            }
-          : cmd.type === "crashed"
-            ? {
-                ok: false as const,
-                failure: { fate: "crashed" as const, cause: "server" as const },
-              }
-            : cmd.type === "expired"
-              ? {
-                  ok: false as const,
-                  failure: {
-                    fate: "expired" as const,
-                    cause: "server" as const,
-                  },
-                }
-              : protocolError(`unknown cmd type: ${String(cmd.type)}`);
-  settleEntry(s, entry, outcome);
+  settleEntry(s, entry, outcomeOf(cmd));
+};
+
+const consumeVerdicts = (s: Session) => {
+  const verdicts = s.record.verdicts ?? [];
+  const consumed = new Set<number>();
+  for (const verdict of verdicts) {
+    const entry = s.pending.find((p) => p.seq === verdict.seq);
+    if (!entry) continue;
+    consumed.add(verdict.seq);
+    cover(s, entry);
+    settleEntry(s, entry, outcomeOf(verdict as StatewireCmd));
+  }
+  if (consumed.size === 0) return;
+  setRecord(s, {
+    ...s.record,
+    commands: s.record.commands.filter((c) => !consumed.has(c.seq)),
+    verdicts: verdicts.filter((v) => !consumed.has(v.seq)),
+  });
+  publish(s);
+  wake(s);
 };
 
 const handleCmds = (s: Session, cmds: StatewireCmd[]) => {
   for (const cmd of cmds) handleCmd(s, cmd);
+  syncBacklog(s);
   wake(s);
 };
 
@@ -330,7 +488,7 @@ const snapClocks = (s: Session, seqWm: number, ctxWm: number) => {
     setRecord(s, { ...s.record, nextSeq: seqWm + 1 });
     for (const old of tail) {
       s.lifecycle?.onCovered?.(old.inv);
-      enqueue(s, old.command, old.inv.params, old.resolve, old.reject);
+      enqueueInner(s, old.command, old.inv.params, old.resolve, old.reject);
     }
   }
   const ctxAligned =
@@ -356,24 +514,37 @@ const handleHello = (
   s.frameFailures = 0;
   s.resumeAt = 0;
   s.ephemeral = record === "ephemeral";
+  if (s.ephemeral) s.deactivated = true;
   const [attachCmd, attachCtx] = s.attachLaneSeqs;
   s.attachLaneSeqs = [new Set(), new Set()];
-  if (record === "resumed") {
-    // Resending unsettled statements is exactly-once-safe: absorbed replays
-    // re-emit their stored verdicts (applied while still in flight).
-    for (const entry of s.pending) {
-      entry.posted = attachCmd.has(entry.seq);
+  const reconcile = () => {
+    if (record === "resumed") {
+      if (s.shared) adoptStored(s);
+      // Resending unsettled statements is exactly-once-safe: absorbed replays
+      // re-emit their stored verdicts (applied while still in flight).
+      for (const entry of s.pending) {
+        entry.posted = attachCmd.has(entry.seq);
+      }
+      const ctxWatermark = syn.ctxSeq ?? 0;
+      s.ctxPending = s.ctxPending.filter((c) => c.seq > ctxWatermark);
+      for (const c of s.ctxPending) c.posted = attachCtx.has(c.seq);
+      snapClocks(s, syn.seq ?? 0, ctxWatermark);
+      syncBacklogInner(s);
+    } else {
+      resetRecord(s, s.record.clientId);
     }
-    const ctxWatermark = syn.ctxSeq ?? 0;
-    s.ctxPending = s.ctxPending.filter((c) => c.seq > ctxWatermark);
-    for (const c of s.ctxPending) c.posted = attachCtx.has(c.seq);
-    snapClocks(s, syn.seq ?? 0, ctxWatermark);
-  } else {
-    resetRecord(s, s.record.clientId);
+    s.sessionKnown = true;
+  };
+  if (!s.shared || s.deactivated) {
+    reconcile();
+    publishIngested(s);
+    void pump(s);
+    return;
   }
-  s.sessionKnown = true;
-  publishIngested(s);
-  void pump(s);
+  void transact(s, reconcile).then(() => {
+    publishIngested(s);
+    void pump(s);
+  });
 };
 
 const handleOps = (
@@ -382,6 +553,7 @@ const handleOps = (
 ) => {
   ingestOps(s, ops);
   for (const cmd of cmds) handleCmd(s, cmd);
+  syncBacklog(s);
   publishIngested(s);
 };
 
@@ -425,7 +597,11 @@ const handleDetach = (s: Session) => {
 const handleFinish = (s: Session, { reason }: { reason: string }) => {
   if (reason === "evicted" || reason === "error") return;
   s.attach = "finished";
-  settleAll(s, reason === "superseded" ? "superseded" : "gone");
+  // Superseded over shared storage: the superseder resends our backlog and
+  // parks the verdicts; our promises settle from the observed record.
+  if (!(s.shared && reason === "superseded")) {
+    settleAll(s, reason === "superseded" ? "superseded" : "gone");
+  }
   publish(s);
   wake(s);
 };
@@ -510,7 +686,12 @@ const pump = async (s: Session) => {
       for (const entry of lanes.cmdEntries) entry.attempted = true;
       let result;
       try {
-        result = await transport.send(lanes.frame);
+        // Shared storage: the lock across the send keeps per-lane arrival
+        // ordered across sharers during attach handover.
+        const send = () => transport.send(lanes.frame);
+        result = await (s.shared && !s.deactivated
+          ? s.store.lock!(send)
+          : send());
       } catch {
         if (!s.running || isFinished(s)) return;
         s.frameFailures += 1;
@@ -554,16 +735,34 @@ const pump = async (s: Session) => {
 };
 
 const start = (s: Session) => {
+  if (s.shared) {
+    s.shared.unsubscribe = s.store.subscribe!(() => {
+      void transact(s, () => consumeVerdicts(s));
+    });
+    s.running = true;
+    void transact(s, () => {
+      if (s.store.load() === null) s.store.save(s.record);
+      s.recordPersisted = true;
+      adoptStored(s);
+      consumeVerdicts(s);
+    }).then(() => void pump(s));
+    return;
+  }
   if (!s.recordPersisted) {
     s.recordPersisted = true;
     s.store.save(s.record);
   }
+  adoptStored(s);
   s.running = true;
   void pump(s);
 };
 
 const stop = (s: Session) => {
   s.running = false;
+  if (s.shared) {
+    s.shared.unsubscribe?.();
+    s.shared.unsubscribe = null;
+  }
   wake(s);
   settleAll(s, "unmount");
 };
@@ -574,7 +773,7 @@ const setTransport = (s: Session, transport: RemoteLink) => {
   wake(s);
 };
 
-const enqueue = (
+const enqueueInner = (
   s: Session,
   command: WireCommand,
   params: readonly unknown[],
@@ -582,7 +781,6 @@ const enqueue = (
   reject: (error: StatewireSendError) => void,
 ) => {
   const seq = s.record.nextSeq;
-  setRecord(s, { ...s.record, nextSeq: seq + 1 });
   const entry: Pending = {
     seq,
     command,
@@ -600,8 +798,58 @@ const enqueue = (
     reject,
   };
   s.pending.push(entry);
+  setRecord(s, { ...s.record, nextSeq: seq + 1, commands: mergeBacklog(s) });
   s.lifecycle?.onStart(entry.inv);
-  void pump(s);
+};
+
+const enqueue = (
+  s: Session,
+  command: WireCommand,
+  params: readonly unknown[],
+  resolve: (payload: unknown) => void,
+  reject: (error: StatewireSendError) => void,
+) => {
+  if (!s.shared) {
+    enqueueInner(s, command, params, resolve, reject);
+    void pump(s);
+    return;
+  }
+  void transact(s, () =>
+    enqueueInner(s, command, params, resolve, reject),
+  ).then(() => void pump(s));
+};
+
+// A stored command cannot be told from one that reached the server: attempted
+// keeps a fresh record settling it lost instead of replaying it blind.
+const adoptStored = (s: Session) => {
+  const known = new Set(s.pending.map((p) => p.seq));
+  const stored = s.record.commands.filter((c) => !known.has(c.seq));
+  if (stored.length === 0) return;
+  for (const { seq, ...command } of stored) {
+    const params =
+      command.meta === undefined
+        ? command.params
+        : (reviveValue([...command.params], command.meta) as unknown[]);
+    const entry: Pending = {
+      seq,
+      command,
+      inv: {
+        method: command.method,
+        params,
+        ts: Date.now(),
+        seq,
+        clientId: s.record.clientId,
+      },
+      attempted: true,
+      posted: false,
+      applied: false,
+      resolve: () => {},
+      reject: () => {},
+    };
+    s.pending.push(entry);
+    s.lifecycle?.onStart(entry.inv);
+  }
+  s.pending.sort((a, b) => a.seq - b.seq);
 };
 
 const sendCommand = (
@@ -633,8 +881,9 @@ const setContext = (s: Session, value: Record<string, unknown>): void => {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     throw new Error("statewire: context must be a plain object");
   }
+  if (!s.running || isFinished(s)) return;
   const { value: encoded, meta } = encodeValue(value);
-  s.ctxOps = [
+  const ops = [
     {
       op: "replace",
       path: [],
@@ -642,24 +891,52 @@ const setContext = (s: Session, value: Record<string, unknown>): void => {
       ...(meta !== undefined && { meta }),
     },
   ];
-  const seq = s.record.ctxNextSeq;
-  setRecord(s, { ...s.record, ctxNextSeq: seq + 1 });
-  s.ctxPending.push({ seq, ops: s.ctxOps, posted: false });
-  wake(s);
-  void pump(s);
+  s.ctxOps = ops;
+  const mint = () => {
+    const seq = s.record.ctxNextSeq;
+    setRecord(s, { ...s.record, ctxNextSeq: seq + 1 });
+    s.ctxPending.push({ seq, ops, posted: false });
+  };
+  if (!s.shared) {
+    mint();
+    wake(s);
+    void pump(s);
+    return;
+  }
+  void transact(s, mint).then(() => {
+    wake(s);
+    void pump(s);
+  });
 };
 
 export const useStatewireSession = (
   options: StatewireSessionOptions,
 ): Session => {
   const [defaultStore] = useState(createMemorySessionStore);
-  const store = options.sessionStore ?? defaultStore;
+  const mounted = useContext(SessionStorageContext);
+  if (options.sessionStore !== undefined && mounted !== undefined) {
+    throw new Error(
+      "statewire: session storage is set twice — drop the transport's sessionStore or the client's storage.session",
+    );
+  }
+  const store = options.sessionStore ?? mounted ?? defaultStore;
+  if ((store.lock === undefined) !== (store.subscribe === undefined)) {
+    throw new Error(
+      "statewire: session storage must provide lock and subscribe together",
+    );
+  }
   const [s] = useState((): Session => {
     const stored = store.load();
+    if (stored !== null && !Array.isArray(stored.commands)) {
+      throw new Error(
+        "statewire: session storage loaded a record without a commands array",
+      );
+    }
     const record = stored ?? {
       clientId: newClientId(),
       nextSeq: 1,
       ctxNextSeq: 1,
+      commands: [],
     };
     const session: Session = {
       record,
@@ -678,7 +955,12 @@ export const useStatewireSession = (
       },
       recordPersisted: stored !== null,
       store,
+      shared:
+        store.lock !== undefined
+          ? { txq: Promise.resolve(), parked: [], unsubscribe: null }
+          : false,
       ephemeral: false,
+      deactivated: false,
       sessionKnown: false,
       durableSeq: 0,
       resumeAt: 0,

package/src/client/sessionStore.ts

@@ -1,20 +1,13 @@
-export type StatewireSessionRecord = {
-  clientId: string;
-  nextSeq: number;
-  ctxNextSeq: number;
-};
-
-export type StatewireSessionStore = {
-  load: () => StatewireSessionRecord | null;
-  save: (record: StatewireSessionRecord) => void;
-};
+import { createContext } from "react";
+import type { StatewireClient } from "../statewire";
 
-export type StatewireSessionStoreOptions = {
-  sessionStore?: StatewireSessionStore | undefined;
-};
+/** The session storage `useStatewire` mounts, read by the transport's session. */
+export const SessionStorageContext = createContext<
+  StatewireClient.SessionStorage | undefined
+>(undefined);
 
-export const createMemorySessionStore = (): StatewireSessionStore => {
-  let record: StatewireSessionRecord | null = null;
+export const createMemorySessionStore = (): StatewireClient.SessionStorage => {
+  let record: StatewireClient.SessionRecord | null = null;
   return {
     load: () => record,
     save: (next) => {