cairnq 0.4.0 → 0.6.0

package/dist/worker.d.ts

@@ -1,12 +1,35 @@
+import type { BackpressureOptions } from "./backpressure.js";
 import { TaskContext } from "./context.js";
 import type { TaskStore } from "./store/base.js";
 import { type TaskDef } from "./task.js";
+export { retryDelayMs, DEFAULT_RETRY_BACKOFF_MS, DEFAULT_RETRY_BACKOFF_MAX_MS } from "./backoff.js";
 export type Handler = (ctx: TaskContext, payload: any) => unknown | Promise<unknown>;
 /** Handler typed against a TaskDef<P, R>: payload is P, the return is R. */
 export type TypedHandler<P, R> = (ctx: TaskContext, payload: P) => R | Promise<R>;
+/**
+ * A batch handler takes one argument: the list of contexts. There is no payload
+ * shortcut to pair with it — payloads are per task, so they are read off the
+ * items (`item.payload`), which is also what a handler must hold to settle one
+ * of them.
+ *
+ * Returning a map of task id -> result fills in results for the tasks the
+ * handler did not settle itself; anything else returned is ignored.
+ */
+export type BatchHandler = (items: TaskContext[]) => void | Record<string, unknown> | Promise<void | Record<string, unknown>>;
 /** Where an error the worker recovered from came from. */
 export type ErrorPhase = "claim" | "execute";
-export interface WorkerOptions {
+/**
+ * Backpressure is accepted here too, not only on CairnQ: a handler spawning
+ * children through TaskContext.submit is a producer, and in a worker process
+ * there is usually no CairnQ handle to have configured the store.
+ */
+export interface WorkerOptions extends Partial<BackpressureOptions> {
+    /**
+     * Handler calls allowed to run at once. A batch call counts as one, however
+     * many tasks it carries — size it for how much work you want in flight, not
+     * for how many tasks that comes to. Per-name limits refine it; `maxInFlightBytes`
+     * bounds memory, which task counts never did.
+     */
     concurrency?: number;
     leaseMs?: number;
     heartbeatIntervalMs?: number;
@@ -25,6 +48,39 @@ export interface WorkerOptions {
      * a retryable `handler_timeout` failure. Unset disables the ceiling.
      */
     maxRunMs?: number;
+    /**
+     * Resident payload bytes allowed across running handlers, independent of
+     * their count.
+     *
+     * `concurrency` bounds tasks, not memory, so a worker sized for small payloads
+     * holds concurrency * largest-payload bytes the moment a batch of big ones
+     * arrives — for payloads that carry media inline, that is the difference
+     * between megabytes and gigabytes resident. Once the budget is spent the
+     * worker stops claiming until running handlers give it back.
+     *
+     * The bound is on tasks already executing: it is read between claims, never
+     * during one, and a claim commits to its rows before any size is known. One
+     * poll can therefore overshoot by up to `claimBatch` rows per registered name
+     * (or one whole `batch`, whichever is larger). Lower `claimBatch`, or the batch
+     * sizes, to tighten that. A single payload larger than the entire budget still
+     * runs — alone, rather than deadlocking the worker.
+     *
+     * Costs one JSON serialization per task to measure, so it is only computed
+     * when set. Unset disables the budget.
+     */
+    maxInFlightBytes?: number;
+    /**
+     * Call ceilings that several names can draw from, by name — `{ gpu: 1 }`.
+     * A handler joins one with `task(name, { resource: "gpu" }, fn)`.
+     *
+     * `concurrency` caps a name against itself, which cannot say what usually
+     * binds a worker doing heavy local work: several *different* handlers
+     * contending for one scarce thing — a GPU, an index that tolerates a single
+     * writer. The limit belongs to that thing rather than to any one name, so it
+     * is declared here, once, and at capacity 1 it is mutual exclusion across the
+     * names that join it.
+     */
+    resources?: Record<string, number>;
     /**
      * Called for errors the worker survived — a claim that threw, a store write
      * that failed while finalizing a task. Without it these are silent: the run
@@ -36,14 +92,35 @@ export interface WorkerOptions {
         taskId?: string;
     }) => void;
 }
-/** Exponential backoff for the next attempt of a task that just failed. */
-export declare function retryDelayMs(attempt: number, baseMs: number, maxMs: number): number;
 export declare class Worker {
     private readonly store;
     private readonly queues;
     private readonly opts;
     private readonly handlers;
     private readonly workerId;
+    /** Payload bytes charged to running handlers — see maxInFlightBytes. */
+    private inFlightBytes;
+    /** Calls in flight, for the names that cap their own concurrency. */
+    private readonly callsInFlight;
+    /**
+     * Calls holding units of each declared resource. A resource is the same shape
+     * of budget as a name's own `concurrency` — a ceiling on calls — differing
+     * only in who draws from it: several names rather than one. That is what
+     * expresses "these handlers share one GPU" without inventing a queue per
+     * resource.
+     */
+    private readonly resourceCalls;
+    /** Rotates which source is offered the free budget first — see loop(). */
+    private claimCursor;
+    /** Invalidated by task(); see schedule(). */
+    private scheduleCache;
+    /**
+     * Retry backoff, resolved once. Both settlement paths read these — the
+     * worker's own `safeFail` and the TaskContext it hands a handler — so
+     * resolving the defaults per call site is how the two drift apart.
+     */
+    private readonly backoffMs;
+    private readonly backoffMaxMs;
     private stopped;
     private stopWake;
     private readonly stopped$;
@@ -63,6 +140,30 @@ export declare class Worker {
     task(handler: Handler): this;
     task(name: string, handler: Handler): this;
     task<P, R>(def: TaskDef<P, R>, handler: TypedHandler<P, R>): this;
+    /**
+     * Batch delivery: the handler takes one argument, a `TaskContext[]` of up to
+     * `batch` tasks, instead of `(ctx, payload)`. Use it when the work itself is
+     * batched — one embedding call over 256 texts rather than 256 calls — and size
+     * it by what the downstream API wants, not by the queue.
+     *
+     * `concurrency` caps the calls this name may run at once, under the worker's
+     * own. Use it to keep one expensive name from taking the whole worker.
+     *
+     * `resource` draws each call from a ceiling declared in
+     * `WorkerOptions.resources` and shared with every other name that names it —
+     * at capacity 1, mutual exclusion across those names.
+     */
+    task(name: string | TaskDef, opts: {
+        batch: number;
+        concurrency?: number;
+        resource?: string;
+    }, handler: BatchHandler): this;
+    /** Per-name concurrency or a shared resource, without batching: the handler
+     * still takes `(ctx, payload)`. */
+    task(name: string | TaskDef, opts: {
+        concurrency?: number;
+        resource?: string;
+    }, handler: Handler): this;
     stop(): void;
     /** Close the underlying store connection. Call after run() returns. */
     close(): Promise<void>;
@@ -71,6 +172,52 @@ export declare class Worker {
     run(opts?: {
         concurrency?: number;
     }): Promise<void>;
+    /**
+     * Split one claim into handler calls, each with the registration to run it.
+     *
+     * A claim is filtered by queue and by the names this worker handles, so it
+     * comes back mixed; batch size is per name (one embedding call wants 256
+     * texts, one Docling parse wants exactly 1). So group by name, then chunk each
+     * group by that name's size. Names registered without `batch` come back as
+     * one-task calls, as do names not registered at all — reachable only if a
+     * handler is unregistered mid-run, and dispatched to failNoHandler().
+     *
+     * The registration rides along because this is where it was resolved; looking
+     * it up again at the call site would put "is this name batched" in two places.
+     */
+    private deliveries;
+    private context;
+    /**
+     * How this poll's claim is split into per-name quotas, plus the union of names
+     * the probe spans.
+     *
+     * Cached and invalidated by `task()`, rather than rebuilt each poll: handlers
+     * may be registered after run() started, but only there, and this otherwise
+     * allocates a source per name on every tick for a worker's whole lifetime.
+     *
+     * A name that limits itself — by `batch`, by its own `concurrency`, or by a
+     * `resource` — needs a quota the shared draw cannot express, so it gets a
+     * source of its own; every other name shares one, where a task is a call.
+     *
+     * A resource is deliberately *not* one source spanning its names: `batch` is
+     * per name, and a single source carries one batch size, so two members that
+     * batch differently could not share a draw. Keeping a source per name and
+     * letting several of them draw down one shared ceiling composes with batching
+     * instead of excluding it.
+     */
+    private schedule;
+    /**
+     * A source's own call ceiling for one poll, or undefined when only the
+     * worker-wide budget applies.
+     *
+     * Three independent ceilings, whichever binds first: the name's own concurrency
+     * less what it is already running; its resource's capacity less what is running
+     * *and* what earlier draws in this same poll already took (`taken`); and
+     * `claimBatch`. The last is a ceiling on *rows* per poll, so it converts at this
+     * source's batch size — and never below one call, or a `claimBatch` under some
+     * name's batch would stall that name outright.
+     */
+    private sourceCalls;
     private loop;
     /** Blocking-style entry point for a standalone worker process: run until
      * SIGINT/SIGTERM, then close the store. Use this at a script's top level;
@@ -83,20 +230,98 @@ export declare class Worker {
         concurrency?: number;
     }): Promise<T>;
     /**
-     * Run one task to completion. Never rejects: a task-level failure is reported
-     * through onError and the loop moves on. (It used to reject into a promise
-     * nobody awaited — an unhandled rejection that took the process down.)
+     * Record a claimed task this worker cannot run. Reachable only if a name is
+     * unregistered mid-run — the claim filters on the registered names — so it does
+     * not start a handler or a heartbeat for a task it will not run.
+     */
+    private failNoHandler;
+    /**
+     * Run one handler call to completion — one task, or a whole batch. Never
+     * rejects: a task-level failure is reported through onError and the loop moves
+     * on. (It used to reject into a promise nobody awaited — an unhandled rejection
+     * that took the process down.)
+     *
+     * One lifecycle for both delivery modes, because a single-task handler *is* the
+     * one-element case: the same heartbeat covers the call, the same classifier
+     * reads its error, and the same rule settles what is left. Only two things vary
+     * — how the handler is invoked, and where a leftover task's result comes from —
+     * so those are the only two branches below.
+     *
+     * The contract is single: **when the handler returns, every task it did not
+     * settle itself is settled by how the call ended.** Returning succeeds them,
+     * throwing fails them (retryably, or as the thrown TaskError says). That is
+     * what keeps the ordinary cases free of bookkeeping — a handler that just
+     * returns has finished 256 tasks — while still letting it pick individual
+     * tasks off with `item.succeed()` / `item.fail()` as it goes.
+     *
+     * For a batch, a returned map of task id -> result fills in results for the
+     * tasks left over; anything else returned is ignored, and unmentioned tasks
+     * succeed with no result (the common shape, where the handler's output went to
+     * a database rather than into the task row). For a single task the return value
+     * simply is the result.
      */
-    private execute;
+    private runCall;
     /**
-     * Run one attempt, bounded by maxRunMs when set. On timeout the attempt is
-     * abandoned: the context is flagged lease-lost first (ctx.signal aborts, and
-     * a handler that keeps running can never write again — see
-     * TaskContext.owned), then the still-pending promise is left to settle on
-     * its own, its outcome discarded. The caller records the handler_timeout
-     * failure; lease recovery is NOT involved, so redelivery is immediate.
+     * How an attempt that ended badly is recorded: [envelope, retryable], or null
+     * when there is nothing to record.
+     *
+     * One classifier for both delivery modes, so a handler error cannot mean
+     * different things depending on how its task happened to be delivered. That
+     * includes LostLease, which is not an outcome at all: it means a write through
+     * this context was already rejected, so recording anything more would be
+     * rejected too. Both modes then leave the task alone — the single-task one has
+     * nothing else to do, and a batch lets its remaining tasks fall to lease expiry
+     * and redelivery rather than stamping them with a failure the handler never
+     * reported.
+     */
+    private outcomeOf;
+    /**
+     * Finalize one task the handler left for the worker to decide — the tail of
+     * both delivery modes.
+     *
+     * Includes the unserializable-result rule: the handler succeeded but its value
+     * cannot cross the JSON protocol (BigInt, non-finite number, circular), which
+     * is deterministic, so it fails permanently rather than being redelivered to
+     * fail the same way every attempt.
+     */
+    private succeedOne;
+    /**
+     * Settle every task the handler did not settle itself, concurrently, reporting
+     * rather than throwing. Each task keeps its own attempt count and backoff —
+     * they are separate tasks that happened to be delivered together.
+     *
+     * allSettled, because one task's write failing must not abandon the rest of the
+     * batch mid-settlement — the others still hold leases and would sit `running`
+     * until expiry. Each outcome is reported against the task it belongs to;
+     * without that, an operator learns a settlement failed somewhere in a batch of
+     * 256.
+     */
+    private settleEach;
+    /**
+     * Run one attempt — of one task or of a whole batch — bounded by maxRunMs when
+     * set.
+     *
+     * On timeout the attempt is abandoned: every context it covers is flagged
+     * lease-lost first (ctx.signal aborts, and a handler that keeps running can
+     * never write again, nor settle anything behind the worker's back — see
+     * TaskContext.owned), then the still-pending promise is left to settle on its
+     * own, its outcome discarded. The caller records the handler_timeout failure;
+     * lease recovery is NOT involved, so redelivery is immediate.
      */
     private attempt;
+    /**
+     * One statement per beat, however many tasks the call covers — a single-task
+     * handler is just the one-element case.
+     *
+     * Only tasks still in play are renewed. A task the handler already settled is
+     * terminal, and re-leasing it would be a write against a row nobody owns; that
+     * is also why an absence is only read as lease loss after re-checking
+     * `settled`, since the handler may have finalized the task while this beat was
+     * in flight, which takes the row out of `running` and out of the reply. A task
+     * genuinely missing lost its lease (another worker recovered it), so its
+     * context is flagged and the handler stops being able to write through it —
+     * only that one, never its neighbours.
+     */
     private startHeartbeat;
     private safeFail;
     /**