@cogenta/core 0.1.0

package/dist/queue/bullmq.js

@@ -0,0 +1,391 @@
+import { randomUUID } from 'node:crypto';
+import { CogentaError } from '../errors/index.js';
+import { createLogger } from '../logger/index.js';
+/**
+ * Loads bullmq if the host application installed it. Absent is a normal
+ * outcome, not an error: it is what makes a site without Redis fall back to the
+ * database queue instead of failing to boot.
+ */
+export async function loadBullmqModule() {
+    try {
+        return (await import('bullmq'));
+    }
+    catch {
+        return null;
+    }
+}
+const DEFAULT_PREFIX = 'cogenta:queue';
+const DEFAULT_LEASE_MS = 5 * 60 * 1000;
+const DEFAULT_BATCH_SIZE = 10;
+const DEFAULT_BACKOFF_MS = 1000;
+const DEFAULT_STALLED_INTERVAL_MS = 30_000;
+const DEFAULT_MAX_ATTEMPTS = 3;
+const PROBE_TIMEOUT_MS = 3000;
+/** The name of the queue that exists only to hold a connection for `ping`. */
+const CONTROL_QUEUE = '__cogenta_control';
+/**
+ * Cogenta says "higher priority runs first"; bullmq says "lower number runs
+ * first", and reserves 0 for "no priority at all". Mapping onto a mid-range
+ * origin keeps both signs of a Cogenta priority inside bullmq's 1..2097151
+ * window, and keeps every job prioritised so ordering never depends on which
+ * of the two internal lists a job landed in.
+ */
+const PRIORITY_ORIGIN = 1_048_576;
+const MAX_BULLMQ_PRIORITY = 2_097_151;
+function toBullmqPriority(priority) {
+    return Math.min(Math.max(PRIORITY_ORIGIN - Math.trunc(priority), 1), MAX_BULLMQ_PRIORITY);
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/**
+ * A Cogenta job id carries the job name, because bullmq shards by queue and a
+ * bare id says nothing about which queue to look in. The alternative — a second
+ * index in Redis — is state that can drift from the jobs it describes.
+ */
+function encodeJobId(name, jobId) {
+    return `${name}:${jobId}`;
+}
+function decodeJobId(id) {
+    const at = id.lastIndexOf(':');
+    if (at <= 0)
+        return null;
+    const jobId = id.slice(at + 1);
+    if (!UUID.test(jobId))
+        return null;
+    return { name: id.slice(0, at), jobId };
+}
+function toJobStatus(state) {
+    switch (state) {
+        case 'completed':
+            return 'completed';
+        case 'failed':
+            return 'failed';
+        case 'active':
+            return 'running';
+        // waiting, waiting-children, delayed, prioritized: all "not started yet".
+        default:
+            return 'pending';
+    }
+}
+/**
+ * The optimal job queue: Redis, driven through bullmq.
+ *
+ * Jobs are fetched by hand rather than by a bullmq `Worker` loop, because
+ * `QueueDriver.tick()` is the contract both drivers answer to — a site on shared
+ * hosting drives it from cron, and the same call has to mean the same thing
+ * here. bullmq documents this as the manual-fetching pattern, and it keeps the
+ * atomic claim (the L0 acceptance criterion) inside Redis where it belongs.
+ */
+export function createBullmqQueue(options) {
+    const { module, url } = options;
+    const now = options.now ?? Date.now;
+    const prefix = options.prefix ?? DEFAULT_PREFIX;
+    const leaseMs = options.leaseMs ?? DEFAULT_LEASE_MS;
+    const batchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;
+    const backoffMs = options.backoffMs ?? DEFAULT_BACKOFF_MS;
+    const stalledInterval = options.stalledIntervalMs ?? DEFAULT_STALLED_INTERVAL_MS;
+    const logger = (options.logger ?? createLogger()).child({ component: 'queue' });
+    const connection = { url };
+    const handlers = new Map();
+    const queues = new Map();
+    const workers = new Map();
+    /** Cancelled jobs, by id. bullmq has no cancelled state, so we keep our own. */
+    const tombstoneKey = `${prefix}:cancelled`;
+    function queueFor(name) {
+        const existing = queues.get(name);
+        if (existing !== undefined)
+            return existing;
+        const created = new module.Queue(name, { connection, prefix });
+        queues.set(name, created);
+        return created;
+    }
+    async function redis() {
+        return queueFor(CONTROL_QUEUE).getBackend().client;
+    }
+    async function workerFor(name) {
+        const existing = workers.get(name);
+        if (existing !== undefined)
+            return existing;
+        const created = new module.Worker(name, null, {
+            connection,
+            prefix,
+            autorun: false,
+            lockDuration: leaseMs,
+            stalledInterval,
+            // Nothing renews a lock here: `tick` holds it for the duration of one
+            // handler and then reports an outcome. A lock that outlives the process
+            // is exactly what the stalled checker is for.
+            skipLockRenewal: true,
+        });
+        workers.set(name, created);
+        // Manual fetching does not start the stalled checker, and without it a job
+        // whose worker was killed stays "active" forever — no other worker ever
+        // gets it back.
+        await created.startStalledCheckTimer();
+        return created;
+    }
+    async function runOne(job, token) {
+        const handler = handlers.get(job.name);
+        const id = encodeJobId(job.name, job.id ?? '');
+        const maxAttempts = job.opts.attempts ?? DEFAULT_MAX_ATTEMPTS;
+        if (handler === undefined) {
+            // Unreachable in practice: a worker only exists for a registered name.
+            // Releasing the job is still better than holding a lock we cannot honour.
+            await job.moveToFailed(new Error(`No handler for jobs named "${job.name}".`), token, false);
+            return;
+        }
+        const decoded = {
+            id,
+            name: job.name,
+            payload: job.data.payload,
+            // bullmq counts attempts that finished; this one is in flight.
+            attempt: job.attemptsMade + 1,
+            maxAttempts,
+        };
+        try {
+            await handler(decoded);
+            await job.moveToCompleted(null, token, false);
+        }
+        catch (error) {
+            const failure = error instanceof Error ? error : new Error(String(error));
+            await job.moveToFailed(failure, token, false);
+            const exhausted = decoded.attempt >= maxAttempts;
+            logger.warn(exhausted ? 'job failed for good' : 'job failed, will retry', {
+                id,
+                name: job.name,
+                attempt: decoded.attempt,
+                maxAttempts,
+            });
+        }
+    }
+    return {
+        enqueue: async (enqueueOptions) => {
+            if (enqueueOptions.name.length === 0) {
+                throw new CogentaError({
+                    code: 'QUEUE_FAILED',
+                    message: 'A job must have a name.',
+                    hint: 'The name is what routes the job to a handler registered with process().',
+                });
+            }
+            const jobId = randomUUID();
+            const delay = Math.max(0, (enqueueOptions.runAt ?? now()) - now());
+            await queueFor(enqueueOptions.name).add(enqueueOptions.name, { payload: enqueueOptions.payload ?? null }, {
+                jobId,
+                priority: toBullmqPriority(enqueueOptions.priority ?? 0),
+                attempts: enqueueOptions.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
+                backoff: { type: 'exponential', delay: backoffMs },
+                ...(delay > 0 ? { delay } : {}),
+            });
+            return encodeJobId(enqueueOptions.name, jobId);
+        },
+        process: (name, handler) => {
+            if (handlers.has(name)) {
+                throw new CogentaError({
+                    code: 'QUEUE_FAILED',
+                    message: `A handler is already registered for jobs named "${name}".`,
+                    hint: 'One handler per job name. Register a different name, or compose inside the existing handler.',
+                });
+            }
+            handlers.set(name, handler);
+        },
+        tick: async () => {
+            let handled = 0;
+            // Only names this process registered are fetched, so two workers with
+            // different handlers each take their own work instead of locking jobs
+            // they would have to put back.
+            for (const name of handlers.keys()) {
+                const worker = await workerFor(name);
+                while (handled < batchSize) {
+                    // A fresh token per job: it is the lock's owner, and it has to be
+                    // presented again to report the outcome.
+                    const token = randomUUID();
+                    const job = await worker.getNextJob(token, { block: false });
+                    if (job === undefined || job === null)
+                        break;
+                    handled += 1;
+                    await runOne(job, token);
+                }
+                if (handled >= batchSize)
+                    break;
+            }
+            return handled;
+        },
+        cancel: async (id) => {
+            const parsed = decodeJobId(id);
+            if (parsed === null)
+                return;
+            const job = await queueFor(parsed.name).getJob(parsed.jobId);
+            if (job === undefined)
+                return;
+            const state = toJobStatus(await job.getState());
+            // A running job is left alone: cancelling it here would only lose track of
+            // work that is still happening in another process.
+            if (state !== 'pending')
+                return;
+            const tombstone = {
+                id,
+                name: job.name,
+                status: 'cancelled',
+                attempt: job.attemptsMade,
+                maxAttempts: job.opts.attempts ?? DEFAULT_MAX_ATTEMPTS,
+                runAt: job.timestamp + job.delay,
+                lastError: undefined,
+            };
+            // Written before the removal: a crash between the two leaves a job that
+            // reads as cancelled and is gone, never one that reads as alive and is not.
+            const client = await redis();
+            await client.hset(tombstoneKey, id, JSON.stringify(tombstone));
+            await job.remove();
+        },
+        status: async (id) => {
+            const parsed = decodeJobId(id);
+            if (parsed === null)
+                return null;
+            const client = await redis();
+            const tombstone = await client.hget(tombstoneKey, id);
+            if (tombstone !== null)
+                return JSON.parse(tombstone);
+            const job = await queueFor(parsed.name).getJob(parsed.jobId);
+            if (job === undefined)
+                return null;
+            const failedReason = job.failedReason;
+            return {
+                id,
+                name: job.name,
+                status: toJobStatus(await job.getState()),
+                attempt: job.attemptsMade,
+                maxAttempts: job.opts.attempts ?? DEFAULT_MAX_ATTEMPTS,
+                runAt: job.timestamp + job.delay,
+                lastError: failedReason === undefined || failedReason === '' ? undefined : failedReason,
+            };
+        },
+        close: async () => {
+            handlers.clear();
+            // Workers first: each holds a blocking connection, and closing the queues
+            // underneath it turns a clean shutdown into a pile of connection errors.
+            for (const worker of workers.values())
+                await worker.close();
+            workers.clear();
+            for (const queue of queues.values())
+                await queue.close();
+            queues.clear();
+        },
+    };
+}
+/** Redis URLs carry a password. Nothing derived from one reaches an operator. */
+function withoutUrl(message) {
+    return message.replace(/rediss?:\/\/\S+/gi, '<redis url>');
+}
+async function withDeadline(work, ms) {
+    let timer;
+    try {
+        return await Promise.race([
+            work,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error('Redis did not answer in time.')), ms);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+export function bullmqQueueDriver(options = {}) {
+    const prefix = options.prefix ?? DEFAULT_PREFIX;
+    let instance;
+    let probe;
+    async function loadOrThrow() {
+        const module = await loadBullmqModule();
+        if (module === null) {
+            throw new CogentaError({
+                code: 'DRIVER_INIT_FAILED',
+                message: 'The Redis queue driver needs the "bullmq" package.',
+                hint: 'Run `pnpm add bullmq`, or leave queue.driver unset to use the database queue.',
+            });
+        }
+        return module;
+    }
+    return {
+        name: 'bullmq',
+        tier: 'optimal',
+        // Does Redis actually answer? Not "is a URL configured?" — the difference is
+        // what turns a graceful fallback into a startup crash.
+        available: async (config) => {
+            if (config.url === undefined)
+                return false;
+            const module = await loadBullmqModule();
+            if (module === null)
+                return false;
+            // `retryStrategy` returning null tells ioredis to give up instead of
+            // reconnecting forever, which is what makes an absent Redis answer "no"
+            // rather than hang. The working connection keeps the default.
+            const attempt = new module.Queue(CONTROL_QUEUE, {
+                connection: { url: config.url, retryStrategy: () => null },
+                prefix,
+            });
+            try {
+                const client = await withDeadline(attempt.getBackend().client, PROBE_TIMEOUT_MS);
+                await withDeadline(client.ping(), PROBE_TIMEOUT_MS);
+                return true;
+            }
+            catch {
+                return false;
+            }
+            finally {
+                await attempt.close().catch(() => undefined);
+            }
+        },
+        init: async (config) => {
+            const module = await loadOrThrow();
+            const { url } = config;
+            if (url === undefined) {
+                throw new CogentaError({
+                    code: 'DRIVER_INIT_FAILED',
+                    message: 'The Redis queue driver needs a connection URL.',
+                    hint: 'Set queue.url (or REDIS_URL), or leave queue.driver unset to use the database queue.',
+                });
+            }
+            probe ??= new module.Queue(CONTROL_QUEUE, { connection: { url }, prefix });
+            instance ??= createBullmqQueue({ ...options, module, url });
+            return instance;
+        },
+        dispose: async () => {
+            try {
+                await instance?.close();
+                await probe?.close();
+            }
+            catch {
+                // Shutdown must not fail because the connection already dropped.
+            }
+            instance = undefined;
+            probe = undefined;
+        },
+        health: async () => {
+            if (probe === undefined) {
+                return { status: 'down', driver: 'bullmq', tier: 'optimal', message: 'Not connected.' };
+            }
+            const startedAt = Date.now();
+            try {
+                const client = await withDeadline(probe.getBackend().client, PROBE_TIMEOUT_MS);
+                await withDeadline(client.ping(), PROBE_TIMEOUT_MS);
+                return {
+                    status: 'ok',
+                    driver: 'bullmq',
+                    tier: 'optimal',
+                    latencyMs: Date.now() - startedAt,
+                    // The URL is not reported: it routinely carries a password.
+                    message: 'Connected.',
+                };
+            }
+            catch (error) {
+                return {
+                    status: 'down',
+                    driver: 'bullmq',
+                    tier: 'optimal',
+                    message: withoutUrl(error instanceof Error ? error.message : 'Redis did not answer.'),
+                };
+            }
+        },
+    };
+}
+//# sourceMappingURL=bullmq.js.map

package/dist/queue/bullmq.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bullmq.js","sourceRoot":"","sources":["../../src/queue/bullmq.ts"],"names":[],"mappings":"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"}

package/dist/queue/database.d.ts

@@ -0,0 +1,17 @@
+import { type DatabaseHandle } from '../db/index.js';
+import { type Logger } from '../logger/index.js';
+import type { QueueDriver, QueueDriverOptions } from './types.js';
+export interface DatabaseQueueOptions extends QueueDriverOptions {
+    readonly db: DatabaseHandle;
+    readonly logger?: Logger;
+}
+/**
+ * The degraded job queue: a SQL table, drained by whoever calls `tick()` — a
+ * system cron on shared hosting, a loop in a long-lived process elsewhere.
+ *
+ * Its whole reason to exist is rule R1: a Cogenta install must work with no
+ * Redis and no persistent worker. That makes correctness under concurrency
+ * non-negotiable, because this is the driver most sites will actually run.
+ */
+export declare function createDatabaseQueue(options: DatabaseQueueOptions): QueueDriver;
+//# sourceMappingURL=database.d.ts.map

package/dist/queue/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/queue/database.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,cAAc,EAMpB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAC9D,OAAO,KAAK,EAMV,WAAW,EACX,kBAAkB,EACnB,MAAM,YAAY,CAAA;AAOnB,MAAM,WAAW,oBAAqB,SAAQ,kBAAkB;IAC9D,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAA;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAkCD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,WAAW,CAiP9E"}

package/dist/queue/database.js

@@ -0,0 +1,242 @@
+import { randomUUID } from 'node:crypto';
+import process from 'node:process';
+import { identifier, limit, sql, unsafeRaw, } from '../db/index.js';
+import { CogentaError } from '../errors/index.js';
+import { createLogger } from '../logger/index.js';
+const TABLE = 'cogenta_jobs';
+const DEFAULT_LEASE_MS = 5 * 60 * 1000;
+const DEFAULT_BATCH_SIZE = 10;
+const MAX_BACKOFF_MS = 60_000;
+/** Exponential, capped. A failing job must not retry in a tight loop. */
+function backoffMs(attempt) {
+    return Math.min(2 ** attempt * 1000, MAX_BACKOFF_MS);
+}
+const CLAIM_ATTEMPTS = 5;
+/**
+ * Deadlocks and serialisation failures are normal under contention, not bugs.
+ *
+ * InnoDB detects a cycle between two claim transactions and kills one of them;
+ * Postgres reports a serialisation failure for the same situation. Both
+ * databases document the remedy as "retry the transaction", so that is what the
+ * claim does — silently, because a worker losing a race is not an incident.
+ */
+function isRetryableConflict(error) {
+    const code = error.cause?.code ?? '';
+    if (code === 'ER_LOCK_DEADLOCK' || code === '40001' || code === '40P01')
+        return true;
+    return /deadlock|could not serialize/i.test(error instanceof Error ? error.message : String(error));
+}
+/**
+ * The degraded job queue: a SQL table, drained by whoever calls `tick()` — a
+ * system cron on shared hosting, a loop in a long-lived process elsewhere.
+ *
+ * Its whole reason to exist is rule R1: a Cogenta install must work with no
+ * Redis and no persistent worker. That makes correctness under concurrency
+ * non-negotiable, because this is the driver most sites will actually run.
+ */
+export function createDatabaseQueue(options) {
+    const { db } = options;
+    const now = options.now ?? Date.now;
+    const leaseMs = options.leaseMs ?? DEFAULT_LEASE_MS;
+    const batchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;
+    const logger = (options.logger ?? createLogger()).child({ component: 'queue' });
+    const worker = `${process.pid}-${randomUUID().slice(0, 8)}`;
+    const handlers = new Map();
+    const table = identifier(TABLE, db.dialect);
+    let ready = false;
+    // Postgres, MySQL 8 and MariaDB 10.6+ can skip rows another transaction has
+    // locked. SQLite cannot, and does not need to: BEGIN IMMEDIATE serialises
+    // writers, so only one claim runs at a time.
+    const skipLocked = db.dialect === 'sqlite' ? unsafeRaw('') : unsafeRaw('for update skip locked');
+    async function ensureTable() {
+        if (ready)
+            return;
+        await db.query(sql `
+      create table if not exists ${table} (
+        id varchar(64) not null primary key,
+        name varchar(255) not null,
+        payload text,
+        status varchar(16) not null,
+        attempt integer not null,
+        max_attempts integer not null,
+        priority integer not null,
+        run_at bigint not null,
+        locked_until bigint,
+        locked_by varchar(255),
+        last_error text
+      )`);
+        // The index the claim query lives on. Without it, every tick scans the
+        // whole table, which is fine at ten jobs and fatal at a hundred thousand.
+        await db
+            .query(sql `create index ${identifier('cogenta_jobs_claim', db.dialect)}
+            on ${table} (status, run_at)`)
+            .catch(() => undefined); // already there
+        ready = true;
+    }
+    async function claim(names) {
+        for (let attempt = 1;; attempt += 1) {
+            try {
+                return await claimOnce(names);
+            }
+            catch (error) {
+                if (attempt >= CLAIM_ATTEMPTS || !isRetryableConflict(error))
+                    throw error;
+                logger.debug('claim lost a race, retrying', { attempt });
+            }
+        }
+    }
+    async function claimOnce(names) {
+        if (names.length === 0)
+            return [];
+        const at = now();
+        const nameList = names.map((name) => sql `${name}`);
+        const inList = nameList.reduce((left, right) => sql `${left}, ${right}`);
+        return db.transaction(async (tx) => {
+            const found = await tx.query(sql `
+          select id, name, payload, attempt, max_attempts
+          from ${table}
+          where status = ${'pending'}
+            and run_at <= ${at}
+            and name in (${inList})
+          order by priority desc, run_at asc
+          limit ${limit(batchSize)}
+          ${skipLocked}`);
+            const claimed = [];
+            for (const row of found.rows) {
+                const attempt = Number(row.attempt) + 1;
+                const updated = await tx.query(sql `
+            update ${table}
+            set status = ${'running'},
+                attempt = ${attempt},
+                locked_by = ${worker},
+                locked_until = ${at + leaseMs}
+            where id = ${row.id} and status = ${'pending'}`);
+                // On SQLite the write lock makes this always true. Elsewhere it is the
+                // second gate: if another worker got there first, we skip the job
+                // rather than run it twice.
+                if (updated.rowsAffected === 0)
+                    continue;
+                claimed.push({
+                    id: row.id,
+                    name: row.name,
+                    payload: row.payload === null ? null : JSON.parse(row.payload),
+                    attempt,
+                    maxAttempts: Number(row.max_attempts),
+                });
+            }
+            return claimed;
+        }, { immediate: true });
+    }
+    /** Returns an expired lease to the pool: the worker holding it is gone. */
+    async function reclaimExpired() {
+        await db.query(sql `
+      update ${table}
+      set status = ${'pending'}, locked_by = ${null}, locked_until = ${null}
+      where status = ${'running'} and locked_until is not null and locked_until <= ${now()}`);
+    }
+    async function succeed(job) {
+        await db.query(sql `
+      update ${table}
+      set status = ${'completed'}, locked_by = ${null}, locked_until = ${null}
+      where id = ${job.id}`);
+    }
+    async function fail(job, error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const exhausted = job.attempt >= job.maxAttempts;
+        await db.query(sql `
+      update ${table}
+      set status = ${exhausted ? 'failed' : 'pending'},
+          run_at = ${exhausted ? now() : now() + backoffMs(job.attempt)},
+          locked_by = ${null},
+          locked_until = ${null},
+          last_error = ${message}
+      where id = ${job.id}`);
+        logger.warn(exhausted ? 'job failed for good' : 'job failed, will retry', {
+            id: job.id,
+            name: job.name,
+            attempt: job.attempt,
+            maxAttempts: job.maxAttempts,
+        });
+    }
+    return {
+        enqueue: async (enqueueOptions) => {
+            await ensureTable();
+            if (enqueueOptions.name.length === 0) {
+                throw new CogentaError({
+                    code: 'QUEUE_FAILED',
+                    message: 'A job must have a name.',
+                    hint: 'The name is what routes the job to a handler registered with process().',
+                });
+            }
+            const id = randomUUID();
+            await db.query(sql `
+        insert into ${table} (id, name, payload, status, attempt, max_attempts, priority, run_at)
+        values (${id}, ${enqueueOptions.name},
+                ${JSON.stringify(enqueueOptions.payload ?? null)},
+                ${'pending'}, ${0}, ${enqueueOptions.maxAttempts ?? 3},
+                ${enqueueOptions.priority ?? 0}, ${enqueueOptions.runAt ?? now()})`);
+            return id;
+        },
+        process: (name, handler) => {
+            if (handlers.has(name)) {
+                throw new CogentaError({
+                    code: 'QUEUE_FAILED',
+                    message: `A handler is already registered for jobs named "${name}".`,
+                    hint: 'One handler per job name. Register a different name, or compose inside the existing handler.',
+                });
+            }
+            handlers.set(name, handler);
+        },
+        tick: async () => {
+            await ensureTable();
+            await reclaimExpired();
+            // Only jobs this process can actually handle are claimed. Two workers with
+            // different handlers each take their own work instead of locking jobs they
+            // would have to put back.
+            const claimed = await claim([...handlers.keys()]);
+            for (const job of claimed) {
+                const handler = handlers.get(job.name);
+                if (handler === undefined)
+                    continue;
+                try {
+                    await handler(job);
+                    await succeed(job);
+                }
+                catch (error) {
+                    await fail(job, error);
+                }
+            }
+            return claimed.length;
+        },
+        cancel: async (id) => {
+            await ensureTable();
+            // A running job is left alone: cancelling it here would only lose track of
+            // work that is still happening in another process.
+            await db.query(sql `
+        update ${table} set status = ${'cancelled'}
+        where id = ${id} and status = ${'pending'}`);
+        },
+        status: async (id) => {
+            await ensureTable();
+            const result = await db.query(sql `
+        select id, name, status, attempt, max_attempts, run_at, last_error
+        from ${table} where id = ${id}`);
+            const row = result.rows[0];
+            if (row === undefined)
+                return null;
+            return {
+                id: row.id,
+                name: row.name,
+                status: row.status,
+                attempt: Number(row.attempt),
+                maxAttempts: Number(row.max_attempts),
+                runAt: Number(row.run_at),
+                lastError: row.last_error ?? undefined,
+            };
+        },
+        close: async () => {
+            handlers.clear();
+        },
+    };
+}
+//# sourceMappingURL=database.js.map