cairnq 0.8.0 → 0.10.0

package/src/client.ts

@@ -4,7 +4,15 @@ import { TaskCanceled, TaskFailed } from "./errors.js";
 import { isFailed, isSucceeded, type Task, type TaskRef, type TaskStatus } from "./models.js";
 import { SQLiteStore } from "./store/sqlite.js";
 import { PostgresStore } from "./store/postgres.js";
-import type { ListInput, PurgeInput, SubmitInput, TaskStore } from "./store/base.js";
+import type { PgExecutor } from "./store/pg-executor.js";
+import type {
+  ListInput,
+  PurgeInput,
+  SubmitInput,
+  TaskStore,
+  WatchOptions,
+  WatchSignal,
+} from "./store/base.js";
 import { type TaskDef, taskName } from "./task.js";
 import { DEFAULT_WAIT_TIMEOUT_MS, type PollOptions, pollWait, pollWaitByKey } from "./wait.js";
 
@@ -53,11 +61,16 @@ export class CairnQ {
     return new CairnQ(new SQLiteStore(path, { busyTimeoutMs }), client);
   }
 
-  /** Multi-host backend. `dsn` is a libpq connection string; requires the
-   * optional `pg` package. */
-  static postgres(dsn: string, opts: { max?: number } & ClientOptions = {}): CairnQ {
-    const { max, ...client } = opts;
-    return new CairnQ(new PostgresStore(dsn, { max }), client);
+  /** Multi-host backend. `source` is a libpq connection string — which requires
+   * the optional `pg` package — or a PgExecutor over a driver the application
+   * already runs (an ORM's pool, say), which cairnq then shares instead of
+   * opening a second one. */
+  static postgres(
+    source: string | PgExecutor,
+    opts: { max?: number; schema?: string } & ClientOptions = {},
+  ): CairnQ {
+    const { max, schema, ...client } = opts;
+    return new CairnQ(new PostgresStore(source, { max, schema }), client);
   }
 
   get store(): TaskStore {
@@ -146,6 +159,20 @@ export class CairnQ {
     return this._store.stats();
   }
 
+  /**
+   * Call `onSignal` when the tasks on `queues` may have changed. Returns an
+   * unsubscribe.
+   *
+   * Notify-accelerated polling, not an event log: a signal means "re-read now",
+   * and `stats()` / `list()` / `get()` are where the truth is. On Postgres an
+   * idle watch costs nothing and signals land in milliseconds; everywhere else
+   * the timer alone still delivers, so the same consumer code is correct either
+   * way. See TaskStore.watch for the full contract.
+   */
+  watch(opts: WatchOptions, onSignal: (signal: WatchSignal) => void): () => void {
+    return this._store.watch(opts, onSignal);
+  }
+
   /** Wait for a task to finish. Resolves with the terminal Task (any status);
    * throws TaskTimeout without stopping the task, so `wait(err.taskId)` picks the
    * same wait back up — from another process, or after a longer deadline. */

package/src/context.ts

@@ -3,6 +3,7 @@ import { asEnvelope, type FailReason, LostLease } from "./errors.js";
 import { cancelRequested, type Task } from "./models.js";
 import type { SubmitOptions } from "./client.js";
 import type { TaskStore } from "./store/base.js";
+import type { PgSession } from "./store/pg-executor.js";
 import { type TaskDef, taskName } from "./task.js";
 import { pollWait } from "./wait.js";
 
@@ -36,7 +37,7 @@ export class TaskContext {
   constructor(
     private readonly store: TaskStore,
     private readonly task: Task,
-    public readonly workerId: string,
+    private readonly ownerId: string,
     private readonly leaseMs: number,
     opts: TaskContextOptions = {},
   ) {
@@ -47,6 +48,10 @@ export class TaskContext {
   get taskId(): string {
     return this.task.id;
   }
+  /** The worker running this task — what `worker_id` on the row points at. */
+  get workerId(): string {
+    return this.ownerId;
+  }
   get name(): string {
     return this.task.name;
   }
@@ -149,7 +154,7 @@ export class TaskContext {
     return this.owned(() =>
       this.store.progress({
         taskId: this.task.id,
-        workerId: this.workerId,
+        workerId: this.ownerId,
         progress: value,
         message,
       }),
@@ -160,7 +165,7 @@ export class TaskContext {
     return this.owned(() =>
       this.store.heartbeat({
         taskId: this.task.id,
-        workerId: this.workerId,
+        workerId: this.ownerId,
         leaseMs: this.leaseMs,
       }),
     );
@@ -195,12 +200,48 @@ export class TaskContext {
   async succeed(result: unknown = null): Promise<Task | null> {
     if (this.isSettled) return null;
     const task = await this.owned(() =>
-      this.store.complete({ taskId: this.task.id, workerId: this.workerId, result }),
+      this.store.complete({ taskId: this.task.id, workerId: this.ownerId, result }),
     );
     this.markSettled();
     return task;
   }
 
+  /**
+   * Finalize this task as succeeded, committing the caller's own writes in the
+   * SAME transaction as the settlement. Whatever `write` returns becomes the
+   * task's result.
+   *
+   *     await ctx.succeedIn(async (session) => {
+   *       await db.withSession(session).insert(pages).values(rendered)
+   *       return { pages: rendered.length }
+   *     })
+   *
+   * The alternative — write the rows, then settle — has a window between the two
+   * commits where the work is durable but the task still reads as running. A
+   * crash there re-runs the whole task, which for a render or an ingest means
+   * recomputing it, and for non-idempotent work means doing it twice.
+   *
+   * `session` is the driver's, so this needs a Postgres store built on a
+   * PgExecutor the application shares with its own driver; anything else throws.
+   * If the settlement finds the lease gone, `write`'s work is rolled back with
+   * it and LostLease is raised. Returns null if this task was already settled.
+   *
+   * `write` may be replayed if the backend retries the transaction — derive
+   * nothing inside it that cannot be derived twice.
+   */
+  async succeedIn<T>(write: (session: PgSession) => Promise<T>): Promise<Task | null> {
+    if (this.isSettled) return null;
+    const task = await this.owned(async () => {
+      const { task } = await this.store.completeIn<PgSession, T>(
+        { taskId: this.task.id, workerId: this.ownerId },
+        write,
+      );
+      return task;
+    });
+    this.markSettled();
+    return task;
+  }
+
   /**
    * Finalize this task as failed, now. `error` may be a string reason, an Error,
    * a TaskError (which carries its own retryability), or a ready envelope.
@@ -216,7 +257,7 @@ export class TaskContext {
     const task = await this.owned(() =>
       this.store.fail({
         taskId: this.task.id,
-        workerId: this.workerId,
+        workerId: this.ownerId,
         error: envelope,
         retryable,
         delayMs: failDelayMs(this.task.attempt, retryable, this.backoffMs, this.backoffMaxMs),

package/src/errors.ts

@@ -208,6 +208,27 @@ export class ProtocolVersionMismatch extends CairnQError {
   }
 }
 
+/**
+ * This connection is not pointed at the cairnq installation the rest of the
+ * deployment is using — raised at connect, before any task is written.
+ *
+ * The schema a Postgres connection resolves to is out-of-band configuration
+ * (`search_path`, a `schema` option, an ORM's pool settings), so two processes
+ * given the same DSN can still land in different schemas. Every migration is
+ * `create table if not exists`, so the odd one out does not fail: it builds a
+ * second, empty installation and its protocol version check passes against the
+ * cairnq_meta it just created. Left undetected, an API and a worker then agree
+ * about everything except WHERE, and no task ever crosses.
+ *
+ * The Python SDK raises the same named error.
+ */
+export class SchemaMismatch extends CairnQError {
+  constructor(message: string) {
+    super(message);
+    this.name = "SchemaMismatch";
+  }
+}
+
 /** A value could not be encoded for a protocol JSON column (non-finite number,
  * BigInt, circular structure, …). Raised at the boundary — submit rejects with
  * it, and a worker records a handler result that triggers it as a permanent

package/src/index.ts

@@ -12,8 +12,19 @@ export { defineTask } from "./task.js";
 export type { TaskDef } from "./task.js";
 export { SQLiteStore } from "./store/sqlite.js";
 export { PostgresStore } from "./store/postgres.js";
+export { ListenUnavailable } from "./store/pg-executor.js";
+export type { PgExecutor, PgSession, Row } from "./store/pg-executor.js";
+export { createPoolExecutor } from "./store/pg-pool.js";
 export { TaskStore } from "./store/base.js";
-export type { ListInput, PurgeInput, SubmitInput, Conflict } from "./store/base.js";
+export type {
+  ListInput,
+  PurgeInput,
+  SubmitInput,
+  Conflict,
+  WatchOptions,
+  WatchSignal,
+} from "./store/base.js";
+export { DEFAULT_WATCH_POLL_MS } from "./store/base.js";
 export type { Task, TaskRef, TaskStatus, TerminalStatus } from "./models.js";
 export {
   STATUSES,
@@ -37,6 +48,7 @@ export {
   LostLease,
   EventLoopBlocked,
   ProtocolVersionMismatch,
+  SchemaMismatch,
   SerializationError,
 } from "./errors.js";
 export type { FailReason } from "./errors.js";

package/src/models.ts

@@ -39,6 +39,19 @@ export interface TaskRef {
 }
 
 const JSON_COLUMNS = ["payload", "result", "error", "metadata"] as const;
+// The bigint columns. `attempt` / `max_attempts` / `priority` are int4 and
+// `progress` is double precision, so every driver already gives those as numbers;
+// only int8 has a wire form worth normalizing. Nullability differs per column
+// (completed_at_ms may be null, created_at_ms may not), so the coercion has to
+// preserve null rather than turn it into 0.
+const MS_COLUMNS = [
+  "lease_until_ms",
+  "run_at_ms",
+  "cancel_requested_at_ms",
+  "created_at_ms",
+  "updated_at_ms",
+  "completed_at_ms",
+] as const;
 // As a const tuple so TerminalStatus derives from it — the same declare-once
 // pattern as STATUSES/TaskStatus above.
 export const TERMINAL = ["succeeded", "failed", "canceled"] as const;
@@ -63,6 +76,20 @@ export function rowToTask(row: Record<string, unknown>): Task {
     // already-decoded object. Parse only a string — never assume one backend.
     t[col] = typeof v === "string" ? JSON.parse(v) : (v ?? null);
   }
+  for (const col of MS_COLUMNS) {
+    const v = row[col];
+    // Same argument, for the other column type the drivers disagree about.
+    // Postgres sends int8 down the wire as text to protect precision it cannot
+    // know is unneeded; `pg` surfaces that as a string, postgres.js does too,
+    // asyncpg decodes to int. Normalizing here rather than demanding it of every
+    // driver is what keeps an INJECTED executor honest: the alternative is
+    // asking an application to change its driver's global int8 handling to suit
+    // cairnq, which breaks that application's own bigint columns.
+    //
+    // Lossless: every one of these is an epoch-ms, and a millisecond timestamp
+    // does not reach Number.MAX_SAFE_INTEGER until the year 287396.
+    t[col] = v == null ? null : Number(v);
+  }
   return t as unknown as Task;
 }
 

package/src/store/base.ts

@@ -201,6 +201,35 @@ export function statementParams(sql: string): readonly string[] {
  * them in one place is what stops SQLite and Postgres from drifting apart in
  * behavior; the shared SQL already stops them from drifting in wording.
  */
+/**
+ * Why `watch` is calling back.
+ *
+ * `queued` / `done` come from the store's push channel and name what moved;
+ * `poll` is the timer saying the watch cannot rule out a change. None of them
+ * carries state — the row is the truth.
+ */
+export interface WatchSignal {
+  reason: "queued" | "done" | "poll";
+  /** The queue a task was queued on. Only on `queued`. */
+  queue?: string;
+  /** The task that reached a terminal status. Only on `done`. */
+  taskId?: string;
+}
+
+export interface WatchOptions {
+  /** Restrict `queued` signals to these queues. Unset watches every queue. */
+  queues?: string[];
+  /**
+   * How often to signal in the absence of a push channel — and, where there is
+   * one, how long a dropped listener can go unnoticed. The default trades a
+   * dashboard's idle query rate against how stale it may look.
+   */
+  pollMs?: number;
+}
+
+/** See WatchOptions.pollMs. */
+export const DEFAULT_WATCH_POLL_MS = 2_000;
+
 export abstract class TaskStore {
   /** Set by useBackpressure; null means submit is ungated. */
   private gate: QueueDepthGate | null = null;
@@ -222,6 +251,37 @@ export abstract class TaskStore {
    */
   protected abstract tx<T>(fn: (fetch: Fetch) => Promise<T>): Promise<T>;
 
+  /**
+   * `tx`, but also handing `fn` the driver's own session so the CALLER can run
+   * their statements in the same transaction as the protocol's.
+   *
+   * This is what lets a task's settlement and the rows that task produced commit
+   * together. Without it the two are separate transactions and there is a window
+   * where the work is durable but the task still reads as unfinished — a crash
+   * there costs a full recomputation on retry, and for non-idempotent work costs
+   * more than that.
+   *
+   * Optional, because the session type is the driver's, not the protocol's: a
+   * store that has no session worth handing out simply does not implement it and
+   * `completeIn` reports that. Postgres implements it; SQLite does not.
+   */
+  protected txWithSession?<T>(fn: (fetch: Fetch, session: unknown) => Promise<T>): Promise<T>;
+
+  /**
+   * Register for this store's push channel, if it has one; returns an
+   * unsubscribe. A store without a push channel does not implement this, and
+   * `watch` degrades to its timer alone.
+   */
+  protected subscribePush?(onSignal: (signal: WatchSignal) => void): () => void;
+
+  /**
+   * Nudge the push channel back up if it has dropped. Called from `watch`'s
+   * timer, which is the only thing keeping a client-side subscriber alive: a
+   * process that never claims never calls claimWake, so without this a listener
+   * that died once would never come back there.
+   */
+  protected warmPush?(): void;
+
   /**
    * Whether it is worth opening the claim transaction at all. SQLite gates its
    * single write lock behind a read-only probe; Postgres readers don't block
@@ -460,6 +520,57 @@ export abstract class TaskStore {
     return out;
   }
 
+  /**
+   * Call `onSignal` when the tasks on `queues` may have changed — something was
+   * queued, or something finished.
+   *
+   * This is notify-ACCELERATED POLLING, not an event log, and the difference is
+   * the whole contract. Where a push channel is available (Postgres LISTEN) an
+   * idle watch costs nothing and a signal arrives within milliseconds of the
+   * event. Where it is not — a transaction-mode pooler refuses LISTEN, SQLite has
+   * no channel at all — the timer alone still delivers `poll` signals, so a
+   * consumer that re-reads on every signal is correct in both cases and merely
+   * less prompt in one.
+   *
+   * What it will NOT do is promise that a signal means something happened, or
+   * that every event produces its own signal. Treat a signal as "re-read now"
+   * and take the truth from `stats()` / `list()` / `get()`, which is where it
+   * lives. `reason` is a hint for reading less: a `done` signal names the task,
+   * so a dashboard can refresh that row instead of the list.
+   *
+   * Returns an unsubscribe. The timer is unref'd — watching does not hold a
+   * process open.
+   */
+  watch(opts: WatchOptions, onSignal: (signal: WatchSignal) => void): () => void {
+    const pollMs = Math.max(1, opts.pollMs ?? DEFAULT_WATCH_POLL_MS);
+    const queues = opts.queues ?? null;
+    let live = true;
+    const emit = (signal: WatchSignal): void => {
+      // A signal delivered after unsubscribe would have the consumer re-reading
+      // a store it has stopped caring about, possibly a closed one.
+      if (live) onSignal(signal);
+    };
+    const unsubscribe = this.subscribePush?.((signal) => {
+      // A queued signal names its queue, so a watch scoped to some queues can
+      // drop the rest. A done signal names only the task — which queue it was on
+      // is not in the notification, so it is never filtered out.
+      if (signal.reason === "queued" && queues && signal.queue && !queues.includes(signal.queue)) {
+        return;
+      }
+      emit(signal);
+    });
+    const timer = setInterval(() => {
+      this.warmPush?.();
+      emit({ reason: "poll" });
+    }, pollMs);
+    timer.unref?.();
+    return () => {
+      live = false;
+      unsubscribe?.();
+      clearInterval(timer);
+    };
+  }
+
   /**
    * How many more tasks fit on `queue` under `maxDepth` — 0 once it is full.
    *
@@ -636,6 +747,45 @@ export abstract class TaskStore {
     });
   }
 
+  /**
+   * `complete`, with the caller's own writes committed in the same transaction.
+   *
+   * `fn` runs first and whatever it returns becomes the task's result; the
+   * settlement is the last statement in the transaction. So a lost lease — the
+   * settlement matching no row — rolls the caller's writes back with it, and
+   * there is no ordering in which the work is recorded but the task is not.
+   *
+   * The settlement runs LAST rather than checking ownership up front on purpose:
+   * the ownership predicate lives in the protocol's complete.sql, and a
+   * fail-fast pre-check here would be a second copy of it, free to drift. The
+   * cost of that choice is that a doomed attempt does its work before finding
+   * out, which is the rare path.
+   *
+   * `fn` must be replayable for the same reason `tx`'s callback must be.
+   */
+  async completeIn<S, T>(
+    input: { taskId: string; workerId: string },
+    fn: (session: S) => Promise<T>,
+  ): Promise<{ task: Task; value: T }> {
+    if (!this.txWithSession) {
+      throw new Error(
+        "this store cannot share a transaction with the caller — " +
+          "completeIn requires a Postgres store (see PgExecutor)",
+      );
+    }
+    return this.txWithSession(async (fetch, session) => {
+      const value = await fn(session as S);
+      const rows = await fetch("complete", {
+        id: input.taskId,
+        worker_id: input.workerId,
+        result: value == null ? null : dumpJson(value),
+      });
+      // Rolls back `fn`'s writes along with the settlement that did not land.
+      if (!rows.length) throw new LostLease(input.taskId);
+      return { task: rowToTask(rows[0]), value };
+    });
+  }
+
   async fail(input: {
     taskId: string;
     workerId: string;

package/src/store/pg-executor.ts

@@ -0,0 +1,91 @@
+/**
+ * The seam between PostgresStore and whatever actually talks to Postgres.
+ *
+ * PostgresStore owns the *dialect* — the protocol's named-parameter SQL rewritten
+ * to `$n`, the migration ledger, the LISTEN policy. It does not own the
+ * *connection*. Applications that already run a Postgres driver (an ORM, a pool
+ * they size themselves) pass their own executor and cairnq joins that session
+ * instead of opening a second one, which is what makes a task's settlement
+ * commit in the same transaction as the rows the task produced.
+ *
+ * Implementing one is small — see `createPoolExecutor` in pg-pool.ts for the
+ * reference implementation over `pg`. An adapter passes rows through as its
+ * driver produced them: cairnq normalizes both column types the drivers disagree
+ * about (jsonb decoded or not, int8 as text or number) in `rowToTask`, so no
+ * adapter has to reconfigure its driver — and none has to change how the
+ * application's OWN columns come back in order to satisfy cairnq.
+ */
+
+/** A row as the driver hands it back: column name -> value. */
+export type Row = Record<string, unknown>;
+
+/**
+ * Somewhere statements can run. The same shape whether it is a pool (each call
+ * on some connection) or one transaction's dedicated connection — the store's
+ * statements do not care, and this is what lets `tx` hand the same interface to
+ * its callback.
+ */
+export interface PgSession {
+  /**
+   * One parameterised statement, `$1`-style. `values` is positional and may
+   * legitimately contain nulls — a null parameter is "this filter is off" in
+   * several protocol statements, not a missing argument.
+   */
+  query(text: string, values: readonly unknown[]): Promise<Row[]>;
+  /**
+   * Parameterless SQL that may hold several statements, for migration DDL.
+   * Separate from `query` because it must go over the simple query protocol:
+   * the extended protocol a parameterised call uses accepts only one statement,
+   * and every migration is a script.
+   */
+  exec(sql: string): Promise<void>;
+}
+
+/** A session that can also open transactions, listen, and be shut down. */
+export interface PgExecutor extends PgSession {
+  /**
+   * Run `fn` inside one transaction on one dedicated connection, committing if
+   * it returns and rolling back if it throws. The store relies on both halves:
+   * a claim that cannot see its own `recover_leases` is a double-dispatch, and a
+   * keyed submit that commits half way poisons the key.
+   */
+  tx<T>(fn: (session: PgSession) => Promise<T>): Promise<T>;
+
+  /**
+   * Subscribe a dedicated connection to `channels`. Optional: an executor that
+   * omits it (or a Postgres that refuses LISTEN) costs latency, never
+   * correctness — the store falls back to plain polling, which is the contract
+   * PROTOCOL.md gives for push wakeups.
+   *
+   * Resolves with a function that stops listening. `onClose` reports a
+   * connection that dropped on its own, so the store can degrade and retry.
+   *
+   * Throw `ListenUnavailable` when this Postgres will never accept LISTEN — a
+   * transaction-mode pooler, say. Any other rejection is read as transient and
+   * retried with backoff, so a permanent condition raised as a plain Error
+   * becomes a reconnect loop that cannot succeed.
+   */
+  listen?(
+    channels: readonly string[],
+    onNotify: (channel: string, payload: string | undefined) => void,
+    onClose: () => void,
+  ): Promise<() => void>;
+
+  /**
+   * Release this executor's resources. Called by PostgresStore.close() ONLY for
+   * an executor the store created itself: an injected one belongs to the caller,
+   * whose other work would not survive cairnq closing it.
+   */
+  close(): Promise<void>;
+}
+
+/**
+ * LISTEN will not work on this connection, and retrying cannot change that.
+ * See `PgExecutor.listen`.
+ */
+export class ListenUnavailable extends Error {
+  constructor(message = "LISTEN is not available on this connection") {
+    super(message);
+    this.name = "ListenUnavailable";
+  }
+}