statewire 0.18.1 → 0.19.0

package/src/client/timing.ts

@@ -6,6 +6,8 @@ export const timing = {
   random: Math.random,
 };
 
+export const retryHint = (ms: number) => Math.min(ms, timing.backoffMaxMs);
+
 export const backoff = (attempt: number) => {
   const limit = Math.min(
     timing.backoffBaseMs * 2 ** (attempt - 1),

package/src/host/engine.ts

@@ -3,11 +3,13 @@
  * message/payload travel to the client's rejected promise.
  */
 export class StatewireReject extends Error {
+  readonly code?: string;
   readonly payload?: unknown;
 
-  constructor(message: string, options?: { payload?: unknown }) {
+  constructor(message: string, options?: { code?: string; payload?: unknown }) {
     super(message);
     this.name = "StatewireReject";
+    if (options?.code !== undefined) this.code = options.code;
     if (options?.payload !== undefined) this.payload = options.payload;
   }
 }

package/src/host/host.ts

@@ -16,6 +16,9 @@ const isDev = () =>
 
 const stateHosts = new WeakMap<object, StatewireHost.StateHost>();
 
+export const documentIdentity = (protocol: string, key?: readonly string[]) =>
+  JSON.stringify([protocol, key ?? null]);
+
 /** Host-side accessor for a `useStatewireState` state object's source (`snapshot()` reads the committed state). */
 export const getStateHost = (
   state: object,
@@ -25,8 +28,10 @@ type StateCell = {
   current: unknown;
   draft: StateDraft<object> | null;
   changed: StatewirePath[];
+  documents: Map<string, StatewireHost.Document>;
   onOp: ((op: Statewire.Op) => void) | null;
   onChange: (() => void) | null;
+  onDocuments: (() => void) | null;
   ctl: StatewireHost.StateCtl;
   host: StatewireHost.StateHost;
   bump: () => void;
@@ -45,8 +50,10 @@ export const useStatewireState = <TState>(
       current: sanitizeValue(init()),
       draft: null,
       changed: [[]],
+      documents: new Map(),
       onOp: null,
       onChange: null,
+      onDocuments: null,
       bump: () => setVersion((v) => v + 1),
       ctl: {
         apply: (ops) => {
@@ -73,6 +80,38 @@ export const useStatewireState = <TState>(
           c.changed = [];
           return changed;
         },
+        mount: (protocol, value, options) => {
+          const key = options?.key;
+          const main = options?.main ?? key === undefined;
+          if (main) {
+            for (const [id, doc] of c.documents) {
+              if (
+                doc.protocol === protocol &&
+                doc.main &&
+                id !== documentIdentity(protocol, key)
+              )
+                throw new Error(
+                  `statewire: ${protocol} already has a main document`,
+                );
+            }
+          }
+          c.documents.set(documentIdentity(protocol, key), {
+            protocol,
+            key: key === undefined ? null : [...key],
+            main,
+            value: sanitizeValue(value),
+          });
+          c.onDocuments?.();
+        },
+        unmount: (protocol, key) => {
+          if (!c.documents.delete(documentIdentity(protocol, key)))
+            throw new Error("statewire: document is not mounted");
+          c.onDocuments?.();
+        },
+        documents: () => c.documents,
+        setOnDocuments: (listener) => {
+          c.onDocuments = listener;
+        },
       },
     };
     return c;
@@ -128,6 +167,7 @@ export type CommandsSubmission = {
   params: readonly unknown[];
   clientId?: string;
   caller?: StatewireHost.Caller;
+  attach?: StatewireHost.Attach;
   onApplied?: () => void;
   onSettle?: (outcome: CommandsOutcome) => void;
 };
@@ -178,13 +218,12 @@ type CommandsCell = {
 
 const STALL_WARN_MS = 5000;
 
-// In-process dispatch has no wire client: never any ambient context, trivially attached.
+// In-process dispatch has no wire client: trivially attached.
 const LOCAL_CALLER: StatewireHost.Caller = Object.freeze({
   get clientId(): string {
     throw new Error("statewire: in-process dispatch has no client id");
   },
   auth: undefined,
-  context: null,
   isConnected: true,
 });
 
@@ -196,6 +235,7 @@ const toSendError = (error: unknown): StatewireSendError =>
           fate: "rejected",
           cause: "server",
           message: error.message,
+          ...(error.code !== undefined && { code: error.code }),
           ...(error.payload !== undefined && { payload: error.payload }),
         })
       : new StatewireSendError({
@@ -221,8 +261,8 @@ const settleInvocation = (
   if (inv.settled) return;
   inv.settled = true;
   cell.active.delete(inv);
-  applyInvocation(cell, inv);
   if (settled.type === "resolved") {
+    applyInvocation(cell, inv);
     const outcome: CommandsOutcome =
       settled.value === undefined
         ? { type: "accepted" }
@@ -231,6 +271,7 @@ const settleInvocation = (
     inv.origin?.onSettle?.(outcome);
     call.resolve(outcome.payload);
   } else {
+    cell.listener?.onCovered?.(inv);
     const error = toSendError(settled.error);
     const outcome: CommandsOutcome = { type: "rejected", error };
     cell.listener?.onSettle(inv, outcome);
@@ -299,8 +340,14 @@ const dispatch = (cell: CommandsCell, call: QueuedCall) => {
   cell.active.set(inv, call);
   cell.listener?.onStart(inv);
   cell.listener?.onPosted?.(inv);
+  const attach = call.origin?.attach;
   const ctx: StatewireHost.Ctx = {
     caller: call.origin?.caller ?? LOCAL_CALLER,
+    get attach() {
+      if (attach === undefined)
+        throw new Error("statewire: in-process dispatch has no attach");
+      return attach;
+    },
     signal: inv.controller.signal,
     applied: () => {
       if (!inv.settled) applyInvocation(cell, inv);

package/src/host/http.ts

@@ -141,6 +141,7 @@ const attachSse = (
   clientId: string,
   auth: unknown,
   selection: StatewireProtocol.Selection,
+  frame?: ParsedFrame,
 ): SseAttachment => {
   let controller: ReadableStreamDefaultController<Uint8Array>;
   let connection: Registration["connection"] | null = null;
@@ -194,7 +195,15 @@ const attachSse = (
       }
     },
   };
-  const registration = register(h, clientId, socket, false, auth, selection);
+  const registration = register(
+    h,
+    clientId,
+    socket,
+    false,
+    auth,
+    selection,
+    frame,
+  );
   connection = registration?.connection ?? null;
   if (!open) connection?.close();
   return {
@@ -220,24 +229,6 @@ const streamResponse = (
   });
 };
 
-const admitAttachFrame = (
-  h: SocketHostState,
-  registration: Registration,
-  frame: ParsedFrame,
-) => {
-  if (frame.ctx.length === 0 && frame.cmd.length === 0) return;
-  const admission = admitFrame(
-    h,
-    registration.rec,
-    frame,
-    registration.conn.auth,
-    registration.conn.selection,
-  );
-  if (admission.type === "refused") {
-    sendTo(h, registration.conn, JSON.stringify(admission.syn));
-  }
-};
-
 const getStream = async (
   h: SocketHostState,
   request: Request,
@@ -283,10 +274,7 @@ const postStream = async (
   }
   let frame: ParsedFrame;
   try {
-    frame =
-      body === null && !raw.trim()
-        ? { ctx: [], cmd: [] }
-        : parseFrameValue(body);
+    frame = body === null && !raw.trim() ? { cmd: [] } : parseFrameValue(body);
   } catch (error) {
     if (!(error instanceof Error) || error.name !== "StatewireViolation") {
       throw error;
@@ -307,14 +295,16 @@ const postStream = async (
   ]);
   if ("fin" in selection)
     return Response.json(selection, { status: selection.fin.status });
-  const attachment = attachSse(h, client.clientId, authorized.auth, selection);
-  if (attachment.registration === null) return streamResponse(attachment, null);
-  const lease = mintLease();
-  attachment.registration.conn.lease = lease;
+  let attachment: SseAttachment;
   try {
-    admitAttachFrame(h, attachment.registration, frame);
+    attachment = attachSse(
+      h,
+      client.clientId,
+      authorized.auth,
+      selection,
+      frame,
+    );
   } catch (error) {
-    closeConn(h, attachment.registration.conn, 1008, "invalid-context");
     if (!(error instanceof Error) || error.name !== "StatewireViolation")
       throw error;
     return Response.json(
@@ -322,6 +312,9 @@ const postStream = async (
       { status: 400 },
     );
   }
+  if (attachment.registration === null) return streamResponse(attachment, null);
+  const lease = mintLease();
+  attachment.registration.conn.lease = lease;
   return streamResponse(attachment, lease);
 };
 
@@ -376,7 +369,6 @@ export const frames = async (
     return Response.json({ error: "stale-lease" }, { status: 423 });
   }
   const clientId = leased.clientId;
-  const rec = h.clients.get(clientId)!;
   const raw = await readFrameBody(request);
   if (raw === null) {
     return Response.json({ error: "frame body too large" }, { status: 413 });
@@ -395,7 +387,7 @@ export const frames = async (
   }
   let admission: ReturnType<typeof admitFrame>;
   try {
-    admission = admitFrame(h, rec, frame, leased.auth, leased.selection);
+    admission = admitFrame(h, leased, frame);
   } catch (error) {
     if (!(error instanceof Error) || error.name !== "StatewireViolation")
       throw error;