statewire 0.19.0 → 0.19.2

package/src/client/session.ts

@@ -140,7 +140,8 @@ const EMPTY_LANE: StatewireClient.SessionLane = { nextSeq: 1, commands: [] };
 const laneOf = (
   record: StatewireClient.SessionRecord,
   protocol: string,
-): StatewireClient.SessionLane => record.lanes[protocol] ?? EMPTY_LANE;
+): StatewireClient.SessionLane =>
+  Object.hasOwn(record.lanes, protocol) ? record.lanes[protocol]! : EMPTY_LANE;
 
 const withLane = (
   record: StatewireClient.SessionRecord,
@@ -157,7 +158,7 @@ const isEphemeral = (s: Session, protocol: string) =>
   ) ?? false;
 
 const durableSeqOf = (s: Session, protocol: string) =>
-  s.durableSeq[protocol] ?? 0;
+  Object.hasOwn(s.durableSeq, protocol) ? s.durableSeq[protocol]! : 0;
 
 const laneEntries = (s: Session, protocol: string) =>
   s.pending.filter((p) => p.command.protocol === protocol);
@@ -506,10 +507,14 @@ const resetRecord = (s: Session, clientId: string) =>
 
 // 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 adoptReset = (s: Session, stored: StatewireClient.SessionRecord) => {
   rebaseRecord(s, () => {
     s.record = stored;
   });
+  // The host attributes frames by lease, and the lease is bound to the id
+  // this attach was opened with.
+  if (s.attach === "attached") s.transport?.connection.reconnect();
+};
 
 // The record died with the attach: mint a fresh id for the next one.
 const ephemeralDetach = (s: Session) => {
@@ -775,7 +780,9 @@ const handleHello = (
     for (const lane of lanes) {
       if (lane.record === "ephemeral") {
         s.ephemeralSeqs[lane.name] = Math.max(
-          s.ephemeralSeqs[lane.name] ?? 0,
+          Object.hasOwn(s.ephemeralSeqs, lane.name)
+            ? s.ephemeralSeqs[lane.name]!
+            : 0,
           ...laneEntries(s, lane.name).map((p) => p.seq),
         );
       } else s.durableSeq[lane.name] = lane.seq ?? 0;
@@ -897,7 +904,10 @@ const buildLanes = (
         (cmdGate === "persisted" &&
           (s.persistedRecord?.clientId !== s.record.clientId ||
             entry.seq >= laneOf(s.persistedRecord, protocol).nextSeq)));
-    if (gated || (protocol in last && entry.seq !== last[protocol]! + 1)) {
+    if (
+      gated ||
+      (Object.hasOwn(last, protocol) && entry.seq !== last[protocol]! + 1)
+    ) {
       stopped.add(protocol);
       continue;
     }
@@ -1094,7 +1104,9 @@ const enqueueInner = (
   const protocol = command.protocol;
   const ephemeral = isEphemeral(s, protocol);
   const seq = ephemeral
-    ? (s.ephemeralSeqs[protocol] ?? 0) + 1
+    ? (Object.hasOwn(s.ephemeralSeqs, protocol)
+        ? s.ephemeralSeqs[protocol]!
+        : 0) + 1
     : Math.max(
         laneOf(s.record, protocol).nextSeq,
         durableSeqOf(s, protocol) + 1,
@@ -1144,10 +1156,8 @@ const enqueue = (
     return;
   }
   void transact(s, () => {
-    if (!s.running) {
-      reject(new StatewireSendError({ fate: "aborted", cause: "unmount" }));
-      return;
-    }
+    // A send queued behind the lock before this tab unmounted still lands in
+    // the shared journal: another sharer adopts and replays it.
     if (isFinished(s)) {
       reject(new StatewireSendError({ fate: "aborted", cause: "stream-gone" }));
       return;

package/src/client/sessionStore.ts

@@ -20,6 +20,9 @@ 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 DocumentStorageContext = createContext<
   StatewireDocuments.Storage | undefined
 >(undefined);

package/src/client/timing.ts

@@ -3,6 +3,7 @@ export const timing = {
   backoffMaxMs: 30_000,
   backoffResetMs: 30_000,
   heartbeatTimeoutMs: 30_000,
+  pingIntervalMs: 10_000,
   random: Math.random,
 };
 

package/src/host/socket.ts

@@ -256,22 +256,15 @@ const cmdOf = (adm: Admission, outcome: CommandsOutcome): Cmd => {
         ...(failure.message !== undefined && { message: failure.message }),
       };
     case "rejected": {
-      if (failure.code !== undefined) {
-        const message =
-          failure.code === "unknown-command"
-            ? `unknown method: '${adm.method}'`
-            : failure.message;
-        return {
-          ...at,
-          type: "rejected",
-          code: failure.code,
-          ...(message !== undefined && { message }),
-        };
-      }
+      const message =
+        failure.code === "unknown-command"
+          ? `unknown method: '${adm.method}'`
+          : failure.message;
       return {
         ...at,
         type: "rejected",
-        ...(failure.message !== undefined && { message: failure.message }),
+        ...(failure.code !== undefined && { code: failure.code }),
+        ...(message !== undefined && { message }),
         ...encodePayload(failure.payload),
       };
     }
@@ -313,6 +306,7 @@ const parseInitialFrame = (raw: string) => {
 
 export type SocketHostState = {
   protocol: StatewireProtocol.Definition;
+  key: readonly string[] | undefined;
   wireVersion: StatewireProtocol.Range;
   heartbeatMs: number;
   wsInitTimeoutMs: number;
@@ -653,9 +647,7 @@ export const flush = (h: SocketHostState, fin?: StatewireHost.Fin) => {
   h.pendingOps = [];
   h.pendingApplied = new Map();
   h.pendingCmds = new Map();
-  // Applied entries anchor to their effects: piggybacked on the ops packet
-  // when one is flushing, standalone otherwise. Terminal verdicts ride their
-  // own packet.
+  // One packet per flush: ops first, then applied entries, then verdicts.
   for (const conn of [...h.conns]) {
     if (!conn.ready) continue;
     const forConn = (list: Cmd[] | undefined) =>
@@ -664,9 +656,11 @@ export const flush = (h: SocketHostState, fin?: StatewireHost.Fin) => {
       ...(selects(conn, h.protocol.name) ? mainOps : []),
       ...diffView(h, conn),
     ];
-    const appliedEntries = [
+    const cmd = [
       ...forConn(applied.get(conn.clientId)),
       ...conn.pendingApplied.splice(0),
+      ...forConn(cmds.get(conn.clientId)),
+      ...conn.pendingCmds.splice(0),
     ];
     if (ops.length > 0) {
       sendTo(
@@ -674,19 +668,12 @@ export const flush = (h: SocketHostState, fin?: StatewireHost.Fin) => {
         conn,
         JSON.stringify({
           ops,
-          ...(appliedEntries.length > 0 && { cmd: appliedEntries }),
+          ...(cmd.length > 0 && { cmd }),
           ...(edge && { idle: level }),
         }),
       );
-    } else if (appliedEntries.length > 0) {
-      sendTo(h, conn, JSON.stringify({ cmd: appliedEntries }));
-    }
-    const verdicts = [
-      ...forConn(cmds.get(conn.clientId)),
-      ...conn.pendingCmds.splice(0),
-    ];
-    if (verdicts.length > 0) {
-      sendTo(h, conn, JSON.stringify({ cmd: verdicts }));
+    } else if (cmd.length > 0) {
+      sendTo(h, conn, JSON.stringify({ cmd }));
     }
     if (edge && ops.length === 0) {
       sendTo(h, conn, JSON.stringify({ idle: level }));
@@ -1052,6 +1039,10 @@ const message = (h: SocketHostState, conn: Conn, data: string) => {
     closeConn(h, conn, 1009, "frame too large");
     return;
   }
+  if (data === "{}") {
+    if (conn.sawFrame) sendTo(h, conn, "{}");
+    return;
+  }
   const first = !conn.sawFrame;
   conn.sawFrame = true;
   let admission: ReturnType<typeof admitFrame>;
@@ -1464,6 +1455,12 @@ export const register = (
   };
   conn.attach = attachOf(h, conn);
   h.conns.add(conn);
+  try {
+    h.current?.attaching?.(conn.attach);
+  } catch (error) {
+    closeConn(h, conn, 1011, "attach failed");
+    throw error;
+  }
   gcClients(h);
   ensureHeartbeat(h);
   const isEphemeral = (s: CmdStatement) =>
@@ -1491,6 +1488,7 @@ export const register = (
     ops.push({
       op: "mount",
       protocol: h.protocol.name,
+      ...(h.key !== undefined && { key: h.key }),
       main: true,
       value,
       ...(meta !== undefined && { meta }),
@@ -1610,6 +1608,7 @@ const useSocketHost = (
   const [h] = useState((): SocketHostState => {
     const host: SocketHostState = {
       protocol: { name: DEFAULT_PROTOCOL, version: WIRE_VERSION },
+      key: undefined,
       wireVersion: { version: WIRE_VERSION },
       heartbeatMs: 15_000,
       wsInitTimeoutMs: 5_000,
@@ -1652,6 +1651,7 @@ const useSocketHost = (
     name: DEFAULT_PROTOCOL,
     version: WIRE_VERSION,
   };
+  h.key = options?.key;
   h.wireVersion = options?.wireVersion ?? { version: WIRE_VERSION };
   setHeartbeatMs(h, options?.heartbeatIntervalMs ?? 15_000);
   h.pushback = options?.pushback;

package/src/host-internal.ts

@@ -78,6 +78,8 @@ export namespace StatewireHostInternal {
 
   export type SocketHostOptions<TAuth = unknown> = {
     protocol?: StatewireProtocol.Definition;
+    /** Key of the host protocol's main document. */
+    key?: readonly string[];
     wireVersion?: StatewireProtocol.Range;
     /** Gates every attach; the awaited return value is the attach's auth, exposed to command handlers as `this.caller.auth`. The first attach binds the client id's record to this value; a later attach whose value is not structurally equal is refused (HTTP 403, socket close 1008). */
     authorize?: (ctx: {

package/src/statewire.ts

@@ -1,7 +1,14 @@
 import type { StatewireDocuments } from "./wire/documents";
 import type { StatewireProtocol } from "./wire/protocol";
 import type { StatewireHost } from "./host";
-import { useMemo, useRef, useState, useSyncExternalStore } from "react";
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from "react";
 import {
   createTapRoot,
   flushTapSync,
@@ -17,6 +24,7 @@ import type { Statewire } from "./types";
 import type { TERMINAL } from "./client/connection";
 import {
   DocumentStorageContext,
+  LinkContext,
   ProtocolContext,
   SessionStorageContext,
 } from "./client/sessionStore";
@@ -26,11 +34,13 @@ const useSessionTransport = ({
   session,
   documents,
   protocol,
+  link,
 }: {
   transport: ResourceElement<Statewire<any, any>>;
   session: StatewireClient.SessionStorage | undefined;
   documents: StatewireDocuments.Storage | undefined;
   protocol: StatewireProtocol.Options;
+  link: { isNew?: boolean | undefined };
 }): Statewire<unknown> =>
   useContextProvider(SessionStorageContext, session, () =>
     // oxlint-disable-next-line react-hooks/rules-of-hooks
@@ -38,7 +48,10 @@ const useSessionTransport = ({
       // oxlint-disable-next-line react-hooks/rules-of-hooks
       useContextProvider(ProtocolContext, protocol, () =>
         // oxlint-disable-next-line react-hooks/rules-of-hooks
-        useResource(transport),
+        useContextProvider(LinkContext, link, () =>
+          // oxlint-disable-next-line react-hooks/rules-of-hooks
+          useResource(transport),
+        ),
       ),
     ),
   );
@@ -78,15 +91,21 @@ export const useStatewire = <
       keyPrefixes: options.keyPrefixes,
     }),
   };
+  const link = useMemo(
+    () => (options.isNew === undefined ? {} : { isNew: options.isNew }),
+    [options.isNew],
+  );
   const value = useResource(
     SessionTransport({
       transport: options.transport,
       session,
       documents,
       protocol,
+      link,
     }),
   );
   const core = useStatewireCore(() => latest.current, value);
+  useEffect(() => core.rematerialize(), [core, options.materializeKey]);
   const [subscribe] = useState(
     () => (listener: () => void) =>
       core.subscribe(() => flushTapSync(listener)),
@@ -104,29 +123,36 @@ export const useStatewire = <
     core.getFailed,
   );
   const connection = value.connection ?? CONNECTED_CONNECTION;
+  const {
+    documents: source,
+    selection,
+    invoke: transportInvoke,
+    failures: transportFailures,
+  } = value;
+
+  const invoke = useCallback(
+    (protocol: string, method: string, params: readonly unknown[]) => {
+      if (!transportInvoke)
+        throw new Error(
+          "statewire: transport does not support protocol commands",
+        );
+      return transportInvoke(protocol, method, params);
+    },
+    [transportInvoke],
+  );
 
   return useMemo(() => {
-    const failures = (): NonNullable<typeof value.failures> => {
-      if (!value.failures) {
+    const failures = (): NonNullable<typeof transportFailures> => {
+      if (!transportFailures) {
         throw new Error("statewire: this transport has no failed-send lane");
       }
-      return value.failures;
+      return transportFailures;
     };
     return {
       state,
-      documents: value.documents,
-      selection: value.selection,
-      invoke: (
-        protocol: string,
-        method: string,
-        params: readonly unknown[],
-      ) => {
-        if (!value.invoke)
-          throw new Error(
-            "statewire: transport does not support protocol commands",
-          );
-        return value.invoke(protocol, method, params);
-      },
+      documents: source,
+      selection,
+      invoke,
       getState: core.getState as () => TState,
       connection,
       commands: core.commands as Statewire.CommandsProxy<TCommands>,
@@ -137,7 +163,17 @@ export const useStatewire = <
       discardFailed: (entry: StatewireClient.FailedCommand) =>
         failures().discard(entry),
     };
-  }, [state, isBusy, failed, connection, core, value]);
+  }, [
+    state,
+    isBusy,
+    failed,
+    connection,
+    core,
+    source,
+    selection,
+    invoke,
+    transportFailures,
+  ]);
 };
 
 export const StatewireResource = <
@@ -222,6 +258,8 @@ export namespace StatewireClient {
     wireVersion?: StatewireProtocol.Range;
     applicationProtocols?: readonly StatewireProtocol.Offer[] | "*";
     transport: ResourceElement<Statewire<TState, TCommands>>;
+    /** The session does not exist on the server yet: the transport's first attach waits for the first command send; the transport's own `isNew` wins. */
+    isNew?: boolean;
     /** Durable session: the mounted storage holds this client's lane identity and its un-durable commands, which resend on the next attach. */
     storage?:
       | {
@@ -233,6 +271,8 @@ export namespace StatewireClient {
     initialState?: TState;
     optimistic?: Optimistic<NonNullable<TState>, TCommands>;
     materialize?: Materialize<NonNullable<TState>>;
+    /** Republishes through `materialize` when it changes (`Object.is`); `materialize` itself is read fresh on every publish. */
+    materializeKey?: unknown;
     onStateChange?: (
       state: NonNullable<TState>,
       ctx: { changes: Statewire.Changes },
@@ -331,9 +371,10 @@ export namespace StatewireClient {
   };
 
   /**
-   * Mutate the draft to make server-accepted, still-uncommitted intents in
-   * the state concrete (e.g. dispatch records into messages). Runs after the
-   * optimistic folds on every published state.
+   * Mutate the draft to fold client-known facts into the state: server-accepted,
+   * still-uncommitted intents (e.g. dispatch records into messages) or the live
+   * state of a sibling statewire. Runs after the optimistic folds on every
+   * published state; `materializeKey` republishes when the facts change.
    */
   export type Materialize<TState> = (draft: TState) => void;
 

package/src/transports/remote.ts

@@ -1,5 +1,5 @@
-import { useContext, useEffect } from "react";
-import { ProtocolContext } from "../client/sessionStore";
+import { useContext, useEffect, useMemo } from "react";
+import { LinkContext, ProtocolContext } from "../client/sessionStore";
 import type { Statewire } from "../types";
 import {
   documentSource,
@@ -24,30 +24,40 @@ export const useStatewireRemote = <
   options: TOptions,
   useLink: (options: TOptions, ctx: StatewireRemoteProps) => RemoteLink,
 ): Statewire<any, any> => {
-  const inherited = useContext(ProtocolContext);
-  const configured = { ...inherited, ...options };
+  const configured = {
+    ...useContext(ProtocolContext),
+    ...useContext(LinkContext),
+    ...options,
+  };
   const s = useStatewireSession(configured);
   const conn = useLink(configured, s.ctx);
   useEffect(() => setTransport(s, conn), [s, conn]);
+  const lanes = useMemo(
+    () => ({
+      documents: documentSource(s),
+      invoke: (protocol: string, method: string, params: readonly unknown[]) =>
+        invokeProtocol(s, protocol, method, params),
+      failures: {
+        list: () => failedCommands(s),
+        retry: (entry: StatewireClient.FailedCommand) => retryFailed(s, entry),
+        discard: (entry: StatewireClient.FailedCommand) =>
+          discardFailed(s, entry),
+      },
+    }),
+    [s],
+  );
 
   return {
     state: s.canonical,
-    documents: documentSource(s),
+    ...lanes,
     get selection() {
       return s.selection;
     },
-    invoke: (protocol, method, params) =>
-      invokeProtocol(s, protocol, method, params),
     commands: s.commands,
     connection: conn.connection,
     source: s.source,
     get isBusy() {
       return !s.idle;
     },
-    failures: {
-      list: () => failedCommands(s),
-      retry: (entry) => retryFailed(s, entry),
-      discard: (entry) => discardFailed(s, entry),
-    },
   };
 };

package/src/transports/testing.ts

@@ -45,9 +45,9 @@ export const createMockTransport = <TState>(
   protocol = "default",
   options: { ephemeral?: readonly string[] } = {},
 ): MockTransport<TState> => {
-  const ephemeral = (options.ephemeral ?? []).map(
-    (child) => `${protocol}/${child}`,
-  );
+  // Read per attach: a test can grow the lane set between connects.
+  const ephemeralLanes = () =>
+    (options.ephemeral ?? []).map((child) => `${protocol}/${child}`);
   let state: unknown = initialState;
   let clientId = "";
   let finished = false;
@@ -85,6 +85,7 @@ export const createMockTransport = <TState>(
       clientId = id;
       if (!clients.has(id)) clients.set(id, {});
       const rec = clients.get(id)!;
+      const ephemeral = ephemeralLanes();
       for (const lane of ephemeral) delete rec[lane];
       const frame = JSON.parse(String(init?.body ?? "{}")) as StatewireFrame;
       admit(id, frame);

package/src/transports/ws.ts

@@ -57,6 +57,7 @@ const runSocket = (
 ): Promise<AttemptOutcome> =>
   new Promise((resolve, reject) => {
     let timer: ReturnType<typeof setTimeout> | undefined;
+    let ping: ReturnType<typeof setInterval> | undefined;
     let timedOut = false;
     let outcome: AttemptOutcome | null = null;
     let closed = false;
@@ -78,10 +79,14 @@ const runSocket = (
         return;
       }
       ws.send(frame);
+      // A ping keeps a host that cannot run timers (a hibernating durable
+      // object answers it without waking) talking before the silence timeout.
+      ping = setInterval(() => ws.send("{}"), timing.pingIntervalMs);
     };
     const stale = () => Boolean(outcome) || closed || abort.signal.aborted;
     const fail = (error: unknown) => {
       clearTimeout(timer);
+      clearInterval(ping);
       reject(error instanceof Error ? error : new Error("protocol"));
       ws.close();
     };
@@ -116,6 +121,7 @@ const runSocket = (
     ws.onclose = () => {
       closed = true;
       clearTimeout(timer);
+      clearInterval(ping);
       if (outcome) resolve(outcome);
       else reject(new Error(timedOut ? "timeout" : "network"));
     };

package/src/types.ts

@@ -67,6 +67,8 @@ export interface Statewire<
   /** Negation of the server's broadcast idle level; absent means always busy. */
   isBusy?: boolean;
   work?: { readonly isIdle: boolean };
+  /** Called by the serving host once an attach is registered, before its hello: documents mounted here ride the hello. */
+  attaching?: (attach: StatewireHost.Attach) => void;
   /** Called by the serving host when an attach ends; its ephemeral documents and includes are gone. */
   detached?: (attach: StatewireHost.Attach) => void;
   /** The retained failed-send lane; present on transports with a durable session. */