cairnq 0.1.0 → 0.3.0

package/src/context.ts

@@ -1,3 +1,4 @@
+import { LostLease } from "./errors.js";
 import { cancelRequested, type Task } from "./models.js";
 import type { SubmitOptions } from "./client.js";
 import type { TaskStore } from "./store/base.js";
@@ -6,6 +7,12 @@ import { pollWait } from "./wait.js";
 
 /** Handed to a task handler. Worker-side capabilities mirror the Python SDK. */
 export class TaskContext {
+  private readonly abort = new AbortController();
+  private leaseLost = false;
+  // Cancellation is monotonic: once the DB has told us a cancel was requested it
+  // can't be taken back, so canceled() can answer from this without a re-read.
+  private cancelSeen = false;
+
   constructor(
     private readonly store: TaskStore,
     private readonly task: Task,
@@ -38,28 +45,78 @@ export class TaskContext {
     return this.task.payload;
   }
 
+  /**
+   * True once this worker has lost the task's lease — it expired and another
+   * worker reclaimed it. Nothing this handler writes will be recorded any more
+   * and the task is already running elsewhere, so a long handler should check
+   * this (or `signal`) and bail out instead of continuing to do side effects.
+   */
+  get lostLease(): boolean {
+    return this.leaseLost;
+  }
+
+  /** Aborts when the lease is lost. Pass it to fetch / any AbortSignal-aware API. */
+  get signal(): AbortSignal {
+    return this.abort.signal;
+  }
+
+  /** @internal Called by the worker when an owned write reports a lost lease. */
+  markLeaseLost(): void {
+    if (this.leaseLost) return;
+    this.leaseLost = true;
+    this.abort.abort(new LostLease(this.task.id));
+  }
+
+  // Every owned write returns the current row, so cancellation and lease loss
+  // ride along on writes the handler was making anyway.
+  private observe(task: Task): Task {
+    if (cancelRequested(task)) this.cancelSeen = true;
+    return task;
+  }
+
+  private async owned(write: () => Promise<Task>): Promise<Task> {
+    // Short-circuit once the lease is known lost: nothing this context writes
+    // may be recorded any more. Locally, not just via the store's ownership
+    // check — after an abandoned (timed-out) attempt the same worker may
+    // re-claim this task under the same workerId, and a zombie handler's write
+    // would then pass ownership against the NEW attempt.
+    if (this.leaseLost) throw new LostLease(this.task.id);
+    try {
+      return this.observe(await write());
+    } catch (err) {
+      if (err instanceof LostLease) this.markLeaseLost();
+      throw err;
+    }
+  }
+
   async progress(value: number | null, message: string | null = null): Promise<Task> {
-    return this.store.progress({
-      taskId: this.task.id,
-      workerId: this.workerId,
-      progress: value,
-      message,
-    });
+    return this.owned(() =>
+      this.store.progress({
+        taskId: this.task.id,
+        workerId: this.workerId,
+        progress: value,
+        message,
+      }),
+    );
   }
 
   async heartbeat(): Promise<Task> {
-    return this.store.heartbeat({
-      taskId: this.task.id,
-      workerId: this.workerId,
-      leaseMs: this.leaseMs,
-    });
+    return this.owned(() =>
+      this.store.heartbeat({
+        taskId: this.task.id,
+        workerId: this.workerId,
+        leaseMs: this.leaseMs,
+      }),
+    );
   }
 
-  /** Cooperative cancel check. */
+  /** Cooperative cancel check. Free once a heartbeat has already seen the flag. */
   async canceled(): Promise<boolean> {
+    if (this.cancelSeen) return true;
     const t = await this.store.get(this.task.id);
     if (!t) return true;
-    return cancelRequested(t) || t.status === "canceled";
+    if (cancelRequested(t)) this.cancelSeen = true;
+    return this.cancelSeen || t.status === "canceled";
   }
 
   /** Submit a child task; parent/root/correlation are wired automatically. */

package/src/errors.ts

@@ -1,3 +1,6 @@
+import { nowMs } from "./ids.js";
+import { cancelRequested, isQueued, type Task } from "./models.js";
+
 /** The single shape of the JSON error envelope (see PROTOCOL.md). Everything that
  * records an error — a handler exception, a missing handler, lease expiry, a thrown
  * TaskError — builds it here, so the contract's fields live in one place. */
@@ -17,7 +20,15 @@ export function errorEnvelope(e: {
   };
 }
 
-export class CairnQError extends Error {}
+export class CairnQError extends Error {
+  constructor(message?: string) {
+    super(message);
+    // Subclasses each set their own; without this a bare CairnQError reports
+    // "Error", and `err.name` is how callers (and the conformance runner) tell
+    // one apart from another.
+    this.name = "CairnQError";
+  }
+}
 
 export class AlreadyExists extends CairnQError {
   constructor(public key: string) {
@@ -26,11 +37,44 @@ export class AlreadyExists extends CairnQError {
   }
 }
 
-/** wait/call did not reach a terminal status in time. The task keeps running. */
+/** One line of "why hasn't this finished" from the last snapshot wait()
+ * observed. No worker running, no handler for the name, wrong queue, and two
+ * processes on different database files all look identical from the API side —
+ * queued, never claimed — so that case names the likely causes. */
+function timeoutDetail(task: Task | null): string {
+  if (!task) return "task not found — wrong database file, or already purged?";
+  if (isQueued(task)) {
+    const delayMs = task.run_at_ms - nowMs();
+    if (task.attempt === 0 && delayMs <= 0) {
+      return (
+        `never claimed by a worker — is a worker running with a handler for ` +
+        `'${task.name}' on queue '${task.queue}', against this same database?`
+      );
+    }
+    const next = delayMs > 0 ? `, next run in ~${delayMs}ms` : "";
+    return `still queued (attempt ${task.attempt}/${task.max_attempts})${next}`;
+  }
+  if (cancelRequested(task)) return "cancel requested, waiting for the handler to observe it";
+  return `still running (attempt ${task.attempt}/${task.max_attempts})`;
+}
+
+/** wait/call did not reach a terminal status in time. The task keeps running.
+ * `task` is the last snapshot wait() observed (null if get() found nothing), and
+ * the message says what state it was stuck in — a queued-never-claimed task is
+ * the classic first-run failure (no worker, no handler, wrong queue or file). */
 export class TaskTimeout extends CairnQError {
-  constructor(public taskId: string) {
-    super(`task ${taskId} did not finish in time`);
+  readonly task: Task | null;
+  constructor(
+    public taskId: string,
+    opts: { timeoutMs?: number; task?: Task | null } = {},
+  ) {
+    super(
+      opts.timeoutMs == null
+        ? `task ${taskId} did not finish in time`
+        : `task ${taskId} did not finish within ${opts.timeoutMs}ms: ${timeoutDetail(opts.task ?? null)}`,
+    );
     this.name = "TaskTimeout";
+    this.task = opts.task ?? null;
   }
 }
 
@@ -81,6 +125,17 @@ export class ProtocolVersionMismatch extends CairnQError {
   }
 }
 
+/** 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
+ * `unserializable_result` failure. The Python SDK raises the same named error. */
+export class SerializationError extends CairnQError {
+  constructor(message: string) {
+    super(message);
+    this.name = "SerializationError";
+  }
+}
+
 /** Throw inside a handler to control how the failure is recorded. Defaults to
  * non-retryable so deterministic errors fail fast instead of burning retries.
  * Any other thrown value is treated as retryable. */

package/src/index.ts

@@ -7,7 +7,8 @@ export { defineTask } from "./task.js";
 export type { TaskDef } from "./task.js";
 export { SQLiteStore } from "./store/sqlite.js";
 export { PostgresStore } from "./store/postgres.js";
-export type { ListInput, SubmitInput, TaskStore, Conflict } from "./store/base.js";
+export { TaskStore } from "./store/base.js";
+export type { ListInput, PurgeInput, SubmitInput, Conflict } from "./store/base.js";
 export type { Task, TaskStatus } from "./models.js";
 export {
   STATUSES,
@@ -28,4 +29,5 @@ export {
   TaskError,
   LostLease,
   ProtocolVersionMismatch,
+  SerializationError,
 } from "./errors.js";

package/src/sql.ts

@@ -2,17 +2,22 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-// Locate the shared cairnq-protocol dir. Resolution: $CAIRNQ_PROTOCOL_DIR ->
-// vendored `_protocol/` next to this module -> walk up to `cairnq-protocol/`
-// (monorepo dev). Both SDKs load the SAME .sql strings (zero-drift guarantee).
-// The dir is laid out per-dialect (sql/<dialect>/*.sql, migrations/<dialect>/*.sql)
-// so a second backend (Postgres) slots in beside sqlite; `dialect` picks the subtree.
+// Locate the shared cairnq-protocol dir. Resolution: $CAIRNQ_PROTOCOL_DIR -> walk
+// up to `cairnq-protocol/` (monorepo dev) -> vendored `_protocol/` next to this
+// module (written at publish time). Both SDKs load the SAME .sql strings
+// (zero-drift guarantee). The dir is laid out per-dialect (sql/<dialect>/*.sql,
+// migrations/<dialect>/*.sql) so a second backend (Postgres) slots in beside
+// sqlite; `dialect` picks the subtree.
+//
+// The source tree wins over the vendored copy on purpose: vendoring is a publish
+// step that also runs locally, and a stale `_protocol/` shadowing the canonical
+// SQL means edits to cairnq-protocol/ are silently not under test. An installed
+// package has no repo above it, so it falls through to the vendored copy.
 export function findProtocolRoot(): string {
   const env = process.env.CAIRNQ_PROTOCOL_DIR;
   if (env) return env;
-  let dir = dirname(fileURLToPath(import.meta.url));
-  const vendored = join(dir, "_protocol");
-  if (existsSync(join(vendored, "sql"))) return vendored;
+  const start = dirname(fileURLToPath(import.meta.url));
+  let dir = start;
   for (let i = 0; i < 10; i++) {
     const candidate = join(dir, "cairnq-protocol");
     if (existsSync(join(candidate, "sql"))) return candidate;
@@ -20,6 +25,8 @@ export function findProtocolRoot(): string {
     if (parent === dir) break;
     dir = parent;
   }
+  const vendored = join(start, "_protocol");
+  if (existsSync(join(vendored, "sql"))) return vendored;
   throw new Error("cannot locate cairnq-protocol; set CAIRNQ_PROTOCOL_DIR");
 }