statewire 0.0.0-0 → 0.0.2

package/src/client/session.ts

@@ -0,0 +1,696 @@
+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 { Statewire } from "../types";
+import type { StatewireClient } from "../statewire";
+import { createMemorySessionStore } from "./sessionStore";
+import type {
+  StatewireSessionRecord,
+  StatewireSessionStore,
+  StatewireSessionStoreOptions,
+} from "./sessionStore";
+import { retryDelay } from "./timing";
+import { createMethodProxy } from "../util/methodProxy";
+import { randomId } from "../util/randomId";
+import { StatewireSendError } from "../types";
+import type {
+  RemoteLink,
+  StatewireRemoteProps,
+  StatewireSubmitResult,
+  StatewireWireCommand,
+} from "../transports/sse";
+
+/**
+ * queued/trying/posted: overlay live, result pending. awaiting-result: acked
+ * (overlay gone) but the result rides a late res; `posted: false` re-sends.
+ * settled-live: result settled but the overlay stays until the covering ack.
+ * done: removed from the queue.
+ */
+type PendingState =
+  | { at: "queued"; pendingMarked: boolean }
+  | { at: "trying"; pendingMarked: boolean; failedAttempts: number }
+  | { at: "posted"; pendingMarked: boolean; failedAttempts: number }
+  | { at: "awaiting-result"; posted: boolean; failedAttempts: number }
+  | { at: "settled-live"; posted: boolean; failedAttempts: number }
+  | { at: "done" };
+
+type Pending = {
+  readonly seq: number;
+  readonly command: StatewireWireCommand;
+  readonly inv: CommandsInvocation;
+  state: PendingState;
+  resolve: (payload: unknown) => void;
+  reject: (error: StatewireSendError) => void;
+};
+
+type Outcome =
+  | { ok: true; payload: unknown }
+  | { ok: false; failure: StatewireClient.SendFailure };
+
+const isResolved = (state: PendingState) =>
+  state.at === "settled-live" || state.at === "done";
+
+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.
+  trying: [
+    "queued",
+    "trying",
+    "posted",
+    "awaiting-result",
+    "settled-live",
+    "done",
+  ],
+  posted: ["posted", "trying", "awaiting-result", "settled-live", "done"],
+  "awaiting-result": ["awaiting-result", "done"],
+  "settled-live": ["settled-live", "done"],
+  done: [],
+};
+
+const transition = (
+  s: Session,
+  entry: Pending,
+  next: PendingState,
+  outcome?: Outcome,
+) => {
+  const prev = entry.state;
+  if (!legalTransitions[prev.at].includes(next.at)) {
+    throw new Error(
+      `statewire: illegal pending transition ${prev.at} -> ${next.at}`,
+    );
+  }
+  const settles = !isResolved(prev) && isResolved(next);
+  if (settles && outcome === undefined) {
+    throw new Error(
+      `statewire: settling transition ${prev.at} -> ${next.at} without an outcome`,
+    );
+  }
+  const covers = !isStateSettled(prev) && isStateSettled(next);
+  entry.state = next;
+  if (covers) 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,
+      });
+    } else {
+      entry.reject(new StatewireSendError(outcome.failure));
+      s.lifecycle?.onSettle(entry.inv, {
+        type: "rejected",
+        error: new StatewireSendError(outcome.failure),
+      });
+    }
+  }
+  if (next.at === "done") {
+    s.pending = s.pending.filter((p) => p !== entry);
+  }
+};
+
+const carried = (
+  state: Exclude<PendingState, { at: "done" }>,
+): { posted: boolean; failedAttempts: number } =>
+  state.at === "queued"
+    ? { posted: false, failedAttempts: 0 }
+    : state.at === "trying" || state.at === "posted"
+      ? { posted: state.at === "posted", failedAttempts: state.failedAttempts }
+      : { posted: state.posted, failedAttempts: state.failedAttempts };
+
+const newClientId = () => `c-${randomId()}`;
+
+const rejectedSend = (
+  failure: StatewireClient.SendFailure,
+): Promise<unknown> => {
+  const result = Promise.reject<unknown>(new StatewireSendError(failure));
+  result.catch(() => {});
+  return result;
+};
+
+type AttachState = "detached" | "attached" | "finished";
+
+type Session = {
+  record: StatewireSessionRecord;
+  ctx: StatewireRemoteProps;
+  recordPersisted: boolean;
+  store: StatewireSessionStore;
+  lastAck: number;
+  pending: Pending[];
+  canonical: unknown;
+  lastPublished: unknown;
+  changed: StatewirePath[];
+  source: Statewire.StateSource;
+  attach: AttachState;
+  attachEpoch: number;
+  running: boolean;
+  pumping: boolean;
+  transport: RemoteLink | null;
+  waiters: (() => void)[];
+  lifecycle: CommandsListener | null;
+  notify: () => void;
+  emitEvent: (event: unknown) => void;
+  send: (command: StatewireWireCommand) => Promise<unknown>;
+  commands: Record<string, (...params: unknown[]) => Promise<unknown>>;
+};
+
+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,
+    pending: [],
+    canonical: undefined,
+    lastPublished: undefined,
+    changed: [],
+    source: {
+      snapshot: () => s.canonical,
+      takeChanged: () => {
+        const changed = s.changed;
+        s.changed = [];
+        return changed;
+      },
+      setOnChange: (listener) => {
+        s.notify = listener ?? (() => {});
+      },
+    },
+    attach: "detached",
+    attachEpoch: 0,
+    running: false,
+    pumping: false,
+    transport: null,
+    waiters: [],
+    lifecycle: null,
+    notify: () => {},
+    emitEvent: () => {},
+    send: (command) => sendCommand(s, command),
+    commands: createMethodProxy((method, params) => s.send({ method, params })),
+  };
+  bindCommandsHost(s.commands, {
+    setListener: (listener) => {
+      s.lifecycle = listener;
+    },
+  });
+  return s;
+};
+
+const publish = (s: Session) => {
+  if (s.canonical === s.lastPublished) return;
+  s.lastPublished = s.canonical;
+  s.notify();
+};
+
+const wake = (s: Session) => {
+  const waiters = s.waiters;
+  s.waiters = [];
+  for (const waiter of waiters) waiter();
+};
+
+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: StatewireClient.SendFailure;
+  },
+) => {
+  const cause = (
+    {
+      evicted: "session-lost",
+      unmount: "unmount",
+      gone: "stream-gone",
+      superseded: "superseded",
+    } as const
+  )[detach];
+  const batch = s.pending;
+  const detachFailure = (entry: Pending): StatewireClient.SendFailure => {
+    const state = entry.state;
+    if (state.at === "awaiting-result")
+      return { fate: "result-unavailable", cause };
+    if (state.at === "queued") {
+      const cascades = batch.some(
+        (p) => p.seq < entry.seq && p.state.at !== "queued",
+      );
+      return { fate: "aborted", cause: cascades ? "cascade" : cause };
+    }
+    return { fate: "lost", cause };
+  };
+  for (const entry of [...batch]) {
+    const failure =
+      entry === verdict?.entry ? verdict.failure : detachFailure(entry);
+    transition(s, entry, { at: "done" }, { ok: false, failure });
+  }
+};
+
+const evict = (
+  s: Session,
+  verdict?: {
+    entry: Pending;
+    failure: StatewireClient.SendFailure;
+  },
+) => {
+  settleAll(s, "evicted", verdict);
+  s.record = { clientId: newClientId(), nextSeq: 1 };
+  s.store.save(s.record);
+  s.attach = "detached";
+  publish(s);
+  wake(s);
+};
+
+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);
+  }
+};
+
+const spliceAcked = (s: Session, seq: number, settleVoid: boolean) => {
+  for (const entry of [...s.pending]) {
+    const state = entry.state;
+    if (entry.seq > seq || isStateSettled(state)) continue;
+    if (state.at === "settled-live") {
+      transition(s, entry, { at: "done" });
+    } else if (settleVoid && !state.pendingMarked) {
+      transition(s, entry, { at: "done" }, { ok: true, payload: undefined });
+    } else {
+      transition(s, entry, { at: "awaiting-result", ...carried(state) });
+    }
+  }
+};
+
+const protocolError = (message: string): never => {
+  throw new Error(`statewire: protocol error: ${message}`);
+};
+
+const applyResponse = (s: Session, response: StatewireResponse) => {
+  const entry = s.pending.find((p) => p.seq === response.seq);
+  if (!entry) return;
+  const state = entry.state;
+  if (state.at === "done") return;
+  switch (response.type) {
+    case "pending":
+      if (
+        state.at === "queued" ||
+        state.at === "trying" ||
+        state.at === "posted"
+      ) {
+        transition(s, entry, { ...state, pendingMarked: true });
+      }
+      break;
+    case "accepted":
+      if (state.at === "settled-live") break;
+      transition(
+        s,
+        entry,
+        state.at === "awaiting-result"
+          ? { at: "done" }
+          : { at: "settled-live", ...carried(state) },
+        { ok: true, payload: response.payload },
+      );
+      break;
+    case "rejected":
+      transition(
+        s,
+        entry,
+        { at: "done" },
+        {
+          ok: false,
+          failure:
+            response.code === "unknown-command"
+              ? { fate: "unknown-command", cause: "server" }
+              : response.code === "invalid-params"
+                ? {
+                    fate: "invalid-params",
+                    cause: "server",
+                    message:
+                      response.message ??
+                      protocolError("rejected response missing message"),
+                  }
+                : {
+                    fate: "rejected",
+                    cause: "server",
+                    message:
+                      response.message ??
+                      protocolError("rejected response missing message"),
+                    ...(response.payload !== undefined && {
+                      payload: response.payload,
+                    }),
+                  },
+        },
+      );
+      break;
+    case "crashed":
+    case "result-unavailable":
+      if (state.at === "settled-live") break;
+      transition(
+        s,
+        entry,
+        state.at === "awaiting-result"
+          ? { at: "done" }
+          : { at: "settled-live", ...carried(state) },
+        { ok: false, failure: { fate: response.type, cause: "server" } },
+      );
+      break;
+  }
+};
+
+const ingestOps = (s: Session, ops: unknown[]) => {
+  const applied = applyOps(s.canonical, ops);
+  s.canonical = applied.state;
+  s.changed.push(...applied.changedPaths);
+  return applied.events;
+};
+
+const publishIngested = (s: Session, events: unknown[]) => {
+  publish(s);
+  for (const event of events) s.emitEvent(event);
+  wake(s);
+};
+
+const handleSnapshot = (
+  s: Session,
+  { ops, lastSeq }: { ops: unknown[]; lastSeq: number },
+) => {
+  if (lastSeq === -1 && s.attach !== "detached") {
+    evict(s);
+    s.transport?.connection.reconnect();
+    publishIngested(s, ingestOps(s, ops));
+    return;
+  }
+  const events = ingestOps(s, ops);
+  s.attach = "attached";
+  s.attachEpoch += 1;
+  // The attach snapshot is not the true covering envelope: acked entries
+  // stay awaiting their result and re-send under seq dedup.
+  noteAcked(s, lastSeq);
+  spliceAcked(s, lastSeq, false);
+  s.lastAck = lastSeq;
+  for (const entry of s.pending) {
+    const state = entry.state;
+    if (entry.seq <= lastSeq) {
+      if (state.at === "awaiting-result" && state.posted) {
+        transition(s, entry, { ...state, posted: false });
+      }
+      if (state.at === "awaiting-result") void pump(s);
+    } else if (state.at === "posted") {
+      // Above the ack watermark a prior receipt no longer counts.
+      transition(s, entry, {
+        at: "trying",
+        pendingMarked: state.pendingMarked,
+        failedAttempts: state.failedAttempts,
+      });
+      void pump(s);
+    } else if (state.at === "settled-live" && state.posted) {
+      transition(s, entry, { ...state, posted: false });
+      void pump(s);
+    }
+  }
+  publishIngested(s, events);
+};
+
+const handleOps = (
+  s: Session,
+  {
+    ops,
+    res,
+    ack,
+  }: { ops: unknown[]; res?: StatewireResponse[]; ack?: number },
+) => {
+  const horizon = ack === undefined ? s.lastAck : Math.max(s.lastAck, ack);
+  if (res !== undefined) {
+    for (const response of res) {
+      if (response.seq > horizon) {
+        protocolError("response seq beyond the ack");
+      }
+    }
+  }
+  const events = ingestOps(s, ops);
+  if (ack !== undefined) noteAcked(s, ack);
+  if (res !== undefined) for (const response of res) applyResponse(s, response);
+  if (ack !== undefined) {
+    spliceAcked(s, ack, true);
+    s.lastAck = Math.max(s.lastAck, ack);
+  }
+  publishIngested(s, events);
+};
+
+const handleFinish = (s: Session, { reason }: { reason: string }) => {
+  if (reason === "evicted" || reason === "error") return;
+  s.attach = "finished";
+  settleAll(s, reason === "superseded" ? "superseded" : "gone");
+  publish(s);
+  wake(s);
+};
+
+const isFinished = (s: Session) => s.attach === "finished";
+
+const sendable = (p: Pending) =>
+  p.state.at === "queued" ||
+  p.state.at === "trying" ||
+  ((p.state.at === "awaiting-result" || p.state.at === "settled-live") &&
+    !p.state.posted);
+
+const pump = async (s: Session) => {
+  if (s.pumping) return;
+  s.pumping = true;
+  try {
+    while (s.running && !isFinished(s)) {
+      const entry = s.pending.find(sendable);
+      if (!entry) return;
+      const transport = s.transport;
+      if (s.attach !== "attached" || !transport) {
+        await waitForWake(s);
+        continue;
+      }
+      const clientId = s.record.clientId;
+      const epoch = s.attachEpoch;
+      if (entry.state.at === "queued") {
+        transition(s, entry, {
+          at: "trying",
+          pendingMarked: entry.state.pendingMarked,
+          failedAttempts: 0,
+        });
+      }
+      let result: StatewireSubmitResult;
+      try {
+        result = await transport.send({
+          seq: entry.seq,
+          command: entry.command,
+        });
+      } catch (error) {
+        if (!s.running || isFinished(s)) return;
+        if (!s.pending.includes(entry)) continue;
+        const state = inFlight(entry.state);
+        transition(s, entry, {
+          ...state,
+          failedAttempts: state.failedAttempts + 1,
+        });
+        await sleepUntilWake(s, retryDelay(error, state.failedAttempts + 1));
+        continue;
+      }
+      if (!s.running) return;
+      if (!s.pending.includes(entry)) continue;
+      if (result.type === "receipt") {
+        const response = result.response;
+        const state = entry.state;
+        if (state.at === "trying" || state.at === "posted") {
+          transition(s, entry, {
+            at: "posted",
+            pendingMarked: state.pendingMarked,
+            failedAttempts: state.failedAttempts,
+          });
+        } else if (
+          state.at === "awaiting-result" ||
+          state.at === "settled-live"
+        ) {
+          transition(s, entry, { ...state, posted: true });
+        }
+        s.lifecycle?.onPosted?.(entry.inv);
+        if (response !== undefined) {
+          applyResponse(s, response);
+          publish(s);
+        }
+      } else if (result.type === "rejected") {
+        transition(
+          s,
+          entry,
+          { at: "done" },
+          {
+            ok: false,
+            failure: {
+              fate: "rejected",
+              cause: "server",
+              message: result.message,
+            },
+          },
+        );
+        publish(s);
+      } else if (result.type === "stale-lease") {
+        if (epoch === s.attachEpoch) await waitForWake(s);
+      } else if (result.type === "unknown-client") {
+        // Eviction is never decided on the POST leg: re-attach first and let
+        // the snapshot's lastSeq deliver the verdict. An answered attempt
+        // proves the server never admitted this seq, so a clean entry requeues.
+        if (epoch === s.attachEpoch) {
+          const state = entry.state;
+          if (state.at === "trying" && state.failedAttempts === 0) {
+            transition(s, entry, {
+              at: "queued",
+              pendingMarked: state.pendingMarked,
+            });
+          }
+          s.transport?.connection.reconnect();
+          while (
+            s.running &&
+            !isFinished(s) &&
+            epoch === s.attachEpoch &&
+            clientId === s.record.clientId
+          ) {
+            await waitForWake(s);
+          }
+        }
+      } else if (result.type === "seq-gap") {
+        if (clientId === s.record.clientId) {
+          console.error(
+            `statewire: server reports a seq gap for seq ${entry.seq}; ` +
+              "treating the session as corrupt and rotating the client id",
+          );
+          // 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 = inFlight(entry.state);
+          const failure: StatewireClient.SendFailure =
+            state.at === "awaiting-result"
+              ? { fate: "result-unavailable", cause: "session-lost" }
+              : {
+                  fate: state.failedAttempts > 0 ? "lost" : "aborted",
+                  cause: "session-lost",
+                };
+          evict(s, { entry, failure });
+          s.transport?.connection.reconnect();
+        }
+      }
+    }
+  } finally {
+    s.pumping = false;
+  }
+};
+
+const start = (s: Session) => {
+  if (!s.recordPersisted) {
+    s.recordPersisted = true;
+    s.store.save(s.record);
+  }
+  s.running = true;
+  void pump(s);
+};
+
+const stop = (s: Session) => {
+  s.running = false;
+  wake(s);
+  settleAll(s, "unmount");
+};
+
+const setTransport = (s: Session, transport: RemoteLink) => {
+  if (s.transport === transport) return;
+  s.transport = transport;
+  wake(s);
+};
+
+const sendCommand = (
+  s: Session,
+  command: StatewireWireCommand,
+): Promise<unknown> => {
+  if (!s.running) {
+    return rejectedSend({ fate: "aborted", cause: "unmount" });
+  }
+  if (isFinished(s)) {
+    return rejectedSend({ fate: "aborted", cause: "stream-gone" });
+  }
+  const seq = s.record.nextSeq;
+  s.record = { ...s.record, nextSeq: seq + 1 };
+  s.store.save(s.record);
+  const entry: Pending = {
+    seq,
+    command,
+    inv: {
+      method: command.method,
+      params: command.params,
+      ts: Date.now(),
+      seq,
+      clientId: s.record.clientId,
+    },
+    state: { at: "queued", pendingMarked: false },
+    resolve: () => {},
+    reject: () => {},
+  };
+  const result = new Promise<unknown>((resolve, reject) => {
+    entry.resolve = resolve;
+    entry.reject = reject;
+  });
+  result.catch(() => {});
+  s.pending.push(entry);
+  s.lifecycle?.onStart(entry.inv);
+  void pump(s);
+  return result;
+};
+
+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 { setTransport };

package/src/client/sessionStore.ts

@@ -0,0 +1,23 @@
+export type StatewireSessionRecord = {
+  clientId: string;
+  nextSeq: number;
+};
+
+export type StatewireSessionStore = {
+  load: () => StatewireSessionRecord | null;
+  save: (record: StatewireSessionRecord) => void;
+};
+
+export type StatewireSessionStoreOptions = {
+  sessionStore?: StatewireSessionStore | undefined;
+};
+
+export const createMemorySessionStore = (): StatewireSessionStore => {
+  let record: StatewireSessionRecord | null = null;
+  return {
+    load: () => record,
+    save: (next) => {
+      record = next;
+    },
+  };
+};