@crouton-kit/crouter 0.3.57 → 0.3.59

package/dist/clients/web/push-engine.js

@@ -0,0 +1,256 @@
+// push-engine.ts — the server-side web-push DIFF ENGINE (design D8/push
+// contract). SSE (`events.ts`) is a TRIGGER ONLY (`{kind, ts}`, never data);
+// this module is the one authority that re-reads canvas + decks on that
+// trigger, diffs against persisted last-seen state, and decides what (if
+// anything) to push. It never invents a second attention signal — decks/canvas
+// stay the truth.
+//
+// Two invalidation kinds drive two independent diff passes:
+//   - 'nodes'  -> re-read the canvas roster, detect a conversation ROOT
+//                 (parent === null) crossing into a done|dead|canceled status
+//                 from a non-done status, emit one 'done' push per transition.
+//   - 'inbox'  -> re-read pending asks (deck provenance), detect an ask id that
+//                 is present now but was not known-notified before, emit one
+//                 'needs-you' push per NEW ask, coalesced per conversation.
+//
+// On server start, `seed()` records the current state and sends NOTHING — a
+// restart is not an attention event.
+//
+// Last-seen state is only advanced past a suppressed (rate-capped) item when
+// that item was not actually the reason for suppression; a rate-capped
+// transition/ask is deliberately left out of the persisted state so the NEXT
+// invalidation retries it rather than silently losing it forever.
+import { isAllowedPushEndpoint } from './push-registry.js';
+const DONE_STATUSES = new Set(['done', 'dead', 'canceled']);
+/** Minimum interval between pushes for the same conversation root — coalesces
+ *  a burst of distinct events (several new asks, or an ask+done in close
+ *  succession) into at most one send per window, never a storm. */
+const DEFAULT_RATE_WINDOW_MS = 30_000;
+export class PushDiffEngine {
+    registry;
+    lastSeen;
+    readCanvasNodes;
+    readPendingAsks;
+    sendPush;
+    isTargetScope;
+    now;
+    rateWindowMs;
+    /** Drain-queue state: only one diff pass mutates last-seen at a time. An
+     *  invalidation arriving mid-pass sets its pending flag and is reprocessed
+     *  when the current pass finishes — no two passes race the same snapshot. */
+    draining = false;
+    pendingNodes = false;
+    pendingInbox = false;
+    /** Per-conversation rate-cap clock. Deliberately in-memory/process-lifetime
+     *  only (not persisted) — a restart re-seeding silently is already the
+     *  no-storm guarantee; the rate cap only smooths a live process's bursts. */
+    lastPushAt = new Map();
+    /** Per-(conversationId+kind) set of subscription ids already delivered for
+     *  the CURRENT still-pending notification. A transient failure on one
+     *  subscription must never cause a later retry to re-send to subscriptions
+     *  that already got `'sent'` — this is exactly what remembers them across
+     *  passes. Cleared the moment the event fully succeeds (or has no eligible
+     *  subscriber left), since a later, distinct event reusing the same key
+     *  must start fresh. */
+    deliveredForKey = new Map();
+    constructor(deps) {
+        this.registry = deps.registry;
+        this.lastSeen = deps.lastSeen;
+        this.readCanvasNodes = deps.readCanvasNodes;
+        this.readPendingAsks = deps.readPendingAsks;
+        this.sendPush = deps.sendPush;
+        this.isTargetScope = deps.isTargetScope;
+        this.now = deps.now ?? (() => Date.now());
+        this.rateWindowMs = deps.rateWindowMs ?? DEFAULT_RATE_WINDOW_MS;
+    }
+    /** Seed last-seen from a fresh canvas+deck read and send nothing. Call once
+     *  on server start — a restart must never be an attention event. */
+    async seed() {
+        const [nodes, asks] = await Promise.all([this.readCanvasNodes(), this.readPendingAsks()]);
+        const roots = {};
+        for (const n of nodes) {
+            if (n.parent !== null)
+                continue;
+            roots[n.node_id] = { status: n.status, attention_count: n.attention_count };
+        }
+        const askState = {};
+        for (const a of asks)
+            askState[a.id] = { present: true };
+        this.lastSeen.replace({ schemaVersion: 1, updatedAt: this.now(), roots, asks: askState });
+    }
+    /** 'nodes' invalidation: re-read the canvas roster, emit a 'done' push for
+     *  every conversation root that just crossed into a done|dead|canceled
+     *  status from a non-done status. */
+    async onNodesInvalidation() {
+        this.pendingNodes = true;
+        await this.drain();
+    }
+    async onInboxInvalidation() {
+        this.pendingInbox = true;
+        await this.drain();
+    }
+    /** Serialize passes: if a pass is already running, just set the pending flag
+     *  and return — the running drain loop will pick it up. Otherwise run pending
+     *  passes until none remain. */
+    async drain() {
+        if (this.draining)
+            return;
+        this.draining = true;
+        try {
+            while (this.pendingNodes || this.pendingInbox) {
+                if (this.pendingNodes) {
+                    this.pendingNodes = false;
+                    await this.runNodesPass();
+                }
+                if (this.pendingInbox) {
+                    this.pendingInbox = false;
+                    await this.runInboxPass();
+                }
+            }
+        }
+        finally {
+            this.draining = false;
+        }
+    }
+    async runNodesPass() {
+        const nodes = await this.readCanvasNodes();
+        const prev = this.lastSeen.snapshot();
+        const nextRoots = {};
+        for (const n of nodes) {
+            if (n.parent !== null)
+                continue;
+            const before = prev.roots[n.node_id];
+            const isTransition = before !== undefined && !DONE_STATUSES.has(before.status) && DONE_STATUSES.has(n.status);
+            if (!isTransition) {
+                nextRoots[n.node_id] = { status: n.status, attention_count: n.attention_count };
+                continue;
+            }
+            const sent = await this.emit(n.node_id, {
+                conversationId: n.node_id,
+                kind: 'done',
+                title: 'Conversation finished',
+                snippet: `This conversation is now ${n.status}.`,
+            });
+            // Rate-capped: keep the PRE-transition state so the next 'nodes'
+            // invalidation still sees a non-done -> done edge and retries.
+            nextRoots[n.node_id] = sent ? { status: n.status, attention_count: n.attention_count } : before;
+        }
+        this.lastSeen.replace({ schemaVersion: prev.schemaVersion, updatedAt: this.now(), roots: nextRoots, asks: prev.asks });
+    }
+    /** 'inbox' invalidation: re-read pending asks, emit exactly one 'needs-you'
+     *  push per conversation for its NEW (not-yet-notified) asks, coalesced. An
+     *  ask no longer present (resolved/missing) is simply dropped, never
+     *  notified. */
+    async runInboxPass() {
+        const asks = await this.readPendingAsks();
+        const prev = this.lastSeen.snapshot();
+        const nextAsks = {};
+        const newByConversation = new Map();
+        for (const ask of asks) {
+            if (prev.asks[ask.id]?.present === true) {
+                // Already known + already notified at some point — keep tracked, never
+                // re-notify the same unresolved ask.
+                nextAsks[ask.id] = { present: true };
+                continue;
+            }
+            const list = newByConversation.get(ask.conversationId) ?? [];
+            list.push(ask);
+            newByConversation.set(ask.conversationId, list);
+        }
+        for (const [conversationId, list] of newByConversation) {
+            const first = list[0];
+            const extra = list.length - 1;
+            const sent = await this.emit(conversationId, {
+                conversationId,
+                kind: 'needs-you',
+                askId: first.jobId,
+                title: first.conversationTitle,
+                snippet: extra > 0 ? `${first.title} (+${extra} more)` : first.title,
+            });
+            if (sent) {
+                for (const ask of list)
+                    nextAsks[ask.id] = { present: true };
+            }
+            // Rate-capped: leave these ask ids OUT of nextAsks so the next 'inbox'
+            // invalidation still sees them as new and retries once the window clears.
+        }
+        this.lastSeen.replace({ schemaVersion: prev.schemaVersion, updatedAt: this.now(), roots: prev.roots, asks: nextAsks });
+    }
+    /** Send one push per ELIGIBLE subscription — one whose authScope is on the
+     *  watched boundary (`isTargetScope`) AND that opted in for this payload kind.
+     *  Respects the per-conversation rate cap; prunes any subscription the push
+     *  service reports gone (404/410) or whose endpoint fails the push-service
+     *  allowlist re-check. Tracks per-subscription delivery for this notification
+     *  (`deliveredForKey`) so a retry after a transient failure on one
+     *  subscription never re-sends to a subscription that already got `'sent'`.
+     *  Returns true iff last-seen may advance: false when suppressed by the rate
+     *  cap OR when a transient send error means the item must be retried next
+     *  pass. A no-eligible pass returns true (nothing to retry). */
+    async emit(conversationId, payload) {
+        // Eligible = in the watched auth scope AND opted-in for this payload kind.
+        const eligible = this.registry.snapshot().filter((r) => {
+            if (!this.isTargetScope(r.authScope))
+                return false;
+            if (payload.kind === 'done' && !r.prefs.doneNotifications)
+                return false;
+            return true;
+        });
+        // Keyed by conversation + kind: a later, distinct event reusing this key
+        // (once cleared below) must start with a fresh delivered set.
+        const key = `${conversationId}:${payload.kind}`;
+        // No eligible subscriber -> the event is fully handled (nothing to retry);
+        // advance last-seen. Checked BEFORE the rate cap so a no-eligible pass never
+        // stalls the state on a phantom retry.
+        if (eligible.length === 0) {
+            this.deliveredForKey.delete(key);
+            return true;
+        }
+        const now = this.now();
+        const last = this.lastPushAt.get(conversationId) ?? 0;
+        if (now - last < this.rateWindowMs)
+            return false; // rate-capped -> retry next pass
+        this.lastPushAt.set(conversationId, now);
+        const delivered = this.deliveredForKey.get(key) ?? new Set();
+        let transientFailure = false;
+        for (const record of eligible) {
+            // Already delivered to this subscription for this event on an earlier
+            // pass — never re-send it (this is the fix for duplicate pushes on
+            // transient-failure retry: only the subscriptions that actually failed
+            // are retried).
+            if (delivered.has(record.id))
+                continue;
+            if (!isAllowedPushEndpoint(record.endpoint)) {
+                // Defense in depth: re-check the push-service allowlist immediately
+                // before every outbound connect (no DNS/host TOCTOU), even though
+                // normalizeEndpoint already enforced it at subscribe time. A record
+                // that fails this can never be sent to safely — prune it.
+                this.registry.deleteById(record.id);
+                continue;
+            }
+            let result;
+            try {
+                result = await this.sendPush(record, payload);
+            }
+            catch {
+                result = 'error';
+            }
+            if (result === 'gone')
+                this.registry.deleteById(record.id);
+            else if (result === 'sent')
+                delivered.add(record.id);
+            else
+                transientFailure = true;
+        }
+        // A transient send failure must NOT advance last-seen — retry next pass
+        // (design: "update last-seen only after a successful diff pass"), and the
+        // subscriptions already delivered above must stay remembered so that retry
+        // only reaches the ones that failed. A pruned 'gone'/disallowed record is
+        // not a failure: nothing left to retry for it.
+        if (transientFailure) {
+            this.deliveredForKey.set(key, delivered);
+            return false;
+        }
+        this.deliveredForKey.delete(key);
+        return true;
+    }
+}

package/dist/clients/web/push-registry.d.ts

@@ -0,0 +1,89 @@
+import type { NodeLifeStatus } from './web-client/shared/protocol.js';
+export interface PushPreferences {
+    doneNotifications: boolean;
+}
+export interface PushSubscriptionRecord {
+    id: string;
+    endpoint: string;
+    keys: {
+        p256dh: string;
+        auth: string;
+    };
+    authScope: string;
+    createdAt: number;
+    lastSeenAt: number;
+    prefs: PushPreferences;
+}
+export interface PushRegistryFile {
+    schemaVersion: number;
+    records: PushSubscriptionRecord[];
+}
+export interface PushLastSeenRootState {
+    status: NodeLifeStatus;
+    attention_count: number;
+}
+export interface PushLastSeenAskState {
+    present: boolean;
+}
+export interface PushLastSeenFile {
+    schemaVersion: number;
+    updatedAt: number;
+    roots: Record<string, PushLastSeenRootState>;
+    asks: Record<string, PushLastSeenAskState>;
+}
+/** A locally generated VAPID keypair, persisted so the same identity signs
+ *  every outbound push across restarts. The private key never leaves this
+ *  file/process — only `publicKey` is ever served to a client. */
+export interface VapidKeypairFile {
+    schemaVersion: number;
+    publicKey: string;
+    privateKey: string;
+    subject: string;
+}
+export declare class PushRequestError extends Error {
+    readonly statusCode: number;
+    constructor(statusCode: number, message: string);
+}
+export declare function registryPath(): string;
+export declare function lastSeenPath(): string;
+export declare function vapidPath(): string;
+export declare function pushBodyMaxBytes(): number;
+/** Re-checkable at any later point (e.g. immediately before an outbound send,
+ *  not just at subscribe time) with no dependency on DNS resolution — the
+ *  allowlist match is a pure string check, so there is nothing to TOCTOU. */
+export declare function isAllowedPushEndpoint(endpoint: string): boolean;
+export declare function normalizeEndpoint(endpoint: unknown): string;
+export declare function subscriptionIdForEndpoint(endpoint: string): string;
+export declare function parsePushSubscriptionBody(rawBody: string, authScope: string, now?: number): PushSubscriptionRecord;
+export declare function parsePushDeleteBody(rawBody: string): {
+    endpoint: string;
+};
+/** Load the persisted VAPID keypair, generating and persisting a fresh one on
+ *  first run. One keypair per server identity (design D8/push contract) —
+ *  every subscription is signed with the same public key for the life of this
+ *  `crtrHome()`. The private key never leaves this file/process. */
+export declare function loadOrCreateVapidKeypair(path?: string, subject?: string): VapidKeypairFile;
+export declare class PushRegistryStore {
+    private readonly path;
+    private state;
+    private readonly byId;
+    constructor(path?: string);
+    snapshot(): PushSubscriptionRecord[];
+    listByScope(authScope: string): PushSubscriptionRecord[];
+    upsert(record: PushSubscriptionRecord): PushSubscriptionRecord;
+    touchById(id: string, lastSeenAt: number): PushSubscriptionRecord | null;
+    /** Scoped delete for the HTTP DELETE verb: a caller may only remove a
+     *  subscription it owns (its authScope matches the stored record's). Pruning a
+     *  service-reported-gone endpoint is a separate, unscoped path (`deleteById`). */
+    deleteByEndpoint(endpoint: string, authScope: string): boolean;
+    deleteById(id: string): boolean;
+    private persist;
+}
+export declare class PushLastSeenStore {
+    private readonly path;
+    private state;
+    constructor(path?: string);
+    snapshot(): PushLastSeenFile;
+    replace(next: PushLastSeenFile): void;
+    private persist;
+}