@apisurf/ngn-core 0.2.7 → 0.2.8

package/dist/core.d.ts

@@ -1,6 +1,7 @@
 import { FsNodeFileDescriptor } from '@apisurf/ngn-os';
-import { Client, InArgs, ResultSet, InStatement } from '@apisurf/ngn-persistence';
+import { Client, InArgs, ResultSet, InStatement, InValue } from '@apisurf/ngn-persistence';
 export { initDbFileIfNotExists } from '@apisurf/ngn-persistence';
+import { Cron } from 'croner';
 
 type CompilerOptions = {
     /** Minify output */
@@ -120,6 +121,349 @@ interface TaskSqlite {
  */
 declare function closeTaskDatabases(): void;
 
+/**
+ * A length of time as tasks write it: milliseconds, or a string such as
+ * `"500ms"`, `"30s"`, `"4m"`, `"2h"` or `"1d"`.
+ */
+type Duration = number | `${number}${"ms" | "s" | "m" | "h" | "d"}`;
+
+/**
+ * Named leases in `locks`.
+ *
+ * Taking one is a single upsert that only overwrites a row whose lease has
+ * run out, so two processes on one file cannot both win, and a lease left by
+ * a process that died is free once it expires. Every acquisition gets its own
+ * holder token: two runs of one task in one process are two holders.
+ */
+declare class LockService {
+    private db;
+    constructor(db: Client);
+    /** The holder token on success, null when someone else holds an unexpired lease. */
+    tryAcquire(name: string, ttlMs: number, taskRunId: number | null): Promise<string | null>;
+    /** Push the lease out; false when it was lost (it expired and someone took it). */
+    renew(name: string, holder: string, ttlMs: number): Promise<boolean>;
+    release(name: string, holder: string): Promise<void>;
+}
+
+interface LockOptions {
+    /**
+     * How long the lease lasts if this process stops renewing it (it dies, or
+     * the event loop is stuck). Renewed while held. Default one minute.
+     */
+    ttl?: Duration;
+    /**
+     * How long to wait for a lock someone else holds: `true` (default) waits
+     * until the run's deadline, or for as long as it takes when there is none;
+     * `false` gives up at once; a duration waits that long.
+     */
+    wait?: boolean | Duration;
+}
+/**
+ * Thrown by `ctx.lock` when the lock could not be had in time. Tasks can tell
+ * it apart by `name`, which survives a second copy of ngn in node_modules where
+ * `instanceof` would not.
+ */
+declare class LockBusyError extends Error {
+    readonly lockName: string;
+    name: string;
+    constructor(lockName: string);
+}
+interface Held {
+    release(): Promise<void>;
+}
+/** The locks one run takes, all recorded against its `task_runs` row. */
+declare function createRunLocks(service: LockService, taskRunId: number): {
+    /** `ctx.lock`: run `fn` holding `name`, released however `fn` ends. */
+    lock<T>(name: string, fn: () => Promise<T> | T, options: LockOptions, deadline: number | null): Promise<T>;
+    /**
+     * Take every lock in `names` without waiting, for `exclusive`. Names are
+     * taken in sorted order so two runs asking for overlapping sets cannot
+     * each hold half. If any is busy, the ones already taken are given back.
+     */
+    holdAll(names: readonly string[]): Promise<{
+        busy: string;
+    } | Held>;
+};
+type RunLocks = ReturnType<typeof createRunLocks>;
+
+/** Where a job is in its life. `dead` and `done` are final until `reopen`. */
+type JobStatus = "ready" | "leased" | "done" | "dead" | "parked";
+
+interface WorkerHandle<W> {
+    /** Which worker this is, from 0. */
+    index: number;
+    /** What `worker.setup` returned for this worker, e.g. a browser tab. */
+    resource: W;
+    /** The `until` signal: aborts when the run should stop taking on work. */
+    signal: AbortSignal;
+    /**
+     * Hand this job back unworked instead of completing it, by default without
+     * spending its attempt.
+     */
+    release(options?: {
+        delay?: Duration;
+        refund?: boolean;
+    }): void;
+    /**
+     * Stop this job's group for the rest of the call: this job and any of the
+     * group's jobs already claimed are handed back, and no more are claimed.
+     * For a site that answered with a bot wall, where every other page would
+     * get the same answer.
+     */
+    stopGroup(options?: {
+        delay?: Duration;
+        refund?: boolean;
+    }): void;
+}
+interface WorkOptions<W> {
+    /** Jobs worked at once. Default 1. */
+    concurrency?: number;
+    /** Most jobs this call takes. Default no limit. */
+    max?: number;
+    /**
+     * Most jobs one group contributes to this call, or a function giving each
+     * group its own cap (one site is slower, or touchier, than another). A cap of
+     * 0 leaves the group alone. Default no limit.
+     */
+    perGroup?: number | ((group: string) => number);
+    /**
+     * When to stop taking on work: a signal, or an epoch-ms time. Jobs already
+     * started are finished. Default `ctx.run.signal`.
+     */
+    until?: AbortSignal | number;
+    /** Per-worker resources, made when a worker takes its first job. */
+    worker?: {
+        setup?: (index: number) => Promise<W> | W;
+        teardown?: (resource: W, index: number) => Promise<void> | void;
+    };
+}
+type WorkHandler<T, W> = (job: Job<T>, worker: WorkerHandle<W>) => Promise<unknown> | unknown;
+interface WorkSummary {
+    done: number;
+    /** Attempts that failed, the ones that left their job dead included. */
+    failed: number;
+    /** Of those, how many jobs had no attempts left. */
+    dead: number;
+    /** Claimed and handed back unworked. */
+    released: number;
+    /** Jobs due that this call left for the next one. */
+    remaining: number;
+    /** How long the oldest ready job has waited, or null when there is none. */
+    oldestAgeMs: number | null;
+    /** Groups stopped with `stopGroup`. */
+    stoppedGroups: string[];
+    /** Why the call ended. */
+    stoppedBy: "empty" | "deadline" | "max";
+}
+
+/** What a queue knows about the run that opened it. */
+interface QueueRunContext {
+    /** The task's next tick, for `"next-tick"` backoff. */
+    nextAt: number | null;
+    /** The run's deadline signal, `work()`'s default `until`. */
+    signal?: AbortSignal;
+}
+/**
+ * When a failed job may be tried again:
+ *
+ * - `"next-tick"` (default): not before the task's next scheduled run, so a
+ *   retry never competes with the run that is failing. Without a schedule it
+ *   is straight away.
+ * - a duration: that long after the failure.
+ * - `{ base, max }`: `base`, doubling with each attempt, never above `max`.
+ */
+type Backoff = "next-tick" | Duration | {
+    base: Duration;
+    max?: Duration;
+};
+interface QueueOptions {
+    /**
+     * The database the queue lives in: any `ctx.sqlite.initDB(...)` instance,
+     * or `ctx.sqlite` itself (the default). Keeping it next to your own tables is
+     * what lets `addStatement` go in the same batch as the row a job is about.
+     */
+    db?: {
+        client: Client;
+    };
+    /** Attempts a job gets before it is `dead`. Default 3. */
+    maxAttempts?: number;
+    backoff?: Backoff;
+    /** How long a claim lasts before the job is claimable again. Default 10 minutes. */
+    lease?: Duration;
+}
+interface AddJob<T> {
+    /** De-duplicates: a key already in this queue, in any status, is not added again. */
+    key?: string;
+    /** Groups are served fairly and never two at once by `work()`; e.g. a host. */
+    group?: string;
+    payload?: T;
+    /** Higher first, within a group. Default 0. */
+    priority?: number;
+    /** Not before this long from now. */
+    delay?: Duration;
+    /** Overrides the queue's `maxAttempts` for this job. */
+    maxAttempts?: number;
+}
+interface Job<T> {
+    id: number;
+    key: string | null;
+    group: string | null;
+    payload: T;
+    priority: number;
+    /** Attempts so far, this one included. */
+    attempts: number;
+    maxAttempts: number;
+    /** The error the previous attempt failed with. */
+    lastError: string | null;
+    createdAt: number;
+}
+interface ClaimOptions {
+    limit: number;
+    /** At most this many jobs per group. */
+    perGroup?: number;
+    /** Leave these groups' jobs where they are. */
+    skipGroups?: readonly string[];
+    /** Leave these jobs where they are, e.g. ones this run already tried. */
+    skipIds?: readonly number[];
+}
+/** Which jobs `park`, `reopen` and `prune` act on. Fields combine with AND. */
+interface JobFilter {
+    group?: string | readonly string[];
+    /** Every group except these. Jobs with no group match. */
+    groupNotIn?: readonly string[];
+    key?: string | readonly string[];
+}
+interface QueueStats {
+    ready: number;
+    /** Ready jobs whose `run_after` has passed: what a claim could take now. */
+    due: number;
+    leased: number;
+    done: number;
+    dead: number;
+    parked: number;
+    /** How long the oldest ready job has waited since it was added, or null. */
+    oldestReadyAgeMs: number | null;
+}
+/**
+ * A named queue over `_ngn_jobs` in one database.
+ *
+ * Every state change is a single statement guarded by what the caller saw, so
+ * two runs (or two processes) working one queue cannot both take a job, and a
+ * run whose lease ran out cannot settle a job someone else has since claimed.
+ */
+declare class Queue<T = unknown> {
+    private readonly client;
+    readonly name: string;
+    private readonly options;
+    private readonly run;
+    private readonly maxAttempts;
+    private readonly leaseMs;
+    constructor(client: Client, name: string, options: QueueOptions, run: QueueRunContext);
+    /**
+     * The INSERT for one job, to run in your own `batch` beside the row the job
+     * is about. A key already in the queue makes it a no-op.
+     */
+    addStatement(job: AddJob<T>): {
+        sql: string;
+        args: InValue[];
+    };
+    /** Add one job or several. Returns how many were new; the rest had keys already queued. */
+    add(jobs: AddJob<T> | readonly AddJob<T>[]): Promise<number>;
+    /**
+     * Take up to `limit` jobs that are due, counting an attempt on each and
+     * leasing them for the queue's `lease`.
+     *
+     * With groups, the jobs are drawn a group at a time: every group's first job
+     * before any group's second, groups in a fresh random order each claim. So
+     * a claim spreads over as many groups as it can, and when `limit` cuts a
+     * round short it is not always the same groups left out.
+     */
+    claim({ limit, perGroup, skipGroups, skipIds }: ClaimOptions): Promise<Job<T>[]>;
+    /**
+     * Jobs whose lease ran out on their last attempt: no claim will take them
+     * again, so they are marked `dead` rather than left looking leased forever.
+     */
+    private retireStatement;
+    /**
+     * Settle a claimed job, if the claim is still ours: same job, same attempt,
+     * still leased. False when the lease expired and the job moved on.
+     */
+    private settle;
+    /** The job is finished. */
+    complete(job: Job<T>): Promise<boolean>;
+    /**
+     * The attempt failed. The job backs off and is tried again, or is `dead`
+     * once it has had all its attempts. `delay` overrides the backoff.
+     */
+    fail(job: Job<T>, error: unknown, { delay }?: {
+        delay?: Duration;
+    }): Promise<boolean>;
+    /**
+     * Hand a claimed job back unworked. By default the attempt is refunded: for
+     * a job that never got a fair try, such as a site that walled the run.
+     */
+    release(job: Job<T>, { delay, refund }?: {
+        delay?: Duration;
+        refund?: boolean;
+    }): Promise<boolean>;
+    /** How long a job that just failed its `attempts`th attempt waits. */
+    private backoffMs;
+    /**
+     * Set ready jobs aside, e.g. ones no handler can read yet. Parked jobs are
+     * never claimed until `reopen`. Returns how many were parked.
+     */
+    park(filter: JobFilter, reason?: string): Promise<number>;
+    /**
+     * Make jobs ready again with their attempts reset: parked ones by default,
+     * or any of `from`, e.g. `["dead"]` to retry what gave up.
+     */
+    reopen(filter?: JobFilter, { from }?: {
+        from?: readonly Exclude<JobStatus, "leased" | "ready">[];
+    }): Promise<number>;
+    /**
+     * Delete finished jobs last touched more than `olderThan` ago, `done` ones by
+     * default. A pruned key can be added again.
+     */
+    prune({ olderThan, status, }: {
+        olderThan: Duration;
+        status?: readonly Exclude<JobStatus, "leased" | "ready">[];
+    }): Promise<number>;
+    /**
+     * Work through the queue until it is empty, `max` is reached or the run's
+     * deadline passes, `concurrency` jobs at a time and never two of one group
+     * at once. A handler that returns completes its job; one that throws fails
+     * it. Whatever is left waits for the next run.
+     */
+    work<W = undefined>(handler: WorkHandler<T, NoInfer<W>>, options?: WorkOptions<W>): Promise<WorkSummary>;
+    /** The job with `key`, in whatever state it is in. */
+    get(key: string): Promise<(Job<T> & {
+        status: JobStatus;
+    }) | null>;
+    stats(): Promise<QueueStats>;
+}
+
+/**
+ * The run this context belongs to, and how long it has. Times are epoch
+ * milliseconds, as everywhere in ngn's database.
+ */
+interface TaskRun {
+    /** This run's `task_runs.id`. */
+    id: number;
+    /** When the tick that started it fired; null for a run with no schedule. */
+    scheduledAt: number | null;
+    /** When the next tick is due; null for a run with no schedule. */
+    nextAt: number | null;
+    /**
+     * When to stop starting new work: shortly before `nextAt`, or sooner with a
+     * `budget` export. Null when neither applies.
+     */
+    deadline: number | null;
+    /**
+     * Aborts at `deadline`. It is a request: ngn does not stop a run that keeps
+     * going past it.
+     */
+    signal: AbortSignal;
+}
 type LiveSourceParams = {
     livePath: `live:${string}`;
     code: string;
@@ -154,12 +498,30 @@ interface TaskContext {
     timing: {
         start(label: string): () => Promise<void>;
     };
+    run: TaskRun;
+    /**
+     * Run `fn` holding the named lock, shared with every task and process using
+     * the same ngn database. Waits for it by default; throws a `LockBusyError`
+     * when it cannot be had in time.
+     */
+    lock<T>(name: string, fn: () => Promise<T> | T, options?: LockOptions): Promise<T>;
+    /**
+     * Open a named job queue, by default in this task's own database. Any task
+     * that opens the same name on the same database shares it.
+     */
+    queue<T = unknown>(name: string, options?: QueueOptions): Promise<Queue<T>>;
     /**
      * SQLite scoped to the folder this task file lives in. Always present — no
      * configuration required.
      */
     sqlite: TaskSqlite;
 }
+/**
+ * What a scheduled tick does when the task's previous run is still going:
+ * `"skip"` records the tick as a skipped run, `"allow"` starts another run
+ * beside it.
+ */
+type OverlapPolicy = "skip" | "allow";
 
 interface CompiledTaskCallbacks {
     onTaskLoadComplete?: ({ paths, md5Hash, compiledCode, }: {
@@ -175,7 +537,6 @@ interface CompiledTaskCallbacks {
         fileTaskId: number;
         fileTaskVersionId: number;
     }>;
-    onTaskExecutionStart?: () => Promise<void>;
     onTaskCodeLoaded?: () => Promise<void>;
     onTaskExportsLoaded?: () => Promise<void>;
 }
@@ -183,45 +544,81 @@ interface TaskRuntimeCallbacks {
     onNotFound?: (meta: {
         path: string;
     }) => Promise<void>;
+    /** `reason` is set when ngn skipped the run, rather than the task's `shouldSkip`. */
     onSkip?: (meta: {
         path: string;
+        reason?: string;
     }) => Promise<void>;
     onStart?: (meta: {
         path: string;
     }) => Promise<void>;
     onSuccess?: (meta: {
         path: string;
+        result?: unknown;
     }) => Promise<void>;
     onFailure?: (meta: {
         path: string;
     }) => Promise<void>;
 }
+/**
+ * One run's bookkeeping: its row in `task_runs`, and everything that writes
+ * against that row. Made fresh for every execution, so two runs of one task
+ * that overlap never write to each other's row.
+ */
+interface RunControls {
+    id: number;
+    log: TaskContext["log"];
+    timing: TaskContext["timing"];
+    locks: RunLocks;
+    callbacks: TaskRuntimeCallbacks;
+}
 type BuildCompiledTaskConfigFn = ({ sourcePath, compiledPath, }: {
     sourcePath: string;
     compiledPath: string;
-}) => {
+}) => TaskConfig;
+/** Everything one task file gets from ngn, built once per `Task`. */
+type TaskConfig = {
     compiledPath: string;
     sourcePath: string;
     taskCallbacks: CompiledTaskCallbacks;
-    runtimeCallbacks: TaskRuntimeCallbacks;
+    /**
+     * Open a run: insert its `task_runs` row and hand back what writes to it.
+     * `retryOf` is the first run of the tick a retry belongs to.
+     */
+    startRun: (options?: {
+        retryOf?: number | null;
+    }) => Promise<RunControls>;
+    /** The task's run history, for the circuit breaker. */
+    history: {
+        recentTickOutcomes(limit: number): Promise<Array<{
+            id: number;
+            outcome: "success" | "failure";
+        }>>;
+        countSkipsSince(reason: string, afterId: number): Promise<number>;
+    };
     env: TaskContext["env"];
     kv: TaskContext["kv"];
-    log: TaskContext["log"];
-    timing: TaskContext["timing"];
     sqlite: TaskContext["sqlite"];
 };
 
+interface ExecuteSchedule {
+    /** When the tick fired, epoch ms. */
+    scheduledAt?: number | null;
+    /** When the next tick is due, epoch ms. */
+    nextAt?: number | null;
+}
 declare class Task {
     private taskCallbacks;
-    private runtimeCallbacks;
+    private startRun;
+    private history;
     private env;
     private kv;
-    private log;
-    private timing;
     private sqlite;
     private meta;
     private entry;
     private entryExports;
+    /** Executions started and not yet settled. */
+    private inFlight;
     constructor({ entryParams, buildConfigFn, }: {
         entryParams: EntryParams;
         buildConfigFn: BuildCompiledTaskConfigFn;
@@ -234,12 +631,56 @@ declare class Task {
     get taskPath(): string;
     get codeHash(): string | null;
     get timingPattern(): string | undefined;
+    /**
+     * The task's `overlap` export, `"skip"` when it has none. Throws on anything
+     * else, naming the task, so a typo fails at schedule time.
+     */
+    get overlapPolicy(): OverlapPolicy;
+    /**
+     * Check the exports that shape how the task is scheduled, so a bad value
+     * fails when the task is scheduled rather than on its first tick.
+     */
+    validateExports(): void;
+    /** Whether an execution of this task is in progress. */
+    get isRunning(): boolean;
+    /**
+     * Record a run that ngn decided not to start, without loading or calling any
+     * of the task's code. Needs the task to have been registered by an earlier
+     * execution, which is always so for a run skipped because one is in progress.
+     */
+    skip(reason: string): Promise<void>;
     hasTaskExport(): boolean;
     hasTimingExport(): boolean;
     loadEntry(): Promise<void>;
     private loadAndRegister;
     private runTask;
-    execute(): Promise<void>;
+    /**
+     * Run the task for one tick, retrying as its `retry` export allows. A
+     * scheduled tick passes when it fired and when the next one is due, which
+     * `ctx.run.deadline` and the retry window are worked out from.
+     */
+    execute(schedule?: ExecuteSchedule): Promise<void>;
+    private executeWithRetries;
+    /**
+     * Retry only a run that got as far as running: a module that will not load
+     * fails the same way every time. Then it has to fit before the next tick,
+     * and the task's `shouldRetry` gets the last word.
+     */
+    private shouldRetry;
+    /**
+     * Whether the breaker holds this tick back: after `after` failed ticks in a
+     * row it skips 1, 2, 4… ticks (counted since the latest failure), letting
+     * one through in between to see whether things have recovered.
+     */
+    private breakerOpen;
+    /**
+     * Why ngn will not start this run, or null. Checked in order: the breaker
+     * (scheduled first attempts only), then the `exclusive` locks, which are
+     * left held on success.
+     */
+    private holdBack;
+    private buildContext;
+    private executeOnce;
 }
 
 declare class TaskLibrary {
@@ -283,6 +724,13 @@ declare class TaskOnceRunner {
     run(): Promise<void>;
 }
 
+declare function isCronPatternValid(pattern: string): boolean;
+/**
+ * Schedule a loaded task on `pattern`. The task's exports are checked here, so
+ * a bad `overlap` or `budget` fails now rather than on the first tick.
+ */
+declare function scheduleTask(task: Task, pattern: string, onError: (error: unknown) => void): Cron<undefined>;
+
 declare function setupDbClient(dbPath: string): Promise<Client>;
 declare function getDbClient(): Client;
 
@@ -291,4 +739,4 @@ declare function createControlsGenerator({ dbClient, env, }: {
     env: TaskContext["env"];
 }): BuildCompiledTaskConfigFn;
 
-export { Compiler, type DBInstance, type InitDBOptions, type Migration, Task, type TaskContext, TaskLibrary, TaskLibraryScheduler, TaskOnceRunner, type TaskSqlite, closeTaskDatabases, createControlsGenerator, executeEsm, getDbClient, setupDbClient };
+export { type AddJob, type Backoff, type ClaimOptions, Compiler, type DBInstance, type Duration, type InitDBOptions, type Job, type JobFilter, type JobStatus, LockBusyError, type LockOptions, type Migration, type OverlapPolicy, Queue, type QueueOptions, type QueueStats, Task, type TaskContext, TaskLibrary, TaskLibraryScheduler, TaskOnceRunner, type TaskRun, type TaskSqlite, type WorkHandler, type WorkOptions, type WorkSummary, type WorkerHandle, closeTaskDatabases, createControlsGenerator, executeEsm, getDbClient, isCronPatternValid, scheduleTask, setupDbClient };