@pipedog/core 0.0.0 → 0.2.0

package/dist/workers/runner.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Worker runner for managing worker execution and orchestration.
+ *
+ * This module provides the `WorkerRunner` class. It runs `BaseWorker`
+ * instances (including `PipelineWorker`) to completion, owning the shared
+ * `WorkerBus`, the worker registry, and the worker manager that backs the
+ * entire session.
+ *
+ * For a typical single-pipeline bot, register the worker with
+ * `WorkerRunner.addWorkers` and then call `WorkerRunner.run`:
+ *
+ * @example
+ * ```ts
+ * const runner = new WorkerRunner();
+ * await runner.addWorkers(worker);
+ * await runner.run();
+ * ```
+ *
+ * For multi-worker setups, register every worker the same way:
+ *
+ * @example
+ * ```ts
+ * const runner = new WorkerRunner();
+ * await runner.addWorkers(new CodeWorker("code-worker", ...), worker);
+ * await runner.run();
+ * ```
+ *
+ * By default, `run()` ends once every root worker has finished — so a
+ * single-pipeline bot naturally ends when its pipeline does. Multi-worker
+ * bots whose helpers run forever (e.g. waiting for bus messages) end by
+ * calling `WorkerRunner.end` / `WorkerRunner.cancel` from an event handler
+ * (typically on transport disconnect). For long-lived hosts that add and
+ * remove workers over many sessions (e.g. an HTTP server), pass
+ * `autoEnd: false` to `run()` so the runner does not exit when no workers
+ * are left.
+ */
+import { Event, type Task } from "@pipedog/asyncio";
+import { BusCancelWorkerMessage, BusEndWorkerMessage, type BusMessage, BusWorkerRegistryMessage, type WorkerBus } from "../bus/index.ts";
+import { WorkerRegistry } from "../registry/index.ts";
+import { WorkerReadyData } from "../registry/types.ts";
+import { type BaseTaskManager } from "../utils/asyncio/task_manager.ts";
+import { BaseObject } from "../utils/base_object.ts";
+import { type BaseWorker } from "./base_worker.ts";
+/** A worker registered on the runner and its background task. */
+declare class _WorkerEntry {
+    worker: BaseWorker;
+    runnerTask: Task<unknown> | null;
+    constructor(options: {
+        worker: BaseWorker;
+        runnerTask?: Task<unknown> | null;
+    });
+}
+export interface WorkerRunnerOptions {
+    /**
+     * Optional name for the runner instance. Defaults to a UUID-based name.
+     * Must be unique across runners in a distributed setup.
+     */
+    name?: string | null;
+    /** Optional `WorkerBus`. Defaults to a new in-process `AsyncQueueBus`. */
+    bus?: WorkerBus | null;
+    /** Whether to automatically handle SIGINT signals. */
+    handleSigint?: boolean;
+    /** Whether to automatically handle SIGTERM signals. */
+    handleSigterm?: boolean;
+    /** Whether to force garbage collection once every worker has been torn down. */
+    forceGc?: boolean;
+    /**
+     * Whether to warn about tasks left running on the shared task manager once
+     * every worker has finished.
+     */
+    checkDanglingTasks?: boolean;
+    /** Optional task manager for handling tasks. */
+    taskManager?: BaseTaskManager | null;
+}
+export interface WorkerRunnerRunOptions {
+    /**
+     * When true (the default), the runner ends once every root worker has
+     * finished. When false, the runner blocks until `end()` or `cancel()` is
+     * called.
+     */
+    autoEnd?: boolean;
+}
+declare const WorkerRunner_base: typeof BaseObject & import("../utils/mixin.ts").Ctor<import("../bus/subscriber.ts").BusSubscriberMethods>;
+/**
+ * Manages worker execution.
+ *
+ * Provides a high-level interface for running workers with automatic signal
+ * handling (SIGINT/SIGTERM), optional garbage collection, proper cleanup of
+ * resources, and a worker bus + registry for multi-worker orchestration.
+ *
+ * Two entry points:
+ *
+ * - `addWorkers(...workers)` — register one or more workers on the runner's
+ *   bus and start them in the background. Workers run concurrently and
+ *   remaining workers are cancelled when the runner ends.
+ * - `run()` — block until the runner ends. By default (`autoEnd: true`) the
+ *   runner ends once every root worker has finished; pass `autoEnd: false`
+ *   to keep the runner up until `end()` / `cancel()` is called.
+ *
+ * Event handlers available:
+ *
+ * - `on_ready` — fired after the runner has finished its initialization and
+ *   any added workers have been started.
+ * - `on_error` — fired when starting an added worker fails.
+ */
+export declare class WorkerRunner extends WorkerRunner_base {
+    protected _bus: WorkerBus;
+    protected _registry: WorkerRegistry;
+    protected _checkDanglingTasks: boolean;
+    protected _entries: Map<string, _WorkerEntry>;
+    protected _knownRunners: Set<string>;
+    protected _running: boolean;
+    protected _autoEnd: boolean;
+    protected _cancelReason: string | null;
+    protected _shutdownEvent: Event;
+    protected _sigTask: Task<void> | null;
+    protected _handleSigint: boolean;
+    protected _handleSigterm: boolean;
+    protected _forceGc: boolean;
+    /**
+     * Initialize the worker runner.
+     *
+     * @param options Runner options (see `WorkerRunnerOptions`).
+     */
+    constructor(options?: WorkerRunnerOptions);
+    /** The bus this runner hosts; shared across launched workers. */
+    get bus(): WorkerBus;
+    /** The worker registry this runner owns. */
+    get registry(): WorkerRegistry;
+    /**
+     * Look up a worker running on this runner by name.
+     *
+     * Only workers added to this runner have a local instance to return. A
+     * worker on another runner is addressable over the bus by name but has no
+     * object here, so it looks the same as an unknown name.
+     *
+     * @param name The name the worker was created with.
+     * @returns The worker, or null if this runner has no worker by that name.
+     */
+    getWorker(name: string): BaseWorker | null;
+    /**
+     * Add one or more workers to the runner.
+     *
+     * Adding a worker attaches it to the runner's bus and registry, and starts
+     * it in the background. If the runner is not yet running (`addWorkers` was
+     * called before `run()`), workers are queued and started during run setup;
+     * if the runner is already running, each worker starts immediately.
+     *
+     * Every added worker is a peer: the runner privileges none of them. They
+     * run concurrently, and whichever are still running when the runner ends
+     * are cancelled. With `autoEnd: true` the runner ends once every root
+     * worker has finished, so a worker that never finishes on its own, such as
+     * a bus-only one waiting for messages, keeps it up until `end()` or
+     * `cancel()` is called.
+     *
+     * @param workers One or more workers to add.
+     */
+    addWorkers(...workers: BaseWorker[]): Promise<void>;
+    /**
+     * Run all added workers until the runner is stopped.
+     *
+     * By default (`autoEnd: true`), the runner ends once every root worker has
+     * finished — so a single-pipeline bot naturally ends when its pipeline
+     * does. Multi-worker bots whose helpers run forever (e.g. waiting for bus
+     * messages) end by calling `end()` / `cancel()` from an event handler
+     * (typically on transport disconnect). For long-lived hosts that add and
+     * remove workers over many sessions (e.g. an HTTP server), pass
+     * `autoEnd: false` so the runner does not exit when no workers are left.
+     *
+     * @param options.autoEnd When true (the default), the runner ends once
+     *   every root worker has finished. When false, the runner blocks until
+     *   `end()` or `cancel()` is called.
+     */
+    run(options?: WorkerRunnerRunOptions): Promise<void>;
+    /** Schedule all root pipeline workers to stop when their current processing is complete. */
+    stopWhenDone(): Promise<void>;
+    /**
+     * Gracefully end all running workers.
+     *
+     * Idempotent; subsequent calls are ignored.
+     *
+     * @param reason Optional human-readable reason for ending.
+     */
+    end(reason?: string | null): Promise<void>;
+    /**
+     * Immediately cancel all running workers.
+     *
+     * Signals shutdown, which `run()` answers by cancelling every worker still
+     * going and waiting for it. Idempotent; subsequent calls are ignored.
+     *
+     * @param reason Optional human-readable reason for cancelling. Reaches each
+     *   worker on the cancel message sent as the runner exits.
+     */
+    cancel(reason?: string | null): Promise<void>;
+    /** Process incoming bus messages for runner-level concerns. */
+    onBusMessage(message: BusMessage): Promise<void>;
+    /** One-time per-run setup: worker manager, bus, signal handlers, launched workers. */
+    protected _setupSession(): Promise<void>;
+    /**
+     * Cancel every worker still going and wait for it to finish.
+     *
+     * The one place the runner cancels its workers, reached on every way out:
+     * an ended session, a cancelled one, or the last root worker finishing. A
+     * worker whose task has already finished is left alone.
+     */
+    protected _cancelSpawnedWorkers(): Promise<void>;
+    /**
+     * Ask each root worker that has not finished to wind down.
+     *
+     * Both messages this takes end a worker, gracefully or not. A worker whose
+     * task has already finished is skipped; one that has not started yet has
+     * not finished either, so it is still told.
+     *
+     * Sending is all this does. The worker finishes in its own time, which is
+     * what the returned entries are for.
+     *
+     * @param messageClass The per-worker message to send.
+     * @param reason Optional human-readable reason, carried on each message.
+     * @returns The entries that were messaged, root or otherwise.
+     */
+    protected _finishRunningWorkers(messageClass: typeof BusEndWorkerMessage | typeof BusCancelWorkerMessage, reason: string | null): Promise<_WorkerEntry[]>;
+    /**
+     * Run `setup_worker_runner` from each file in `PIPECAT_SETUP_FILES`.
+     *
+     * A setup file may define `setup_worker_runner(runner)` (or `setupWorkerRunner`) to add workers,
+     * attach event handlers, or wire other runner-level configuration.
+     */
+    protected _loadSetupFiles(): Promise<void>;
+    /** Run a registered worker as a background task. */
+    protected _startWorker(entry: _WorkerEntry): Promise<void>;
+    /** Drive a registered worker to completion. */
+    protected _runWorker(worker: BaseWorker): Promise<void>;
+    /** Called when a local added worker registers as ready. */
+    protected _onLocalWorkerReady(data: WorkerReadyData): Promise<void>;
+    /** Broadcast this runner's workers to the bus. */
+    protected _sendRegistry(): Promise<void>;
+    /** Handle a registry message from a remote runner. */
+    protected _handleWorkerRegistry(message: BusWorkerRegistryMessage): Promise<void>;
+    /**
+     * Set up SIGINT handler for graceful shutdown.
+     *
+     * DIVERGENCE: installed through the host's `process.on` when there is one
+     * (Bun, Node, Deno); a no-op on runtimes without process signals (Workers).
+     */
+    protected _setupSigint(): void;
+    /**
+     * Set up SIGTERM handler for graceful shutdown.
+     *
+     * DIVERGENCE: see `_setupSigint`.
+     */
+    protected _setupSigterm(): void;
+    /** Handle interrupt signals by cancelling the runner. */
+    protected _sigHandler(): void;
+    /** Cancel the runner due to signal interruption. */
+    protected _sigCancel(): Promise<void>;
+    /**
+     * Force garbage collection and log results.
+     *
+     * DIVERGENCE: JS has no `gc.collect()` count or `gc.garbage`; this calls
+     * the global `gc()` when the runtime exposes one (e.g. Node/Deno with
+     * `--expose-gc`).
+     */
+    protected _gcCollect(): Promise<void>;
+    /** Warn about tasks left running on the task manager this runner owns. */
+    protected _printDanglingTasks(): void;
+}
+export {};
+//# sourceMappingURL=runner.d.ts.map