cairnq 0.7.0 → 0.9.0

package/src/store/base.ts

@@ -6,7 +6,15 @@ import {
   ProtocolVersionMismatch,
   SerializationError,
 } from "../errors.js";
-import { rowToTask, STATUSES, TERMINAL, type Task, type TaskStatus } from "../models.js";
+import {
+  isTerminalStatus,
+  rowToRef,
+  rowToTask,
+  STATUSES,
+  type Task,
+  type TaskRef,
+  type TaskStatus,
+} from "../models.js";
 import { type BackpressureOptions, QueueDepthGate } from "../backpressure.js";
 
 const rejectMangled = function (this: unknown, _key: string, v: unknown): unknown {
@@ -77,7 +85,7 @@ export type Conflict = (typeof CONFLICTS)[number];
  */
 function reusable(conflict: Conflict, status: TaskStatus): boolean {
   if (conflict === "replace") return false;
-  if (!TERMINAL.includes(status)) return true;
+  if (!isTerminalStatus(status)) return true;
   return conflict === "reuse-succeeded" && status === "succeeded";
 }
 
@@ -110,8 +118,32 @@ export interface ListInput {
   offset?: number;
 }
 
+/** Validate a purge's inputs. Shared with RetentionSweeper, which fail-fasts at
+ * construction on the same rules an hourly sweep would otherwise only surface
+ * through its onError hook — one statement of the rules, two callers. */
+export function validatePurgeInput(input: PurgeInput): void {
+  if (input.olderThanMs != null && (!Number.isFinite(input.olderThanMs) || input.olderThanMs < 0)) {
+    throw new Error(`olderThanMs must be >= 0, got ${input.olderThanMs}`);
+  }
+  if (input.limit != null && input.limit < 1) {
+    throw new Error(`limit must be >= 1, got ${input.limit}`);
+  }
+  // Terminal only: purge never deletes live work, so accepting `queued` here
+  // would be accepting a filter that silently matches nothing.
+  if (input.status != null && !isTerminalStatus(input.status)) {
+    throw new Error(`status must be terminal, got ${input.status}`);
+  }
+}
+
 export interface PurgeInput {
   olderThanMs?: number;
+  /** Restrict the sweep to one terminal status. Retention needs are tiered —
+   * succeeded rows are spent once their result is consumed, failed ones are
+   * worth keeping for diagnosis — and without this the shortest-lived tier
+   * sets the retention for every row. Absent means all terminal statuses. */
+  status?: TaskStatus;
+  /** Restrict the sweep to one task name. Absent means all names. */
+  name?: string;
   limit?: number;
 }
 
@@ -169,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;
@@ -190,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
@@ -234,6 +326,10 @@ export abstract class TaskStore {
     return rows.length ? rowToTask(rows[0]) : null;
   }
 
+  private static oneRef(rows: any[]): TaskRef | null {
+    return rows.length ? rowToRef(rows[0]) : null;
+  }
+
   // ------------------------------------------------------------- client side
   /**
    * Bound how deep a queue may get before `submit` blocks. Off unless set.
@@ -305,7 +401,7 @@ export abstract class TaskStore {
           // 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)) {
+          if (!isTerminalStatus(current.status as TaskStatus)) {
             await fetch("cancel", { id: existing[0].task_id });
           }
         }
@@ -324,6 +420,18 @@ export abstract class TaskStore {
     return TaskStore.one(await this.fetch("get_by_key", { key }));
   }
 
+  /** The wait loop's probe: id + status alone, so polling a task with a large
+   * payload does not re-read and re-parse that payload on every beat. */
+  async getStatus(taskId: string): Promise<TaskRef | null> {
+    return TaskStore.oneRef(await this.fetch("get_status", { id: taskId }));
+  }
+
+  /** getStatus, following a key instead of an id — re-resolved per call, so a
+   * `replace` moves the probe onto the new task. */
+  async getStatusByKey(key: string): Promise<TaskRef | null> {
+    return TaskStore.oneRef(await this.fetch("get_status_by_key", { key }));
+  }
+
   async list(input: ListInput = {}): Promise<Task[]> {
     // Validate up front, like submit's conflict guard: a typo'd status otherwise
     // matches nothing and returns [] indistinguishably from "no such tasks".
@@ -385,14 +493,11 @@ export abstract class TaskStore {
    * call it in a loop until it returns fewer than `limit`.
    */
   async purge(input: PurgeInput = {}): Promise<string[]> {
-    if (input.olderThanMs != null && input.olderThanMs < 0) {
-      throw new Error(`olderThanMs must be >= 0, got ${input.olderThanMs}`);
-    }
-    if (input.limit != null && input.limit < 1) {
-      throw new Error(`limit must be >= 1, got ${input.limit}`);
-    }
+    validatePurgeInput(input);
     const rows = await this.fetch("purge", {
       older_than_ms: input.olderThanMs ?? 0,
+      status: input.status ?? null,
+      name: input.name ?? null,
       limit: input.limit ?? 1_000,
     });
     return rows.map((r) => r.id as string);
@@ -415,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.
    *
@@ -591,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,90 @@
+/**
+ * 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` below for the reference
+ * implementation over `pg`, and PROTOCOL.md for the two things an adapter must
+ * get right that are easy to miss: int8 must come back as a JS number (every
+ * cairnq bigint is an epoch-ms or a counter, all inside the safe range), and
+ * jsonb must come back as an object, not a string.
+ */
+
+/** 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";
+  }
+}

package/src/store/pg-pool.ts

@@ -0,0 +1,156 @@
+import type * as PG from "pg";
+
+import { ListenUnavailable, type PgExecutor, type PgSession, type Row } from "./pg-executor.js";
+
+// `pg` is an optional dependency: the SDK is SQLite-first, so it's loaded lazily
+// the first time a pool-backed executor is built. Absent -> a clear install hint.
+// An application that brings its own executor never reaches this.
+let pgModule: typeof import("pg") | null = null;
+async function loadPg(): Promise<typeof import("pg")> {
+  if (pgModule) return pgModule;
+  let mod: { default?: typeof import("pg") } & typeof import("pg");
+  try {
+    mod = (await import("pg")) as never;
+  } catch {
+    throw new Error("PostgresStore requires the 'pg' package — install it (e.g. `npm i pg`)");
+  }
+  const pg = (mod.default ?? mod) as typeof import("pg");
+  // Postgres returns bigint (int8, OID 20) as a string to avoid precision loss.
+  // Every cairnq bigint is an epoch-ms or a counter, all within Number's safe
+  // integer range, so parse to number once (globally) to match the Task model
+  // (*_ms typed as number, same as the SQLite SDK). Set before any query runs.
+  pg.types.setTypeParser(pg.types.builtins.INT8, (v: string) => (v == null ? null : Number(v)));
+  pgModule = pg;
+  return pg;
+}
+
+/**
+ * Roll back on the way out of a failed transaction, without letting the rollback
+ * become the error the caller sees. A dropped connection fails both the statement
+ * and the rollback, and it is the first one that says what went wrong.
+ */
+async function rollbackQuietly(client: PG.PoolClient): Promise<void> {
+  try {
+    await client.query("rollback");
+  } catch {
+    // Already rolled back, or the connection is gone. Either way the original
+    // error is the one worth propagating.
+  }
+}
+
+/** The PgSession face of one pg client or pool. */
+function session(q: Pick<PG.PoolClient, "query">): PgSession {
+  return {
+    async query(text: string, values: readonly unknown[]): Promise<Row[]> {
+      return (await q.query(text, values as unknown[])).rows;
+    },
+    async exec(sql: string): Promise<void> {
+      // No values: pg sends this over the simple query protocol, which is what
+      // makes a multi-statement migration script legal here and not in query().
+      await q.query(sql);
+    },
+  };
+}
+
+/**
+ * A Postgres identifier that is safe to interpolate — cairnq quotes the schema
+ * name, and a name that could close that quote could rewrite the statement.
+ * Deliberately narrower than what Postgres accepts: a schema cairnq is asked to
+ * live in is a deployment decision, not a place to be clever.
+ */
+const PLAIN_IDENT = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+
+/**
+ * The built-in executor: a `pg.Pool` over a libpq DSN. What `CairnQ.postgres(dsn)`
+ * uses, and the reference for what an adapter over another driver must do.
+ *
+ * Creating it does not connect — `pg.Pool` is lazy, and the store's first
+ * statement (the migration ledger) is what proves the database is reachable.
+ *
+ * `schema` puts cairnq's tables in a schema of their own rather than in whatever
+ * the connection's search_path leads with. The protocol's SQL names no schema, so
+ * this is a per-connection `search_path` and not one statement changes.
+ */
+export async function createPoolExecutor(
+  dsn: string,
+  opts: { max?: number; schema?: string } = {},
+): Promise<PgExecutor> {
+  const pg = await loadPg();
+  const schema = opts.schema;
+  if (schema !== undefined && !PLAIN_IDENT.test(schema)) {
+    throw new Error(
+      `schema must be a plain identifier (letters, digits, _ and $, not starting ` +
+        `with a digit), got ${JSON.stringify(schema)}`,
+    );
+  }
+  const pool = new pg.Pool({ connectionString: dsn, max: opts.max });
+  if (schema) {
+    // Queued on the connection before it is handed out, so every statement this
+    // pool ever runs — migrations included — resolves in the right schema. Pooled
+    // connections come and go, which is why this is per-connection rather than a
+    // one-off at startup.
+    pool.on("connect", (client) => {
+      void client.query(`set search_path to "${schema}"`);
+    });
+  }
+  if (schema) {
+    // Created once, here, rather than from the connect handler (which would ask
+    // for CREATE privilege on every new connection) or from the migrations
+    // (which name no schema, by design). Without it the first `create table`
+    // fails with "no schema has been selected to create in", which says nothing
+    // about the cause. This is the one thing that makes building the executor
+    // connect; without `schema` it stays lazy.
+    try {
+      await pool.query(`create schema if not exists "${schema}"`);
+    } catch (e) {
+      await pool.end();
+      throw e;
+    }
+  }
+  const poolSession = session(pool);
+
+  return {
+    query: poolSession.query,
+    exec: poolSession.exec,
+
+    async tx<T>(fn: (s: PgSession) => Promise<T>): Promise<T> {
+      const client = await pool.connect();
+      try {
+        await client.query("begin");
+        const out = await fn(session(client));
+        await client.query("commit");
+        return out;
+      } catch (e) {
+        await rollbackQuietly(client);
+        throw e;
+      } finally {
+        client.release();
+      }
+    },
+
+    async listen(channels, onNotify, onClose): Promise<() => void> {
+      // Built from the raw DSN rather than taken from the pool: a listener holds
+      // its connection for its whole life, and a pooled one would be a slot the
+      // store never gives back. If `opts` ever grows connection-level settings
+      // (ssl, application_name), the listener must receive them too.
+      const client = new pg.Client({ connectionString: dsn });
+      await client.connect(); // failure here is transient: caller retries with backoff
+      client.on("notification", (msg) => onNotify(msg.channel, msg.payload));
+      // A dropped listener degrades to polling; the store reconnects on the next wake.
+      client.on("error", () => onClose());
+      try {
+        await client.query(channels.map((c) => `listen ${c}`).join("; "));
+      } catch (e) {
+        void client.end().catch(() => {});
+        // Connected, but LISTEN was refused (e.g. a transaction-mode pooler) —
+        // deterministic, so tell the store not to retry.
+        throw new ListenUnavailable(e instanceof Error ? e.message : undefined);
+      }
+      return () => void client.end().catch(() => {});
+    },
+
+    async close(): Promise<void> {
+      await pool.end();
+    },
+  };
+}