@zerotal/flow 1.0.0

package/src/dehydrate.ts

@@ -0,0 +1,333 @@
+import type { Component } from "./Component.ts";
+import type { Snapshot, SnapshotData } from "./types.ts";
+import { serializeValue, deserializeValue } from "./synths/index.ts";
+import {
+  getComputedKeys,
+  getTransientKeys,
+  getExposedProps,
+  getLockedProps,
+  getUrlProps,
+  getListeners,
+  getPresenceProps,
+  resolvePresenceChannel,
+  getSharedProps,
+  resolveSharedChannel,
+} from "./decorators.ts";
+import { ZerotalError, safeEqual, hmacHex, RequestContext } from "@zerotal/core";
+
+// ── Stable JSON stringify ─────────────────────────────────────────────────────
+// Keys are sorted so the HMAC is deterministic regardless of insertion order.
+
+function stableStringify(value: unknown): string {
+  if (value === null || value === undefined) return JSON.stringify(value);
+  if (typeof value !== "object" || Array.isArray(value)) return JSON.stringify(value);
+  const sorted: Record<string, unknown> = {};
+  for (const k of Object.keys(value as object).sort()) {
+    sorted[k] = (value as Record<string, unknown>)[k];
+  }
+  return JSON.stringify(sorted, (_key, v: unknown) =>
+    typeof v === "object" && v !== null && !Array.isArray(v)
+      ? Object.fromEntries(
+          Object.entries(v as Record<string, unknown>).sort(([a], [b]) => (a < b ? -1 : 1)),
+        )
+      : v,
+  );
+}
+
+// ── HMAC helpers ──────────────────────────────────────────────────────────────
+
+function _appKey(): string {
+  const key = Bun.env["APP_KEY"];
+  if (!key) throw new Error("[Flow] APP_KEY is not set. Snapshot signing requires APP_KEY.");
+  return key;
+}
+
+function _sign(payload: string): string {
+  return hmacHex(payload, _appKey());
+}
+
+function _verify(payload: string, checksum: string): boolean {
+  // Constant-time comparison via the shared helper (its length pre-check is
+  // safe here — the digest length is a fixed public constant).
+  return safeEqual(_sign(payload), checksum);
+}
+
+// ── Identity binding ──────────────────────────────────────────────────────────
+
+/**
+ * How long a snapshot stays valid after being issued. 12 hours comfortably outlives any
+ * real page session while putting an end to a captured one.
+ */
+export const SNAPSHOT_MAX_AGE_SECONDS = 12 * 60 * 60;
+
+/**
+ * The authenticated user a snapshot is being issued to, or `undefined` for an anonymous
+ * request. Read structurally: `@zerotal/flow` does not depend on `@zerotal/auth`.
+ * @internal
+ */
+function currentSubject(): string | undefined {
+  const ctx = RequestContext.tryGet() as { user?: { id?: unknown } | null } | undefined;
+  const id = ctx?.user?.id;
+  return id === undefined || id === null ? undefined : String(id);
+}
+
+// ── Signing payload ───────────────────────────────────────────────────────────
+// children and listeners are excluded from signing:
+//   - children: Livewire pattern — ids are derived server-side, never trusted from client
+//   - listeners: server-derived from class decorators, cannot meaningfully be tampered
+//     with (@on methods are still validated against @expose allowlist on every call)
+
+function _signingPayload(snapshot: Omit<Snapshot, "checksum">): string {
+  const memo = { ...snapshot.memo, children: undefined, listeners: undefined };
+  return stableStringify({ data: snapshot.data, memo });
+}
+
+// ── Dehydration ───────────────────────────────────────────────────────────────
+
+export function dehydrate(
+  page: Component,
+  memo: Pick<Snapshot["memo"], "id" | "name" | "path"> & {
+    children?: Snapshot["memo"]["children"];
+  },
+): Snapshot {
+  const computedKeys = getComputedKeys(page);
+  const transientKeys = getTransientKeys(page);
+  const exposedProps = getExposedProps(page);
+  const lockedProps = getLockedProps(page);
+  const urlProps = getUrlProps(page);
+  const data: SnapshotData = {};
+
+  // Only @expose-d and @locked properties cross the network boundary.
+  const serializable = new Set([...exposedProps, ...lockedProps]);
+
+  for (const key of serializable) {
+    if (computedKeys.has(key)) continue;
+    if (transientKeys.has(key)) continue;
+    const val = (page as unknown as Record<string, unknown>)[key];
+    if (typeof val === "function") continue;
+
+    const [serialized, meta] = serializeValue(val);
+
+    // Mark @locked properties so the client proxy refuses writes to them.
+    if (lockedProps.has(key)) {
+      meta["locked"] = true;
+    }
+
+    // Merge @url metadata into the synth tuple meta so the client knows
+    // which props to sync to the URL query string and how.
+    const urlOpts = urlProps.get(key);
+    if (urlOpts) {
+      meta["url"] = { as: urlOpts.as ?? key, history: urlOpts.history ?? "replace" };
+    }
+
+    data[key] = [serialized, meta];
+  }
+
+  // Collect @on listeners for the client event router.
+  // Excluded from HMAC signing (server-derived, can't usefully be tampered with).
+  const listenersMap = getListeners(page.constructor as { prototype: object });
+  const listeners = listenersMap.size > 0 ? Object.fromEntries(listenersMap) : undefined;
+
+  // Named slot HTML passed down by the parent. Signed (server-generated), and carried
+  // so the child can re-render its own actions with the slot content intact.
+  const slots = Object.keys(page._flowSlots).length > 0 ? page._flowSlots : undefined;
+
+  // @presence props → resolved channel, so the client subscribes to the right presence
+  // channel(s). Signed (server-resolved from the component). Empty when none.
+  const presenceMap = getPresenceProps(page);
+  const presence =
+    presenceMap.size > 0
+      ? [...presenceMap].map(([prop, channel]) => ({
+          prop,
+          channel: resolvePresenceChannel(channel, page),
+        }))
+      : undefined;
+
+  // @shared props → resolved channel, so the client subscribes and converges on change.
+  // Signed (server-resolved from the component). Empty when none.
+  const sharedMap = getSharedProps(page);
+  const shared =
+    sharedMap.size > 0
+      ? [...sharedMap].map(([prop, channel]) => ({
+          prop,
+          channel: resolveSharedChannel(channel, page),
+        }))
+      : undefined;
+
+  // Children collected during the render that preceded this dehydrate call.
+  // Excluded from HMAC (Livewire pattern).
+  const snapshotMemo: Snapshot["memo"] = {
+    ...memo,
+    children: [...page._childIds],
+    listeners,
+    slots,
+    presence,
+    shared,
+    sub: currentSubject(),
+    iat: Math.floor(Date.now() / 1000),
+  };
+  const partial = { data, memo: snapshotMemo };
+  const checksum = _sign(_signingPayload(partial));
+
+  return { data, memo: snapshotMemo, checksum };
+}
+
+// ── Hydration ─────────────────────────────────────────────────────────────────
+
+export class FlowIntegrityError extends ZerotalError {
+  constructor(msg = "Invalid snapshot checksum") {
+    super(msg, "E_PULSE_INTEGRITY", 400);
+  }
+}
+
+/**
+ * A snapshot whose signature is genuine but which does not belong to this requester, or
+ * which has aged out. Distinct from {@link FlowIntegrityError} because the cause and the
+ * fix are different: nothing was tampered with, the snapshot is simply not yours.
+ */
+export class FlowSnapshotOwnershipError extends ZerotalError {
+  constructor(msg = "Snapshot was not issued to this session") {
+    super(msg, "E_PULSE_SNAPSHOT_OWNER", 403);
+  }
+}
+
+export async function hydrate<T extends Component>(
+  snapshot: Snapshot,
+  PageClass: new () => T,
+): Promise<T> {
+  // 1. Verify HMAC (children and listeners excluded from signing).
+  if (!verifySnapshot(snapshot)) {
+    throw new FlowIntegrityError();
+  }
+
+  // 2. Verify the snapshot belongs to whoever is asking, and has not aged out. The HMAC
+  //    proves integrity, not ownership — a genuine signature over someone else's state is
+  //    still someone else's state.
+  assertSnapshotSubject(snapshot);
+
+  // 3. Fresh blank instance — constructor runs but onMount() is skipped.
+  const page = new PageClass();
+  (page as Record<string, unknown>)["_skipMount"] = true;
+
+  // 4. Restore slots + each property (see applySnapshotData).
+  await applySnapshotData(page, snapshot);
+
+  return page;
+}
+
+/** Verify a snapshot's HMAC against the current APP_KEY. Public so durable-snapshot
+ *  restore can validate a stored snapshot before trusting it (a rotated key → false). */
+export function verifySnapshot(snapshot: Snapshot): boolean {
+  return _verify(_signingPayload(snapshot), snapshot.checksum);
+}
+
+/**
+ * Assert that a snapshot was issued to whoever is making the current request, and has not
+ * aged out.
+ *
+ * A signature says the bytes are unmodified. It does not say whose bytes they are — so
+ * `@locked accountId = 42`, which the docs describe as tamper-proof server-authoritative
+ * state, was replayable by any other authenticated user who came by a snapshot signed for
+ * someone else. Middleware re-runs on every frame, so authentication is genuinely
+ * re-checked; what it could not catch is that the *state* belonged to a different person.
+ *
+ * An anonymous-issued snapshot stays usable by anonymous requests only, and vice versa: a
+ * snapshot's subject changing means the identity changed, and identity changes are exactly
+ * when carried-over state should stop being trusted.
+ *
+ * @param snapshot - The snapshot about to be hydrated.
+ * @throws {@link FlowSnapshotOwnershipError} When the subject does not match or the
+ *   snapshot is older than {@link SNAPSHOT_MAX_AGE_SECONDS}.
+ */
+export function assertSnapshotSubject(snapshot: Snapshot): void {
+  if (snapshot.memo.sub !== currentSubject()) {
+    throw new FlowSnapshotOwnershipError();
+  }
+  const iat = snapshot.memo.iat;
+  if (typeof iat !== "number" || Math.floor(Date.now() / 1000) - iat > SNAPSHOT_MAX_AGE_SECONDS) {
+    throw new FlowSnapshotOwnershipError("Snapshot has expired — reload the page.");
+  }
+}
+
+/**
+ * Restore a snapshot's slots + property values into an EXISTING component instance (the
+ * deserialize half of {@link hydrate}, without the fresh-instance/HMAC steps). Used by the
+ * durable-snapshot resume path, which restores into a page that already ran onBoot().
+ */
+export async function applySnapshotData(page: Component, snapshot: Snapshot): Promise<void> {
+  // Restore parent-supplied slot HTML so this.slot(name) works. Signed in the memo.
+  if (snapshot.memo.slots) page._flowSlots = { ...snapshot.memo.slots };
+  // Restore each property through its synthesizer.
+  await Promise.all(
+    Object.entries(snapshot.data).map(async ([key, [data, meta]]) => {
+      (page as unknown as Record<string, unknown>)[key] = await deserializeValue(data, meta);
+    }),
+  );
+}
+
+// ── Snapshot delta encoding ───────────────────────────────────────────────────
+
+/** The wire form of a snapshot delta — only what changed, plus the new identity/checksum. */
+export interface SnapshotDelta {
+  memo: Snapshot["memo"];
+  checksum: string;
+  /** Changed (or newly added) `[value, meta]` tuples, keyed by property name. */
+  dataDelta: SnapshotData;
+  /** Property names present in `prev` but gone from `next`. */
+  dataRemoved: string[];
+}
+
+/**
+ * Diff two snapshots into the minimal set of changes to transmit. `next` is the freshly
+ * dehydrated state; `prev` is the client's own snapshot (its `data` is exactly what the
+ * client holds), so applying this delta to `prev.data` reproduces `next.data` value-for-
+ * value — and the carried `next.checksum` (signed over the full `next.data`) therefore
+ * verifies when the client sends the reconstructed snapshot back on its next action.
+ */
+export function encodeSnapshotDelta(prev: Snapshot, next: Snapshot): SnapshotDelta {
+  const dataDelta: SnapshotData = {};
+  for (const [key, tuple] of Object.entries(next.data)) {
+    const before = prev.data[key];
+    if (before === undefined || JSON.stringify(before) !== JSON.stringify(tuple)) {
+      dataDelta[key] = tuple;
+    }
+  }
+  const dataRemoved: string[] = [];
+  for (const key of Object.keys(prev.data)) {
+    if (!(key in next.data)) dataRemoved.push(key);
+  }
+  return { memo: next.memo, checksum: next.checksum, dataDelta, dataRemoved };
+}
+
+/**
+ * Rebuild a full snapshot from a prior snapshot and a delta (mirror of
+ * {@link encodeSnapshotDelta}). Used on the client, and by tests to prove the
+ * reconstruction verifies. Pure — does not mutate `prev`.
+ */
+export function applySnapshotDelta(prev: Snapshot, delta: SnapshotDelta): Snapshot {
+  const data: SnapshotData = { ...prev.data };
+  for (const key of delta.dataRemoved) delete data[key];
+  Object.assign(data, delta.dataDelta);
+  return { data, memo: delta.memo, checksum: delta.checksum };
+}
+
+// ── Snapshot size warning (dev mode) ─────────────────────────────────────────
+
+const SNAPSHOT_WARN_BYTES = 100 * 1024; // 100 KB
+
+export function warnIfLarge(snapshot: Snapshot, name: string): void {
+  const env = Bun.env["APP_ENV"] ?? "development";
+  if (env === "production" || env === "prod") return;
+
+  // Buffer.byteLength is a native call that avoids allocating a typed array.
+  const size = Buffer.byteLength(JSON.stringify(snapshot), "utf8");
+  if (size > SNAPSHOT_WARN_BYTES) {
+    console.warn(
+      `\n[Flow] Warning: ${name} snapshot is ${Math.round(size / 1024)} KB.\n` +
+        `Large snapshots slow every round trip. Consider:\n` +
+        `  → @transient on display-only collections (re-load them inside the action that needs them)\n` +
+        `  → Storing only IDs in state; eager-loading records inside individual actions\n` +
+        `  → @computed for values derivable from other state\n`,
+    );
+  }
+}

package/src/durable.ts

@@ -0,0 +1,243 @@
+// ── Durable / resumable snapshots ─────────────────────────────────────────────
+//
+// A component opts in with `static durable = true` (or `{ ttl, scope }`). Its signed
+// snapshot is then persisted server-side after every request, keyed by user (or session)
+// + route + component. On a fresh GET the stored snapshot is restored — skipping onMount —
+// so the user resumes exactly across a tab close/reopen, a device switch, or a reconnect
+// after the held client snapshot is gone. With a persistent store (see setDurableStore),
+// it also survives a server redeploy.
+//
+// The snapshot is HMAC-signed, so a tampered or stale-key entry fails verification and
+// falls back to a fresh mount; keying by user/session id isolates one user from another.
+
+import type { Component } from "./Component.ts";
+import type { Snapshot } from "./types.ts";
+import type { HttpContext } from "@zerotal/core";
+import { verifySnapshot, applySnapshotData } from "./dehydrate.ts";
+
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+
+/**
+ * A component's durable-snapshot opt-in, set as `static durable` on the component.
+ *
+ * - `true` — enable with defaults (24h TTL, `"user"` scope).
+ * - `{ ttl, scope }` — enable with a custom lifetime and keying:
+ *   - `ttl` — a duration string like `"30s"`, `"15m"`, `"2h"`, `"7d"` (defaults to 24h if omitted/unparseable).
+ *   - `scope` — `"user"` keys by authenticated user (falling back to session when
+ *     anonymous); `"session"` always keys by session, for per-device durability
+ *     even while logged in.
+ *
+ * @remarks
+ * When enabled, the component's signed snapshot is persisted after every request
+ * and restored on a fresh GET (skipping `onMount`), so a user resumes across a tab
+ * close/reopen, a device switch, or a reconnect. With a persistent store (see
+ * {@link setDurableStore}) it also survives a server redeploy.
+ *
+ * @example
+ * ```ts
+ * class Wizard extends Component {
+ *   static durable = { ttl: "2h", scope: "session" } satisfies DurableOption;
+ *   // ...on the final step:
+ *   @expose finish() { this.clearDurable(); } // drop stored state on completion
+ * }
+ * ```
+ */
+export type DurableOption = boolean | { ttl?: string; scope?: "user" | "session" };
+
+interface DurableConfig {
+  ttlMs: number;
+  /** `"user"` keys by the authenticated user (falling back to session when anonymous);
+   *  `"session"` always keys by session (per-device durability even when logged in). */
+  scope: "user" | "session";
+}
+
+// ── Store ───────────────────────────────────────────────────────────────────────
+// Default is an in-process TTL Map — survives reconnect/tab-close/device-switch within
+// the process lifetime. Swap a persistent backend (e.g. @zerotal/cache/Redis) via
+// setDurableStore() to also survive a server redeploy.
+
+/**
+ * Pluggable backing store for durable component snapshots.
+ *
+ * @remarks
+ * The default {@link MemoryDurableStore} keeps entries in-process with TTL
+ * eviction — durable across reconnect/tab-close/device-switch within the process
+ * lifetime, but lost on redeploy. Swap a persistent backend (e.g.
+ * `@zerotal/cache`/Redis) via {@link setDurableStore} to also survive redeploys.
+ * Methods may be sync or async; a swapped store is responsible for its own TTL
+ * eviction (the `ttlMs` hint is passed to {@link DurableStore.set | set}).
+ */
+export interface DurableStore {
+  /** Fetch a stored snapshot by key, or `undefined` if absent/expired. */
+  get(key: string): Promise<Snapshot | undefined> | Snapshot | undefined;
+  /** Store a snapshot under `key`, expiring after `ttlMs` if supported. */
+  set(key: string, value: Snapshot, ttlMs?: number): Promise<void> | void;
+  /** Remove a stored snapshot (used on flow completion via `clearDurable()`). */
+  delete(key: string): Promise<void> | void;
+}
+
+class MemoryDurableStore implements DurableStore {
+  private _map = new Map<string, { snap: Snapshot; expiresAt: number }>();
+  get(key: string): Snapshot | undefined {
+    const e = this._map.get(key);
+    if (!e) return undefined;
+    if (e.expiresAt < Date.now()) {
+      this._map.delete(key);
+      return undefined;
+    }
+    return e.snap;
+  }
+  set(key: string, value: Snapshot, ttlMs = DEFAULT_TTL_MS): void {
+    this._map.set(key, { snap: value, expiresAt: Date.now() + ttlMs });
+  }
+  delete(key: string): void {
+    this._map.delete(key);
+  }
+  /** @internal Evict expired entries so the map doesn't grow unbounded. */
+  _sweep(): void {
+    const now = Date.now();
+    for (const [k, e] of this._map) if (e.expiresAt < now) this._map.delete(k);
+  }
+}
+
+let _store: DurableStore = new MemoryDurableStore();
+
+// Bound the default store's memory; a swapped store manages its own eviction (TTL).
+setInterval(() => {
+  if (_store instanceof MemoryDurableStore) _store._sweep();
+}, 60 * 60_000).unref?.();
+
+/**
+ * Replace the process-wide durable-snapshot store. Call once at boot to move
+ * durability off the default in-process map onto a persistent backend so resumable
+ * state survives a server redeploy (and is shared across instances).
+ *
+ * @param store - The store implementation to install.
+ *
+ * @example
+ * ```ts
+ * // boot: persist durable snapshots in Redis so they outlive redeploys.
+ * setDurableStore(new CacheDurableStore(cache));
+ * ```
+ */
+export function setDurableStore(store: DurableStore): void {
+  _store = store;
+}
+
+/**
+ * Get the active durable-snapshot store (the in-process default, or whatever was
+ * installed via {@link setDurableStore}). Mainly useful for tests or tooling that
+ * inspects persisted snapshots directly.
+ *
+ * @returns The current {@link DurableStore}.
+ */
+export function getDurableStore(): DurableStore {
+  return _store;
+}
+
+/** @internal Test hook — reset to a fresh in-process store between tests. */
+export function _resetDurableStore(): void {
+  _store = new MemoryDurableStore();
+}
+
+// ── Config ────────────────────────────────────────────────────────────────────
+
+/** Parse a duration like `"30s"`, `"15m"`, `"2h"`, `"7d"` into milliseconds. */
+function _parseDuration(ttl: string): number {
+  const m = /^(\d+)\s*(s|m|h|d)$/.exec(ttl.trim());
+  if (!m) return DEFAULT_TTL_MS;
+  const n = Number(m[1]);
+  const unit = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2] as "s" | "m" | "h" | "d"];
+  return n * unit;
+}
+
+/** Resolve a component's `static durable` opt-in into a normalized config, or null when off. */
+export function getDurableConfig(page: Component): DurableConfig | null {
+  const raw = (page.constructor as { durable?: DurableOption }).durable;
+  if (!raw) return null;
+  if (raw === true) return { ttlMs: DEFAULT_TTL_MS, scope: "user" };
+  return {
+    ttlMs: raw.ttl ? _parseDuration(raw.ttl) : DEFAULT_TTL_MS,
+    scope: raw.scope ?? "user",
+  };
+}
+
+// ── Keying ──────────────────────────────────────────────────────────────────────
+
+type SessionLike = { get(k: string): unknown; set(k: string, v: unknown): void };
+const _SID_KEY = "flow:durable:sid";
+
+function _session(ctx: HttpContext): SessionLike | undefined {
+  return (ctx as unknown as { session?: SessionLike }).session;
+}
+
+function _randomSid(): string {
+  return (
+    globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`
+  ).replace(/-/g, "");
+}
+
+/**
+ * Resolve the store key for this component + visitor, or null when no stable identity is
+ * available (user-scoped but anonymous with no session). Session-scoped keys mint and persist
+ * a stable id in the session on first use.
+ */
+function _resolveKey(page: Component, ctx: HttpContext, scope: "user" | "session"): string | null {
+  const comp = page.constructor.name;
+  const routePath = page._flowPath || "/";
+  const userId = (ctx as unknown as { user?: { id?: unknown } }).user?.id;
+
+  if (scope === "user" && userId != null) {
+    return `flow:durable:u:${String(userId)}:${routePath}:${comp}`;
+  }
+  // Session id (user scope with no user → fall back here; or explicit session scope).
+  const session = _session(ctx);
+  if (!session) return null;
+  let sid = session.get(_SID_KEY) as string | undefined;
+  if (!sid) {
+    sid = _randomSid();
+    session.set(_SID_KEY, sid);
+  }
+  return `flow:durable:s:${sid}:${routePath}:${comp}`;
+}
+
+// ── Persist / restore ─────────────────────────────────────────────────────────
+
+/**
+ * Persist a durable component's snapshot after a request (both the initial GET and every WS
+ * action). A no-op unless the component opts in and a key resolves. When the action called
+ * `this.clearDurable()`, the stored entry is deleted instead (flow completion).
+ */
+export async function persistDurable(
+  page: Component,
+  ctx: HttpContext,
+  snapshot: Snapshot,
+): Promise<void> {
+  const cfg = getDurableConfig(page);
+  if (!cfg) return;
+  const key = _resolveKey(page, ctx, cfg.scope);
+  if (!key) return;
+  if (page._clearDurable) {
+    await _store.delete(key);
+    return;
+  }
+  await _store.set(key, snapshot, cfg.ttlMs);
+}
+
+/**
+ * On a fresh GET, restore a durable component from its stored snapshot into `page` (which has
+ * already run onBoot). Returns true when it resumed — the caller then runs onHydrate and skips
+ * onMount. A missing entry, a tampered snapshot, or a rotated APP_KEY (verify fails) returns
+ * false, so the caller mounts fresh.
+ */
+export async function restoreDurable(page: Component, ctx: HttpContext): Promise<boolean> {
+  const cfg = getDurableConfig(page);
+  if (!cfg) return false;
+  const key = _resolveKey(page, ctx, cfg.scope);
+  if (!key) return false;
+  const stored = await _store.get(key);
+  if (!stored || !verifySnapshot(stored)) return false;
+  (page as unknown as Record<string, unknown>)["_skipMount"] = true;
+  await applySnapshotData(page, stored);
+  return true;
+}