statewire 0.19.4 → 0.21.0

package/src/client/session.ts

@@ -1,3 +1,4 @@
+import { encodeContext } from "../wire/context";
 import { wrapStorageError } from "./storageError";
 import {
   DEFAULT_PROTOCOL,
@@ -76,6 +77,7 @@ const rejectedSend = (
 type AttachState = "detached" | "attached" | "finished";
 
 export type StatewireSessionOptions = StatewireProtocol.Options & {
+  context?: Readonly<Record<string, Statewire.Context>>;
   sessionStore?: StatewireClient.SessionStorage | undefined;
   onSessionLost?: StatewireClient.OnSessionLost | undefined;
   onDone?: (() => void) | undefined;
@@ -83,12 +85,17 @@ export type StatewireSessionOptions = StatewireProtocol.Options & {
 
 type Shared = {
   txq: Promise<void>;
+  syncQueued: boolean;
   parked: { protocol: string; verdict: StatewireClient.SessionVerdict }[];
   unsubscribe: (() => void) | null;
 };
 
 type Session = {
   options: StatewireSessionOptions;
+  configuredContext: StatewireSessionOptions["context"];
+  contexts: Map<string, ReturnType<typeof encodeContext>>;
+  dirtyContexts: Set<string>;
+  attachContexts: Map<string, ReturnType<typeof encodeContext>>;
   selection: StatewireProtocol.Selection | undefined;
   record: StatewireClient.SessionRecord;
   ctx: StatewireRemoteProps;
@@ -198,7 +205,6 @@ const storageFailed = (s: Session, cause: unknown) => {
 };
 
 const setRecord = (s: Session, record: StatewireClient.SessionRecord) => {
-  s.record = record;
   if (!s.deactivated) {
     try {
       s.store.save(record);
@@ -207,6 +213,7 @@ const setRecord = (s: Session, record: StatewireClient.SessionRecord) => {
       throw s.storageError;
     }
   }
+  s.record = record;
 };
 
 const toStored = (p: Pending): StatewireClient.SessionCommand => {
@@ -282,8 +289,16 @@ const syncBacklogInner = (s: Session) => {
 };
 
 const syncBacklog = (s: Session) => {
-  if (!s.shared) return syncBacklogInner(s);
-  transactBackground(s, () => syncBacklogInner(s));
+  const shared = s.shared;
+  if (!shared) return syncBacklogInner(s);
+  if (shared.syncQueued) return;
+  shared.syncQueued = true;
+  void transact(s, () => {
+    shared.syncQueued = false;
+    syncBacklogInner(s);
+  }).catch(() => {
+    shared.syncQueued = false;
+  });
 };
 
 // Every record mutation over shared storage is a locked read-modify-write.
@@ -299,7 +314,7 @@ const transact = (s: Session, fn: () => void): Promise<void> => {
       if (stored !== null && stored.clientId !== s.record.clientId) {
         adoptReset(s, stored);
       } else if (stored !== null) {
-        s.record = stored;
+        s.record = boundRecord(stored);
       }
       fn();
       const persistence = s.store.flush?.();
@@ -351,6 +366,25 @@ export const failedCommands = (
   return s.failedList;
 };
 
+export const MAX_FAILED_RETAINED = 256;
+
+const boundFailed = (failed: readonly StatewireClient.FailedCommand[]) =>
+  failed.length > MAX_FAILED_RETAINED
+    ? [...failed].sort((a, b) => a.ts - b.ts).slice(-MAX_FAILED_RETAINED)
+    : failed;
+
+const boundRecord = (record: StatewireClient.SessionRecord) => {
+  let lanes = record.lanes;
+  for (const [protocol, lane] of Object.entries(lanes)) {
+    if (lane.failed !== undefined && lane.failed.length > MAX_FAILED_RETAINED)
+      lanes = {
+        ...lanes,
+        [protocol]: { ...lane, failed: boundFailed(lane.failed) },
+      };
+  }
+  return lanes === record.lanes ? record : { ...record, lanes };
+};
+
 const retainFailedInner = (
   s: Session,
   entry: Pending,
@@ -361,7 +395,7 @@ const retainFailedInner = (
     s,
     withLane(s.record, entry.command.protocol, {
       ...lane,
-      failed: [
+      failed: boundFailed([
         ...(lane.failed ?? []),
         {
           protocol: entry.command.protocol,
@@ -375,7 +409,7 @@ const retainFailedInner = (
           ts: entry.inv.ts,
           seq: entry.seq,
         },
-      ],
+      ]),
     }),
   );
   s.notify();
@@ -491,7 +525,7 @@ const rebaseRecord = (s: Session, adopt: () => void) => {
       ...lanes,
       [protocol]: {
         ...current,
-        failed: [...(current.failed ?? []), ...failed],
+        failed: boundFailed([...(current.failed ?? []), ...failed]),
       },
     };
   }
@@ -509,7 +543,7 @@ const resetRecord = (s: Session, clientId: string) =>
 // attempted history and our survivors re-stamp on the stored clocks.
 const adoptReset = (s: Session, stored: StatewireClient.SessionRecord) => {
   rebaseRecord(s, () => {
-    s.record = stored;
+    s.record = boundRecord(stored);
   });
   // The host attributes frames by lease, and the lease is bound to the id
   // this attach was opened with.
@@ -760,6 +794,16 @@ const handleHello = (
   s: Session,
   { ops, syn }: { ops: unknown[]; syn: StatewireSyn },
 ) => {
+  if (s.attach === "attached") {
+    s.ephemeralSeqs = {};
+    detachEphemeralLanes(s);
+  }
+  for (const [protocol, value] of s.contexts) {
+    if (s.attachContexts.get(protocol) === value)
+      s.dirtyContexts.delete(protocol);
+    else s.dirtyContexts.add(protocol);
+  }
+  s.attachContexts.clear();
   s.selection = selectionOf(syn);
   s.documents = { mode: null, documents: new Map() };
   ingestOps(s, ops);
@@ -809,7 +853,7 @@ const handleOps = (
 ) => {
   ingestOps(s, ops);
   for (const cmd of cmds) handleCmd(s, cmd);
-  syncBacklog(s);
+  if (cmds.length > 0) syncBacklog(s);
   publishIngested(s);
 };
 
@@ -914,12 +958,16 @@ const buildLanes = (
     last[protocol] = entry.seq;
     entries.push(entry);
   }
-  if (entries.length === 0) return null;
+  const ctx = [...s.dirtyContexts].map((protocol) => s.contexts.get(protocol)!);
+  if (entries.length === 0 && ctx.length === 0) return null;
   return {
     frame: {
-      cmd: entries.map((p) => {
-        const { produced: _produced, ...command } = p.command;
-        return { ...command, seq: p.seq };
+      ...(ctx.length > 0 && { ctx }),
+      ...(entries.length > 0 && {
+        cmd: entries.map((p) => {
+          const { produced: _produced, ...command } = p.command;
+          return { ...command, seq: p.seq };
+        }),
       }),
     },
     entries,
@@ -930,6 +978,8 @@ const takeAttachLanes = (s: Session): StatewireFrame | null => {
   s.attachEntries = new Set();
   const wanted = s.lanesOnAttach;
   s.lanesOnAttach = false;
+  for (const protocol of s.contexts.keys()) s.dirtyContexts.add(protocol);
+  s.attachContexts = new Map(s.contexts);
   const lanes = buildLanes(s, wanted && s.sessionKnown ? "persisted" : "none");
   if (!lanes) return null;
   s.attachEntries = new Set(lanes.entries);
@@ -966,6 +1016,7 @@ const pump = async (s: Session) => {
       if (!s.hydrated) await s.ready;
       const transport = s.transport;
       if (buildLanes(s) === null) return;
+      if (transport?.parked && s.pending.length === 0) return;
       if (s.attach !== "attached" || !transport) {
         if (
           (transport?.connection.status === "standby" &&
@@ -995,17 +1046,32 @@ const pump = async (s: Session) => {
         // 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
+        result = await (s.shared && !s.deactivated && lanes.entries.length > 0
           ? s.store.lock!(send)
           : send());
       } catch {
         if (!s.running || isFinished(s)) return;
+        if (lanes.frame.ctx?.length) {
+          s.lanesOnAttach = true;
+          transport.connection.reconnect();
+          await waitForWake(s);
+          continue;
+        }
         s.frameFailures += 1;
         await sleepUntilWake(s, backoff(s.frameFailures));
         continue;
       }
       if (!s.running) return;
       s.frameFailures = 0;
+      if (
+        epoch === s.attachEpoch &&
+        (result.type === "ok" || result.type === "refusal")
+      ) {
+        for (const entry of lanes.frame.ctx ?? []) {
+          if (s.contexts.get(entry.protocol) === entry)
+            s.dirtyContexts.delete(entry.protocol);
+        }
+      }
       if (result.type === "ok") {
         if (epoch === s.attachEpoch) {
           for (const entry of lanes.entries) {
@@ -1186,7 +1252,10 @@ const adoptStored = (s: Session) => {
       const params =
         command.meta === undefined
           ? command.params
-          : (reviveValue([...command.params], command.meta) as unknown[]);
+          : (reviveValue(
+              structuredClone(command.params),
+              command.meta,
+            ) as unknown[]);
       const entry: Pending = {
         seq,
         command: { protocol, ...command },
@@ -1326,7 +1395,7 @@ export const retryFailed = (
   const params =
     found.meta === undefined
       ? found.params
-      : (reviveValue([...found.params], found.meta) as unknown[]);
+      : (reviveValue(structuredClone(found.params), found.meta) as unknown[]);
   const result = new Promise<unknown>((resolve, reject) => {
     const retry = () => {
       if (!s.running) {
@@ -1472,11 +1541,31 @@ const loadSessionRecord = (
       store.save(stored);
     }
   }
-  const record = stored ?? { clientId: newClientId(), lanes: {} };
-  if (stored === null) store.save(record);
+  const record =
+    stored === null
+      ? { clientId: newClientId(), lanes: {} }
+      : boundRecord(stored);
+  if (record !== stored) store.save(record);
   return record;
 };
 
+export const setContext = (
+  s: Session,
+  protocol: string,
+  value: Statewire.Context,
+): void => {
+  if (
+    s.selection
+      ? !s.selection.protocols.some((p) => p.name === protocol)
+      : !offered(s, protocol)
+  )
+    throw new Error(`statewire: protocol "${protocol}" is not negotiated`);
+  s.contexts.set(protocol, encodeContext(protocol, value));
+  s.dirtyContexts.add(protocol);
+  wake(s);
+  void pump(s);
+};
+
 export const useStatewireSession = (
   options: StatewireSessionOptions,
 ): Session => {
@@ -1501,6 +1590,15 @@ export const useStatewireSession = (
         : { clientId: newClientId(), lanes: {} };
     const session: Session = {
       options,
+      configuredContext: options.context,
+      contexts: new Map(
+        Object.entries(options.context ?? {}).map(([protocol, value]) => [
+          protocol,
+          encodeContext(protocol, value),
+        ]),
+      ),
+      dirtyContexts: new Set(Object.keys(options.context ?? {})),
+      attachContexts: new Map(),
       selection: undefined,
       record,
       ctx: {
@@ -1526,7 +1624,12 @@ export const useStatewireSession = (
       documentStore,
       shared:
         store.lock !== undefined
-          ? { txq: Promise.resolve(), parked: [], unsubscribe: null }
+          ? {
+              txq: Promise.resolve(),
+              syncQueued: false,
+              parked: [],
+              unsubscribe: null,
+            }
           : false,
       ephemeral: false,
       deactivated: false,
@@ -1598,6 +1701,12 @@ export const useStatewireSession = (
       "statewire: session storage changed sharedness across renders — lock/subscribe must be present from the first render or never",
     );
   }
+  useEffect(() => {
+    if (s.configuredContext === options.context) return;
+    s.configuredContext = options.context;
+    for (const [protocol, value] of Object.entries(options.context ?? {}))
+      setContext(s, protocol, value);
+  }, [s, options.context]);
   s.options = options;
   s.store = store;
   s.documentStore = documentStore;

package/src/client/sessionStore.ts

@@ -1,6 +1,7 @@
 import type { StatewireDocuments } from "../wire/documents";
 import { createContext } from "react";
 import type { StatewireProtocol } from "../wire/protocol";
+import type { Statewire } from "../types";
 import type { StatewireClient } from "../statewire";
 
 /** The session storage `useStatewire` mounts, read by the transport's session. */
@@ -21,7 +22,10 @@ export const createMemorySessionStore = (): StatewireClient.SessionStorage => {
 export const ProtocolContext = createContext<StatewireProtocol.Options>({});
 
 /** Link options `useStatewire` hands down to whichever transport it mounts. */
-export const LinkContext = createContext<{ isNew?: boolean | undefined }>({});
+export const LinkContext = createContext<{
+  isNew?: boolean | undefined;
+  context?: Readonly<Record<string, Statewire.Context>> | undefined;
+}>({});
 
 export const DocumentStorageContext = createContext<
   StatewireDocuments.Storage | undefined

package/src/host/host.ts

@@ -1,3 +1,4 @@
+import { captureContext } from "../wire/context";
 import { useEffect, useState } from "react";
 import { applyOps, sanitizeValue } from "../wire/ops";
 import type { StatewirePath } from "../wire/ops";
@@ -167,6 +168,7 @@ export type CommandsSubmission = {
   params: readonly unknown[];
   clientId?: string;
   caller?: StatewireHost.Caller;
+  context?: Statewire.Context;
   attach?: StatewireHost.Attach;
   onApplied?: () => void;
   onSettle?: (outcome: CommandsOutcome) => void;
@@ -190,6 +192,7 @@ export const bindCommandsHost = (commands: object, host: CommandsHost) => {
 };
 
 type QueuedCall = {
+  context?: Statewire.Context;
   method: string;
   params: readonly unknown[];
   ts: number;
@@ -206,6 +209,7 @@ type ActiveInvocation = CommandsInvocation & {
 };
 
 type CommandsCell = {
+  context: (() => Statewire.Context) | undefined;
   handlers: Record<string, (...args: never[]) => unknown> | null;
   queue: QueuedCall[];
   active: Map<ActiveInvocation, QueuedCall>;
@@ -227,8 +231,13 @@ const LOCAL_CALLER: StatewireHost.Caller = Object.freeze({
   isConnected: true,
 });
 
-const toSendError = (error: unknown): StatewireSendError =>
-  error instanceof StatewireSendError
+const toSendError = (error: unknown): StatewireSendError => {
+  if (
+    !(error instanceof StatewireSendError) &&
+    !(error instanceof StatewireReject)
+  )
+    console.error("statewire command failed", error);
+  return error instanceof StatewireSendError
     ? error
     : error instanceof StatewireReject
       ? new StatewireSendError({
@@ -241,8 +250,9 @@ const toSendError = (error: unknown): StatewireSendError =>
       : new StatewireSendError({
           fate: "failed",
           cause: "server",
-          message: error instanceof Error ? error.message : String(error),
+          message: "the command failed",
         });
+};
 
 const applyInvocation = (cell: CommandsCell, inv: ActiveInvocation) => {
   if (inv.applied) return;
@@ -343,6 +353,7 @@ const dispatch = (cell: CommandsCell, call: QueuedCall) => {
   const attach = call.origin?.attach;
   const ctx: StatewireHost.Ctx = {
     caller: call.origin?.caller ?? LOCAL_CALLER,
+    context: call.context ?? call.origin?.context ?? Object.freeze({}),
     get attach() {
       if (attach === undefined)
         throw new Error("statewire: in-process dispatch has no attach");
@@ -416,9 +427,11 @@ export const useStatewireCommands = <THandlers extends Statewire.Commands>(
     | undefined
     | null
     | false,
+  options?: StatewireHost.CommandsOptions,
 ): Statewire.CommandsProxy<StatewireHost.HandledCommands<THandlers>> => {
   const [built] = useState(() => {
     const cell: CommandsCell = {
+      context: undefined,
       handlers: null,
       queue: [],
       active: new Map(),
@@ -438,6 +451,7 @@ export const useStatewireCommands = <THandlers extends Statewire.Commands>(
             return;
           }
           cell.queue.push({
+            context: captureContext(cell.context?.() ?? {}),
             method,
             params,
             ts: Date.now(),
@@ -479,6 +493,7 @@ export const useStatewireCommands = <THandlers extends Statewire.Commands>(
     return { cell, proxy };
   });
 
+  built.cell.context = options?.context;
   useEffect(() => {
     const { cell } = built;
     cell.unmounted = false;

package/src/host/http.ts

@@ -8,6 +8,7 @@ import {
   authEquals,
   closeConn,
   flush,
+  expireLease,
   parseFrame,
   parseFrameValue,
   register,
@@ -94,9 +95,10 @@ const headersOf = (request: Request): Record<string, string> =>
 const authorize = async (
   h: SocketHostState,
   headers: Record<string, string>,
-): Promise<{ auth: unknown } | { refused: Response }> => {
+): Promise<{ auth: unknown; authorizedAt: number } | { refused: Response }> => {
   try {
-    return { auth: await h.authorize?.({ headers }) };
+    const auth = await h.authorize?.({ headers });
+    return { auth, authorizedAt: Date.now() };
   } catch (error) {
     if (error instanceof Response) return { refused: error };
     throw error;
@@ -140,6 +142,7 @@ const attachSse = (
   h: SocketHostState,
   clientId: string,
   auth: unknown,
+  authorizedAt: number,
   selection: StatewireProtocol.Selection,
   frame?: ParsedFrame,
 ): SseAttachment => {
@@ -203,6 +206,7 @@ const attachSse = (
     auth,
     selection,
     frame,
+    authorizedAt,
   );
   connection = registration?.connection ?? null;
   if (!open) connection?.close();
@@ -249,7 +253,13 @@ const getStream = async (
   ]);
   if ("fin" in selection)
     return Response.json(selection, { status: selection.fin.status });
-  const attachment = attachSse(h, client.clientId, authorized.auth, selection);
+  const attachment = attachSse(
+    h,
+    client.clientId,
+    authorized.auth,
+    authorized.authorizedAt,
+    selection,
+  );
   const lease = attachment.registration === null ? null : mintLease();
   if (attachment.registration !== null)
     attachment.registration.conn.lease = lease;
@@ -301,6 +311,7 @@ const postStream = async (
       h,
       client.clientId,
       authorized.auth,
+      authorized.authorizedAt,
       selection,
       frame,
     );
@@ -365,11 +376,24 @@ export const frames = async (
     lease === null
       ? undefined
       : [...h.conns].find((conn) => conn.open && conn.lease === lease);
-  if (h.disposed || h.finished !== null || leased === undefined) {
+  if (
+    h.disposed ||
+    h.finished !== null ||
+    leased === undefined ||
+    expireLease(h, leased)
+  ) {
     return Response.json({ error: "stale-lease" }, { status: 423 });
   }
   const clientId = leased.clientId;
   const raw = await readFrameBody(request);
+  if (
+    !leased.open ||
+    h.disposed ||
+    h.finished !== null ||
+    expireLease(h, leased)
+  ) {
+    return Response.json({ error: "stale-lease" }, { status: 423 });
+  }
   if (raw === null) {
     return Response.json({ error: "frame body too large" }, { status: 413 });
   }
@@ -382,7 +406,12 @@ export const frames = async (
     }
     return violationResponse(h, clientId, error.message);
   }
-  if (!leased.open || h.disposed || h.finished !== null) {
+  if (
+    !leased.open ||
+    h.disposed ||
+    h.finished !== null ||
+    expireLease(h, leased)
+  ) {
     return Response.json({ error: "stale-lease" }, { status: 423 });
   }
   let admission: ReturnType<typeof admitFrame>;
@@ -393,6 +422,9 @@ export const frames = async (
       throw error;
     return violationResponse(h, clientId, error.message);
   }
+  if (admission.type === "expired") {
+    return Response.json({ error: "stale-lease" }, { status: 423 });
+  }
   if (admission.type === "refused") {
     const retry = admission.syn.syn.retry;
     return Response.json(admission.syn, {