@datalayer/core 1.1.66 → 1.2.12

package/lib/api/orchestration/events.js

@@ -0,0 +1,245 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { operationUrl } from './client.js';
+import { isTerminal } from './lifecycle.js';
+/** The user channel's event for a tree that moved, and the stream's roll-up. */
+export const TREE_EVENT = 'orchestration.tree';
+/**
+ * Split what has arrived into the complete events and what is left over,
+ * which is the beginning of an event still arriving.
+ */
+export const readServerSentEvents = (buffer) => {
+    const blocks = buffer.replace(/\r\n/g, '\n').split('\n\n');
+    const rest = blocks.pop() ?? '';
+    const events = blocks
+        .filter(block => block.trim() !== '')
+        .map(block => {
+        const framed = { event: 'message', data: '' };
+        const data = [];
+        for (const line of block.split('\n')) {
+            if (line.startsWith(':')) {
+                continue;
+            }
+            const colon = line.indexOf(':');
+            const field = colon === -1 ? line : line.slice(0, colon);
+            const value = colon === -1 ? '' : line.slice(colon + 1).replace(/^ /, '');
+            if (field === 'id') {
+                framed.id = value;
+            }
+            else if (field === 'event') {
+                framed.event = value;
+            }
+            else if (field === 'data') {
+                data.push(value);
+            }
+        }
+        framed.data = data.join('\n');
+        return framed;
+    });
+    return { events, rest };
+};
+/** The service refused the subscription; asking again would be refused again. */
+export class SubscriptionRefused extends Error {
+    status;
+    detail;
+    constructor(status, detail) {
+        super(`The subscription was refused with ${status}: ${detail}`);
+        this.status = status;
+        this.detail = detail;
+        this.name = 'SubscriptionRefused';
+    }
+}
+const pause = (milliseconds, signal) => new Promise(resolve => {
+    if (milliseconds <= 0 || signal?.aborted) {
+        resolve();
+        return;
+    }
+    const timer = setTimeout(resolve, milliseconds);
+    signal?.addEventListener('abort', () => {
+        clearTimeout(timer);
+        resolve();
+    }, { once: true });
+});
+/**
+ * Subscribe to an execution — and its tree — until it is over.
+ *
+ * A dropped connection, before the service answered or in the middle of the
+ * stream, is resumed from the last event received. A refusal is not: it
+ * rejects `done` with `SubscriptionRefused`. An abort ends the subscription
+ * quietly, because stopping is the caller's decision rather than a failure.
+ */
+export const subscribeToExecution = (options, executionId, subscribe) => {
+    let lastEventId = subscribe.lastEventId;
+    const fetcher = subscribe.fetch ??
+        ((url, init) => fetch(url, init));
+    const query = {
+        includeChildren: subscribe.includeChildren,
+        fromSequence: subscribe.fromSequence,
+    };
+    const address = new URL(operationUrl(options, 'executions.subscribe', { execution_id: executionId }, query));
+    for (const wanted of subscribe.events ?? []) {
+        address.searchParams.append('events', wanted);
+    }
+    const url = address.toString();
+    const maxReconnects = subscribe.maxReconnects ?? 5;
+    const run = async () => {
+        let dropsInARow = 0;
+        for (;;) {
+            const headers = { Accept: 'text/event-stream' };
+            if (options.token) {
+                headers.Authorization = `Bearer ${options.token}`;
+            }
+            if (lastEventId) {
+                headers['Last-Event-ID'] = lastEventId;
+            }
+            let response;
+            try {
+                response = await fetcher(url, {
+                    headers,
+                    signal: subscribe.signal,
+                    credentials: 'include',
+                });
+            }
+            catch {
+                if (subscribe.signal?.aborted) {
+                    return;
+                }
+            }
+            if (response && !response.ok) {
+                throw new SubscriptionRefused(response.status, await response.text());
+            }
+            let ended = false;
+            if (response?.body) {
+                const reader = response.body.getReader();
+                const decoder = new TextDecoder();
+                let buffer = '';
+                for (;;) {
+                    let chunk;
+                    try {
+                        chunk = await reader.read();
+                    }
+                    catch {
+                        if (subscribe.signal?.aborted) {
+                            return;
+                        }
+                        break;
+                    }
+                    if (chunk.done) {
+                        break;
+                    }
+                    buffer += decoder.decode(chunk.value, { stream: true });
+                    const { events, rest } = readServerSentEvents(buffer);
+                    buffer = rest;
+                    for (const framed of events) {
+                        if (framed.event === 'end') {
+                            ended = true;
+                            continue;
+                        }
+                        if (framed.id) {
+                            lastEventId = framed.id;
+                        }
+                        if (framed.event === TREE_EVENT) {
+                            subscribe.onTree?.(JSON.parse(framed.data), framed.id ?? '');
+                        }
+                        else {
+                            subscribe.onEvent(JSON.parse(framed.data), framed.id ?? '');
+                        }
+                        dropsInARow = 0;
+                    }
+                }
+            }
+            if (ended) {
+                subscribe.onEnd?.();
+                return;
+            }
+            if (subscribe.signal?.aborted) {
+                return;
+            }
+            dropsInARow += 1;
+            if (dropsInARow > maxReconnects) {
+                throw new Error(`The subscription to '${executionId}' dropped ${dropsInARow} times with no event in between.`);
+            }
+            await pause(subscribe.reconnectDelayMs ?? 1000, subscribe.signal);
+        }
+    };
+    return { done: run(), lastEventId: () => lastEventId };
+};
+/**
+ * What a tree is doing, worked out from its canonical events alone (O2-03).
+ *
+ * The same summary the subscription sends as `orchestration.tree`: each
+ * execution's latest state, its parent, its worker and its goal — the message
+ * of the event that created it — and its depth below the first execution the
+ * events cover. Each execution's events are read in their own sequence,
+ * whatever order they arrived in.
+ */
+export const treeFromEvents = (events) => {
+    const nodes = new Map();
+    let root = '';
+    const ordered = [...events].sort((one, other) => one.executionId === other.executionId
+        ? one.sequence - other.sequence
+        : one.executionId < other.executionId
+            ? -1
+            : 1);
+    for (const event of ordered) {
+        root = root || event.rootExecutionId;
+        let node = nodes.get(event.executionId);
+        if (!node) {
+            node = {
+                parent: event.parentExecutionId ?? null,
+                goal: event.message ?? '',
+                agentId: '',
+                updatedAt: event.emittedAt,
+            };
+            nodes.set(event.executionId, node);
+        }
+        node.agentId = event.agentId ?? node.agentId;
+        node.protocol = event.protocol ?? node.protocol;
+        node.status = event.state ?? node.status;
+        node.updatedAt = event.emittedAt;
+    }
+    const depth = (executionId) => {
+        const parent = nodes.get(executionId)?.parent;
+        return parent && nodes.has(parent) ? depth(parent) + 1 : 0;
+    };
+    const executions = [];
+    for (const [executionId, node] of nodes) {
+        if (node.status && node.protocol) {
+            executions.push({
+                executionId,
+                parentExecutionId: node.parent,
+                depth: depth(executionId),
+                status: node.status,
+                agentId: node.agentId,
+                protocol: node.protocol,
+                goal: node.goal,
+                updatedAt: node.updatedAt,
+            });
+        }
+    }
+    const counts = {};
+    for (const one of executions) {
+        counts[one.status] = (counts[one.status] ?? 0) + 1;
+    }
+    return {
+        rootExecutionId: root,
+        executions,
+        counts,
+        terminal: executions.every(one => isTerminal(one.status)),
+    };
+};
+/** Whether a user-channel message is a tree announcement. */
+export const isTreeAnnouncement = (message) => {
+    if (typeof message !== 'object' || message === null) {
+        return false;
+    }
+    const { event, data } = message;
+    return (event === TREE_EVENT &&
+        typeof data === 'object' &&
+        data !== null &&
+        typeof data.rootExecutionId ===
+            'string' &&
+        Array.isArray(data.executions));
+};