cairnq 0.5.0 → 0.7.0

package/src/store/base.ts

@@ -6,7 +6,7 @@ import {
   ProtocolVersionMismatch,
   SerializationError,
 } from "../errors.js";
-import { rowToTask, STATUSES, type Task, type TaskStatus } from "../models.js";
+import { rowToTask, STATUSES, TERMINAL, type Task, type TaskStatus } from "../models.js";
 import { type BackpressureOptions, QueueDepthGate } from "../backpressure.js";
 
 const rejectMangled = function (this: unknown, _key: string, v: unknown): unknown {
@@ -62,9 +62,25 @@ export function checkProtocolVersion(version: number): void {
 // CONFLICTS is the canonical declaration; the type derives from it so the
 // runtime guard in submit() and the type can't drift apart (same pattern as
 // STATUSES/TaskStatus in models.ts).
-const CONFLICTS = ["reuse", "reject", "replace"] as const;
+const CONFLICTS = ["reuse", "reuse-succeeded", "reject", "replace"] as const;
 export type Conflict = (typeof CONFLICTS)[number];
 
+/**
+ * Whether a keyed submit's strategy accepts the task the key already points at.
+ *
+ * Both reuse strategies deduplicate work that is still in play — that is what a
+ * key is for, and the answer cannot depend on the outcome of a task that has no
+ * outcome yet. They differ only on what a *finished* task means: `reuse` treats
+ * the key as free again, while `reuse-succeeded` reads a succeeded task as a
+ * cached result. Neither ever hands back a failed or canceled one, which would
+ * poison the key for every later submit (see PROTOCOL.md "Key conflict").
+ */
+function reusable(conflict: Conflict, status: TaskStatus): boolean {
+  if (conflict === "replace") return false;
+  if (!TERMINAL.includes(status)) return true;
+  return conflict === "reuse-succeeded" && status === "succeeded";
+}
+
 /** The queue a submit lands on when it names none. Owned here, where the
  * default is applied, so nothing above has to re-derive it. */
 export const DEFAULT_QUEUE = "default";
@@ -283,10 +299,15 @@ export abstract class TaskStore {
         // free after all, whatever the strategy.
         const current = (await fetch("get", { id: existing[0].task_id }))[0];
         if (current) {
-          if (conflict === "reuse") return rowToTask(current);
           if (conflict === "reject") throw new AlreadyExists(key);
-          // "replace": cancel the recorded task, then repoint the key below.
-          await fetch("cancel", { id: existing[0].task_id });
+          if (reusable(conflict, current.status as TaskStatus)) return rowToTask(current);
+          // The strategy declined the recorded task, so the key repoints to the
+          // fresh one inserted below. Cancel only what is still live: a terminal
+          // task has nothing to stop, and cancelling it would rewrite a settled
+          // row (and hand a `canceled` back to whoever is waiting on it).
+          if (!TERMINAL.includes(current.status as TaskStatus)) {
+            await fetch("cancel", { id: existing[0].task_id });
+          }
         }
       }
       const row = (await fetch("insert_task", ins))[0];
@@ -425,26 +446,82 @@ export abstract class TaskStore {
     limit?: number;
     names?: string[];
   }): Promise<Task[]> {
-    // One queue is the common case and gets its own statement: a list-valued queue
-    // filter cannot be read in claim order, so the planner sorts every claimable
-    // row to take LIMIT of them, and claim's cost grows with the queued backlog
-    // while it holds the claim transaction. See claim_one_queue.sql.
+    const names = input.names ?? null;
+    const claimed = await this.claimSession(
+      { queues: input.queues, workerId: input.workerId, leaseMs: input.leaseMs, names },
+      (claim) => claim(names, input.limit ?? 1),
+    );
+    return claimed ?? [];
+  }
+
+  /**
+   * Open one claim transaction and let the caller draw from it repeatedly.
+   *
+   * The transaction is what has to live here: the read-only probe that keeps an
+   * idle worker off SQLite's single write lock, the `recover_leases` whose
+   * reclaimed leases must be visible to the claims that follow and to nobody in
+   * between, and the write lock itself. *What* gets claimed under it is the
+   * caller's business — a worker drawing a separate quota per task name is
+   * scheduling policy, and this layer has no vocabulary for the "handler call"
+   * that policy is denominated in. It knows queues, names, limits and rows.
+   *
+   * `plan` is handed a `claim(names, limit)` it may call any number of times,
+   * each a separate statement under the same lock and the same recovery, and
+   * each free to size itself from what the previous one returned. That feedback
+   * is the reason this is a callback rather than a list of quotas: a caller
+   * dividing a budget up front has to guess, and every share handed to a name
+   * with nothing queued is a slot left idle until the next poll.
+   *
+   * `plan` runs with the write lock held, so it must await nothing but that
+   * callback.
+   *
+   * `names` is the union `plan` might ask for — the probe and the recovery are
+   * filtered by it. Returns undefined when the probe finds nothing claimable, in
+   * which case `plan` never runs and no transaction is opened.
+   */
+  async claimSession<T>(
+    input: { queues: string[]; workerId: string; leaseMs?: number; names: string[] | null },
+    plan: (claim: (names: string[] | null, limit: number) => Promise<Task[]>) => Promise<T>,
+  ): Promise<T | undefined> {
+    // A list-valued filter cannot be read in claim order, so the planner sorts
+    // every claimable row to take LIMIT of them and the claim's cost grows with
+    // the backlog while it holds the transaction. Both filters therefore have an
+    // equality form, picked per draw: one queue is the common deployment, and one
+    // name is every per-name quota. See claim_one_queue.sql and claim_one_name.sql.
     const oneQueue = input.queues.length === 1;
-    const params: Params = {
+    const base: Params = {
       queues: input.queues,
       queue: oneQueue ? input.queues[0] : null,
-      names: input.names ?? null,
+      names: input.names,
+      name: null,
       worker_id: input.workerId,
       lease_ms: input.leaseMs ?? 30_000,
-      limit: input.limit ?? 1,
+      limit: 1,
       lease_expired_error: LEASE_EXPIRED_ERROR_JSON,
     };
-    if (!(await this.hasClaimableWork(params))) return [];
-    // Recovery must share the claim's transaction: a lease reclaimed here has to
-    // be visible to the claim that follows, and to nobody in between.
+    if (!(await this.hasClaimableWork(base))) return undefined;
     return this.tx(async (fetch) => {
-      await fetch("recover_leases", params);
-      return (await fetch(oneQueue ? "claim_one_queue" : "claim", params)).map(rowToTask);
+      await fetch("recover_leases", base);
+      return plan(async (names, limit) => {
+        // A draw asking for nothing, or filtered to no names, claims nothing —
+        // answer it here rather than spending a statement to learn that.
+        if (limit <= 0 || names?.length === 0) return [];
+        const oneName = names?.length === 1;
+        const statement = oneName
+          ? oneQueue
+            ? "claim_one_queue_one_name"
+            : "claim_one_name"
+          : oneQueue
+            ? "claim_one_queue"
+            : "claim";
+        const rows = await fetch(statement, {
+          ...base,
+          names,
+          name: oneName ? names![0] : null,
+          limit,
+        });
+        return rows.map(rowToTask);
+      });
     });
   }
 
@@ -456,6 +533,33 @@ export abstract class TaskStore {
     });
   }
 
+  /**
+   * Renew several leases in one statement. Returns `taskId -> cancel requested`
+   * for the tasks this worker still holds.
+   *
+   * Deliberately not an ownedWrite: ownership is per task here, so there is no
+   * single answer to "did it work". A task **absent** from the result lost its
+   * lease, and the caller decides what that means for that one task rather than
+   * failing the whole beat.
+   *
+   * It returns flags rather than Tasks because nothing downstream needs a task:
+   * the caller renews leases and observes cancellation, and whole rows would drag
+   * every payload back on every beat for the life of the call.
+   */
+  async heartbeatBatch(input: {
+    taskIds: string[];
+    workerId: string;
+    leaseMs?: number;
+  }): Promise<Map<string, boolean>> {
+    if (!input.taskIds.length) return new Map();
+    const rows = await this.fetch("heartbeat_batch", {
+      ids: input.taskIds,
+      worker_id: input.workerId,
+      lease_ms: input.leaseMs ?? 30_000,
+    });
+    return new Map(rows.map((r) => [r.id as string, r.cancel_requested_at_ms != null]));
+  }
+
   async progress(input: {
     taskId: string;
     workerId: string;

package/src/store/sqlite.ts

@@ -357,7 +357,10 @@ export class SQLiteStore extends TaskStore {
           bound[name] = now - (params.older_than_ms as number);
           break;
         case "queues":
-          bound[name] = JSON.stringify(params.queues);
+        case "ids":
+          // json_each needs a JSON array. Postgres binds the array itself as
+          // text[], so only this dialect encodes.
+          bound[name] = JSON.stringify(params[name]);
           break;
         case "names":
           // json_each needs a JSON array; null stays null so the SQL's

package/src/wait.ts

@@ -7,6 +7,14 @@ export const DEFAULT_POLL_MS = 100;
 export const MAX_POLL_MS = 500;
 const GROWTH = 1.5;
 
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+export interface PollOptions {
+  timeoutMs: number;
+  pollMs?: number;
+  maxPollMs?: number;
+}
+
 /**
  * Grow the polling interval towards the ceiling.
  *
@@ -19,28 +27,64 @@ export function nextPollMs(current: number, maxMs: number): number {
   return Math.min(maxMs, Math.max(current + 1, Math.floor(current * GROWTH)));
 }
 
-/** Poll get() until terminal or timeout. Returns the terminal Task (any status).
- * Throws TaskTimeout, leaving the task running. `pollMs` is the *first* interval;
- * it backs off towards `maxPollMs`. */
-export async function pollWait(
-  store: TaskStore,
-  taskId: string,
-  {
-    timeoutMs,
-    pollMs = DEFAULT_POLL_MS,
-    maxPollMs = MAX_POLL_MS,
-  }: { timeoutMs: number; pollMs?: number; maxPollMs?: number },
+/**
+ * Poll `read` until it yields a terminal task, or the timeout elapses.
+ *
+ * `wake` is what the loop sleeps on between reads: a store with a push channel
+ * (Postgres) cuts it short when the task goes terminal, but the re-read is the
+ * source of truth either way, so a plain sleep is always a correct answer.
+ */
+async function poll(
+  read: () => Promise<Task | null>,
+  wake: (task: Task | null, ms: number) => Promise<void>,
+  subject: string,
+  key: string | null,
+  { timeoutMs, pollMs = DEFAULT_POLL_MS, maxPollMs = MAX_POLL_MS }: PollOptions,
 ): Promise<Task> {
   const deadline = nowMs() + timeoutMs;
   let interval = pollMs;
   for (;;) {
-    const task = await store.get(taskId);
+    const task = await read();
     if (task && isTerminal(task)) return task;
     const remaining = deadline - nowMs();
-    if (remaining <= 0) throw new TaskTimeout(taskId, { timeoutMs, task });
-    // A store with a push channel (Postgres) cuts the sleep short when the task
-    // goes terminal; the re-get above stays the source of truth either way.
-    await store.taskDoneWake(taskId, Math.min(interval, remaining));
+    if (remaining <= 0) throw new TaskTimeout(task?.id ?? subject, { timeoutMs, task, key });
+    await wake(task, Math.min(interval, remaining));
     interval = nextPollMs(interval, maxPollMs);
   }
 }
+
+/** Poll get() until terminal or timeout. Returns the terminal Task (any status).
+ * Throws TaskTimeout, leaving the task running. `pollMs` is the *first* interval;
+ * it backs off towards `maxPollMs`. */
+export function pollWait(store: TaskStore, taskId: string, opts: PollOptions): Promise<Task> {
+  return poll(
+    () => store.get(taskId),
+    (_task, ms) => store.taskDoneWake(taskId, ms),
+    taskId,
+    null,
+    opts,
+  );
+}
+
+/**
+ * The same wait, following a key instead of an id.
+ *
+ * The key is re-resolved on every read, because that is what a key means: a
+ * pointer to the task that is *current* under it. A `replace` landing mid-wait
+ * moves the wait onto the new task rather than reporting the cancellation of the
+ * old one, and a key that points at nothing yet is simply not finished — it
+ * polls until something appears, the same way waiting on an id that does not
+ * exist yet does.
+ *
+ * There is nothing to subscribe to before the key resolves, so those naps are
+ * plain sleeps; once it resolves, the store's push channel applies as usual.
+ */
+export function pollWaitByKey(store: TaskStore, key: string, opts: PollOptions): Promise<Task> {
+  return poll(
+    () => store.getByKey(key),
+    (task, ms) => (task ? store.taskDoneWake(task.id, ms) : sleep(ms)),
+    key,
+    key,
+    opts,
+  );
+}