statewire 0.20.0 → 0.22.0

package/src/host/socket.ts

@@ -128,10 +128,15 @@ export type Conn = {
   lease: string | null;
   /** The awaited `authorize` return captured at this attach's authorization. */
   auth: unknown;
+  authorizedAt: number | undefined;
+  leaseTimer: ReturnType<typeof setTimeout> | null;
   lanes: Map<string, Lane>;
   contexts: Map<string, Statewire.Context>;
   documents: Map<string, StatewireHost.Document>;
   included: Set<string>;
+  onIncludedChange:
+    | ((included: readonly StatewireHostInternal.IncludedDocument[]) => void)
+    | undefined;
   view: Map<string, { doc: number; value: unknown }>;
   nextDoc: number;
   pendingApplied: Cmd[];
@@ -316,13 +321,11 @@ const cmdOf = (adm: Admission, outcome: CommandsOutcome): Cmd => {
       };
     }
     default:
+      console.error("statewire command failed", outcome.error);
       return {
         ...at,
         type: "failed",
-        message:
-          outcome.error instanceof Error
-            ? outcome.error.message
-            : String(outcome.error),
+        message: "the command failed",
       };
   }
 };
@@ -356,6 +359,7 @@ export type SocketHostState = {
   key: readonly string[] | undefined;
   wireVersion: StatewireProtocol.Range;
   heartbeatMs: number;
+  maxLeaseLifetimeMs: number | null;
   wsInitTimeoutMs: number;
   maxSubscribers: number;
   maxInflightCommands: number;
@@ -451,6 +455,10 @@ export const closeConn = (
   if (!conn.open) return;
   conn.open = false;
   h.conns.delete(conn);
+  if (conn.leaseTimer !== null) {
+    clearTimeout(conn.leaseTimer);
+    conn.leaseTimer = null;
+  }
   try {
     conn.socket.close(code, reason);
   } catch {
@@ -473,6 +481,49 @@ export const sendTo = (h: SocketHostState, conn: Conn, data: string) => {
   }
 };
 
+const expiredAt = (h: SocketHostState, authorizedAt: number | undefined) => {
+  const now = Date.now();
+  return (
+    authorizedAt === undefined ||
+    !Number.isFinite(authorizedAt) ||
+    authorizedAt < 0 ||
+    authorizedAt > now ||
+    (h.maxLeaseLifetimeMs !== null &&
+      now - authorizedAt >= h.maxLeaseLifetimeMs)
+  );
+};
+
+const leaseExpiredFin = JSON.stringify({
+  fin: { reason: "reconnect", code: "lease-expired" },
+});
+
+export const expireLease = (h: SocketHostState, conn: Conn): boolean => {
+  if (!conn.open || expiredAt(h, conn.authorizedAt)) {
+    if (conn.open) {
+      sendTo(h, conn, leaseExpiredFin);
+      closeConn(h, conn, 1000, "lease-expired");
+    }
+    return true;
+  }
+  return false;
+};
+
+const armLeaseTimer = (h: SocketHostState, conn: Conn) => {
+  if (conn.leaseTimer !== null) clearTimeout(conn.leaseTimer);
+  conn.leaseTimer = null;
+  if (h.disposed || h.maxLeaseLifetimeMs === null || expireLease(h, conn))
+    return;
+  const delay = h.maxLeaseLifetimeMs - (Date.now() - conn.authorizedAt!);
+  conn.leaseTimer = setTimeout(
+    () => {
+      conn.leaseTimer = null;
+      if (!expireLease(h, conn)) armLeaseTimer(h, conn);
+    },
+    Math.min(delay, 2_147_483_647),
+  );
+  (conn.leaseTimer as unknown as { unref?: () => void }).unref?.();
+};
+
 const violate = (h: SocketHostState, conn: Conn, reason: string) => {
   sendTo(
     h,
@@ -593,6 +644,33 @@ const diffView = (h: SocketHostState, conn: Conn): WireOp[] => {
   return ops;
 };
 
+const notifyIncluded = (conn: Conn) =>
+  conn.onIncludedChange?.(
+    [...conn.included].map(
+      (id) => JSON.parse(id) as StatewireHostInternal.IncludedDocument,
+    ),
+  );
+
+const restoredIncluded = (
+  included: readonly StatewireHostInternal.IncludedDocument[],
+): Set<string> =>
+  new Set(
+    included.map((entry) => {
+      if (
+        !Array.isArray(entry) ||
+        entry.length !== 2 ||
+        typeof entry[0] !== "string" ||
+        !(
+          entry[1] === null ||
+          (Array.isArray(entry[1]) &&
+            entry[1].every((part) => typeof part === "string"))
+        )
+      )
+        throw new TypeError("statewire: invalid restored include");
+      return documentIdentity(entry[0], entry[1] ?? undefined);
+    }),
+  );
+
 const attachOf = (h: SocketHostState, conn: Conn): StatewireHost.Attach => {
   const requireSelected = (protocol: string) => {
     const entry = conn.selection.protocols.find((p) => p.name === protocol);
@@ -652,11 +730,15 @@ const attachOf = (h: SocketHostState, conn: Conn): StatewireHost.Attach => {
     include: (protocol, key) => {
       if (requireSelected(protocol).record !== undefined)
         throw new Error(`statewire: protocol ${protocol} is not durable`);
-      conn.included.add(documentIdentity(protocol, key));
+      const id = documentIdentity(protocol, key);
+      if (conn.included.has(id)) return;
+      conn.included.add(id);
+      notifyIncluded(conn);
       markViews(h);
     },
     exclude: (protocol, key) => {
-      conn.included.delete(documentIdentity(protocol, key));
+      if (!conn.included.delete(documentIdentity(protocol, key))) return;
+      notifyIncluded(conn);
       markViews(h);
     },
   };
@@ -990,6 +1072,7 @@ const admitCmd = (
 // never a close; an ephemeral gap is a violation (the lane has no replay).
 export type FrameAdmission =
   | { type: "ok" }
+  | { type: "expired" }
   | {
       type: "refused";
       syn: {
@@ -1071,6 +1154,7 @@ export const admitFrame = (
   conn: Conn,
   frame: ParsedFrame,
 ): FrameAdmission => {
+  if (expireLease(h, conn)) return { type: "expired" };
   validateContexts(h, conn, frame);
   installContexts(h, conn, frame);
   const rec = h.clients.get(conn.clientId)!;
@@ -1120,6 +1204,7 @@ export const admitFrame = (
       return refusal(h, conn, retry);
     }
   }
+  if (expireLease(h, conn)) return { type: "expired" };
   for (const s of fresh) admitCmd(h, lanes.get(s.protocol)!, conn, s);
   for (const [protocol, lane] of lanes) {
     const last = fresh.findLast((s) => s.protocol === protocol);
@@ -1133,7 +1218,8 @@ export const admitFrame = (
 };
 
 const message = (h: SocketHostState, conn: Conn, data: string) => {
-  if (!conn.open || h.disposed || h.finished !== null) return;
+  if (!conn.open || h.disposed || h.finished !== null || expireLease(h, conn))
+    return;
   if (frameIsOversized(data)) {
     sendTo(
       h,
@@ -1269,6 +1355,19 @@ const connectAuthorized = (
 ): StatewireHostInternal.SocketConnection | null => {
   const authorize = h.authorize;
   if (options.authorized === true) {
+    if (expiredAt(h, options.authorizedAt)) {
+      try {
+        socket.send(leaseExpiredFin);
+      } catch {
+        /* peer already gone */
+      }
+      try {
+        socket.close(1000, "lease-expired");
+      } catch {
+        /* peer already gone */
+      }
+      return null;
+    }
     const registration = register(
       h,
       clientId,
@@ -1276,6 +1375,9 @@ const connectAuthorized = (
       options.authorized === true,
       options.auth,
       options.selection,
+      undefined,
+      options.authorizedAt,
+      options,
     );
     return registration?.connection ?? null;
   }
@@ -1403,6 +1505,7 @@ const connectAuthorized = (
         .then(() => authorize?.({ headers }))
         .then((auth) => {
           if (!pending.open || h.disposed || h.finished !== null) return;
+          const authorizedAt = Date.now();
           const selection = negotiateProtocols(
             new Headers(headers),
             h.wireVersion,
@@ -1413,7 +1516,7 @@ const connectAuthorized = (
             closePending(h, pending, 1008, selection.fin.message);
             return;
           }
-          options.onAuthorized?.(auth, selection);
+          options.onAuthorized?.(auth, selection, authorizedAt);
           pending.open = false;
           h.pendingConns.delete(pending);
           if (pending.timer !== null) clearTimeout(pending.timer);
@@ -1427,6 +1530,10 @@ const connectAuthorized = (
               auth,
               selection,
               frame,
+              authorizedAt,
+              options.onIncludedChange === undefined
+                ? {}
+                : { onIncludedChange: options.onIncludedChange },
             );
           } catch (error) {
             if (violationReason(error) === null) throw error;
@@ -1489,7 +1596,13 @@ export const register = (
     protocols: [{ name: h.protocol.name, version: h.protocol.version }],
   },
   frame: ParsedFrame = { cmd: [] },
+  authorizedAt?: number,
+  included: Pick<
+    StatewireHostInternal.SocketConnectOptions,
+    "included" | "onIncludedChange"
+  > = {},
 ): Registration | null => {
+  const restored = restoredIncluded(included.included ?? []);
   const refuse = (code: number, reason: string) => {
     try {
       socket.close(code, reason);
@@ -1513,6 +1626,14 @@ export const register = (
   if (atSubscriberLimit(h)) {
     return refuseSubscriberLimit(socket);
   }
+  if (expiredAt(h, authorizedAt)) {
+    try {
+      socket.send(leaseExpiredFin);
+    } catch {
+      /* peer already gone */
+    }
+    return refuse(1000, "lease-expired");
+  }
   const known = h.clients.get(clientId);
   if (known !== undefined && !authEquals(known.principal, auth)) {
     try {
@@ -1553,10 +1674,13 @@ export const register = (
     lastSentAt: 0,
     lease: null,
     auth,
+    authorizedAt,
+    leaseTimer: null,
     lanes: new Map(),
     contexts: new Map(),
     documents: new Map(),
-    included: new Set(),
+    included: restored,
+    onIncludedChange: included.onIncludedChange,
     view: new Map(),
     nextDoc: 1,
     pendingApplied: [],
@@ -1577,6 +1701,8 @@ export const register = (
   }
   gcClients(h);
   ensureHeartbeat(h);
+  armLeaseTimer(h, conn);
+  if (!conn.open) return null;
   const isEphemeral = (s: CmdStatement) =>
     selection.protocols.find((p) => p.name === s.protocol)?.record ===
     "ephemeral";
@@ -1596,6 +1722,7 @@ export const register = (
   const earlyAdmission = admit(early);
   if (early.length > 0) flush(h);
   notifyClientRecords(h);
+  if (expireLease(h, conn)) return null;
   const ops: WireOp[] = [];
   if (selects(conn, h.protocol.name)) {
     const { value, meta } = encodeDocument(h.stateHost!.snapshot());
@@ -1670,10 +1797,15 @@ const resume = (h: SocketHostState) => {
   h.disposed = false;
   h.stateHost?.setOnOp((op) => recordOp(h, op));
   h.stateHost?.setOnDocuments(() => markViews(h));
+  for (const conn of h.conns) armLeaseTimer(h, conn);
 };
 
 const suspend = (h: SocketHostState) => {
   h.disposed = true;
+  for (const conn of h.conns) {
+    if (conn.leaseTimer !== null) clearTimeout(conn.leaseTimer);
+    conn.leaseTimer = null;
+  }
   if (h.heartbeatTimer !== null) {
     clearInterval(h.heartbeatTimer);
     h.heartbeatTimer = null;
@@ -1725,6 +1857,7 @@ const useSocketHost = (
       key: undefined,
       wireVersion: { version: WIRE_VERSION },
       heartbeatMs: 15_000,
+      maxLeaseLifetimeMs: 86_400_000,
       wsInitTimeoutMs: 5_000,
       maxSubscribers: MAX_SUBSCRIBERS,
       maxInflightCommands: MAX_INFLIGHT_COMMANDS_PER_HOST,
@@ -1768,6 +1901,22 @@ const useSocketHost = (
   h.key = options?.key;
   h.wireVersion = options?.wireVersion ?? { version: WIRE_VERSION };
   setHeartbeatMs(h, options?.heartbeatIntervalMs ?? 15_000);
+  const maxLeaseLifetimeMs =
+    options?.maxLeaseLifetimeMs === undefined
+      ? 86_400_000
+      : options.maxLeaseLifetimeMs;
+  if (
+    maxLeaseLifetimeMs !== null &&
+    (!Number.isFinite(maxLeaseLifetimeMs) || maxLeaseLifetimeMs <= 0)
+  ) {
+    throw new TypeError(
+      "maxLeaseLifetimeMs must be finite and positive or null",
+    );
+  }
+  if (h.maxLeaseLifetimeMs !== maxLeaseLifetimeMs) {
+    h.maxLeaseLifetimeMs = maxLeaseLifetimeMs;
+    for (const conn of [...h.conns]) armLeaseTimer(h, conn);
+  }
   h.pushback = options?.pushback;
   h.wsInitTimeoutMs = options?.wsInitTimeoutMs ?? 5_000;
   const maxSubscribers =

package/src/host-internal.ts

@@ -21,6 +21,7 @@ export namespace StatewireHostInternal {
     headers?: Record<string, string>;
     /** The adapter restored this socket from an already-authorized session. */
     authorized?: boolean;
+    authorizedAt?: number;
     selection?: StatewireProtocol.Selection;
     /** The restored session's captured auth value; it must satisfy the client record's principal binding. */
     auth?: unknown;
@@ -28,9 +29,20 @@ export namespace StatewireHostInternal {
     onAuthorized?: (
       auth: unknown,
       selection: StatewireProtocol.Selection,
+      authorizedAt: number,
     ) => void;
+    /** Documents the attach had included before the adapter retained its socket; they ride the hello. */
+    included?: readonly IncludedDocument[];
+    /** Called with the attach's whole include set each time `include` or `exclude` changes it. */
+    onIncludedChange?: (included: readonly IncludedDocument[]) => void;
   };
 
+  /** A durable document an attach included: `[protocol, key]`. */
+  export type IncludedDocument = readonly [
+    protocol: string,
+    key: readonly string[] | null,
+  ];
+
   export type SocketHost = {
     /** Null means refused: the socket was told (fin and/or close) and is dead. */
     connect: (
@@ -88,6 +100,8 @@ export namespace StatewireHostInternal {
     /** Time allowed to complete WebSocket initialization and authorization. */
     wsInitTimeoutMs?: number;
     heartbeatIntervalMs?: number;
+    /** Maximum attach lifetime in milliseconds; defaults to 24 hours, null disables expiry. */
+    maxLeaseLifetimeMs?: number | null;
     /** Maximum number of concurrently attached WebSocket and SSE streams. */
     maxSubscribers?: number;
     /** Maximum number of admitted commands still running across all clients. */

package/src/statewire.ts

@@ -156,6 +156,15 @@ export const useStatewire = <
     [transportInvoke],
   );
 
+  const setContext = useCallback(
+    (protocol: string, value: Statewire.Context) => {
+      if (!transportSetContext)
+        throw new Error("statewire: transport does not support context");
+      transportSetContext(protocol, value);
+    },
+    [transportSetContext],
+  );
+
   return useMemo(() => {
     const failures = (): NonNullable<typeof transportFailures> => {
       if (!transportFailures) {
@@ -168,11 +177,7 @@ export const useStatewire = <
       documents: source,
       selection,
       invoke,
-      setContext: (protocol: string, value: Statewire.Context) => {
-        if (!transportSetContext)
-          throw new Error("statewire: transport does not support context");
-        transportSetContext(protocol, value);
-      },
+      setContext,
       getState: core.getState as () => TState,
       connection,
       commands: core.commands as Statewire.CommandsProxy<TCommands>,
@@ -193,7 +198,7 @@ export const useStatewire = <
     selection,
     invoke,
     transportFailures,
-    transportSetContext,
+    setContext,
   ]);
 };
 

package/src/transports/sse.ts

@@ -61,6 +61,7 @@ export type ConnectionState = StatewireClient.ConnectionState;
 /** The live wire a remote session drives: connection status plus frame submission. */
 export type RemoteLink = {
   storageFailed: (error: Error) => void;
+  protocolFailed: (error: Error) => void;
   connection: StatewireClient.Connection;
   /** A deferred first attach still waiting; `reconnect()` releases it. */
   parked: boolean;
@@ -69,6 +70,16 @@ export type RemoteLink = {
 
 const LEASE_HEADER = "Statewire-Lease";
 
+let warnedNoLease = false;
+
+const warnNoLease = () => {
+  if (warnedNoLease) return;
+  warnedNoLease = true;
+  console.warn(
+    "statewire: SSE attach returned no readable Statewire-Lease header; commands will re-attach the stream. Cross-origin hosts must expose it (Access-Control-Expose-Headers: Statewire-Lease).",
+  );
+};
+
 const baseUrl = (options: StatewireClient.HttpOptions) =>
   options.url.replace(/\/$/, "");
 
@@ -181,6 +192,7 @@ const attemptStream = async (
   if (!res.body)
     throw new Error("statewire: protocol error: stream response has no body");
   c.lease = res.headers.get(LEASE_HEADER);
+  if (c.lease === null) warnNoLease();
   const reader = res.body.getReader();
   const cancel = () => {
     void reader.cancel().catch(() => {});