statewire 0.16.0 → 0.17.0

package/src/client/session.ts

@@ -1,4 +1,16 @@
-import { applyDocumentOps } from "../wire/documents";
+import {
+  DEFAULT_PROTOCOL,
+  WIRE_VERSION,
+  protocolOffers,
+  inRange,
+} from "../wire/protocol";
+import type { StatewireProtocol } from "../wire/protocol";
+import {
+  applyDocumentOps,
+  mainDocument,
+  findDocument,
+  resolveDocumentKey,
+} from "../wire/documents";
 import type { StatewireDocuments } from "../wire/documents";
 import { useContext, useEffect, useState } from "react";
 
@@ -17,6 +29,7 @@ import type { CommandsInvocation, CommandsListener } from "../host/host";
 import type { Statewire } from "../types";
 import type { StatewireClient } from "../statewire";
 import {
+  DocumentStorageContext,
   SessionStorageContext,
   createMemorySessionStore,
 } from "./sessionStore";
@@ -31,6 +44,8 @@ import type {
 } from "../transports/sse";
 
 type WireCommand = {
+  protocol: string;
+  produced?: NonNullable<StatewireClient.SessionCommand["produced"]>;
   method: string;
   params: unknown[];
   meta?: unknown;
@@ -70,7 +85,7 @@ const rejectedSend = (
 
 type AttachState = "detached" | "attached" | "finished";
 
-export type StatewireSessionOptions = {
+export type StatewireSessionOptions = StatewireProtocol.Options & {
   sessionStore?: StatewireClient.SessionStorage | undefined;
   onSessionLost?: StatewireClient.OnSessionLost | undefined;
   onDone?: (() => void) | undefined;
@@ -83,10 +98,14 @@ type Shared = {
 };
 
 type Session = {
+  options: StatewireSessionOptions;
+  selection: StatewireProtocol.Selection | undefined;
+  contextDocuments: StatewireDocuments.State;
   record: StatewireClient.SessionRecord;
   ctx: StatewireRemoteProps;
   recordPersisted: boolean;
   store: StatewireClient.SessionStorage;
+  documentStore: StatewireDocuments.Storage | undefined;
   shared: Shared | false;
   ephemeral: boolean;
   /** An ephemeral record died with its attach: the storage is off for good. */
@@ -104,6 +123,7 @@ type Session = {
   frameFailures: number;
   pending: Pending[];
   canonical: unknown;
+  documentListeners: Set<() => void>;
   documents: StatewireDocuments.State;
   lastPublished: unknown;
   changed: StatewirePath[];
@@ -209,6 +229,20 @@ const transact = (s: Session, fn: () => void): Promise<void> => {
         adoptReset(s, stored);
       } else if (stored !== null) {
         s.record = stored;
+        if (stored.context !== undefined) {
+          const posted = new Set(
+            s.ctxPending.filter((p) => p.posted).map((p) => p.seq),
+          );
+          s.ctxOps = stored.context.ops;
+          s.contextDocuments = applyDocumentOps(
+            { mode: "mounted", documents: new Map() },
+            stored.context.ops,
+          );
+          s.ctxPending = stored.context.pending.map((p) => ({
+            ...p,
+            posted: posted.has(p.seq),
+          }));
+        }
       }
       fn();
     }),
@@ -250,6 +284,10 @@ const retainFailedInner = (
     failed: [
       ...(s.record.failed ?? []),
       {
+        protocol: entry.command.protocol,
+        ...(entry.command.produced !== undefined && {
+          produced: entry.command.produced,
+        }),
         command: entry.command.method,
         params: entry.command.params,
         ...(entry.command.meta !== undefined && { meta: entry.command.meta }),
@@ -462,8 +500,8 @@ const handleCmd = (s: Session, cmd: StatewireCmd) => {
     if (entry) cover(s, entry);
     return;
   }
-  parkVerdict(s, cmd);
   if (!entry) return;
+  parkVerdict(s, cmd);
   cover(s, entry);
   settleEntry(s, entry, outcomeOf(cmd));
 };
@@ -495,14 +533,50 @@ const handleCmds = (s: Session, cmds: StatewireCmd[]) => {
 };
 
 const ingestOps = (s: Session, ops: unknown[]) => {
-  const applied = applyDocumentOps(s.documents, ops);
+  const applied = applyDocumentOps(s.documents, ops, s.selection?.protocols);
   s.documents = applied;
-  s.canonical = applied.documents.get(0)?.value;
-  s.changed.push(...applied.changedPaths);
+  const next =
+    s.selection === undefined
+      ? applied.documents.get(0)?.value
+      : s.options.applicationProtocols === "*"
+        ? Object.fromEntries(
+            [...applied.documents].map(([id, d]) => [
+              `${d.protocol}:${d.key === null ? id : JSON.stringify(d.key)}`,
+              d.value,
+            ]),
+          )
+        : mainDocument(applied, s.options.protocol ?? DEFAULT_PROTOCOL)?.value;
+  if (next !== s.canonical)
+    s.changed.push(
+      ...(applied.changedPaths.length ? applied.changedPaths : [[]]),
+    );
+  s.canonical = next;
+};
+
+const cacheDocuments = (s: Session) => {
+  if (s.documentStore && s.selection) {
+    for (const document of s.documents.documents.values()) {
+      if (!document.protocol || !document.key) continue;
+      const key = resolveDocumentKey(
+        document.key,
+        s.options.keyPrefixes?.[document.protocol],
+      );
+      const version = s.selection.protocols.find(
+        (p) => p.name === document.protocol,
+      )?.version;
+      if (key !== undefined && version !== undefined)
+        s.documentStore.save(
+          [s.documentStore.namespace ?? "", document.protocol, ...key],
+          { version, value: document.value },
+        );
+    }
+  }
 };
 
 const publishIngested = (s: Session) => {
   publish(s);
+  cacheDocuments(s);
+  for (const listener of s.documentListeners) listener();
   wake(s);
 };
 
@@ -514,6 +588,10 @@ const snapCtxClock = (s: Session, ctxWm: number) => {
     s.ctxPending.every((c, i) => c.seq === ctxWm + 1 + i) &&
     s.record.ctxNextSeq === ctxWm + s.ctxPending.length + 1;
   if (!ctxAligned) {
+    if (ctxWm > 0)
+      throw new Error(
+        "statewire: context history is missing; use a new client id",
+      );
     setRecord(s, { ...s.record, ctxNextSeq: ctxWm + 1 });
     restateContext(s);
   }
@@ -531,11 +609,11 @@ const sessionLostInner = (s: Session, seqWm: number, ctxWm: number) => {
   setRecord(s, {
     clientId: s.record.clientId,
     nextSeq: seqWm + 1,
-    ctxNextSeq: ctxWm + 1,
+    ctxNextSeq: s.record.ctxNextSeq,
     commands: [],
     ...(s.record.failed !== undefined && { failed: s.record.failed }),
   });
-  restateContext(s);
+  snapCtxClock(s, ctxWm);
   if (
     held.length > 0 &&
     s.onSessionLost?.(held.map((p) => p.inv)) === "requeue"
@@ -561,6 +639,10 @@ const handleHello = (
   if (syn.record !== undefined && syn.record !== "ephemeral") {
     protocolError(`unknown record: ${String(syn.record)}`);
   }
+  s.selection =
+    syn.version === undefined || syn.protocols === undefined
+      ? undefined
+      : { version: syn.version, protocols: syn.protocols };
   s.documents = { mode: null, documents: new Map() };
   ingestOps(s, ops);
   s.attach = "attached";
@@ -583,6 +665,7 @@ const handleHello = (
     s.ctxPending = s.ctxPending.filter((c) => c.seq > ctxWatermark);
     for (const c of s.ctxPending) c.posted = attachCtx.has(c.seq);
     snapCtxClock(s, ctxWatermark);
+    if (s.ctxOps !== undefined) persistContext(s);
     syncBacklogInner(s);
     s.sessionKnown = true;
   };
@@ -620,6 +703,7 @@ const handleRefusal = (s: Session, syn: StatewireSyn) => {
   if (typeof ctxSeq === "number") {
     s.ctxPending = s.ctxPending.filter((c) => c.seq > ctxSeq);
     for (const c of s.ctxPending) c.posted = false;
+    if (s.ctxOps !== undefined) persistContext(s);
   }
   if (typeof syn.retry === "number") {
     s.resumeAt = Date.now() + syn.retry;
@@ -699,7 +783,10 @@ const buildLanes = (s: Session): Lanes | null => {
         ctx: ctxEntries.map((c) => ({ ops: c.ops, seq: c.seq })),
       }),
       ...(cmdEntries.length > 0 && {
-        cmd: cmdEntries.map((p) => ({ ...p.command, seq: p.seq })),
+        cmd: cmdEntries.map((p) => {
+          const { produced: _produced, ...command } = p.command;
+          return { ...command, seq: p.seq };
+        }),
       }),
     },
     cmdEntries,
@@ -850,6 +937,7 @@ const enqueueInner = (
     seq,
     command,
     inv: {
+      protocol: command.protocol,
       method: command.method,
       params,
       ts: Date.now(),
@@ -903,6 +991,12 @@ const adoptStored = (s: Session) => {
   const stored = s.record.commands.filter((c) => !known.has(c.seq));
   if (stored.length === 0) return;
   for (const { seq, ...command } of stored) {
+    const offers = protocolOffers(s.options);
+    if (
+      offers !== "*" &&
+      !offers.some((offer) => offer.name === command.protocol)
+    )
+      continue;
     const params =
       command.meta === undefined
         ? command.params
@@ -911,6 +1005,7 @@ const adoptStored = (s: Session) => {
       seq,
       command,
       inv: {
+        protocol: command.protocol,
         method: command.method,
         params,
         ts: Date.now(),
@@ -933,6 +1028,7 @@ const sendCommand = (
   s: Session,
   method: string,
   params: readonly unknown[],
+  protocol = s.options.protocol ?? DEFAULT_PROTOCOL,
 ): Promise<unknown> => {
   if (!s.running) {
     return rejectedSend({ fate: "aborted", cause: "unmount" });
@@ -944,7 +1040,19 @@ const sendCommand = (
     const { params: encoded, meta } = encodeParams(params);
     enqueue(
       s,
-      { method, params: encoded, ...(meta !== undefined && { meta }) },
+      {
+        protocol,
+        produced: {
+          wire: s.options.wireVersion ?? { version: WIRE_VERSION },
+          protocols:
+            protocolOffers(s.options) === "*" && s.selection
+              ? s.selection.protocols
+              : protocolOffers(s.options),
+        },
+        method,
+        params: encoded,
+        ...(meta !== undefined && { meta }),
+      },
       params,
       resolve,
       reject,
@@ -1029,6 +1137,8 @@ export const retryFailed = (
       enqueueInner(
         s,
         {
+          protocol: current.protocol,
+          ...(current.produced !== undefined && { produced: current.produced }),
           method: current.command,
           params: [...current.params],
           ...(current.meta !== undefined && { meta: current.meta }),
@@ -1053,46 +1163,181 @@ export const retryFailed = (
   return result;
 };
 
-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);
-  const ops = [
-    {
-      op: "replace",
-      path: [],
-      value: encoded,
-      ...(meta !== undefined && { meta }),
-    },
-  ];
+const contextSnapshot = (documents: StatewireDocuments.State) =>
+  [...documents.documents].map(([doc, d]) => {
+    const encoded = encodeValue(d.value);
+    return {
+      op: "mount",
+      ...(doc === 0 ? {} : { doc }),
+      protocol: d.protocol,
+      ...(d.main ? { main: true } : {}),
+      ...(d.key === null ? {} : { key: d.key }),
+      value: encoded.value,
+      ...(encoded.meta === undefined ? {} : { meta: encoded.meta }),
+    };
+  });
+
+const persistContext = (s: Session) => {
+  const ops = contextSnapshot(s.contextDocuments);
   s.ctxOps = ops;
-  const mint = () => {
+  setRecord(s, {
+    ...s.record,
+    context: {
+      ops,
+      pending: s.ctxPending.map(({ seq, ops }) => ({ seq, ops })),
+    },
+  });
+};
+
+const changeContext = (
+  s: Session,
+  build: (documents: StatewireDocuments.State) => readonly unknown[],
+): void => {
+  if (!s.running || isFinished(s)) return;
+  const submit = () => {
+    if (!s.running || isFinished(s)) return;
+    const previous =
+      s.record.context === undefined
+        ? s.contextDocuments
+        : applyDocumentOps(
+            { mode: "mounted", documents: new Map() },
+            s.record.context.ops,
+          );
+    const operations = build(previous);
+    if (!operations.length)
+      throw new Error("statewire: context operations must not be empty");
+    const offers = protocolOffers(s.options);
+    const protocols =
+      s.selection?.protocols ?? (offers === "*" ? undefined : offers);
+    s.contextDocuments = applyDocumentOps(
+      previous,
+      operations,
+      protocols,
+      true,
+    );
     const seq = s.record.ctxNextSeq;
-    setRecord(s, { ...s.record, ctxNextSeq: seq + 1 });
-    s.ctxPending.push({ seq, ops, posted: false });
+    s.ctxPending = [
+      ...s.ctxPending,
+      {
+        seq,
+        ops: operations.map((op) => {
+          const value = op as Record<string, unknown>;
+          if (value["doc"] !== 0) return value;
+          const { doc: _doc, ...rest } = value;
+          return rest;
+        }),
+        posted: false,
+      },
+    ];
+    s.record = { ...s.record, ctxNextSeq: seq + 1 };
+    persistContext(s);
   };
   if (!s.shared) {
-    mint();
-    wake(s);
-    void pump(s);
-    return;
-  }
-  void transact(s, () => {
-    if (!s.running || isFinished(s)) return;
-    mint();
-  }).then(() => {
+    submit();
     wake(s);
     void pump(s);
+  } else
+    void transact(s, submit).then(() => {
+      wake(s);
+      void pump(s);
+    });
+};
+
+export const updateContext = (s: Session, operations: readonly unknown[]) =>
+  changeContext(s, () => operations);
+
+const setContext = (
+  s: Session,
+  value: Record<string, unknown>,
+  protocol = s.options.protocol ?? DEFAULT_PROTOCOL,
+): void => {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    throw new Error("statewire: context must be a plain object");
+  const encoded = encodeValue(value);
+  changeContext(s, (documents) => {
+    const found = [...documents.documents].find(
+      ([, d]) => d.protocol === protocol && d.main,
+    );
+    const doc = found?.[0] ?? Math.max(-1, ...documents.documents.keys()) + 1;
+    return [
+      {
+        ...(found === undefined
+          ? { op: "mount", protocol, main: true }
+          : { op: "replace", path: [] }),
+        ...(doc === 0 ? {} : { doc }),
+        value: encoded.value,
+        ...(encoded.meta === undefined ? {} : { meta: encoded.meta }),
+      },
+    ];
   });
 };
 
+export const documentSource = (s: Session): StatewireDocuments.Source => ({
+  get: (protocol, key, prefix = s.options.keyPrefixes?.[protocol]) => {
+    const mounted = findDocument(s.documents, protocol, key, prefix);
+    if (mounted !== undefined) return mounted.value;
+    if (!s.documentStore || key === undefined) return undefined;
+    const absolute = resolveDocumentKey(key, prefix);
+    if (absolute === undefined) return undefined;
+    const cached = s.documentStore.load([
+      s.documentStore.namespace ?? "",
+      protocol,
+      ...absolute,
+    ]);
+    if (cached === undefined) return undefined;
+    const offers = protocolOffers(s.options);
+    const offer =
+      offers === "*"
+        ? s.selection?.protocols.find((p) => p.name === protocol)
+        : offers.find((p) => p.name === protocol);
+    return offer !== undefined && inRange(cached.version, offer)
+      ? cached.value
+      : undefined;
+  },
+  list: () => s.documents.documents,
+  subscribe: (listener) => {
+    s.documentListeners.add(listener);
+    return () => {
+      s.documentListeners.delete(listener);
+    };
+  },
+});
+
+export const invokeProtocol = (
+  s: Session,
+  protocol: string,
+  method: string,
+  params: readonly unknown[],
+) => sendCommand(s, method, params, protocol);
+
+const storedCommandCompatible = (
+  command: StatewireClient.SessionCommand,
+  current: NonNullable<StatewireClient.SessionCommand["produced"]>,
+) => {
+  if (
+    !command.produced ||
+    !command.protocol ||
+    !inRange(command.produced.wire.version, current.wire)
+  )
+    return false;
+  const previous = command.produced.protocols;
+  if (current.protocols === "*") return true;
+  if (previous === "*") return false;
+  const produced = previous.find((p) => p.name === command.protocol);
+  const offer = current.protocols.find((p) => p.name === command.protocol);
+  return (
+    produced !== undefined &&
+    offer !== undefined &&
+    inRange(produced.version, offer)
+  );
+};
+
 export const useStatewireSession = (
   options: StatewireSessionOptions,
 ): Session => {
   const [defaultStore] = useState(createMemorySessionStore);
   const mounted = useContext(SessionStorageContext);
+  const documentStore = useContext(DocumentStorageContext);
   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",
@@ -1105,7 +1350,35 @@ export const useStatewireSession = (
     );
   }
   const [s] = useState((): Session => {
-    const stored = store.load();
+    let stored = store.load();
+    if (stored !== null && !Array.isArray(stored.commands))
+      throw new Error(
+        "statewire: session storage loaded a record without a commands array",
+      );
+    const current = {
+      wire: options.wireVersion ?? { version: WIRE_VERSION },
+      protocols: protocolOffers(options),
+    };
+    if (
+      stored !== null &&
+      !stored.commands.every((command) =>
+        storedCommandCompatible(command, current),
+      )
+    ) {
+      if (!store.migrate)
+        throw new Error(
+          "statewire: stored commands require a storage migration",
+        );
+      stored = store.migrate(stored, current);
+      if (
+        stored !== null &&
+        !stored.commands.every((command) =>
+          storedCommandCompatible(command, current),
+        )
+      )
+        throw new Error("statewire: migrated commands are incompatible");
+      if (stored !== null) store.save(stored);
+    }
     if (stored !== null && !Array.isArray(stored.commands)) {
       throw new Error(
         "statewire: session storage loaded a record without a commands array",
@@ -1117,7 +1390,17 @@ export const useStatewireSession = (
       ctxNextSeq: 1,
       commands: [],
     };
+    if (stored === null) store.save(record);
     const session: Session = {
+      options,
+      selection: undefined,
+      contextDocuments:
+        stored?.context === undefined
+          ? { mode: "mounted", documents: new Map() }
+          : applyDocumentOps(
+              { mode: "mounted", documents: new Map() },
+              stored.context.ops,
+            ),
       record,
       ctx: {
         get clientId() {
@@ -1134,6 +1417,7 @@ export const useStatewireSession = (
       },
       recordPersisted: stored !== null,
       store,
+      documentStore,
       shared:
         store.lock !== undefined
           ? { txq: Promise.resolve(), parked: [], unsubscribe: null }
@@ -1146,13 +1430,15 @@ export const useStatewireSession = (
       idle: false,
       onSessionLost: undefined,
       onDone: undefined,
-      ctxOps: undefined,
-      ctxPending: [],
+      ctxOps: stored?.context?.ops,
+      ctxPending:
+        stored?.context?.pending.map((p) => ({ ...p, posted: false })) ?? [],
       lanesOnAttach: false,
       attachLaneSeqs: [new Set(), new Set()],
       frameFailures: 0,
       pending: [],
       canonical: undefined,
+      documentListeners: new Set(),
       documents: { mode: null, documents: new Map() },
       lastPublished: undefined,
       changed: [],
@@ -1191,9 +1477,22 @@ export const useStatewireSession = (
       "statewire: session storage changed sharedness across renders — lock/subscribe must be present from the first render or never",
     );
   }
+  s.options = options;
   s.store = store;
+  s.documentStore = documentStore;
   s.onSessionLost = options.onSessionLost;
   s.onDone = options.onDone;
+  const keyPrefixes = JSON.stringify(options.keyPrefixes);
+  useEffect(() => {
+    cacheDocuments(s);
+  }, [s, documentStore, keyPrefixes]);
+  useEffect(
+    () =>
+      documentStore?.subscribe?.(() => {
+        for (const listener of s.documentListeners) listener();
+      }),
+    [s, documentStore],
+  );
   useEffect(() => {
     start(s);
     return () => stop(s);

package/src/client/sessionStore.ts

@@ -1,4 +1,6 @@
+import type { StatewireDocuments } from "../wire/documents";
 import { createContext } from "react";
+import type { StatewireProtocol } from "../wire/protocol";
 import type { StatewireClient } from "../statewire";
 
 /** The session storage `useStatewire` mounts, read by the transport's session. */
@@ -15,3 +17,9 @@ export const createMemorySessionStore = (): StatewireClient.SessionStorage => {
     },
   };
 };
+
+export const ProtocolContext = createContext<StatewireProtocol.Options>({});
+
+export const DocumentStorageContext = createContext<
+  StatewireDocuments.Storage | undefined
+>(undefined);

package/src/host/host.ts

@@ -102,6 +102,7 @@ type Settled =
   | { type: "rejected"; error: unknown };
 
 export type CommandsInvocation = {
+  readonly protocol?: string;
   readonly method: string;
   readonly params: readonly unknown[];
   readonly ts: number;