@forgezero/runtime 0.1.0 → 0.1.1

package/dist/queue.d.ts

@@ -1,243 +1,102 @@
 /**
- * A keyed work queue — parallel across keys, strictly sequential within one.
- *
- * The problem this solves is narrow and very common: most work can run in any
- * order, but some of it must not. Two credits to the same wallet, two writes to
- * the same vault entry, two deploys of the same application — each pair has to
- * happen one after the other, while everything touching a DIFFERENT wallet,
- * entry or application should run at full width.
- *
- * A global lock gives you the ordering and throws away the throughput. A plain
- * worker pool gives you the throughput and loses the ordering. The answer is to
- * partition by key: the queue is really thousands of tiny FIFOs, and a worker
- * claims a KEY rather than a message.
- *
- * ## Why claim the key, not the message
- *
- * Claiming a message and processing it is the obvious design and it does not
- * order anything: two workers can claim message 1 and message 2 of the same key
- * at the same instant and finish in either order. Claiming the KEY makes
- * ordering structural — while a worker holds `wallet:42`, nobody else can take
- * ANY message for it, so its messages can only be processed in the order they
- * were written.
- *
- * ## What this guarantees, and what it does not
- *
- * GUARANTEED   per-key FIFO order; at-least-once delivery; at most one worker
- *              per key at a time, across the whole cluster; a message that
- *              exhausts its attempts moves to a dead letter INSTEAD of blocking
- *              its key forever.
- *
- * NOT GUARANTEED   exactly-once execution. Nothing can guarantee that: a worker
- *              can complete the side effect and die before recording that it
- *              did. `dedupeKey` collapses duplicate ENQUEUES, and the lease
- *              stops concurrent delivery, but a crash between "money moved" and
- *              "message acknowledged" will redeliver.
- *
- * ## So for money, read this
- *
- * The queue is not what makes a financial operation safe — the HANDLER is. Make
- * the effect idempotent at the point of effect: a ledger posting keyed on the
- * message id and refused by a unique index, or a transfer keyed on an
- * idempotency key the payment provider also honours. Then redelivery is free
- * and the queue only has to provide ordering and durability, which it does.
- *
- * Anything that relies on "the queue delivered it once" is relying on something
- * no queue provides, including this one, including the expensive ones.
+ * Ordered work: sequential within a key, parallel across keys.
+ *
+ * That sentence is the whole contract, and the previous version buried it under
+ * a persistence framework — `QueueStore`, leases, standalone/cluster modes and
+ * an unfinished cluster adapter — that nothing in production ever used. The
+ * framework was also wrong on its own terms: a message left `leased` after its
+ * lease expired became invisible to both the claim and ready reads, so a stale
+ * lease made work unrunnable rather than runnable again.
+ *
+ * Worse for the property that matters, retry backoff did not hold the key. A
+ * task waiting to retry was skipped and a LATER task for the same key ran
+ * first, which is precisely the ordering this module exists to guarantee.
+ *
+ * So persistence is gone. The layer that knows what a pending business request
+ * means is the runtime that issued it — ForgeZero's own durability record is an
+ * Arango row written in the same transaction as the change it describes, and
+ * the outbox drains through here rather than reimplementing ordering.
+ *
+ * ## What it does guarantee
+ *
+ * - Tasks for one key run one at a time, in submission order, INCLUDING across
+ *   a retry: a task that is waiting to try again blocks its key.
+ * - Different keys run concurrently, up to `width`.
+ * - `run()` returns the handler's own value, typed, so a caller can await work
+ *   instead of polling for it.
+ * - `stop()` awaits what is running and what is queued, with a deadline, and
+ *   reports what it managed to finish.
  */
-export interface Clock {
-    now(): number;
+export interface QueueTask<T> {
+    /** Resolves with the handler's value, or rejects with its final error. */
+    readonly result: Promise<T>;
+    /** Stable id, so a caller can cancel or look up this task. */
+    readonly id: string;
+    readonly key: string;
 }
-export declare const systemClock: Clock;
-/** `30s` → 30000. Throws rather than guessing — a wrong window is silent. */
-export declare function durationMs(value: string | number): number;
-export type MessageStatus = 'ready' | 'leased' | 'done' | 'dead';
-export interface Message<Body = unknown> {
-    id: string;
-    /** The partition. Everything sharing it runs in order, one at a time. */
-    key: string;
-    body: Body;
-    /** Monotonic per queue. Decides order within a key. */
-    sequence: number;
-    status: MessageStatus;
+export interface RetryPolicy {
+    /** How many ATTEMPTS in total, including the first. */
     attempts: number;
-    /** Earliest time this may be delivered. Set by a retry backoff. */
-    availableAtMs: number;
-    /** Collapses repeat enqueues within a window. See `enqueue`. */
-    dedupeKey?: string;
-    lastError?: string;
-    enqueuedAtMs: number;
-    completedAtMs?: number;
+    /** Milliseconds before attempt n+1. Called with the 1-based attempt made. */
+    backoffMs: (attempt: number) => number;
 }
-export interface KeyLease {
-    key: string;
-    /** Rises every time the key is granted. A stale holder cannot write. */
-    fence: number;
-    untilMs: number;
-    owner: string;
+export interface QueueOptions {
+    /** How many keys may run at once. Ordering within a key is unaffected. */
+    width?: number;
+    retry?: Partial<RetryPolicy>;
+    /** Injected so tests need no timers and no wall clock. */
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
 }
-/**
- * Where the queue lives. Memory for tests, a database for a cluster.
- *
- * `claimKey` MUST be atomic. A read-then-write implementation hands the same key
- * to two workers under exactly the load that makes ordering matter, and the bug
- * looks like "the queue occasionally processes out of order" — which is the
- * hardest possible thing to reproduce.
- */
-export interface QueueStore<Body = unknown> {
-    /** Which deployment shape this store can serve. See `MODES`. */
-    readonly mode: QueueMode;
-    append(queue: string, message: Message<Body>): Promise<void>;
-    /** Existing message with this dedupe key, if the window has not passed. */
-    findByDedupe(queue: string, dedupeKey: string, sinceMs: number): Promise<Message<Body> | null>;
-    /**
-     * Take the next key that has ready work and is not leased. Atomic.
-     * `exclude` skips keys this worker already holds.
-     */
-    claimKey(queue: string, owner: string, ttlMs: number, nowMs: number): Promise<KeyLease | null>;
-    renewKey(queue: string, lease: KeyLease, ttlMs: number, nowMs: number): Promise<boolean>;
-    releaseKey(queue: string, lease: KeyLease): Promise<void>;
-    /** Ready messages for one key, in sequence order. */
-    readKey(queue: string, key: string, nowMs: number, limit: number): Promise<Message<Body>[]>;
-    update(queue: string, id: string, patch: Partial<Message<Body>>): Promise<void>;
-    stats(queue: string): Promise<QueueStats>;
-    /** Dead-lettered messages, newest first. */
-    dead(queue: string, limit: number): Promise<Message<Body>[]>;
-}
-export interface QueueStats {
-    ready: number;
-    leased: number;
-    dead: number;
-    keys: number;
+export interface DrainReport {
+    completed: number;
+    failed: number;
+    /** Still queued or running when the deadline passed. */
+    abandoned: number;
+    timedOut: boolean;
 }
-/**
- * Standalone and cluster are the same queue with a different store.
- *
- *   standalone  one process, state in memory. No coordination, nothing to
- *               install, and the ordering guarantee still holds — because a
- *               single process claiming its own keys cannot race itself.
- *               Everything is lost on restart, which is correct for a
- *               development machine and wrong for anything holding money.
- *
- *   cluster     several processes over shared storage. The guarantee is the
- *               same and the requirement is stricter: `claimKey` must be
- *               ATOMIC. A read-then-write implementation hands one key to two
- *               workers under exactly the load that makes ordering matter, and
- *               the bug presents as "the queue occasionally processes out of
- *               order" — the hardest possible thing to reproduce.
- *
- * The distinction is declared on the store rather than inferred, so a
- * deployment can refuse to start when a durable queue was expected and a memory
- * one was wired in. That mistake is otherwise invisible until a restart.
- */
-export declare const MODES: readonly ["standalone", "cluster"];
-export type QueueMode = (typeof MODES)[number];
-/**
- * Single process. Correct for tests and for one instance, and honest about
- * being no more — nothing here coordinates across processes.
- */
-export declare function memoryStore<Body = unknown>(clock?: Clock): QueueStore<Body>;
-export interface Handler<Body> {
-    (message: Message<Body>, context: HandlerContext): Promise<void>;
+export declare class QueueStoppedError extends Error {
+    constructor();
 }
-export interface HandlerContext {
-    /** Still ours? False means the lease expired and nothing further may be written. */
-    holdsKey(): Promise<boolean>;
-    log(message: string): void;
-    attempt: number;
+export declare class TaskCancelledError extends Error {
+    constructor();
 }
-export interface QueueOptions<Body> {
-    name: string;
-    store: QueueStore<Body>;
-    handler: Handler<Body>;
-    /** How many KEYS one worker processes at once. Not messages — see the note. */
-    concurrency?: number;
-    /** How long a key lease lasts. Renewed between messages. */
-    leaseMs?: number;
-    /** Attempts before a message is dead-lettered. */
-    maxAttempts?: number;
-    /** Backoff between attempts. Doubles, capped. */
-    backoffMs?: number;
-    maxBackoffMs?: number;
-    /** Repeat enqueues with the same `dedupeKey` inside this window collapse. */
-    dedupeWindowMs?: number;
-    /** Messages taken per key per turn, so one hot key cannot hold a slot forever. */
-    batch?: number;
-    clock?: Clock;
-    owner?: string;
-    onError?: (message: Message<Body>, error: unknown) => void;
+export declare function createQueue(options?: QueueOptions): {
     /**
-     * Refuse to start unless the store is durable.
+     * Submit work and await its value.
      *
-     * Set it wherever losing queued work on a restart would be a real loss.
-     * Without it, wiring the memory store into a cluster is a mistake nothing
-     * reports until the first restart, by which point the work is gone.
+     * The handler's return type flows through, so a caller gets a result
+     * rather than an id to poll — the previous `enqueue` returned only
+     * `{ id, duplicate }` and had nowhere to put an answer.
      */
-    require?: QueueMode;
-}
-export interface EnqueueResult {
-    id: string;
-    /** True when an identical `dedupeKey` was already queued and this was dropped. */
-    duplicate: boolean;
-}
-export declare function createQueue<Body = unknown>(options: QueueOptions<Body>): {
-    enqueue: (args: {
-        key: string;
-        body: Body;
-        dedupeKey?: string;
-        delayMs?: number;
-    }) => Promise<EnqueueResult>;
-    tick: () => Promise<number>;
-    /** Drain until nothing is ready. For tests and for a one-shot worker. */
-    drain(maxPasses?: number): Promise<void>;
-    /** Poll forever. `stop()` lets in-flight keys finish. */
-    start(intervalMs?: number): void;
-    stop(): void;
-    mode: "standalone" | "cluster";
-    stats: () => Promise<QueueStats>;
-    dead: (limit?: number) => Promise<Message<Body>[]>;
-    /** Put a dead message back at the front of its key. An operator decision. */
-    revive(id: string): Promise<void>;
-};
-export type Queue<Body = unknown> = ReturnType<typeof createQueue<Body>>;
-export declare const VERSION = "0.1.0";
-/**
- * The four operations a shared database has to provide, and the one that is
- * hard.
- *
- * Everything except `claimKey` is an ordinary read or write. `claimKey` has to
- * find a key with ready work, check that nobody holds it, and take it — as ONE
- * atomic step. Split into a read and a write, two workers pass the check
- * together and both proceed, and the queue silently stops ordering anything.
- *
- * Written as a small adapter rather than a driver so the same queue runs over
- * ArangoDB, Postgres or Redis, and so this package keeps no dependency.
- */
-export interface ClusterAdapter<Body = unknown> {
-    insert(queue: string, message: Message<Body>): Promise<void>;
-    findDuplicate(queue: string, dedupeKey: string, sinceMs: number): Promise<Message<Body> | null>;
+    run<T>(key: string, handler: () => Promise<T> | T): QueueTask<T>;
+    /** Remove a task that has not started. Running work is left alone. */
+    cancel(id: string): boolean;
+    /** Hold one key. Work already running for it finishes. */
+    pauseKey(key: string): void;
+    resumeKey(key: string): void;
+    /** Hold everything. New submissions are accepted and wait. */
+    pause(): void;
+    resume(): void;
+    /** How much is outstanding, for a health endpoint or a drain decision. */
+    snapshot(): {
+        running: number;
+        queued: number;
+        keys: number;
+        paused: boolean;
+        pausedKeys: string[];
+        completed: number;
+        failed: number;
+    };
+    /** Resolve when nothing is running and nothing is queued. */
+    whenIdle(): Promise<void>;
     /**
-     * ATOMIC. Must return a key that has ready work and no live lease, marking it
-     * leased in the same operation. Returning null means there is nothing to do.
+     * Stop accepting work and await what is left, with a deadline.
+     *
+     * `stop()` used to flip a boolean and return `void`, which is not a
+     * shutdown — a process could exit with work in flight and report success.
+     * This reports what it actually managed.
      */
-    takeKey(args: {
-        queue: string;
-        owner: string;
-        untilMs: number;
-        nowMs: number;
-    }): Promise<KeyLease | null>;
-    extendKey(queue: string, key: string, fence: number, untilMs: number): Promise<boolean>;
-    dropKey(queue: string, key: string, fence: number): Promise<void>;
-    readReady(queue: string, key: string, nowMs: number, limit: number): Promise<Message<Body>[]>;
-    patch(queue: string, id: string, patch: Partial<Message<Body>>): Promise<void>;
-    counts(queue: string): Promise<QueueStats>;
-    deadLetter(queue: string, limit: number): Promise<Message<Body>[]>;
-}
-/**
- * A durable store over any shared database.
- *
- * Declares `mode: 'cluster'`, which is what lets a deployment refuse to start if
- * somebody wires the memory store into production by mistake — a mistake that
- * is otherwise invisible until the first restart takes the queue with it.
- */
-export declare function clusterStore<Body = unknown>(adapter: ClusterAdapter<Body>): QueueStore<Body>;
+    stop(deadlineMs?: number): Promise<DrainReport>;
+};
+export type Queue = ReturnType<typeof createQueue>;