statewire 0.9.2 → 0.10.0

package/src/client/session.ts

@@ -1,17 +1,20 @@
-import { useEffect, useState } from "react";
+import { useContext, useEffect, useState } from "react";
 import { applyOps } from "../wire/ops";
 import type { StatewirePath } from "../wire/ops";
 import type { StatewireCmd, StatewireSyn } from "./connection";
-import { encodeParams, encodeValue, reviveResponse } from "../wire/meta";
+import {
+  encodeParams,
+  encodeValue,
+  reviveResponse,
+  reviveValue,
+} from "../wire/meta";
 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,
+import {
+  SessionStorageContext,
+  createMemorySessionStore,
 } from "./sessionStore";
 import { backoff } from "./timing";
 import { createMethodProxy } from "../util/methodProxy";
@@ -65,16 +68,19 @@ const rejectedSend = (
 
 type AttachState = "detached" | "attached" | "finished";
 
-export type StatewireSessionOptions = StatewireSessionStoreOptions & {
+export type StatewireSessionOptions = {
+  sessionStore?: StatewireClient.SessionStorage | undefined;
   onDone?: (() => void) | undefined;
 };
 
 type Session = {
-  record: StatewireSessionRecord;
+  record: StatewireClient.SessionRecord;
   ctx: StatewireRemoteProps;
   recordPersisted: boolean;
-  store: StatewireSessionStore;
+  store: StatewireClient.SessionStorage;
   ephemeral: boolean;
+  /** An ephemeral record died with its attach: the storage is off for good. */
+  deactivated: boolean;
   sessionKnown: boolean;
   durableSeq: number;
   resumeAt: number;
@@ -128,9 +134,25 @@ const sleepUntilWake = (s: Session, delayMs: number) =>
     s.waiters.push(waiter);
   });
 
-const setRecord = (s: Session, record: StatewireSessionRecord) => {
+const setRecord = (s: Session, record: StatewireClient.SessionRecord) => {
   s.record = record;
-  if (!s.ephemeral) s.store.save(record);
+  if (!s.deactivated) s.store.save(record);
+};
+
+const backlog = (s: Session): StatewireClient.SessionCommand[] =>
+  s.pending
+    .filter((p) => p.seq > s.durableSeq)
+    .map((p) => ({ seq: p.seq, ...p.command }));
+
+// Storage holds what a reload must resend: a command leaves at its dur, at a
+// server verdict, or at a record reset — never at a local channel death.
+const syncBacklog = (s: Session) => {
+  const commands = backlog(s);
+  const unchanged =
+    commands.length === s.record.commands.length &&
+    commands.every((c, i) => c.seq === s.record.commands[i]!.seq);
+  if (unchanged) return;
+  setRecord(s, { ...s.record, commands });
 };
 
 const setIdle = (s: Session, level: boolean) => {
@@ -223,7 +245,7 @@ const resetRecord = (s: Session, clientId: string) => {
   }
   s.pending = [];
   s.durableSeq = 0;
-  setRecord(s, { clientId, nextSeq: 1, ctxNextSeq: 1 });
+  setRecord(s, { clientId, nextSeq: 1, ctxNextSeq: 1, commands: [] });
   for (const old of survivors) {
     s.lifecycle?.onCovered?.(old.inv);
     enqueue(s, old.command, old.inv.params, old.resolve, old.reject);
@@ -301,6 +323,7 @@ const handleCmd = (s: Session, cmd: StatewireCmd) => {
 
 const handleCmds = (s: Session, cmds: StatewireCmd[]) => {
   for (const cmd of cmds) handleCmd(s, cmd);
+  syncBacklog(s);
   wake(s);
 };
 
@@ -356,6 +379,7 @@ const handleHello = (
   s.frameFailures = 0;
   s.resumeAt = 0;
   s.ephemeral = record === "ephemeral";
+  if (s.ephemeral) s.deactivated = true;
   const [attachCmd, attachCtx] = s.attachLaneSeqs;
   s.attachLaneSeqs = [new Set(), new Set()];
   if (record === "resumed") {
@@ -368,6 +392,7 @@ const handleHello = (
     s.ctxPending = s.ctxPending.filter((c) => c.seq > ctxWatermark);
     for (const c of s.ctxPending) c.posted = attachCtx.has(c.seq);
     snapClocks(s, syn.seq ?? 0, ctxWatermark);
+    syncBacklog(s);
   } else {
     resetRecord(s, s.record.clientId);
   }
@@ -382,6 +407,7 @@ const handleOps = (
 ) => {
   ingestOps(s, ops);
   for (const cmd of cmds) handleCmd(s, cmd);
+  syncBacklog(s);
   publishIngested(s);
 };
 
@@ -558,6 +584,7 @@ const start = (s: Session) => {
     s.recordPersisted = true;
     s.store.save(s.record);
   }
+  resume(s);
   s.running = true;
   void pump(s);
 };
@@ -582,7 +609,6 @@ const enqueue = (
   reject: (error: StatewireSendError) => void,
 ) => {
   const seq = s.record.nextSeq;
-  setRecord(s, { ...s.record, nextSeq: seq + 1 });
   const entry: Pending = {
     seq,
     command,
@@ -600,10 +626,41 @@ const enqueue = (
     reject,
   };
   s.pending.push(entry);
+  setRecord(s, { ...s.record, nextSeq: seq + 1, commands: backlog(s) });
   s.lifecycle?.onStart(entry.inv);
   void pump(s);
 };
 
+// A stored command cannot be told from one that reached the server: attempted
+// keeps a fresh record settling it lost instead of replaying it blind.
+const resume = (s: Session) => {
+  const stored = [...s.record.commands].sort((a, b) => a.seq - b.seq);
+  for (const { seq, ...command } of stored) {
+    const params =
+      command.meta === undefined
+        ? command.params
+        : (reviveValue([...command.params], command.meta) as unknown[]);
+    const entry: Pending = {
+      seq,
+      command,
+      inv: {
+        method: command.method,
+        params,
+        ts: Date.now(),
+        seq,
+        clientId: s.record.clientId,
+      },
+      attempted: true,
+      posted: false,
+      applied: false,
+      resolve: () => {},
+      reject: () => {},
+    };
+    s.pending.push(entry);
+    s.lifecycle?.onStart(entry.inv);
+  }
+};
+
 const sendCommand = (
   s: Session,
   method: string,
@@ -653,13 +710,25 @@ export const useStatewireSession = (
   options: StatewireSessionOptions,
 ): Session => {
   const [defaultStore] = useState(createMemorySessionStore);
-  const store = options.sessionStore ?? defaultStore;
+  const mounted = useContext(SessionStorageContext);
+  if (options.sessionStore !== undefined && mounted !== undefined) {
+    throw new Error(
+      "statewire: session storage is set twice — drop the transport's sessionStore or the client's storage.session",
+    );
+  }
+  const store = options.sessionStore ?? mounted ?? defaultStore;
   const [s] = useState((): Session => {
     const stored = store.load();
+    if (stored !== null && !Array.isArray(stored.commands)) {
+      throw new Error(
+        "statewire: session storage loaded a record without a commands array",
+      );
+    }
     const record = stored ?? {
       clientId: newClientId(),
       nextSeq: 1,
       ctxNextSeq: 1,
+      commands: [],
     };
     const session: Session = {
       record,
@@ -679,6 +748,7 @@ export const useStatewireSession = (
       recordPersisted: stored !== null,
       store,
       ephemeral: false,
+      deactivated: false,
       sessionKnown: false,
       durableSeq: 0,
       resumeAt: 0,

package/src/client/sessionStore.ts

@@ -1,20 +1,13 @@
-export type StatewireSessionRecord = {
-  clientId: string;
-  nextSeq: number;
-  ctxNextSeq: number;
-};
-
-export type StatewireSessionStore = {
-  load: () => StatewireSessionRecord | null;
-  save: (record: StatewireSessionRecord) => void;
-};
+import { createContext } from "react";
+import type { StatewireClient } from "../statewire";
 
-export type StatewireSessionStoreOptions = {
-  sessionStore?: StatewireSessionStore | undefined;
-};
+/** The session storage `useStatewire` mounts, read by the transport's session. */
+export const SessionStorageContext = createContext<
+  StatewireClient.SessionStorage | undefined
+>(undefined);
 
-export const createMemorySessionStore = (): StatewireSessionStore => {
-  let record: StatewireSessionRecord | null = null;
+export const createMemorySessionStore = (): StatewireClient.SessionStorage => {
+  let record: StatewireClient.SessionRecord | null = null;
   return {
     load: () => record,
     save: (next) => {

package/src/host/http.ts

@@ -0,0 +1,280 @@
+import type { StatewireHost } from "../host";
+import {
+  CLIENT_ID_RE,
+  admitFrame,
+  closeConn,
+  flush,
+  parseFrame,
+  parseFrameValue,
+  register,
+  sendTo,
+} from "./socket";
+import type { ParsedFrame, Registration, SocketHostState } from "./socket";
+
+const CLIENT_ID_HEADER = "Statewire-Client-Id";
+const LEASE_HEADER = "Statewire-Lease";
+const VERSION_HEADER = "Statewire-Version";
+const VERSION = "1";
+const encoder = new TextEncoder();
+
+const invalidClientIdReason = (clientId: string): string | null => {
+  if (clientId === "") return "id must be non-empty";
+  if (clientId.length > 256) return "id must be at most 256 characters";
+  if (!CLIENT_ID_RE.test(clientId)) {
+    return "id must contain only [A-Za-z0-9._~-]";
+  }
+  return null;
+};
+
+const clientIdResponse = (
+  request: Request,
+): { clientId: string } | { response: Response } => {
+  const clientId = request.headers.get(CLIENT_ID_HEADER);
+  if (clientId === null) {
+    return {
+      response: Response.json(
+        { detail: `missing ${CLIENT_ID_HEADER} header` },
+        { status: 400 },
+      ),
+    };
+  }
+  const reason = invalidClientIdReason(clientId);
+  if (reason !== null) {
+    return {
+      response: Response.json(
+        { detail: `invalid ${CLIENT_ID_HEADER}: ${reason}` },
+        { status: 400 },
+      ),
+    };
+  }
+  return { clientId };
+};
+
+const headersOf = (request: Request): Record<string, string> =>
+  Object.fromEntries(request.headers);
+
+const mergedHeaders = (
+  request: Request,
+  extra: Record<string, string>,
+): Record<string, string> => {
+  const headers = headersOf(request);
+  for (const [name, value] of Object.entries(extra)) {
+    headers[name.toLowerCase()] = value;
+  }
+  return headers;
+};
+
+const authorize = async (
+  h: SocketHostState,
+  headers: Record<string, string>,
+): Promise<Response | null> => {
+  try {
+    await h.authorize?.({ headers });
+    return null;
+  } catch (error) {
+    if (error instanceof Response) return error;
+    throw error;
+  }
+};
+
+const mintLease = (): string => {
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  return btoa(String.fromCharCode(...bytes))
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replace(/=+$/, "");
+};
+
+type SseAttachment = {
+  body: ReadableStream<Uint8Array>;
+  registration: Registration | null;
+};
+
+const attachSse = (h: SocketHostState, clientId: string): SseAttachment => {
+  let controller: ReadableStreamDefaultController<Uint8Array>;
+  let connection: Registration["connection"] | null = null;
+  let open = true;
+  const body = new ReadableStream({
+    start: (next) => {
+      controller = next;
+    },
+    cancel: () => {
+      open = false;
+      connection?.close();
+    },
+  });
+  const socket = {
+    send: (data: string) => {
+      if (!open) return;
+      const frame = data === "{}" ? ": ping\n\n" : `data: ${data}\n\n`;
+      try {
+        controller.enqueue(encoder.encode(frame));
+      } catch {
+        open = false;
+        connection?.close();
+      }
+    },
+    close: () => {
+      if (!open) return;
+      open = false;
+      try {
+        controller.close();
+      } catch {
+        return;
+      }
+    },
+  };
+  const registration = register(h, clientId, socket);
+  connection = registration?.connection ?? null;
+  if (!open) connection?.close();
+  return { body, registration };
+};
+
+const streamResponse = (
+  attachment: SseAttachment,
+  lease: string | null,
+): Response =>
+  new Response(attachment.body, {
+    status: 200,
+    headers: {
+      "Content-Type": "text/event-stream",
+      [VERSION_HEADER]: VERSION,
+      ...(lease !== null && { [LEASE_HEADER]: lease }),
+    },
+  });
+
+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);
+  if (admission.type === "refused") {
+    sendTo(h, registration.conn, JSON.stringify(admission.syn));
+  }
+};
+
+const getStream = async (
+  h: SocketHostState,
+  request: Request,
+): Promise<Response> => {
+  const refused = await authorize(h, headersOf(request));
+  if (refused !== null) return refused;
+  const client = clientIdResponse(request);
+  if ("response" in client) return client.response;
+  const attachment = attachSse(h, client.clientId);
+  const lease = attachment.registration === null ? null : mintLease();
+  if (attachment.registration !== null)
+    attachment.registration.rec.lease = lease;
+  return streamResponse(attachment, lease);
+};
+
+const postStream = async (
+  h: SocketHostState,
+  request: Request,
+): Promise<Response> => {
+  const client = clientIdResponse(request);
+  if ("response" in client) return client.response;
+  let body: unknown;
+  try {
+    body = JSON.parse(await request.text());
+  } catch {
+    return Response.json({ detail: "body must be JSON" }, { status: 400 });
+  }
+  let frame: ParsedFrame;
+  try {
+    frame = parseFrameValue(body, true);
+  } catch (error) {
+    if (!(error instanceof Error) || error.name !== "StatewireViolation") {
+      throw error;
+    }
+    return Response.json({ detail: error.message }, { status: 400 });
+  }
+  if (frame.headers === null) {
+    return Response.json(
+      { detail: "first frame must carry headers" },
+      { status: 400 },
+    );
+  }
+  const refused = await authorize(h, mergedHeaders(request, frame.headers));
+  if (refused !== null) return refused;
+  const attachment = attachSse(h, client.clientId);
+  if (attachment.registration === null) return streamResponse(attachment, null);
+  const lease = mintLease();
+  attachment.registration.rec.lease = lease;
+  admitAttachFrame(h, attachment.registration, frame);
+  return streamResponse(attachment, lease);
+};
+
+export const stream = async (
+  h: SocketHostState,
+  request: Request,
+): Promise<Response> => {
+  if (request.method === "GET") return getStream(h, request);
+  if (request.method === "POST") return postStream(h, request);
+  return new Response(null, {
+    status: 405,
+    headers: { Allow: "GET, POST" },
+  });
+};
+
+const finClient = (
+  h: SocketHostState,
+  clientId: string,
+  fin: StatewireHost.Fin,
+) => {
+  flush(h);
+  for (const conn of [...h.conns]) {
+    if (conn.clientId !== clientId) continue;
+    sendTo(h, conn, JSON.stringify({ fin }));
+    closeConn(h, conn);
+  }
+};
+
+const violationResponse = (
+  h: SocketHostState,
+  clientId: string,
+  reason: string,
+) => {
+  finClient(h, clientId, {
+    reason: "error",
+    message: `protocol violation: ${reason}`,
+  });
+  return Response.json({ error: reason }, { status: 400 });
+};
+
+export const frames = async (
+  h: SocketHostState,
+  request: Request,
+): Promise<Response> => {
+  const refused = await authorize(h, headersOf(request));
+  if (refused !== null) return refused;
+  const client = clientIdResponse(request);
+  if ("response" in client) return client.response;
+  const rec = h.clients.get(client.clientId);
+  const lease = request.headers.get(LEASE_HEADER);
+  if (
+    h.disposed ||
+    h.finished !== null ||
+    rec === undefined ||
+    lease === null ||
+    lease !== rec.lease
+  ) {
+    return Response.json({ error: "stale-lease" }, { status: 423 });
+  }
+  let frame: ParsedFrame;
+  try {
+    frame = parseFrame(await request.text(), false);
+  } catch (error) {
+    if (!(error instanceof Error) || error.name !== "StatewireViolation") {
+      throw error;
+    }
+    return violationResponse(h, client.clientId, error.message);
+  }
+  const admission = admitFrame(h, rec, frame);
+  if (admission.type === "refused") {
+    return Response.json(admission.syn, { status: 409 });
+  }
+  return Response.json({});
+};