cairnq 0.1.0 → 0.3.0

package/dist/store/sqlite.d.ts

@@ -1,20 +1,40 @@
-import { type Task } from "../models.js";
-import type { ListInput, SubmitInput, TaskStore } from "./base.js";
+import { type Fetch, type Params, TaskStore } from "./base.js";
 /**
- * SQLiteStore — better-sqlite3 backend executing the shared cairnq-protocol SQL.
+ * SQLiteStore — the SQLite dialect of the shared cairnq-protocol SQL.
  *
- * The driver is synchronous, which suits SQLite's single writer: claim is one
- * short transaction, the handler runs outside any transaction, and
- * progress/heartbeat/succeed/fail are each their own short write. JS being
- * single-threaded means sync DB calls never interleave. Cross-process contention
- * (deployment mode B) is absorbed by busy_timeout.
+ * Everything protocol-shaped lives in TaskStore; this file is only what SQLite
+ * does differently: better-sqlite3's synchronous driver, BEGIN IMMEDIATE
+ * transactions, a read-only probe in front of the write lock, and time supplied
+ * by the SDK (`:now_ms`) rather than by the database.
+ *
+ * The driver being synchronous suits SQLite's single writer: claim is one short
+ * transaction, the handler runs outside any transaction, and
+ * progress/heartbeat/succeed/fail are each their own short write.
+ *
+ * Cross-process contention is absorbed by retrying in JavaScript, not by
+ * busy_timeout. The two cost the same wait but not the same blocking: a nonzero
+ * busy_timeout waits *inside* the synchronous driver, so a caller that loses the
+ * write lock stalls this process's event loop for up to the whole timeout — the
+ * P99 of an HTTP server that submits tasks. Executing a statement takes
+ * microseconds; waiting for a lock takes milliseconds to seconds, and only the
+ * second part needs to happen off the thread. So busy_timeout goes to 0 (fail
+ * immediately) and the wait becomes an awaited backoff, which the event loop runs
+ * through. The budget is the same either way — `busyTimeoutMs`.
+ *
+ * The open path keeps a real busy_timeout: it is synchronous by nature (WAL
+ * switch, migrations) and happens once, under the caller's `connect()`.
  */
-export declare class SQLiteStore implements TaskStore {
+export declare class SQLiteStore extends TaskStore {
     private readonly path;
-    private readonly opts;
     private db;
     private stmts;
     private readonly statements;
+    /** This store's entry in `fileLocks` — see there for why it is per-database. */
+    private readonly lockKey;
+    /** How long a single operation may keep retrying a lost write lock. */
+    private readonly busyBudgetMs;
+    /** When this connection may next revisit its planner statistics. */
+    private nextStatsRefreshAt;
     constructor(path: string, opts?: {
         busyTimeoutMs?: number;
     });
@@ -22,56 +42,59 @@ export declare class SQLiteStore implements TaskStore {
     close(): Promise<void>;
     private ensure;
     private applyMigrations;
-    private checkVersion;
     private readProtocolVersion;
     protocolVersion(): Promise<number>;
-    private all;
-    private run;
-    private ownedWrite;
-    submit(input: SubmitInput): Promise<Task>;
-    get(taskId: string): Promise<Task | null>;
-    getByKey(key: string): Promise<Task | null>;
-    list(input?: ListInput): Promise<Task[]>;
-    cancel(taskId: string): Promise<Task | null>;
-    cancelByKey(key: string): Promise<Task | null>;
-    retry(taskId: string, opts?: {
-        resetAttempt?: boolean;
-    }): Promise<Task | null>;
-    retryByKey(key: string, opts?: {
-        resetAttempt?: boolean;
-    }): Promise<Task | null>;
-    claim(input: {
-        queues: string[];
-        workerId: string;
-        leaseMs?: number;
-        limit?: number;
-    }): Promise<Task[]>;
-    heartbeat(input: {
-        taskId: string;
-        workerId: string;
-        leaseMs?: number;
-    }): Promise<Task>;
-    progress(input: {
-        taskId: string;
-        workerId: string;
-        progress: number | null;
-        message: string | null;
-    }): Promise<Task>;
-    succeed(input: {
-        taskId: string;
-        workerId: string;
-        result: unknown;
-    }): Promise<Task>;
-    complete(input: {
-        taskId: string;
-        workerId: string;
-        result: unknown;
-    }): Promise<Task>;
-    fail(input: {
-        taskId: string;
-        workerId: string;
-        error: unknown;
-        retryable?: boolean;
-        delayMs?: number;
-    }): Promise<Task>;
+    /**
+     * Adapt the dialect-neutral parameters to what this statement binds.
+     *
+     * SQLite statements carry no DB clock, so every absolute `*_ms` is derived here
+     * from one `now`, and booleans cross as 0/1. The result is narrowed to the
+     * names the SQL actually uses, which is what makes it safe for a caller to pass
+     * one superset of parameters for both dialects.
+     *
+     * Each derivation writes a name Postgres does not use (`lease_until_ms` from
+     * `lease_ms`, and so on), so a statement binds one or the other, never both —
+     * which is why the derived values can be computed unconditionally and left for
+     * the narrowing step to discard.
+     */
+    private bind;
+    private runNow;
+    /** Queue an operation behind every other operation on this database. */
+    private enqueue;
+    /**
+     * Serialize an operation against this database, waiting out a lost write lock on
+     * a jittered backoff. Replaces busy_timeout's synchronous wait (see the class
+     * comment); on exhausting the budget the original SQLITE_BUSY surfaces, which is
+     * what a nonzero busy_timeout would have thrown too.
+     *
+     * Each attempt re-queues rather than backing off while holding its turn: the
+     * contention left to retry is cross-process, and under WAL a *reader* never sees
+     * SQLITE_BUSY at all — so sleeping in place would stall this process's reads
+     * (including the worker's own poll) on a lock they were never waiting for.
+     *
+     * Retrying is safe because an attempt is one statement, or one transaction that
+     * has already rolled back: nothing partially applied survives it. `fn` may
+     * therefore run more than once and must not carry effects of its own — the
+     * callers in TaskStore build their ids and payloads before opening one.
+     */
+    private withLock;
+    /**
+     * Revisit this connection's planner statistics, at most once per
+     * STATS_REFRESH_INTERVAL_MS.
+     *
+     * A connection lives for days, and the statements were prepared against whatever
+     * the table looked like when it opened — a worker started against an empty
+     * database plans as if it were still empty however large the backlog grows. The
+     * prepared statements do pick the refreshed plans up: ANALYZE bumps the schema
+     * cookie, so SQLite silently re-prepares them on next use. That is what makes
+     * this worth doing rather than a restart-only concern.
+     *
+     * Queued rather than run under `withLock`: statistics are best-effort, so losing
+     * the write lock to another process should cost nothing — skip and let the next
+     * interval try, instead of spending an operation's whole retry budget on them.
+     */
+    private maybeRefreshStatistics;
+    protected fetch(name: string, params: Params): Promise<any[]>;
+    protected tx<T>(fn: (fetch: Fetch) => Promise<T>): Promise<T>;
+    protected hasClaimableWork(params: Params): Promise<boolean>;
 }