statewire 0.0.1 → 0.0.3

package/src/client/session.ts

@@ -1,27 +1,28 @@
+import { useEffect, useState } from "react";
 import { applyOps } from "../wire/ops";
 import type { StatewirePath } from "../wire/ops";
 import type { StatewireResponse } from "./connection";
 import { bindCommandsHost } from "../host/host";
 import type { CommandsInvocation, CommandsListener } from "../host/host";
-import type { StatewireStateSource } from "../types";
+import type { Statewire } from "../types";
+import type { StatewireClient } from "../statewire";
 import { createMemorySessionStore } from "./sessionStore";
 import type {
   StatewireSessionRecord,
   StatewireSessionStore,
+  StatewireSessionStoreOptions,
 } from "./sessionStore";
-import { backoff } from "./timing";
+import { retryDelay } from "./timing";
+import { createMethodProxy } from "../util/methodProxy";
+import { randomId } from "../util/randomId";
 import { StatewireSendError } from "../types";
-import type { SendFailure as StatewireSendFailure } from "../types";
 import type {
   RemoteLink,
+  StatewireRemoteProps,
   StatewireSubmitResult,
   StatewireWireCommand,
 } from "../transports/sse";
 
-export type SessionOptions = {
-  sessionStore?: StatewireSessionStore | undefined;
-};
-
 /**
  * queued/trying/posted: overlay live, result pending. awaiting-result: acked
  * (overlay gone) but the result rides a late res; `posted: false` re-sends.
@@ -39,7 +40,8 @@ type PendingState =
 type Pending = {
   readonly seq: number;
   readonly command: StatewireWireCommand;
-  readonly inv: CommandsInvocation;
+  /** null for context submissions — they carry no command lifecycle. */
+  readonly inv: CommandsInvocation | null;
   state: PendingState;
   resolve: (payload: unknown) => void;
   reject: (error: StatewireSendError) => void;
@@ -47,7 +49,7 @@ type Pending = {
 
 type Outcome =
   | { ok: true; payload: unknown }
-  | { ok: false; failure: StatewireSendFailure };
+  | { ok: false; failure: StatewireClient.SendFailure };
 
 const isResolved = (state: PendingState) =>
   state.at === "settled-live" || state.at === "done";
@@ -55,6 +57,15 @@ const isResolved = (state: PendingState) =>
 const isStateSettled = (state: PendingState) =>
   state.at === "awaiting-result" || state.at === "done";
 
+// The pump admits an entry as trying before sending; only the pump itself
+// requeues, and a done entry is never still pending.
+const inFlight = (state: PendingState) => {
+  if (state.at === "queued" || state.at === "done") {
+    throw new Error(`statewire: ${state.at} entry observed after a send`);
+  }
+  return state;
+};
+
 const legalTransitions: Record<PendingState["at"], PendingState["at"][]> = {
   queued: ["queued", "trying", "awaiting-result", "settled-live", "done"],
   // trying -> queued: an answered unknown-client proves the seq was never admitted.
@@ -92,20 +103,22 @@ const transition = (
   }
   const covers = !isStateSettled(prev) && isStateSettled(next);
   entry.state = next;
-  if (covers) s.lifecycle?.onCovered?.(entry.inv);
+  if (covers && entry.inv) s.lifecycle?.onCovered?.(entry.inv);
   if (settles && outcome !== undefined) {
     if (outcome.ok) {
       entry.resolve(outcome.payload);
-      s.lifecycle?.onSettle(entry.inv, {
-        type: "accepted",
-        payload: outcome.payload,
-      });
+      if (entry.inv)
+        s.lifecycle?.onSettle(entry.inv, {
+          type: "accepted",
+          payload: outcome.payload,
+        });
     } else {
       entry.reject(new StatewireSendError(outcome.failure));
-      s.lifecycle?.onSettle(entry.inv, {
-        type: "rejected",
-        error: new StatewireSendError(outcome.failure),
-      });
+      if (entry.inv)
+        s.lifecycle?.onSettle(entry.inv, {
+          type: "rejected",
+          error: new StatewireSendError(outcome.failure),
+        });
     }
   }
   if (next.at === "done") {
@@ -122,10 +135,11 @@ const carried = (
       ? { posted: state.at === "posted", failedAttempts: state.failedAttempts }
       : { posted: state.posted, failedAttempts: state.failedAttempts };
 
-const newClientId = () =>
-  `c-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+const newClientId = () => `c-${randomId()}`;
 
-const rejectedSend = (failure: StatewireSendFailure): Promise<unknown> => {
+const rejectedSend = (
+  failure: StatewireClient.SendFailure,
+): Promise<unknown> => {
   const result = Promise.reject<unknown>(new StatewireSendError(failure));
   result.catch(() => {});
   return result;
@@ -135,14 +149,16 @@ type AttachState = "detached" | "attached" | "finished";
 
 type Session = {
   record: StatewireSessionRecord;
+  ctx: StatewireRemoteProps;
   recordPersisted: boolean;
   store: StatewireSessionStore;
   lastAck: number;
+  context: Record<string, unknown> | undefined;
   pending: Pending[];
   canonical: unknown;
   lastPublished: unknown;
   changed: StatewirePath[];
-  source: StatewireStateSource;
+  source: Statewire.StateSource;
   attach: AttachState;
   attachEpoch: number;
   running: boolean;
@@ -156,38 +172,30 @@ type Session = {
   commands: Record<string, (...params: unknown[]) => Promise<unknown>>;
 };
 
-const createCommandsProxy = (
-  send: (command: StatewireWireCommand) => Promise<unknown>,
-): Session["commands"] => {
-  const memo = new Map<string, (...params: unknown[]) => Promise<unknown>>();
-  return new Proxy({} as Session["commands"], {
-    get: (_target, method) => {
-      if (typeof method !== "string") return undefined;
-      let fn = memo.get(method);
-      if (fn === undefined) {
-        fn = (...params: unknown[]) => send({ method, params });
-        memo.set(method, fn);
-      }
-      return fn;
-    },
-  });
-};
-
-const createSession = (options: SessionOptions): Session => {
+const createSession = (options: StatewireSessionStoreOptions): Session => {
   const store = options.sessionStore ?? createMemorySessionStore();
   const stored = store.load();
   const record = stored ?? { clientId: newClientId(), nextSeq: 1 };
   const s: Session = {
     record,
+    ctx: {
+      get clientId() {
+        return s.record.clientId;
+      },
+      onSnapshot: (args) => handleSnapshot(s, args),
+      onOps: (args) => handleOps(s, args),
+      onFinish: (args) => handleFinish(s, args),
+    },
     recordPersisted: stored !== null,
     store,
     lastAck: -1,
+    context: undefined,
     pending: [],
     canonical: undefined,
     lastPublished: undefined,
     changed: [],
     source: {
-      root: () => s.canonical,
+      snapshot: () => s.canonical,
       takeChanged: () => {
         const changed = s.changed;
         s.changed = [];
@@ -207,7 +215,7 @@ const createSession = (options: SessionOptions): Session => {
     notify: () => {},
     emitEvent: () => {},
     send: (command) => sendCommand(s, command),
-    commands: createCommandsProxy((command) => s.send(command)),
+    commands: createMethodProxy((method, params) => s.send({ method, params })),
   };
   bindCommandsHost(s.commands, {
     setListener: (listener) => {
@@ -231,12 +239,25 @@ const wake = (s: Session) => {
 
 const waitForWake = (s: Session) => new Promise<void>((r) => s.waiters.push(r));
 
+const sleepUntilWake = (s: Session, delayMs: number) =>
+  new Promise<void>((resolve) => {
+    const waiter = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    const timer = setTimeout(() => {
+      s.waiters = s.waiters.filter((w) => w !== waiter);
+      resolve();
+    }, delayMs);
+    s.waiters.push(waiter);
+  });
+
 const settleAll = (
   s: Session,
   detach: "evicted" | "unmount" | "gone" | "superseded",
   verdict?: {
     entry: Pending;
-    failure: StatewireSendFailure;
+    failure: StatewireClient.SendFailure;
   },
 ) => {
   const cause = (
@@ -248,7 +269,7 @@ const settleAll = (
     } as const
   )[detach];
   const batch = s.pending;
-  const detachFailure = (entry: Pending): StatewireSendFailure => {
+  const detachFailure = (entry: Pending): StatewireClient.SendFailure => {
     const state = entry.state;
     if (state.at === "awaiting-result")
       return { fate: "result-unavailable", cause };
@@ -271,13 +292,16 @@ const evict = (
   s: Session,
   verdict?: {
     entry: Pending;
-    failure: StatewireSendFailure;
+    failure: StatewireClient.SendFailure;
   },
 ) => {
   settleAll(s, "evicted", verdict);
   s.record = { clientId: newClientId(), nextSeq: 1 };
   s.store.save(s.record);
   s.attach = "detached";
+  // The server dropped this client's record and its stored context with it:
+  // the new session opens with a fresh full root replace.
+  if (s.context !== undefined) void s.send({ context: s.context });
   publish(s);
   wake(s);
 };
@@ -285,7 +309,7 @@ const evict = (
 const noteAcked = (s: Session, seq: number) => {
   for (const entry of s.pending) {
     if (entry.seq > seq || isStateSettled(entry.state)) continue;
-    s.lifecycle?.onAck(entry.inv);
+    if (entry.inv) s.lifecycle?.onAck(entry.inv);
   }
 };
 
@@ -347,12 +371,16 @@ const applyResponse = (s: Session, response: StatewireResponse) => {
                 ? {
                     fate: "invalid-params",
                     cause: "server",
-                    message: response.message ?? "",
+                    message:
+                      response.message ??
+                      protocolError("rejected response missing message"),
                   }
                 : {
                     fate: "rejected",
                     cause: "server",
-                    message: response.message ?? "",
+                    message:
+                      response.message ??
+                      protocolError("rejected response missing message"),
                     ...(response.payload !== undefined && {
                       payload: response.payload,
                     }),
@@ -382,12 +410,9 @@ const ingestOps = (s: Session, ops: unknown[]) => {
   return applied.events;
 };
 
-const publishIngested = (
-  s: Session,
-  events: { event: unknown; state: unknown }[],
-) => {
+const publishIngested = (s: Session, events: unknown[]) => {
   publish(s);
-  for (const { event } of events) s.emitEvent(event);
+  for (const event of events) s.emitEvent(event);
   wake(s);
 };
 
@@ -459,7 +484,7 @@ const handleOps = (
 };
 
 const handleFinish = (s: Session, { reason }: { reason: string }) => {
-  if (reason === "ended" || reason === "error") return;
+  if (reason === "evicted" || reason === "error") return;
   s.attach = "finished";
   settleAll(s, reason === "superseded" ? "superseded" : "gone");
   publish(s);
@@ -504,18 +529,12 @@ const pump = async (s: Session) => {
       } catch (error) {
         if (!s.running || isFinished(s)) return;
         if (!s.pending.includes(entry)) continue;
-        const state = entry.state;
-        if (state.at === "queued" || state.at === "done") continue;
+        const state = inFlight(entry.state);
         transition(s, entry, {
           ...state,
           failedAttempts: state.failedAttempts + 1,
         });
-        const { retryAfterMs } = error as { retryAfterMs?: unknown };
-        const delay =
-          typeof retryAfterMs === "number"
-            ? retryAfterMs
-            : backoff(state.failedAttempts + 1);
-        await new Promise((r) => setTimeout(r, delay));
+        await sleepUntilWake(s, retryDelay(error, state.failedAttempts + 1));
         continue;
       }
       if (!s.running) return;
@@ -535,13 +554,12 @@ const pump = async (s: Session) => {
         ) {
           transition(s, entry, { ...state, posted: true });
         }
-        s.lifecycle?.onPosted?.(entry.inv);
+        if (entry.inv) s.lifecycle?.onPosted?.(entry.inv);
         if (response !== undefined) {
           applyResponse(s, response);
           publish(s);
         }
       } else if (result.type === "rejected") {
-        const { message, payload } = result;
         transition(
           s,
           entry,
@@ -551,8 +569,7 @@ const pump = async (s: Session) => {
             failure: {
               fate: "rejected",
               cause: "server",
-              message,
-              ...(payload !== undefined && { payload }),
+              message: result.message,
             },
           },
         );
@@ -589,16 +606,14 @@ const pump = async (s: Session) => {
           );
           // Every attempt answered means the server never saw it; a thrown
           // attempt may have left the machine unanswered, so the verdict is "lost".
-          const state = entry.state;
-          const failure: StatewireSendFailure =
+          const state = inFlight(entry.state);
+          const failure: StatewireClient.SendFailure =
             state.at === "awaiting-result"
               ? { fate: "result-unavailable", cause: "session-lost" }
-              : state.at === "queued" || state.at === "done"
-                ? { fate: "aborted", cause: "session-lost" }
-                : {
-                    fate: state.failedAttempts > 0 ? "lost" : "aborted",
-                    cause: "session-lost",
-                  };
+              : {
+                  fate: state.failedAttempts > 0 ? "lost" : "aborted",
+                  cause: "session-lost",
+                };
           evict(s, { entry, failure });
           s.transport?.connection.reconnect();
         }
@@ -646,13 +661,16 @@ const sendCommand = (
   const entry: Pending = {
     seq,
     command,
-    inv: {
-      method: command.method,
-      params: command.params,
-      ts: Date.now(),
-      seq,
-      clientId: s.record.clientId,
-    },
+    inv:
+      command.method === undefined
+        ? null
+        : {
+            method: command.method,
+            params: command.params,
+            ts: Date.now(),
+            seq,
+            clientId: s.record.clientId,
+          },
     state: { at: "queued", pendingMarked: false },
     resolve: () => {},
     reject: () => {},
@@ -663,17 +681,38 @@ const sendCommand = (
   });
   result.catch(() => {});
   s.pending.push(entry);
-  s.lifecycle?.onStart(entry.inv);
+  if (entry.inv) s.lifecycle?.onStart(entry.inv);
   void pump(s);
   return result;
 };
 
-export {
-  createSession,
-  handleSnapshot,
-  handleFinish,
-  handleOps,
-  setTransport,
-  start,
-  stop,
+const setContext = (
+  s: Session,
+  value: Record<string, unknown>,
+): Promise<unknown> => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("statewire: context must be a plain object");
+  }
+  s.context = value;
+  return s.send({ context: value });
+};
+
+export const useStatewireSession = (
+  options: StatewireSessionStoreOptions,
+  emit: (event: unknown) => void,
+): Session => {
+  const [s] = useState(() => createSession(options));
+  useEffect(() => {
+    s.emitEvent = emit;
+    return () => {
+      s.emitEvent = () => {};
+    };
+  }, [s, emit]);
+  useEffect(() => {
+    start(s);
+    return () => stop(s);
+  }, [s]);
+  return s;
 };
+
+export { setContext, setTransport };

package/src/client/sessionStore.ts

@@ -9,7 +9,7 @@ export type StatewireSessionStore = {
 };
 
 export type StatewireSessionStoreOptions = {
-  sessionStore?: StatewireSessionStore;
+  sessionStore?: StatewireSessionStore | undefined;
 };
 
 export const createMemorySessionStore = (): StatewireSessionStore => {

package/src/client/timing.ts

@@ -6,3 +6,9 @@ export const timing = {
 
 export const backoff = (attempt: number) =>
   Math.min(timing.backoffBaseMs * 2 ** (attempt - 1), timing.backoffMaxMs);
+
+export const retryDelay = (error: unknown, attempt: number): number => {
+  const retryAfterMs = (error as { retryAfterMs?: unknown } | undefined)
+    ?.retryAfterMs;
+  return typeof retryAfterMs === "number" ? retryAfterMs : backoff(attempt);
+};

package/src/host/adapter.ts

@@ -0,0 +1,33 @@
+import type { StatewireHostInternal } from "../host-internal";
+
+export const CLIENT_QUERY_PARAM = "client";
+
+export const clientIdFromUrl = (url: string | null | undefined): string => {
+  if (!url) {
+    throw new Error("statewire: cannot resolve client id: missing url");
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(url, "http://statewire");
+  } catch {
+    throw new Error(
+      `statewire: cannot resolve client id: unparseable url "${url}"`,
+    );
+  }
+  const clientId = parsed.searchParams.get(CLIENT_QUERY_PARAM);
+  if (!clientId) {
+    throw new Error(
+      `statewire: url is missing the "${CLIENT_QUERY_PARAM}" query parameter`,
+    );
+  }
+  return clientId;
+};
+
+export const textFrameOrClose = (
+  socket: Pick<StatewireHostInternal.Socket, "close">,
+  data: unknown,
+): string | null => {
+  if (typeof data === "string") return data;
+  socket.close(1008, "text frames only");
+  return null;
+};