statewire 0.10.0 → 0.11.0

package/src/client/session.ts

@@ -73,11 +73,18 @@ export type StatewireSessionOptions = {
   onDone?: (() => void) | undefined;
 };
 
+type Shared = {
+  txq: Promise<void>;
+  parked: StatewireClient.SessionVerdict[];
+  unsubscribe: (() => void) | null;
+};
+
 type Session = {
   record: StatewireClient.SessionRecord;
   ctx: StatewireRemoteProps;
   recordPersisted: boolean;
   store: StatewireClient.SessionStorage;
+  shared: Shared | false;
   ephemeral: boolean;
   /** An ephemeral record died with its attach: the storage is off for good. */
   deactivated: boolean;
@@ -144,15 +151,68 @@ const backlog = (s: Session): StatewireClient.SessionCommand[] =>
     .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 syncBacklog = (s: Session) => {
-  const commands = backlog(s);
+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 });
+  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) => {
@@ -248,11 +308,40 @@ const resetRecord = (s: Session, clientId: string) => {
   setRecord(s, { clientId, nextSeq: 1, ctxNextSeq: 1, commands: [] });
   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);
+};
+
+// 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);
+    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.
@@ -272,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");
@@ -288,37 +430,30 @@ 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[]) => {
@@ -353,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 =
@@ -382,23 +517,34 @@ const handleHello = (
   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);
-    syncBacklog(s);
-  } 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 = (
@@ -451,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);
 };
@@ -536,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;
@@ -580,17 +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);
   }
-  resume(s);
+  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");
 };
@@ -601,7 +773,7 @@ const setTransport = (s: Session, transport: RemoteLink) => {
   wake(s);
 };
 
-const enqueue = (
+const enqueueInner = (
   s: Session,
   command: WireCommand,
   params: readonly unknown[],
@@ -626,15 +798,33 @@ const enqueue = (
     reject,
   };
   s.pending.push(entry);
-  setRecord(s, { ...s.record, nextSeq: seq + 1, commands: backlog(s) });
+  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 resume = (s: Session) => {
-  const stored = [...s.record.commands].sort((a, b) => a.seq - b.seq);
+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
@@ -659,6 +849,7 @@ const resume = (s: Session) => {
     s.pending.push(entry);
     s.lifecycle?.onStart(entry.inv);
   }
+  s.pending.sort((a, b) => a.seq - b.seq);
 };
 
 const sendCommand = (
@@ -690,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: [],
@@ -699,11 +891,22 @@ 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 = (
@@ -717,6 +920,11 @@ export const useStatewireSession = (
     );
   }
   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)) {
@@ -747,6 +955,10 @@ export const useStatewireSession = (
       },
       recordPersisted: stored !== null,
       store,
+      shared:
+        store.lock !== undefined
+          ? { txq: Promise.resolve(), parked: [], unsubscribe: null }
+          : false,
       ephemeral: false,
       deactivated: false,
       sessionKnown: false,

package/src/statewire.ts

@@ -261,12 +261,28 @@ export namespace StatewireClient {
     nextSeq: number;
     ctxNextSeq: number;
     commands: readonly SessionCommand[];
+    /** Terminal verdicts parked for the sharer that minted the seq (shared storage only). */
+    verdicts?: readonly SessionVerdict[];
+  };
+
+  /** A terminal verdict one sharer's connection carried, parked for the sharer awaiting the seq. */
+  export type SessionVerdict = {
+    seq: number;
+    type: "result" | "rejected" | "failed" | "crashed" | "expired";
+    code?: string;
+    message?: string;
+    payload?: unknown;
+    meta?: unknown;
   };
 
   /** Session storage seam; `save` must persist synchronously in the caller's flow. */
   export type SessionStorage = {
     load: () => SessionRecord | null;
     save: (record: SessionRecord) => void;
+    /** Serializes record mutations across sharers; presence marks the storage shared. */
+    lock?: <T>(fn: () => T | Promise<T>) => Promise<T>;
+    /** Notifies of record saves by other sharers; returns unsubscribe. Required alongside `lock`. */
+    subscribe?: (listener: () => void) => () => void;
   };
 
   /** Static headers, or a resolver invoked per request/attach; `staleAuth` is true right after an auth rejection. */