optio-api 0.2.10 → 0.2.11

package/dist/stream-poller.js

@@ -1,288 +1,312 @@
 import { ObjectId } from 'mongodb';
 import { metadataFilterToMongo } from './metadata-filter-query.js';
 import { andScope } from './access-scope.js';
-export function createListPoller(opts) {
-    const { db, prefix, sendEvent, onError, metadataFilter, scope } = opts;
-    const col = db.collection(`${prefix}_processes`);
-    const filter = andScope(metadataFilterToMongo(metadataFilter), scope ?? null);
-    let interval = null;
-    let lastSnapshot = '';
-    async function poll() {
+import { LIST_PROJECTION, listRelevant, treeRelevant, sessionRelevant, } from './process-change-relevance.js';
+import { getProcessChangeHub } from './process-change-hub.js';
+/**
+ * Run `read` once on start, then whenever the hub reports a change `rule`
+ * finds relevant (the hub throttles to one read a second, and polls once a
+ * second where change streams are unavailable). Reads never overlap: a refresh
+ * during a read runs one more read after it. While a read is in flight every
+ * change counts as relevant, since `rule` judges by the last read's members
+ * and the read in flight may have missed the change. A failed read stops the
+ * stream and calls `onError`.
+ *
+ * Spec: docs/2026-10-09-api-change-streams-design.md
+ */
+function driveByChanges(opts, read, rule) {
+    const hub = opts.hub ?? getProcessChangeHub(opts.db, opts.prefix);
+    let stopped = false;
+    let reading = false;
+    let again = false;
+    async function run() {
+        if (stopped)
+            return;
+        if (reading) {
+            again = true;
+            return;
+        }
+        reading = true;
         try {
-            const allProcs = await col.find(filter).sort({ depth: 1, order: 1, _id: 1 }).toArray();
-            const snapshot = JSON.stringify(allProcs.map((p) => ({
-                id: p._id,
-                state: p.status?.state,
-                percent: p.progress?.percent,
-                message: p.progress?.message,
-                supportsResume: p.supportsResume ?? false,
-                hasSavedState: p.hasSavedState ?? false,
-                supportsResurrect: p.supportsResurrect ?? false,
-                hasUnsavedWork: p.hasUnsavedWork ?? false,
-                resurrecting: p.resurrecting ?? false,
-                autoResumeScheduled: p.autoResumeScheduled ?? false,
-                browserOpenRequests: p.browserOpenRequests ?? [],
-            })));
-            if (snapshot !== lastSnapshot) {
-                lastSnapshot = snapshot;
-                sendEvent({
-                    type: 'update',
-                    processes: allProcs.map((p) => ({
-                        _id: p._id.toString(),
-                        processId: p.processId,
-                        name: p.name,
-                        status: p.status,
-                        progress: p.progress,
-                        cancellable: p.cancellable,
-                        special: p.special,
-                        warning: p.warning,
-                        metadata: p.metadata,
-                        depth: p.depth ?? 0,
-                        supportsResume: p.supportsResume ?? false,
-                        hasSavedState: p.hasSavedState ?? false,
-                        supportsResurrect: p.supportsResurrect ?? false,
-                        hasUnsavedWork: p.hasUnsavedWork ?? false,
-                        resurrecting: p.resurrecting ?? false,
-                        autoResumeScheduled: p.autoResumeScheduled ?? false,
-                        browserOpenRequests: p.browserOpenRequests ?? [],
-                    })),
-                });
-            }
+            do {
+                again = false;
+                await read();
+            } while (again && !stopped);
         }
         catch {
             stop();
-            onError();
+            opts.onError();
+        }
+        finally {
+            reading = false;
         }
     }
+    const sub = {
+        isRelevant: (c) => reading || rule(c),
+        refresh: () => { void run(); },
+    };
     function start() {
-        interval = setInterval(poll, 1000);
+        stopped = false;
+        hub.subscribe(sub).then(() => run(), () => {
+            if (stopped)
+                return;
+            stop();
+            opts.onError();
+        });
     }
     function stop() {
-        if (interval) {
-            clearInterval(interval);
-            interval = null;
-        }
+        if (stopped)
+            return;
+        stopped = true;
+        hub.unsubscribe(sub);
     }
     return { start, stop };
 }
+export function createListPoller(opts) {
+    const { db, prefix, sendEvent, metadataFilter, scope } = opts;
+    const col = db.collection(`${prefix}_processes`);
+    const filter = andScope(metadataFilterToMongo(metadataFilter), scope ?? null);
+    let members = new Set();
+    let lastSnapshot = '';
+    async function read() {
+        const allProcs = await col
+            .find(filter, { projection: LIST_PROJECTION })
+            .sort({ depth: 1, order: 1, _id: 1 })
+            .toArray();
+        members = new Set(allProcs.map((p) => String(p._id)));
+        const snapshot = JSON.stringify(allProcs.map((p) => ({
+            id: p._id,
+            state: p.status?.state,
+            percent: p.progress?.percent,
+            message: p.progress?.message,
+            supportsResume: p.supportsResume ?? false,
+            hasSavedState: p.hasSavedState ?? false,
+            supportsResurrect: p.supportsResurrect ?? false,
+            hasUnsavedWork: p.hasUnsavedWork ?? false,
+            resurrecting: p.resurrecting ?? false,
+            autoResumeScheduled: p.autoResumeScheduled ?? false,
+            browserOpenRequests: p.browserOpenRequests ?? [],
+        })));
+        if (snapshot !== lastSnapshot) {
+            lastSnapshot = snapshot;
+            sendEvent({
+                type: 'update',
+                processes: allProcs.map((p) => ({
+                    _id: p._id.toString(),
+                    processId: p.processId,
+                    name: p.name,
+                    status: p.status,
+                    progress: p.progress,
+                    cancellable: p.cancellable,
+                    special: p.special,
+                    warning: p.warning,
+                    metadata: p.metadata,
+                    depth: p.depth ?? 0,
+                    supportsResume: p.supportsResume ?? false,
+                    hasSavedState: p.hasSavedState ?? false,
+                    supportsResurrect: p.supportsResurrect ?? false,
+                    hasUnsavedWork: p.hasUnsavedWork ?? false,
+                    resurrecting: p.resurrecting ?? false,
+                    autoResumeScheduled: p.autoResumeScheduled ?? false,
+                    browserOpenRequests: p.browserOpenRequests ?? [],
+                })),
+            });
+        }
+    }
+    return driveByChanges(opts, read, (c) => listRelevant(c, members));
+}
 export function createTreePoller(opts) {
-    const { db, prefix, sendEvent, onError, rootId, baseDepth, maxDepth } = opts;
+    const { db, prefix, sendEvent, rootId, baseDepth, maxDepth } = opts;
     const col = db.collection(`${prefix}_processes`);
-    let interval = null;
+    const roots = new Set([rootId]);
+    let members = new Set();
     let lastSnapshot = '';
     const lastLogCounts = new Map();
     let firstPoll = true;
-    async function poll() {
-        try {
-            const filter = { rootId: new ObjectId(rootId) };
-            if (maxDepth !== undefined) {
-                filter.depth = { $lte: baseDepth + maxDepth };
-            }
-            const allProcs = await col.find(filter).sort({ depth: 1, order: 1 }).toArray();
-            const snapshot = JSON.stringify(allProcs.map((p) => ({
-                id: p._id, status: p.status, progress: p.progress,
-                widgetData: p.widgetData, uiWidget: p.uiWidget,
-                supportsResume: p.supportsResume ?? false,
-                hasSavedState: p.hasSavedState ?? false,
-                supportsResurrect: p.supportsResurrect ?? false,
-                hasUnsavedWork: p.hasUnsavedWork ?? false,
-                resurrecting: p.resurrecting ?? false,
-                autoResumeScheduled: p.autoResumeScheduled ?? false,
-                browserOpenRequests: p.browserOpenRequests ?? [],
-                metadata: p.metadata,
-            })));
-            if (snapshot !== lastSnapshot) {
-                lastSnapshot = snapshot;
-                sendEvent({
-                    type: 'update',
-                    processes: allProcs.map((p) => ({
-                        _id: p._id.toString(),
-                        parentId: p.parentId?.toString() ?? null,
-                        rootId: p.rootId?.toString() ?? null,
-                        name: p.name,
-                        status: p.status,
-                        progress: p.progress,
-                        cancellable: p.cancellable ?? false,
-                        depth: p.depth,
-                        order: p.order,
-                        widgetData: p.widgetData,
-                        uiWidget: p.uiWidget,
-                        supportsResume: p.supportsResume ?? false,
-                        hasSavedState: p.hasSavedState ?? false,
-                        supportsResurrect: p.supportsResurrect ?? false,
-                        hasUnsavedWork: p.hasUnsavedWork ?? false,
-                        resurrecting: p.resurrecting ?? false,
-                        autoResumeScheduled: p.autoResumeScheduled ?? false,
-                        browserOpenRequests: p.browserOpenRequests ?? [],
-                        metadata: p.metadata,
-                    })),
-                });
+    async function read() {
+        const filter = { rootId: new ObjectId(rootId) };
+        if (maxDepth !== undefined) {
+            filter.depth = { $lte: baseDepth + maxDepth };
+        }
+        const allProcs = await col.find(filter).sort({ depth: 1, order: 1 }).toArray();
+        members = new Set(allProcs.map((p) => String(p._id)));
+        const snapshot = JSON.stringify(allProcs.map((p) => ({
+            id: p._id, status: p.status, progress: p.progress,
+            widgetData: p.widgetData, uiWidget: p.uiWidget,
+            supportsResume: p.supportsResume ?? false,
+            hasSavedState: p.hasSavedState ?? false,
+            supportsResurrect: p.supportsResurrect ?? false,
+            hasUnsavedWork: p.hasUnsavedWork ?? false,
+            resurrecting: p.resurrecting ?? false,
+            autoResumeScheduled: p.autoResumeScheduled ?? false,
+            browserOpenRequests: p.browserOpenRequests ?? [],
+            metadata: p.metadata,
+        })));
+        if (snapshot !== lastSnapshot) {
+            lastSnapshot = snapshot;
+            sendEvent({
+                type: 'update',
+                processes: allProcs.map((p) => ({
+                    _id: p._id.toString(),
+                    parentId: p.parentId?.toString() ?? null,
+                    rootId: p.rootId?.toString() ?? null,
+                    name: p.name,
+                    status: p.status,
+                    progress: p.progress,
+                    cancellable: p.cancellable ?? false,
+                    depth: p.depth,
+                    order: p.order,
+                    widgetData: p.widgetData,
+                    uiWidget: p.uiWidget,
+                    supportsResume: p.supportsResume ?? false,
+                    hasSavedState: p.hasSavedState ?? false,
+                    supportsResurrect: p.supportsResurrect ?? false,
+                    hasUnsavedWork: p.hasUnsavedWork ?? false,
+                    resurrecting: p.resurrecting ?? false,
+                    autoResumeScheduled: p.autoResumeScheduled ?? false,
+                    browserOpenRequests: p.browserOpenRequests ?? [],
+                    metadata: p.metadata,
+                })),
+            });
+        }
+        // Detect log changes
+        let logCleared = false;
+        const newLogEntries = [];
+        for (const p of allProcs) {
+            const pid = p._id.toString();
+            const logLen = (p.log ?? []).length;
+            const lastLen = lastLogCounts.get(pid) ?? 0;
+            if (logLen < lastLen) {
+                logCleared = true;
+                lastLogCounts.set(pid, 0);
             }
-            // Detect log changes
-            let logCleared = false;
-            const newLogEntries = [];
-            for (const p of allProcs) {
-                const pid = p._id.toString();
-                const logLen = (p.log ?? []).length;
-                const lastLen = lastLogCounts.get(pid) ?? 0;
-                if (logLen < lastLen) {
-                    logCleared = true;
-                    lastLogCounts.set(pid, 0);
-                }
-                const effectiveLastLen = lastLogCounts.get(pid) ?? 0;
-                if (logLen > effectiveLastLen) {
-                    const entries = (p.log ?? []).slice(firstPoll ? 0 : effectiveLastLen);
-                    for (const entry of entries) {
-                        newLogEntries.push({
-                            ...entry,
-                            processId: pid,
-                            processLabel: p.name,
-                        });
-                    }
-                    lastLogCounts.set(pid, logLen);
+            const effectiveLastLen = lastLogCounts.get(pid) ?? 0;
+            if (logLen > effectiveLastLen) {
+                const entries = (p.log ?? []).slice(firstPoll ? 0 : effectiveLastLen);
+                for (const entry of entries) {
+                    newLogEntries.push({
+                        ...entry,
+                        processId: pid,
+                        processLabel: p.name,
+                    });
                 }
-            }
-            firstPoll = false;
-            if (logCleared) {
-                sendEvent({ type: 'log-clear' });
-            }
-            if (newLogEntries.length > 0) {
-                newLogEntries.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
-                sendEvent({ type: 'log', entries: newLogEntries });
+                lastLogCounts.set(pid, logLen);
             }
         }
-        catch {
-            stop();
-            onError();
+        firstPoll = false;
+        if (logCleared) {
+            sendEvent({ type: 'log-clear' });
         }
-    }
-    function start() {
-        interval = setInterval(poll, 1000);
-    }
-    function stop() {
-        if (interval) {
-            clearInterval(interval);
-            interval = null;
+        if (newLogEntries.length > 0) {
+            newLogEntries.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+            sendEvent({ type: 'log', entries: newLogEntries });
         }
     }
-    return { start, stop };
+    return driveByChanges(opts, read, (c) => treeRelevant(c, roots, members));
 }
 export function createMultiTreePoller(opts) {
-    const { db, prefix, sendEvent, onError, treeRoots, flatIds, maxDepth } = opts;
+    const { db, prefix, sendEvent, treeRoots, flatIds, maxDepth } = opts;
     const col = db.collection(`${prefix}_processes`);
-    let interval = null;
+    const roots = new Set(treeRoots.map((r) => r.rootId.toString()));
+    let members = new Set();
     let lastSnapshot = '';
     const lastLogCounts = new Map();
     let firstPoll = true;
-    async function poll() {
-        try {
-            const branches = [];
-            if (treeRoots.length > 0) {
-                branches.push({
-                    $or: treeRoots.map((r) => {
-                        const f = { rootId: r.rootId };
-                        if (maxDepth !== undefined) {
-                            f.depth = { $lte: r.baseDepth + maxDepth };
-                        }
-                        return f;
-                    }),
-                });
-            }
-            if (flatIds.length > 0) {
-                branches.push({ _id: { $in: flatIds } });
+    async function read() {
+        const branches = [];
+        if (treeRoots.length > 0) {
+            branches.push({
+                $or: treeRoots.map((r) => {
+                    const f = { rootId: r.rootId };
+                    if (maxDepth !== undefined) {
+                        f.depth = { $lte: r.baseDepth + maxDepth };
+                    }
+                    return f;
+                }),
+            });
+        }
+        if (flatIds.length > 0) {
+            branches.push({ _id: { $in: flatIds } });
+        }
+        if (branches.length === 0)
+            return;
+        const filter = branches.length === 1 ? branches[0] : { $or: branches };
+        const allProcs = await col.find(filter).sort({ depth: 1, order: 1 }).toArray();
+        members = new Set([...allProcs.map((p) => String(p._id)), ...flatIds.map(String)]);
+        const snapshot = JSON.stringify(allProcs.map((p) => ({
+            id: p._id, status: p.status, progress: p.progress,
+            widgetData: p.widgetData, uiWidget: p.uiWidget,
+            supportsResume: p.supportsResume ?? false,
+            hasSavedState: p.hasSavedState ?? false,
+            supportsResurrect: p.supportsResurrect ?? false,
+            hasUnsavedWork: p.hasUnsavedWork ?? false,
+            resurrecting: p.resurrecting ?? false,
+            autoResumeScheduled: p.autoResumeScheduled ?? false,
+            browserOpenRequests: p.browserOpenRequests ?? [],
+            metadata: p.metadata,
+        })));
+        if (snapshot !== lastSnapshot) {
+            lastSnapshot = snapshot;
+            sendEvent({
+                type: 'update',
+                processes: allProcs.map((p) => ({
+                    _id: p._id.toString(),
+                    parentId: p.parentId?.toString() ?? null,
+                    rootId: p.rootId?.toString() ?? null,
+                    processId: p.processId,
+                    name: p.name,
+                    status: p.status,
+                    progress: p.progress,
+                    cancellable: p.cancellable ?? false,
+                    depth: p.depth,
+                    order: p.order,
+                    widgetData: p.widgetData,
+                    uiWidget: p.uiWidget,
+                    supportsResume: p.supportsResume ?? false,
+                    hasSavedState: p.hasSavedState ?? false,
+                    supportsResurrect: p.supportsResurrect ?? false,
+                    hasUnsavedWork: p.hasUnsavedWork ?? false,
+                    resurrecting: p.resurrecting ?? false,
+                    autoResumeScheduled: p.autoResumeScheduled ?? false,
+                    browserOpenRequests: p.browserOpenRequests ?? [],
+                    metadata: p.metadata,
+                })),
+            });
+        }
+        const logClearedRoots = new Set();
+        const newLogEntries = [];
+        for (const p of allProcs) {
+            const pid = p._id.toString();
+            const logLen = (p.log ?? []).length;
+            const lastLen = lastLogCounts.get(pid) ?? 0;
+            if (logLen < lastLen) {
+                logClearedRoots.add(p.rootId?.toString() ?? '');
+                lastLogCounts.set(pid, 0);
             }
-            if (branches.length === 0)
-                return;
-            const filter = branches.length === 1 ? branches[0] : { $or: branches };
-            const allProcs = await col.find(filter).sort({ depth: 1, order: 1 }).toArray();
-            const snapshot = JSON.stringify(allProcs.map((p) => ({
-                id: p._id, status: p.status, progress: p.progress,
-                widgetData: p.widgetData, uiWidget: p.uiWidget,
-                supportsResume: p.supportsResume ?? false,
-                hasSavedState: p.hasSavedState ?? false,
-                supportsResurrect: p.supportsResurrect ?? false,
-                hasUnsavedWork: p.hasUnsavedWork ?? false,
-                resurrecting: p.resurrecting ?? false,
-                autoResumeScheduled: p.autoResumeScheduled ?? false,
-                browserOpenRequests: p.browserOpenRequests ?? [],
-                metadata: p.metadata,
-            })));
-            if (snapshot !== lastSnapshot) {
-                lastSnapshot = snapshot;
-                sendEvent({
-                    type: 'update',
-                    processes: allProcs.map((p) => ({
-                        _id: p._id.toString(),
-                        parentId: p.parentId?.toString() ?? null,
+            const effectiveLastLen = lastLogCounts.get(pid) ?? 0;
+            if (logLen > effectiveLastLen) {
+                const entries = (p.log ?? []).slice(firstPoll ? 0 : effectiveLastLen);
+                for (const entry of entries) {
+                    newLogEntries.push({
+                        ...entry,
+                        processId: pid,
+                        processLabel: p.name,
                         rootId: p.rootId?.toString() ?? null,
-                        processId: p.processId,
-                        name: p.name,
-                        status: p.status,
-                        progress: p.progress,
-                        cancellable: p.cancellable ?? false,
-                        depth: p.depth,
-                        order: p.order,
-                        widgetData: p.widgetData,
-                        uiWidget: p.uiWidget,
-                        supportsResume: p.supportsResume ?? false,
-                        hasSavedState: p.hasSavedState ?? false,
-                        supportsResurrect: p.supportsResurrect ?? false,
-                        hasUnsavedWork: p.hasUnsavedWork ?? false,
-                        resurrecting: p.resurrecting ?? false,
-                        autoResumeScheduled: p.autoResumeScheduled ?? false,
-                        browserOpenRequests: p.browserOpenRequests ?? [],
-                        metadata: p.metadata,
-                    })),
-                });
-            }
-            const logClearedRoots = new Set();
-            const newLogEntries = [];
-            for (const p of allProcs) {
-                const pid = p._id.toString();
-                const logLen = (p.log ?? []).length;
-                const lastLen = lastLogCounts.get(pid) ?? 0;
-                if (logLen < lastLen) {
-                    logClearedRoots.add(p.rootId?.toString() ?? '');
-                    lastLogCounts.set(pid, 0);
-                }
-                const effectiveLastLen = lastLogCounts.get(pid) ?? 0;
-                if (logLen > effectiveLastLen) {
-                    const entries = (p.log ?? []).slice(firstPoll ? 0 : effectiveLastLen);
-                    for (const entry of entries) {
-                        newLogEntries.push({
-                            ...entry,
-                            processId: pid,
-                            processLabel: p.name,
-                            rootId: p.rootId?.toString() ?? null,
-                        });
-                    }
-                    lastLogCounts.set(pid, logLen);
+                    });
                 }
-            }
-            firstPoll = false;
-            for (const rid of logClearedRoots) {
-                sendEvent({ type: 'log-clear', rootId: rid });
-            }
-            if (newLogEntries.length > 0) {
-                newLogEntries.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
-                sendEvent({ type: 'log', entries: newLogEntries });
+                lastLogCounts.set(pid, logLen);
             }
         }
-        catch {
-            stop();
-            onError();
+        firstPoll = false;
+        for (const rid of logClearedRoots) {
+            sendEvent({ type: 'log-clear', rootId: rid });
         }
-    }
-    function start() {
-        interval = setInterval(poll, 1000);
-    }
-    function stop() {
-        if (interval) {
-            clearInterval(interval);
-            interval = null;
+        if (newLogEntries.length > 0) {
+            newLogEntries.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+            sendEvent({ type: 'log', entries: newLogEntries });
         }
     }
-    return { start, stop };
+    return driveByChanges(opts, read, (c) => treeRelevant(c, roots, members));
 }
 /**
  * Poll-backed session-events feed. Each ~1s tick reads processes whose
@@ -290,45 +314,31 @@ export function createMultiTreePoller(opts) {
  * sessionEvents (deduped by length high-water mark per process). Read-only.
  */
 export function createSessionEventsPoller(opts) {
-    const { db, prefix, sessionId, sendEvent, onError, scope } = opts;
+    const { db, prefix, sessionId, sendEvent, scope } = opts;
     const col = db.collection(`${prefix}_processes`);
     const filter = andScope({ originatingSessionId: sessionId }, scope ?? null);
-    let interval = null;
+    let members = new Set();
     const lastCounts = new Map();
-    async function poll() {
-        try {
-            const procs = await col
-                .find(filter)
-                .project({ sessionEvents: 1 })
-                .toArray();
-            for (const p of procs) {
-                const pid = p._id.toString();
-                const events = (p.sessionEvents ?? []);
-                const seen = lastCounts.get(pid) ?? 0;
-                if (events.length > seen) {
-                    sendEvent({
-                        type: 'session-events',
-                        processId: pid,
-                        events: events.slice(seen),
-                    });
-                    lastCounts.set(pid, events.length);
-                }
+    async function read() {
+        const procs = await col
+            .find(filter)
+            .project({ sessionEvents: 1 })
+            .toArray();
+        members = new Set(procs.map((p) => String(p._id)));
+        for (const p of procs) {
+            const pid = p._id.toString();
+            const events = (p.sessionEvents ?? []);
+            const seen = lastCounts.get(pid) ?? 0;
+            if (events.length > seen) {
+                sendEvent({
+                    type: 'session-events',
+                    processId: pid,
+                    events: events.slice(seen),
+                });
+                lastCounts.set(pid, events.length);
             }
         }
-        catch {
-            stop();
-            onError();
-        }
-    }
-    function start() {
-        interval = setInterval(poll, 1000);
-    }
-    function stop() {
-        if (interval) {
-            clearInterval(interval);
-            interval = null;
-        }
     }
-    return { start, stop };
+    return driveByChanges(opts, read, (c) => sessionRelevant(c, sessionId, members));
 }
 //# sourceMappingURL=stream-poller.js.map