@littlebigbrain/client 0.15.0 → 0.16.0

package/dist/workflows.js

@@ -0,0 +1,518 @@
+const base = "/v1/workflows";
+const notJson = (v) => v === undefined ||
+    typeof v === "function" ||
+    typeof v === "symbol" ||
+    typeof v === "bigint";
+/** Where the first value JSON cannot hold sits, as `where.a.b[2]`. */
+const badPath = (value, path, seen = new Set()) => {
+    if (notJson(value) || (typeof value === "number" && !Number.isFinite(value)))
+        return path;
+    if (value === null || typeof value !== "object" || seen.has(value))
+        return null;
+    if (typeof value.toJSON === "function")
+        return null;
+    seen.add(value);
+    for (const [key, item] of Object.entries(value)) {
+        const found = badPath(item, Array.isArray(value) ? `${path}[${key}]` : `${path}.${key}`, seen);
+        if (found)
+            return found;
+    }
+    return null;
+};
+/**
+ * A JSON copy of a workflow value. `where` names the value in the error
+ * (`state`, `continuation`, `step "page.3"`), with the path to the field.
+ */
+const copy = (value, where = "value") => {
+    const at = () => {
+        const path = badPath(value, where);
+        return path ? `: ${path}` : "";
+    };
+    const encoded = JSON.stringify(value, (_key, v) => {
+        if (typeof v === "number" && !Number.isFinite(v))
+            throw new WorkflowError(`Values must be finite JSON numbers${at()}`);
+        if (notJson(v))
+            throw new WorkflowError(`Workflow values must be JSON serializable (use null for no result)${at()} is ${typeof v}`);
+        return v;
+    });
+    return JSON.parse(encoded);
+};
+/** A permanent handler/replay error; ordinary thrown errors retry up to max_attempts. */
+export class WorkflowError extends Error {
+}
+/** Define a version-pinned message handler. Put I/O, clock reads and randomness inside ctx.step. */
+export function workflow(definition) {
+    const registered = {
+        name: definition.name,
+        version: definition.version,
+        initialState: copy(definition.initialState, "initialState"),
+        execute: (ctx, state, message) => definition.onMessage(ctx, state, message),
+        start: (client, id, options) => client.workflows.start(registered, id, options),
+    };
+    return registered;
+}
+export class WorkflowHandle {
+    api;
+    id;
+    constructor(api, id) {
+        this.api = api;
+        this.id = id;
+    }
+    status(options) {
+        return this.api.get(this.id, options);
+    }
+    /** Reuse id when retrying the same message, including after a client restart. */
+    send(message, options) {
+        return this.api.send(this.id, message, options);
+    }
+    /** Deliver an approval, callback or other event to a specific run, including while it waits. */
+    signal(name, value, options) {
+        return this.api.signal(this.id, name, value, options);
+    }
+    history(options) {
+        return this.api.history(this.id, options);
+    }
+    pause(options) {
+        return this.api.control(this.id, "pause", undefined, options);
+    }
+    resume(options) {
+        return this.api.control(this.id, "resume", undefined, options);
+    }
+    retry(turn, options) {
+        return this.api.control(this.id, "retry", turn, options);
+    }
+    cancelTurn(turn, options) {
+        return this.api.control(this.id, "cancel_turn", turn, options);
+    }
+}
+export class WorkflowNamespace {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    handle(id) {
+        return new WorkflowHandle(this, id);
+    }
+    async start(definition, id, options = {}) {
+        await this.create({
+            id,
+            workflow_type: definition.name,
+            version: definition.version,
+            state: definition.initialState,
+            lease_ms: options.leaseMs ?? 60_000,
+            max_attempts: options.maxAttempts ?? 3,
+        });
+        return this.handle(id);
+    }
+    create(request, options) {
+        return this.client.request("POST", `${base}/instances`, {
+            ...options,
+            body: request,
+            retry: true,
+        });
+    }
+    get(id, options) {
+        return this.client.request("GET", `${base}/instances/get`, {
+            ...options,
+            query: { id },
+        });
+    }
+    list(options = {}) {
+        const { after, limit, ...call } = options;
+        return this.client.request("GET", `${base}/instances`, {
+            ...call,
+            query: { after, limit },
+        });
+    }
+    send(workflowId, message, options) {
+        const { id, ...call } = options;
+        return this.client.request("POST", `${base}/instances/message`, {
+            ...call,
+            retry: true,
+            body: { workflow_id: workflowId, id, message: copy(message, "message") },
+        });
+    }
+    signal(workflowId, name, value, options) {
+        const { turn, id, ...call } = options;
+        return this.client.request("POST", `${base}/turns/signal`, {
+            ...call,
+            retry: true,
+            body: {
+                workflow_id: workflowId,
+                turn,
+                id,
+                name,
+                value: copy(value, `signal "${name}"`),
+            },
+        });
+    }
+    history(id, options = {}) {
+        const { after, limit, ...call } = options;
+        return this.client.request("GET", `${base}/instances/history`, {
+            ...call,
+            query: { id, after, limit },
+        });
+    }
+    control(id, action, turn, options) {
+        // Explicit turn number prevents a repeated operator command acting on its successor.
+        return this.client.request("POST", `${base}/instances/control`, {
+            ...options,
+            retry: false,
+            body: { workflow_id: id, action, turn },
+        });
+    }
+    /**
+     * Delete an instance with its turns and history. `deleted` is false when
+     * no instance had the id, or when a retry finished an earlier delete.
+     * The id can be created again once this returns.
+     */
+    deleteInstance(id, options) {
+        return this.client.request("POST", `${base}/instances/delete`, {
+            ...options,
+            retry: true,
+            body: { workflow_id: id },
+        });
+    }
+}
+const suspended = Symbol("workflow sleep");
+/** One turn at a time per worker; run additional worker processes for concurrency. */
+export class WorkflowWorker {
+    client;
+    definitions;
+    options;
+    constructor(client, definitions, options) {
+        this.client = client;
+        this.definitions = definitions;
+        this.options = options;
+        const keys = definitions.map((d) => `${d.name}/${d.version}`);
+        if (!keys.length || new Set(keys).size !== keys.length)
+            throw new WorkflowError("Register distinct workflow name/version pairs");
+    }
+    async run(options) {
+        while (!options.signal.aborted) {
+            try {
+                await this.runOnce({ signal: options.signal, waitMs: 10_000 });
+            }
+            catch (error) {
+                if (options.signal.aborted)
+                    return;
+                throw error;
+            }
+        }
+    }
+    async runOnce(options = {}) {
+        const claimed = await this.client.request("POST", `${base}/turns/claim`, {
+            signal: options.signal,
+            retry: false,
+            body: {
+                worker: this.options.worker,
+                workflows: this.definitions.map((d) => ({
+                    workflow_type: d.name,
+                    version: d.version,
+                })),
+                wait_ms: options.waitMs ?? 0,
+            },
+        });
+        if (!claimed.task)
+            return false;
+        await this.execute(claimed.task, options.signal);
+        return true;
+    }
+    async execute(task, signal) {
+        const definition = this.definitions.find((d) => d.name === task.workflow_type && d.version === task.turn.version);
+        if (!definition)
+            throw new WorkflowError("Server returned an unregistered workflow version");
+        const controller = new AbortController();
+        const abort = () => controller.abort(signal?.reason);
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted)
+            abort();
+        const lease = {
+            workflow_id: task.turn.workflow_id,
+            turn: task.turn.number,
+            token: task.token,
+        };
+        let alive = true, busy = false, position = 0, stopped = false;
+        let invalid;
+        let heartbeat;
+        const check = () => {
+            if (stopped)
+                throw suspended;
+            if (!alive || controller.signal.aborted)
+                throw (controller.signal.reason ??
+                    new WorkflowError("Turn no longer owns its lease"));
+            if (invalid)
+                throw invalid;
+        };
+        const renew = async () => {
+            try {
+                await this.client.request("POST", `${base}/turns/heartbeat`, {
+                    body: lease,
+                    retry: false,
+                    signal: controller.signal,
+                    timeoutMs: Math.max(50, Math.floor(task.lease_ms / 3)),
+                });
+                if (alive && !stopped)
+                    heartbeat = setTimeout(() => {
+                        void renew();
+                    }, Math.max(20, task.lease_ms / 3));
+            }
+            catch (error) {
+                if (alive && !stopped)
+                    controller.abort(error);
+            }
+        };
+        heartbeat = setTimeout(() => {
+            void renew();
+        }, Math.max(20, task.lease_ms / 3));
+        const stopHeartbeat = () => {
+            stopped = true;
+            clearTimeout(heartbeat);
+        };
+        const checkpoint = async (key, kind, effect, delay, signalName, stepOptions = {}) => {
+            check();
+            if (busy || !/^[A-Za-z0-9_.-]{1,128}$/.test(key) || position >= 64) {
+                invalid = new WorkflowError("Await sequential steps with distinct valid keys; at 64 steps return ctx.continue(state, cursor)");
+                throw invalid;
+            }
+            busy = true;
+            try {
+                const index = position++;
+                const old = task.turn.steps[index];
+                if (old) {
+                    if (old.key !== key ||
+                        old.kind !== kind ||
+                        (old.delay_ms ?? undefined) !== delay ||
+                        (old.signal_name ?? undefined) !== signalName) {
+                        invalid = new WorkflowError("Step order changed: keep code for existing workflow versions");
+                        throw invalid;
+                    }
+                    return copy(old.output);
+                }
+                if (task.turn.steps.some((s) => s.key === key)) {
+                    invalid = new WorkflowError("Step keys must be unique within a turn");
+                    throw invalid;
+                }
+                let output = null;
+                if (kind === "step") {
+                    const timeout = stepOptions.timeoutMs ?? 300_000;
+                    const progressTimeout = stepOptions.heartbeatTimeoutMs;
+                    if (!Number.isSafeInteger(timeout) ||
+                        timeout < 100 ||
+                        timeout > 86_400_000 ||
+                        (progressTimeout !== undefined &&
+                            (!Number.isSafeInteger(progressTimeout) ||
+                                progressTimeout < 100 ||
+                                progressTimeout > timeout)))
+                        throw new WorkflowError("Invalid operation/progress timeout");
+                    const begun = await this.client.request("POST", `${base}/turns/operation`, {
+                        signal: controller.signal,
+                        retry: true,
+                        body: {
+                            ...lease,
+                            key,
+                            position: index,
+                            kind: stepOptions.kind ?? "step",
+                            timeout_ms: timeout,
+                            heartbeat_timeout_ms: progressTimeout,
+                        },
+                    });
+                    check(); // A late begin response cannot authorize I/O after lease loss.
+                    let sequence = 0, active = true;
+                    let cursor = begun.operation?.checkpoint ?? null;
+                    let pending = Promise.resolve();
+                    const deadline = setTimeout(() => controller.abort(new Error(`Operation ${key} timed out`)), timeout);
+                    let progressTimer;
+                    const watchProgress = () => {
+                        clearTimeout(progressTimer);
+                        if (progressTimeout !== undefined)
+                            progressTimer = setTimeout(() => controller.abort(new Error(`Operation ${key} stopped reporting progress`)), progressTimeout);
+                    };
+                    watchProgress();
+                    const clearOperationTimers = () => {
+                        clearTimeout(deadline);
+                        clearTimeout(progressTimer);
+                    };
+                    controller.signal.addEventListener("abort", clearOperationTimers, {
+                        once: true,
+                    });
+                    try {
+                        output = copy(await effect({
+                            effectId: `${task.effect_prefix}/${key}`,
+                            signal: controller.signal,
+                            checkpoint: copy(cursor),
+                            heartbeat: (details, options) => {
+                                check();
+                                if (!active)
+                                    throw new WorkflowError("Operation has already finished");
+                                const savedDetails = copy(details, `step "${key}" progress`);
+                                const savedCursor = options && "checkpoint" in options
+                                    ? copy(options.checkpoint, `step "${key}" checkpoint`)
+                                    : undefined;
+                                pending = pending.then(async () => {
+                                    check();
+                                    if (savedCursor !== undefined)
+                                        cursor = savedCursor;
+                                    await this.client.request("POST", `${base}/turns/progress`, {
+                                        signal: controller.signal,
+                                        retry: true,
+                                        body: {
+                                            ...lease,
+                                            key,
+                                            sequence: ++sequence,
+                                            details: savedDetails,
+                                            checkpoint: cursor,
+                                        },
+                                    });
+                                    check();
+                                    watchProgress();
+                                });
+                                // The worker also observes this promise if the handler forgets to await it.
+                                void pending.catch(() => { });
+                                return pending;
+                            },
+                        }), `step "${key}"`);
+                        active = false;
+                        await pending;
+                    }
+                    finally {
+                        active = false;
+                        clearOperationTimers();
+                        controller.signal.removeEventListener("abort", clearOperationTimers);
+                    }
+                }
+                check();
+                if (kind !== "step")
+                    stopHeartbeat();
+                const saved = await this.client.request("POST", `${base}/turns/${kind === "signal" ? "wait-signal" : "checkpoint"}`, {
+                    signal: controller.signal,
+                    retry: true,
+                    body: kind === "signal"
+                        ? {
+                            ...lease,
+                            position: index,
+                            key,
+                            name: signalName,
+                            timeout_ms: delay,
+                        }
+                        : {
+                            ...lease,
+                            position: index,
+                            key,
+                            kind,
+                            output,
+                            delay_ms: delay,
+                        },
+                });
+                if (kind === "signal") {
+                    const entry = saved.steps[index];
+                    task.turn.steps.push(entry);
+                    if (saved.status === "waiting")
+                        throw suspended;
+                    stopped = false;
+                    heartbeat = setTimeout(() => {
+                        void renew();
+                    }, Math.max(20, task.lease_ms / 3));
+                    return copy(entry.output);
+                }
+                task.turn.steps.push({
+                    key,
+                    kind,
+                    output,
+                    delay_ms: delay ?? null,
+                    at_ms: 0,
+                    wake_at_ms: null,
+                    signal_name: null,
+                });
+                if (kind === "sleep")
+                    throw suspended;
+                return copy(output);
+            }
+            finally {
+                busy = false;
+            }
+        };
+        const ctx = {
+            signal: controller.signal,
+            workflowId: lease.workflow_id,
+            messageId: task.turn.message_id,
+            turn: lease.turn,
+            step: async (key, fn, options) => (await checkpoint(key, "step", fn, undefined, undefined, options)),
+            waitForSignal: async (key, options) => {
+                if (!/^[A-Za-z0-9_.-]{1,128}$/.test(options.name) ||
+                    !Number.isSafeInteger(options.timeoutMs) ||
+                    options.timeoutMs < 1 ||
+                    options.timeoutMs > 365 * 86_400_000)
+                    throw new WorkflowError("Invalid signal name/timeout");
+                return (await checkpoint(key, "signal", undefined, options.timeoutMs, options.name));
+            },
+            sleep: async (key, delay) => {
+                if (!Number.isSafeInteger(delay) ||
+                    delay < 0 ||
+                    delay > 365 * 86_400_000)
+                    throw new WorkflowError("Invalid sleep duration");
+                await checkpoint(key, "sleep", undefined, delay);
+            },
+            continue: (state, message) => ({ state, continuation: { message } }),
+        };
+        let onAbort = () => { };
+        const aborted = new Promise((_resolve, reject) => {
+            onAbort = () => reject(controller.signal.reason ?? new Error("Workflow interrupted"));
+            controller.signal.addEventListener("abort", onAbort, { once: true });
+        });
+        // Race cancellation even when a provider ignores AbortSignal. Late managed writes are fenced.
+        try {
+            check();
+            const result = await Promise.race([
+                definition.execute(ctx, copy(task.state), copy(task.turn.message)),
+                aborted,
+            ]);
+            check();
+            if (busy || position !== task.turn.steps.length)
+                throw new WorkflowError("Handler left unawaited steps or omitted saved steps");
+            if (stopped)
+                throw suspended; // A handler must not swallow a sleep suspension and commit.
+            const body = {
+                ...lease,
+                state: copy(result.state, "state"),
+                result: copy(result.result ?? null, "result"),
+                continuation: result.continuation
+                    ? copy(result.continuation, "continuation")
+                    : null,
+            };
+            // Serialize completion retries exactly; a lost response must not rerun effects.
+            stopHeartbeat();
+            await this.client.request("POST", `${base}/turns/complete`, {
+                body,
+                retry: true,
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            if (error === suspended)
+                return;
+            if (controller.signal.aborted) {
+                if (signal?.aborted)
+                    throw signal.reason ?? error;
+                return; // The coordinator expires/fences this attempt and schedules its retry.
+            }
+            stopHeartbeat();
+            await this.client.request("POST", `${base}/turns/fail`, {
+                body: {
+                    ...lease,
+                    error: String(error).slice(0, 1000),
+                    non_retryable: error instanceof WorkflowError,
+                },
+                retry: false,
+                signal: controller.signal,
+            });
+        }
+        finally {
+            controller.signal.removeEventListener("abort", onAbort);
+            alive = false;
+            stopHeartbeat();
+            controller.abort();
+            signal?.removeEventListener("abort", abort);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebigbrain/client",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "TypeScript client for little big brain: search, graph queries, and data import",
   "license": "Apache-2.0",
   "repository": {