@rebasepro/server 0.24.0 → 0.24.1-canary.g56af4a4

package/dist/init/shutdown.d.ts

@@ -14,9 +14,13 @@ interface ShutdownConfig {
     rlsAudit?: {
         stop(): void;
     };
-    /** The expired-token sweep's timer. */
+    /** The expired-token sweep: its timer, and the tick it may have running. */
     authTokenSweep?: {
-        stop(): void;
+        stop(): Promise<void> | void;
+    };
+    /** The history retention sweep: its timer, and the sweep it may have running. */
+    historyRetentionSweep?: {
+        stop(): Promise<void> | void;
     };
     /** The stop `MetricsHistory.start()` returned: its interval writes to the pool. */
     stopMetricsSampler?: () => void;
@@ -27,6 +31,12 @@ interface ShutdownConfig {
      * one of these left open held the shutdown to its force timeout.
      */
     closeLongLivedResponses?: () => void;
+    /**
+     * The email service, when one is configured. A pooled SMTP transport keeps
+     * its connections open between sends; one with a `close()` is closed once
+     * nothing else can send, rather than left for its idle timer.
+     */
+    emailService?: object;
 }
 /**
  * Minimal structural view of the backend instance needed by

package/dist/init.d.ts

@@ -23,7 +23,15 @@ export interface LiveSchemaConfig extends SchemaEditPolicy {
      * read from the repository, rewritten, and committed back through the Git
      * Data API — no clone, no working tree.
      *
-     * Absent, live schema editing needs the project mounted and says so.
+     * Configuring it is the opt-in for a deployment with no source of its own:
+     * live editing then works under `NODE_ENV=production` and with
+     * `schemaEditor: false` (which a bundle boots with), because the write
+     * goes to this repository and never to the files beside the process. The
+     * collections directory is read from it whole, so a relation can name
+     * another collection and a deletion can check its importers.
+     *
+     * Absent, live schema editing needs the project mounted and says so. A
+     * bundle sets it from `REBASE_LIVE_SCHEMA_REPOSITORY` and its credential.
      */
     repository?: RemoteRepositoryConfig;
 }
@@ -377,10 +385,12 @@ export interface RebaseBackendConfig {
     /**
      * Live schema editing — changing the database and committing the change.
      *
-     * Distinct from `schemaEditor`, which only rewrites collection source.
-     * There is nothing to switch on here: the surface mounts whenever there is
-     * a `collectionsDir`, and refuses in its own words when it cannot act. What
-     * this configures is *who* may act.
+     * Distinct from `schemaEditor`, which only rewrites collection source on
+     * this machine. Without a `repository`, live editing writes through that
+     * editor, so it is on exactly where the editor is. With one, it is on
+     * whatever `schemaEditor` and `NODE_ENV` say — that is the opt-in for a
+     * built bundle, which has no source to edit locally (see
+     * {@link LiveSchemaConfig.repository}). Either way it is admin-only.
      */
     liveSchema?: LiveSchemaConfig;
     /** Options that only apply when collections are derived from the database. */
@@ -835,7 +845,7 @@ export interface RebaseBackendInstance {
      * ```ts
      * const { jobQueue } = await initializeRebaseBackend({ jobs: { enabled: true } });
      * const dispatcher = new WebhookDispatcher({ jobQueue });
-     * jobQueue?.register(WEBHOOK_DELIVERY_TASK, ctx => dispatcher.deliverQueuedJob(ctx.payload));
+     * jobQueue?.register(WEBHOOK_DELIVERY_TASK, ctx => dispatcher.deliverQueuedJob(ctx.payload, ctx));
      * ```
      */
     jobQueue?: import("./jobs/index.js").JobQueue;

package/dist/internal-tables-L2t39RdT.js

@@ -0,0 +1,136 @@
+import { createRequire as __rebaseCreateRequire } from "module";
+import __rebaseProcess from "process";
+globalThis.process ??= __rebaseProcess;
+__rebaseCreateRequire(import.meta.url);
+//#region ../common/src/util/internal-tables.ts
+/**
+* The tables Rebase creates for its own bookkeeping, and the SQL that keeps the
+* end-user role away from them.
+*
+* ## Why this exists
+*
+* Authenticated requests run as {@link REBASE_USER_ROLE}, and the boot-time role
+* provisioning grants that role `SELECT, INSERT, UPDATE, DELETE` on every table
+* in the schemas a project uses — including `rebase`, because a project's own
+* collections are allowed to live there (the scaffold puts `users` there). It
+* also sets `ALTER DEFAULT PRIVILEGES`, so a table created *later* by the
+* migrating role inherits the same grant.
+*
+* Every framework-internal table is created later: auth's tables come up during
+* `initializeAuth`, `api_keys` during route mounting, `cron_logs` when the first
+* job registers, `idempotency_keys` on the first request that carries a key. So
+* they all inherited full DML for the end-user role — and none of them enables
+* row-level security, because none of them is a collection with
+* `securityRules`. Measured on a freshly provisioned database, `SET ROLE
+* rebase_user` could read `rebase.refresh_tokens` (session token hashes),
+* `rebase.mfa_factors` (`secret_encrypted`), `rebase.recovery_codes`, and
+* `rebase.api_keys` (including its `admin` flag), and insert into
+* `rebase.app_config`.
+*
+* Nothing routes a user-context query at those tables today, so this was not
+* reachable over the API. That is the wrong thing to depend on: the documented
+* model is that RLS is the authorization boundary, and these tables sat outside
+* it. The boundary is now a privilege boundary instead — the role simply cannot
+* address them.
+*
+* ## Why REVOKE rather than ENABLE ROW LEVEL SECURITY
+*
+* RLS with no policy denies every row, which is the same outcome, but it is the
+* *weaker* statement: it leaves the grant in place, so a later policy — or a
+* `FORCE` flag cleared by some future migration — reopens the table. There is no
+* row of `refresh_tokens` any end user should ever reach, so the honest encoding
+* is "this role has no privilege here at all". It also keeps the owner
+* connection (which auth actually runs on) completely unaffected.
+*
+* ## Keeping it true
+*
+* `packages/rls-check` scans the `rebase` schema — it used to skip it as a
+* "platform" schema — and its `rls-disabled` check fires on exactly the
+* condition this module removes: RLS off *and* a DML grant to a reachable role.
+* So a table added here without a revoke is caught by `pnpm rls:check`, not by
+* someone re-reading this file.
+*/
+/**
+* The Postgres role authenticated requests run as.
+*
+* Defined here rather than in the Postgres driver because both the driver (which
+* provisions the role) and this module (which revokes on its behalf) need it,
+* and a second spelling of a role name is a silent no-op waiting to happen.
+*/
+var REBASE_USER_ROLE = "rebase_user";
+/** Postgres identifiers this module is willing to interpolate. */
+var SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+/**
+* A single statement that takes every privilege on `schema.table` away from the
+* end-user role.
+*
+* Wrapped in a `DO` block guarded on `pg_roles` for two reasons, both of which
+* happen in practice:
+*
+*  - the role does not exist when the connection is unprivileged (Rebase then
+*    relies on native RLS rather than a role switch), and a bare `REVOKE` on a
+*    missing role is an error, not a no-op;
+*  - the table may not exist yet — `cron_logs` never appears in a project with
+*    no cron jobs — and `to_regclass` returning NULL has to be tolerated too.
+*
+* The third guard is the one that decides whether the *right* table is being
+* revoked. The names in {@link REBASE_INTERNAL_TABLES} are unqualified, and the
+* boot-time sweep in `ensureAppRole` applies all of them to every schema a
+* project uses — including the schema its own collections live in. A project is
+* free to call a collection `jobs`, `branches` or `api_keys`, and when it does,
+* the sweep was revoking `rebase_user`'s DML on the project's table on every
+* single boot. That is not a subtle degradation: the collection's whole API
+* answers 500 `permission denied for table …` from then on, which is what
+* happened to a public job board whose vacancies live in `public.jobs`.
+*
+* `relrowsecurity` separates the two cleanly, and it is the same fact this
+* module already relies on. Framework-internal tables carry no RLS — that is the
+* premise stated at the top of this file, and the reason a revoke is needed at
+* all. Every collection table has it enabled, because that is how Rebase
+* enforces `securityRules`. So "RLS is off" is exactly "this is not somebody's
+* collection", and the guard also subsumes the hand-carved `users` exception:
+* the auth user table is a collection, has RLS, and would now be skipped on its
+* own merits rather than by being kept off a list.
+*
+* The fourth guard is about cost, and leaves the end state exactly as it was:
+* the `REVOKE` runs only when it would change something. A `REVOKE` rewrites the
+* table's `pg_class` row whether or not anything was granted, which invalidates
+* every cached plan that touches the table on every connection. Every store
+* that owns an internal table runs this on every boot. So it is skipped when the
+* end-user role holds nothing on the table — no entry in its ACL or in any
+* column's ACL — and the ACL has been written. A table whose ACL has never been
+* written (`relacl` NULL) is still revoked once: the `REVOKE` writes the owner's
+* default ACL out, exactly as before, and from then on it is skipped.
+*
+* One command, so it is safe on handles that speak the extended query protocol
+* and reject multi-statement strings.
+*/
+function revokeInternalTableSql(schema, table) {
+	if (!SAFE_IDENTIFIER.test(schema)) throw new Error(`Refusing to build SQL with an unsafe schema name: ${JSON.stringify(schema)}`);
+	if (!SAFE_IDENTIFIER.test(table)) throw new Error(`Refusing to build SQL with an unsafe table name: ${JSON.stringify(table)}`);
+	const qualified = `"${schema}"."${table}"`;
+	const role = `(SELECT oid FROM pg_roles WHERE rolname = '${REBASE_USER_ROLE}')`;
+	return `
+        DO $rebase_revoke$
+        BEGIN
+            IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = '${REBASE_USER_ROLE}')
+               AND to_regclass('${qualified}') IS NOT NULL
+               AND NOT (SELECT relrowsecurity FROM pg_class WHERE oid = to_regclass('${qualified}'))
+               AND (
+                   (SELECT relacl IS NULL FROM pg_class WHERE oid = to_regclass('${qualified}'))
+                   OR EXISTS (SELECT 1 FROM pg_class c, aclexplode(c.relacl) a
+                              WHERE c.oid = to_regclass('${qualified}') AND a.grantee = ${role})
+                   OR EXISTS (SELECT 1 FROM pg_attribute att, aclexplode(att.attacl) a
+                              WHERE att.attrelid = to_regclass('${qualified}') AND att.attacl IS NOT NULL
+                                AND a.grantee = ${role})
+               ) THEN
+                EXECUTE 'REVOKE ALL ON ${qualified} FROM ${REBASE_USER_ROLE}';
+            END IF;
+        END
+        $rebase_revoke$;
+    `.trim();
+}
+//#endregion
+export { revokeInternalTableSql as n, REBASE_USER_ROLE as t };
+
+//# sourceMappingURL=internal-tables-L2t39RdT.js.map

package/dist/internal-tables-L2t39RdT.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-tables-L2t39RdT.js","names":[],"sources":["../../common/src/util/internal-tables.ts"],"sourcesContent":["/**\n * The tables Rebase creates for its own bookkeeping, and the SQL that keeps the\n * end-user role away from them.\n *\n * ## Why this exists\n *\n * Authenticated requests run as {@link REBASE_USER_ROLE}, and the boot-time role\n * provisioning grants that role `SELECT, INSERT, UPDATE, DELETE` on every table\n * in the schemas a project uses — including `rebase`, because a project's own\n * collections are allowed to live there (the scaffold puts `users` there). It\n * also sets `ALTER DEFAULT PRIVILEGES`, so a table created *later* by the\n * migrating role inherits the same grant.\n *\n * Every framework-internal table is created later: auth's tables come up during\n * `initializeAuth`, `api_keys` during route mounting, `cron_logs` when the first\n * job registers, `idempotency_keys` on the first request that carries a key. So\n * they all inherited full DML for the end-user role — and none of them enables\n * row-level security, because none of them is a collection with\n * `securityRules`. Measured on a freshly provisioned database, `SET ROLE\n * rebase_user` could read `rebase.refresh_tokens` (session token hashes),\n * `rebase.mfa_factors` (`secret_encrypted`), `rebase.recovery_codes`, and\n * `rebase.api_keys` (including its `admin` flag), and insert into\n * `rebase.app_config`.\n *\n * Nothing routes a user-context query at those tables today, so this was not\n * reachable over the API. That is the wrong thing to depend on: the documented\n * model is that RLS is the authorization boundary, and these tables sat outside\n * it. The boundary is now a privilege boundary instead — the role simply cannot\n * address them.\n *\n * ## Why REVOKE rather than ENABLE ROW LEVEL SECURITY\n *\n * RLS with no policy denies every row, which is the same outcome, but it is the\n * *weaker* statement: it leaves the grant in place, so a later policy — or a\n * `FORCE` flag cleared by some future migration — reopens the table. There is no\n * row of `refresh_tokens` any end user should ever reach, so the honest encoding\n * is \"this role has no privilege here at all\". It also keeps the owner\n * connection (which auth actually runs on) completely unaffected.\n *\n * ## Keeping it true\n *\n * `packages/rls-check` scans the `rebase` schema — it used to skip it as a\n * \"platform\" schema — and its `rls-disabled` check fires on exactly the\n * condition this module removes: RLS off *and* a DML grant to a reachable role.\n * So a table added here without a revoke is caught by `pnpm rls:check`, not by\n * someone re-reading this file.\n */\n\n/**\n * The Postgres role authenticated requests run as.\n *\n * Defined here rather than in the Postgres driver because both the driver (which\n * provisions the role) and this module (which revokes on its behalf) need it,\n * and a second spelling of a role name is a silent no-op waiting to happen.\n */\nexport const REBASE_USER_ROLE = \"rebase_user\";\n\n/**\n * Framework-internal table names, unqualified.\n *\n * Deliberately NOT including `users`: the auth user table is also a collection,\n * with `securityRules`, RLS enabled and policies applied. Users read their own\n * row through it — revoking there would break sign-in. `revokeInternalTableSql`\n * now skips any table with RLS enabled, so that exception is enforced rather\n * than merely remembered — and so is the same hazard for every other name here,\n * any of which a project may legitimately use for a collection of its own.\n *\n * `atlas_schema_revisions` is Atlas's migration ledger, which lands in `rebase`\n * because `db migrate apply` passes `--revisions-schema rebase`.\n *\n * Every entry here must also be revoked by whatever creates it, and vice versa:\n * the creation-time revoke fires once, on the boot that first makes the table,\n * so it cannot help a database provisioned before that revoke existed. This\n * list is what the boot-time sweep in `ensureAppRole` iterates, and the sweep\n * is the only thing that can repair an already-granted table. A table revoked\n * at creation but missing here is therefore permanently stranded on any\n * database that predates its revoke.\n *\n * These names are unqualified, and the boot-time sweep applies them to every\n * schema a project uses — so an entry here is a claim on that name in `public`\n * as much as in `rebase`. `jobs` is Rebase's queue at `rebase.jobs` AND a\n * perfectly ordinary collection name, and revoking `public.jobs` from a project\n * that owns it leaves every read failing 42501 with correct policies applied\n * and nothing in the RLS logs to explain it. The `relrowsecurity` guard in\n * `revokeInternalTableSql` is what makes a common noun safe here — it is not a\n * licence to claim more of them.\n */\nexport const REBASE_INTERNAL_TABLES: readonly string[] = [\n    // auth\n    \"user_identities\",\n    \"refresh_tokens\",\n    \"password_reset_tokens\",\n    \"magic_link_tokens\",\n    \"mfa_factors\",\n    \"mfa_challenges\",\n    \"recovery_codes\",\n    \"app_config\",\n    \"schema_meta\",\n    // platform services\n    \"api_keys\",\n    \"cron_logs\",\n    \"cron_claims\",\n    \"cron_job_state\",\n    \"jobs\",\n    \"rate_limit_hits\",\n    \"idempotency_keys\",\n    \"entity_history\",\n    \"branches\",\n    \"metric_samples\",\n    // realtime channels — authorization for these lives in the channel rules the\n    // server evaluates before it reads or writes, never in a row policy\n    \"channel_messages\",\n    \"channel_cursors\",\n    \"channel_presence\",\n    // migration bookkeeping\n    \"atlas_schema_revisions\"\n];\n\n/** Postgres identifiers this module is willing to interpolate. */\nconst SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_$]*$/;\n\n/**\n * A single statement that takes every privilege on `schema.table` away from the\n * end-user role.\n *\n * Wrapped in a `DO` block guarded on `pg_roles` for two reasons, both of which\n * happen in practice:\n *\n *  - the role does not exist when the connection is unprivileged (Rebase then\n *    relies on native RLS rather than a role switch), and a bare `REVOKE` on a\n *    missing role is an error, not a no-op;\n *  - the table may not exist yet — `cron_logs` never appears in a project with\n *    no cron jobs — and `to_regclass` returning NULL has to be tolerated too.\n *\n * The third guard is the one that decides whether the *right* table is being\n * revoked. The names in {@link REBASE_INTERNAL_TABLES} are unqualified, and the\n * boot-time sweep in `ensureAppRole` applies all of them to every schema a\n * project uses — including the schema its own collections live in. A project is\n * free to call a collection `jobs`, `branches` or `api_keys`, and when it does,\n * the sweep was revoking `rebase_user`'s DML on the project's table on every\n * single boot. That is not a subtle degradation: the collection's whole API\n * answers 500 `permission denied for table …` from then on, which is what\n * happened to a public job board whose vacancies live in `public.jobs`.\n *\n * `relrowsecurity` separates the two cleanly, and it is the same fact this\n * module already relies on. Framework-internal tables carry no RLS — that is the\n * premise stated at the top of this file, and the reason a revoke is needed at\n * all. Every collection table has it enabled, because that is how Rebase\n * enforces `securityRules`. So \"RLS is off\" is exactly \"this is not somebody's\n * collection\", and the guard also subsumes the hand-carved `users` exception:\n * the auth user table is a collection, has RLS, and would now be skipped on its\n * own merits rather than by being kept off a list.\n *\n * The fourth guard is about cost, and leaves the end state exactly as it was:\n * the `REVOKE` runs only when it would change something. A `REVOKE` rewrites the\n * table's `pg_class` row whether or not anything was granted, which invalidates\n * every cached plan that touches the table on every connection. Every store\n * that owns an internal table runs this on every boot. So it is skipped when the\n * end-user role holds nothing on the table — no entry in its ACL or in any\n * column's ACL — and the ACL has been written. A table whose ACL has never been\n * written (`relacl` NULL) is still revoked once: the `REVOKE` writes the owner's\n * default ACL out, exactly as before, and from then on it is skipped.\n *\n * One command, so it is safe on handles that speak the extended query protocol\n * and reject multi-statement strings.\n */\nexport function revokeInternalTableSql(schema: string, table: string): string {\n    if (!SAFE_IDENTIFIER.test(schema)) {\n        throw new Error(`Refusing to build SQL with an unsafe schema name: ${JSON.stringify(schema)}`);\n    }\n    if (!SAFE_IDENTIFIER.test(table)) {\n        throw new Error(`Refusing to build SQL with an unsafe table name: ${JSON.stringify(table)}`);\n    }\n    const qualified = `\"${schema}\".\"${table}\"`;\n    const role = `(SELECT oid FROM pg_roles WHERE rolname = '${REBASE_USER_ROLE}')`;\n    return `\n        DO $rebase_revoke$\n        BEGIN\n            IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = '${REBASE_USER_ROLE}')\n               AND to_regclass('${qualified}') IS NOT NULL\n               AND NOT (SELECT relrowsecurity FROM pg_class WHERE oid = to_regclass('${qualified}'))\n               AND (\n                   (SELECT relacl IS NULL FROM pg_class WHERE oid = to_regclass('${qualified}'))\n                   OR EXISTS (SELECT 1 FROM pg_class c, aclexplode(c.relacl) a\n                              WHERE c.oid = to_regclass('${qualified}') AND a.grantee = ${role})\n                   OR EXISTS (SELECT 1 FROM pg_attribute att, aclexplode(att.attacl) a\n                              WHERE att.attrelid = to_regclass('${qualified}') AND att.attacl IS NOT NULL\n                                AND a.grantee = ${role})\n               ) THEN\n                EXECUTE 'REVOKE ALL ON ${qualified} FROM ${REBASE_USER_ROLE}';\n            END IF;\n        END\n        $rebase_revoke$;\n    `.trim();\n}\n\n/**\n * Revoke on every internal table in `schema`, one statement at a time.\n *\n * Best-effort per table: a connection that does not own one of them (a\n * pre-provisioned database, a platform-managed ledger) cannot revoke on it, and\n * that must not take down a boot. The caller decides how loud to be — `onError`\n * exists so the driver can warn without this module importing a logger.\n */\nexport async function revokeInternalTableAccess(\n    execute: (sql: string) => Promise<unknown>,\n    schema: string,\n    options?: { tables?: readonly string[]; onError?: (table: string, error: unknown) => void }\n): Promise<void> {\n    for (const table of options?.tables ?? REBASE_INTERNAL_TABLES) {\n        try {\n            await execute(revokeInternalTableSql(schema, table));\n        } catch (error) {\n            options?.onError?.(table, error);\n        }\n    }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuDA,IAAa,mBAAmB;;AAgEhC,IAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+CxB,SAAgB,uBAAuB,QAAgB,OAAuB;CAC1E,IAAI,CAAC,gBAAgB,KAAK,MAAM,GAC5B,MAAM,IAAI,MAAM,qDAAqD,KAAK,UAAU,MAAM,GAAG;CAEjG,IAAI,CAAC,gBAAgB,KAAK,KAAK,GAC3B,MAAM,IAAI,MAAM,oDAAoD,KAAK,UAAU,KAAK,GAAG;CAE/F,MAAM,YAAY,IAAI,OAAO,KAAK,MAAM;CACxC,MAAM,OAAO,8CAA8C,iBAAiB;CAC5E,OAAO;;;iEAGsD,iBAAiB;kCAChD,UAAU;uFAC2C,UAAU;;mFAEd,UAAU;;2DAElC,UAAU,qBAAqB,KAAK;;kEAE7B,UAAU;kDAC1B,KAAK;;yCAEd,UAAU,QAAQ,iBAAiB;;;;MAItE,KAAK;AACX"}

package/dist/jobs/job-queue.d.ts

@@ -1,5 +1,13 @@
 import type { JobStore } from "./job-store.js";
 import type { JobHandler, JobQueueClient, JobQueueOptions } from "./types.js";
+/**
+ * How long one attempt may run when `jobs.timeoutMs` is left out. Without a
+ * bound, a handler awaiting a socket that never answers held its worker slot
+ * and its claim for the life of the process, with `/health` green. Fifteen
+ * minutes is far past any job that is merely slow, and a job meant to run
+ * longer says so with its own `timeoutMs` — or `0`, for no limit.
+ */
+export declare const DEFAULT_JOB_TIMEOUT_MS: number;
 /** 1s, 5s, 25s, 125s … capped at an hour. */
 export declare function defaultBackoff(attempt: number): number;
 /**

package/dist/jobs/job-store.d.ts

@@ -1,5 +1,13 @@
 import type { DataDriver } from "@rebasepro/types";
 import type { JobRecord } from "./types.js";
+/**
+ * The `NOTIFY` channel an insert announces itself on, with the job's `run_at`
+ * in epoch milliseconds as the payload. Workers listening on it are woken
+ * instead of polling; Postgres delivers it when the insert commits, and not at
+ * all if it rolls back. Frozen: workers of the previous release listen on it
+ * during a rolling deploy.
+ */
+export declare const JOBS_NOTIFY_CHANNEL = "rebase_jobs";
 /**
  * Which claim an outcome belongs to: the worker holding the job, and the
  * attempt that claim spent.
@@ -49,6 +57,22 @@ export interface JobStore {
     heartbeat?(id: string, claim: JobClaim): Promise<boolean>;
     /** Return jobs stranded by a worker that died holding them. Resolves with how many. */
     reapExpired(visibilityTimeoutMs: number): Promise<number>;
+    /**
+     * Call `onWake` whenever any process inserts a job, with the job's `run_at`
+     * in epoch milliseconds. Resolves, once listening, with the stop; rejects
+     * when this database cannot notify this process — no session connection
+     * to hold a `LISTEN` on — and the worker polls instead. `onReconnect` is
+     * called after a dropped connection is back: what was sent meanwhile is
+     * lost. A store without it leaves the worker polling.
+     */
+    subscribe?(onWake: (runAtMs?: number) => void, onReconnect: () => void): Promise<() => Promise<void>>;
+    /**
+     * Delete finished jobs past retention — succeeded ones after
+     * {@link SUCCEEDED_RETENTION_DAYS} days, failed ones after
+     * {@link FAILED_RETENTION_DAYS} — in batches. Resolves with how many went.
+     * The worker runs it on a timer; a store without it keeps every row.
+     */
+    sweepExpired?(): Promise<number>;
     fetch(id: string): Promise<JobRecord | null>;
 }
 export declare function createJobStore(driver: DataDriver): JobStore | undefined;

package/dist/jobs/types.d.ts

@@ -62,6 +62,13 @@ export interface JobContext<P = unknown> {
      */
     attempt: number;
     maxAttempts: number;
+    /**
+     * Aborted when the attempt runs past the queue's `timeoutMs`. Pass it to
+     * `fetch` and anything else that takes one: the attempt is failed and its
+     * worker slot freed at the deadline either way, but a handler that ignores
+     * the signal keeps running in the background, unrecorded.
+     */
+    signal: AbortSignal;
 }
 /**
  * A handler. Throwing is how a job fails — there is no `return false`, because
@@ -89,16 +96,21 @@ export interface EnqueueOptions {
 /** How the worker behaves. */
 export interface JobQueueOptions {
     /**
-     * Off unless asked for. A worker polls the database forever, and turning
-     * that on for every backend that happens to run on Postgres is not a
-     * default anyone chose.
+     * Off unless asked for. A worker looks for work for as long as the process
+     * lives, and turning that on for every backend that happens to run on
+     * Postgres is not a default anyone chose.
      */
     enabled?: boolean;
     /** Named handlers. A job whose `task` is not here is left alone, not failed — see the worker. */
     tasks?: Record<string, JobHandler<never>>;
     /** How many jobs one instance runs at once. Default 5. */
     concurrency?: number;
-    /** How often to look for work when the last look found none. Default 2000ms. */
+    /**
+     * The wait after a look for work that found none — doubled after each
+     * further one, up to 30 seconds, and reset whenever there is work. Only
+     * where the database cannot wake the worker with `NOTIFY`; where it can,
+     * an idle worker looks every 30 seconds as a safety net. Default 2000ms.
+     */
     pollIntervalMs?: number;
     /**
      * How long a claim may go unrenewed before another worker may take the job.
@@ -113,6 +125,15 @@ export interface JobQueueOptions {
      * the job when a run finishes gets to record its outcome.
      */
     visibilityTimeoutMs?: number;
+    /**
+     * How long one attempt may run before it is failed (and retried while
+     * attempts remain), in milliseconds. The handler's `signal` is aborted at
+     * the deadline and its worker slot is freed. Default: 15 minutes
+     * (900000), named in one log line when the worker starts. `0` is no
+     * limit — a handler that never settles then keeps its slot, and its
+     * claim, for as long as the process lives.
+     */
+    timeoutMs?: number;
     /** Attempts before a job is left `failed`. Default 3. */
     maxAttempts?: number;
     /**