pipework 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.10.0
+
+- **Breaking: `createQueue` tables are now emitted by `pipework generate`.** A queue's table was previously hand-written DDL (`schema.sql`) that `generate` never saw, so the table existed nowhere in a consumer's migration baseline — a latent footgun: any test or fresh database that exercised the queue hit `relation "<table>" does not exist` (42P01). The queue table is now built as a `pipe.define()` definition registered at `createQueue` construction and merged into `loadInternalDefinitions`, so `generate` emits its DDL like any other table. **Consumers must regenerate migrations** after upgrading so their queue tables (and the new exclusion columns/indexes) land in the baseline.
+- **New: structured cross-job exclusion for queues.** `createQueue({ exclusion: { arrayColumn, arrayElementType?, blocksAllColumn, tenantColumn } })` — strictly generic, the consumer names the conflict columns; no domain vocabulary in pipework. A job participates when its array is non-null or its blocks-all flag is true; a blocks-all candidate waits for every participating concurrent job, an array candidate is blocked by concurrent blocks-all jobs and by `&&`-overlapping arrays, all tenant-scoped when `tenantColumn` is set. When exclusion is configured the claim runs under `SERIALIZABLE` to defeat write-skew between two claimers passing the same `NOT EXISTS` snapshot, with a partial GIN index (`fastupdate = off`, scoped to claimed/running rows) on the array column and a partial blocks-all index so the predicate locks stay granular at scale. `enqueue` takes `exclusion: { array, blocksAll, tenant }`; claimed jobs carry their exclusion values back.
+- **New: `claim()` is starvation-proof and shutdown-cancellable.** The claim no longer gives up after a fixed retry budget — a serialization failure carries Postgres's safe-retry guarantee (the conflicting transaction committed, so progress was made), so `claim()` retries to a clean attempt with full-jitter backoff and `null` means exactly "nothing claimable," never "gave up under contention." `claim(db, workerId, signal?)` takes an `AbortSignal`; on a worker `stop()` the signal cancels both the retry loop and the poll sleeps so an in-flight or idle worker exits immediately, and `stop()` bounds the wait by `shutdownDeadlineMs` (its deadline timer is cleared the instant the loops exit, so a clean shutdown leaves no armed timer holding the event loop open).
+- **New: filter/expression primitives.** `caseWhen`, JSONB `extract`/`contains` aliases through `filter`, `walReplayLsn`/`replicaFresh` for WAL-LSN read-your-writes checks (typed `SQL<string | null>` / `SQL<boolean | null>` — both are NULL on a primary), and `pipe.field.pgLsn()`. `identifier()` accepts multiple parts and emits a dot-qualified reference — `identifier('chain', 'depth')` renders `"chain"."depth"` so recursive-CTE consumers can qualify CTE columns (which have no `Column` object for `aliasedTableColumn`); single-part behavior unchanged.
+- **Migrate emit fixes (required to express the queue indexes):** `emitCreateIndex` now emits index `WITH (...)` storage options (previously captured in the snapshot but dropped on emit), `indexEqual` compares them (a storage-param change now diffs), and the snapshot no longer emits `ASC NULLS LAST` for non-btree access methods (GIN rejects it — the existing hnsw/ivfflat special-case is generalized to btree-only).
+- **Removed: `clearQueueDefinitions`** (zero callers; was never in the published exports map). Registry access is direct-module only.
+- **Fix: `dropTraceTables` deadlocked against stray fire-and-forget trace writes** in test teardown — teardown now retries on `40P01`/`40001`, symmetric with how the write side already survives.
+
 ## 0.9.0
 
 - **New: runtime role separation — RLS is now actually enforced.** Until now the app connected to Postgres as the database owner, and an owner is `BYPASSRLS` — so every generated RLS policy was inert in production: the 144 policies isolated nothing. This release splits the single per-database role into two. `db setup` now provisions an **owner** role (`<name>_owner`, `BYPASSRLS`) that owns the database, runs migrations, and bootstraps; and a non-owner **runtime** role (`<name>_app`, `NOBYPASSRLS`) that runtime request/job transactions authenticate as and that RLS policies enforce against. Isolation now comes from Postgres itself on a role that cannot bypass it, not from app-side filtering alone. The runtime DML grants (`SELECT, INSERT, UPDATE, DELETE` on tables, `USAGE, SELECT` on sequences) are applied at provision time on an owner-authenticated connection, plus `ALTER DEFAULT PRIVILEGES FOR ROLE <owner>` so every future migration-created table is auto-granted to the runtime role — an RLS-enabled table can never be left ungranted (which would blank rows the app is entitled to). New `buildRuntimeGrants` helper.

package/dist/async/jobs/abortable-delay.d.ts

@@ -0,0 +1,3 @@
+/** setTimeout delay that resolves early when the signal aborts — shutdown must not wait out a backoff or poll interval. */
+export declare function abortableDelay(ms: number, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=abortable-delay.d.ts.map

package/dist/async/jobs/abortable-delay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abortable-delay.d.ts","sourceRoot":"","sources":["../../../src/async/jobs/abortable-delay.ts"],"names":[],"mappings":"AAAA,2HAA2H;AAC3H,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB9E"}

package/dist/async/jobs/abortable-delay.js

@@ -0,0 +1,19 @@
+/** setTimeout delay that resolves early when the signal aborts — shutdown must not wait out a backoff or poll interval. */
+export function abortableDelay(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted === true) {
+            resolve();
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=abortable-delay.js.map

package/dist/async/jobs/abortable-delay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abortable-delay.js","sourceRoot":"","sources":["../../../src/async/jobs/abortable-delay.ts"],"names":[],"mappings":"AAAA,2HAA2H;AAC3H,MAAM,UAAU,cAAc,CAAC,EAAU,EAAE,MAAoB;IAC7D,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QACnC,IAAI,MAAM,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC;YAC7B,OAAO,EAAE,CAAA;YACT,OAAM;QACR,CAAC;QACD,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,YAAY,CAAC,KAAK,CAAC,CAAA;YACnB,OAAO,EAAE,CAAA;QACX,CAAC,CAAA;QACD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;YAC7C,OAAO,EAAE,CAAA;QACX,CAAC,EAAE,EAAE,CAAC,CAAA;QACN,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;IAC5D,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/dist/async/jobs/exclusion.d.ts

@@ -0,0 +1,25 @@
+/** Cross-job exclusion config — names the consumer's conflict columns; the mechanism is pipework's. */
+export interface ExclusionConfig {
+    /** Array column — two jobs whose arrays overlap (`&&`) are mutually exclusive. */
+    readonly arrayColumn?: string;
+    /** Element type of `arrayColumn`. Default `'uuid'`. */
+    readonly arrayElementType?: 'uuid' | 'text';
+    /** Boolean column — a TRUE job is exclusive against every participating job in its scope. */
+    readonly blocksAllColumn?: string;
+    /** Tenant column — exclusion checks compare only jobs with the same tenant value. */
+    readonly tenantColumn?: string;
+}
+export interface ResolvedExclusion {
+    readonly arrayColumn?: string;
+    readonly arrayElementType: 'uuid' | 'text';
+    readonly blocksAllColumn?: string;
+    readonly tenantColumn?: string;
+}
+export declare function resolveExclusion(config: ExclusionConfig | undefined): ResolvedExclusion | undefined;
+/**
+ * The claimability predicate for the claim query's candidate SELECT. Pure
+ * identifiers — all quoted, no values — so the result composes as a raw SQL
+ * fragment. The candidate row is aliased `candidate`, concurrent rows `r`.
+ */
+export declare function exclusionClaimClause(tableQ: string, exclusion: ResolvedExclusion): string;
+//# sourceMappingURL=exclusion.d.ts.map

package/dist/async/jobs/exclusion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exclusion.d.ts","sourceRoot":"","sources":["../../../src/async/jobs/exclusion.ts"],"names":[],"mappings":"AAkBA,uGAAuG;AACvG,MAAM,WAAW,eAAe;IAC9B,kFAAkF;IAClF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAC3C,6FAA6F;IAC7F,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;IACjC,qFAAqF;IACrF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAAA;IAC1C,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC/B;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,GAAG,iBAAiB,GAAG,SAAS,CA8CnG;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,iBAAiB,GAAG,MAAM,CA0BzF"}

package/dist/async/jobs/exclusion.js

@@ -0,0 +1,80 @@
+// Cross-job exclusion gate for the claim query.
+//
+// A job "participates" in exclusion when its array column is non-NULL or its
+// blocks-all flag is true. Against the concurrent set R (claimed/running jobs,
+// tenant-scoped when a tenant column is configured), a pending candidate is
+// claimable when:
+//   - it does not participate: always claimable, and it never blocks others
+//   - it is blocks-all: R contains no participating job
+//   - it carries an array: R contains no blocks-all job and no job whose
+//     array overlaps (&&) the candidate's
+//
+// Two concurrent workers can evaluate these NOT EXISTS checks against the same
+// MVCC snapshot and both pass (write skew) — the claim query must run under
+// SERIALIZABLE; queue.ts handles that.
+import { assertValidIdentifier, quoteIdentifier } from '../../data/db/identifiers.js';
+import { QUEUE_BASE_COLUMNS } from './table.js';
+export function resolveExclusion(config) {
+    if (config === undefined)
+        return undefined;
+    if (config.arrayColumn === undefined && config.blocksAllColumn === undefined) {
+        throw new Error('[pipework] exclusion requires arrayColumn and/or blocksAllColumn.\n\n' +
+            '  A tenantColumn alone only scopes checks — it expresses no conflict.\n' +
+            "  Configure the conflict columns: exclusion: { arrayColumn: 'conflict_keys' }\n" +
+            "  or exclusion: { blocksAllColumn: 'exclusive' }.\n");
+    }
+    if (config.arrayElementType !== undefined && config.arrayColumn === undefined) {
+        throw new Error('[pipework] exclusion.arrayElementType is set but arrayColumn is not.\n\n' +
+            '  arrayElementType only describes arrayColumn.\n' +
+            '  Add arrayColumn, or remove arrayElementType.\n');
+    }
+    const named = [config.arrayColumn, config.blocksAllColumn, config.tenantColumn]
+        .filter((c) => c !== undefined);
+    for (const column of named) {
+        assertValidIdentifier(column, 'exclusion column');
+        if (QUEUE_BASE_COLUMNS.has(column)) {
+            throw new Error(`[pipework] exclusion column "${column}" collides with a base queue column.\n\n` +
+                `  The queue table already owns: ${[...QUEUE_BASE_COLUMNS].join(', ')}\n` +
+                '  Pick a different column name.\n');
+        }
+    }
+    if (new Set(named).size !== named.length) {
+        throw new Error('[pipework] exclusion columns must be distinct.\n\n' +
+            `  Got: arrayColumn=${config.arrayColumn ?? '—'}, blocksAllColumn=${config.blocksAllColumn ?? '—'}, tenantColumn=${config.tenantColumn ?? '—'}\n` +
+            '  Each role needs its own column.\n');
+    }
+    return {
+        ...(config.arrayColumn !== undefined ? { arrayColumn: config.arrayColumn } : {}),
+        arrayElementType: config.arrayElementType ?? 'uuid',
+        ...(config.blocksAllColumn !== undefined ? { blocksAllColumn: config.blocksAllColumn } : {}),
+        ...(config.tenantColumn !== undefined ? { tenantColumn: config.tenantColumn } : {}),
+    };
+}
+/**
+ * The claimability predicate for the claim query's candidate SELECT. Pure
+ * identifiers — all quoted, no values — so the result composes as a raw SQL
+ * fragment. The candidate row is aliased `candidate`, concurrent rows `r`.
+ */
+export function exclusionClaimClause(tableQ, exclusion) {
+    const arr = exclusion.arrayColumn !== undefined ? quoteIdentifier(exclusion.arrayColumn, 'exclusion column') : undefined;
+    const blocks = exclusion.blocksAllColumn !== undefined ? quoteIdentifier(exclusion.blocksAllColumn, 'exclusion column') : undefined;
+    const tenant = exclusion.tenantColumn !== undefined ? quoteIdentifier(exclusion.tenantColumn, 'exclusion column') : undefined;
+    const tenantScope = tenant !== undefined ? `r.${tenant} = candidate.${tenant} AND ` : '';
+    const noConcurrent = (condition) => `NOT EXISTS (SELECT 1 FROM ${tableQ} r WHERE ${tenantScope}r.status IN ('claimed', 'running') AND ${condition})`;
+    if (arr !== undefined && blocks !== undefined) {
+        return '(' +
+            `(candidate.${blocks} = false AND candidate.${arr} IS NULL)` +
+            ` OR (candidate.${blocks} = true AND ${noConcurrent(`(r.${arr} IS NOT NULL OR r.${blocks} = true)`)})` +
+            ` OR (candidate.${blocks} = false AND candidate.${arr} IS NOT NULL` +
+            ` AND ${noConcurrent(`r.${blocks} = true`)}` +
+            ` AND ${noConcurrent(`r.${arr} IS NOT NULL AND r.${arr} && candidate.${arr}`)})` +
+            ')';
+    }
+    if (arr !== undefined) {
+        return `(candidate.${arr} IS NULL OR ${noConcurrent(`r.${arr} IS NOT NULL AND r.${arr} && candidate.${arr}`)})`;
+    }
+    // blocks-all only: participation reduces to the flag itself, so a false
+    // candidate never conflicts and a true candidate waits for true jobs.
+    return `(candidate.${blocks} = false OR ${noConcurrent(`r.${blocks} = true`)})`;
+}
+//# sourceMappingURL=exclusion.js.map

package/dist/async/jobs/exclusion.js.map

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

package/dist/async/jobs/index.d.ts

@@ -1,6 +1,7 @@
 export { executeJob } from './execute.js';
 export { createQueue } from './queue.js';
-export type { Queue, QueueConfig, EnqueueOptions, ClaimedJob, JobResult, BackoffConfig } from './queue.js';
+export type { Queue, QueueConfig, EnqueueOptions, EnqueueExclusion, ClaimedJob, ClaimedExclusion, JobResult, BackoffConfig } from './queue.js';
+export type { ExclusionConfig } from './exclusion.js';
 export type { WaitOptions, WaitResult, ListenClient, ListenHandle } from './listener.js';
 export { parseCron, nextTick } from './cron.js';
 export type { CronSchedule } from './cron.js';

package/dist/async/jobs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/async/jobs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACxC,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC1G,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACxF,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAC/C,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAC7C,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/async/jobs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACxC,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,gBAAgB,EAAE,UAAU,EAAE,gBAAgB,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC9I,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AACrD,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACxF,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAC/C,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAC7C,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/async/jobs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/async/jobs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAGxC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/async/jobs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAIxC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA"}

package/dist/async/jobs/queue.d.ts

@@ -1,12 +1,14 @@
 import type { DB } from '../../data/db/index.js';
+import type { DefinedTable } from '../../data/domain/types.js';
 import type { ListenClient, WaitOptions, WaitResult } from './listener.js';
 import type { ScheduleSpec, ScheduleInfo, SchedulerOptions } from './scheduler.js';
+import type { ExclusionConfig } from './exclusion.js';
 export interface BackoffConfig {
     readonly type: 'exponential' | 'fixed';
     readonly delayMs: number;
     readonly maxDelayMs?: number;
 }
-/** Queue configuration — table name, stale timeout, max attempts, backoff strategy. */
+/** Queue configuration — table name, stale timeout, max attempts, backoff strategy, cross-job exclusion. */
 export interface QueueConfig {
     readonly table?: string;
     readonly staleTimeoutMs?: number;
@@ -14,6 +16,17 @@ export interface QueueConfig {
     readonly claimFilter?: (candidateAlias: string) => string;
     readonly maxAttempts?: number;
     readonly backoff?: BackoffConfig;
+    /** Cross-job exclusion gate — overlap/blocks-all/tenant columns checked against claimed/running jobs at claim time. */
+    readonly exclusion?: ExclusionConfig;
+}
+/** Exclusion values for one job — mapped onto the configured exclusion columns. */
+export interface EnqueueExclusion {
+    /** Conflict set for the configured arrayColumn; null/omitted = non-participating. */
+    readonly array?: readonly string[] | null;
+    /** TRUE makes this job exclusive against every participating job in its scope. */
+    readonly blocksAll?: boolean;
+    /** Tenant value for the configured tenantColumn — required when one is configured. */
+    readonly tenant?: string;
 }
 /** Options for enqueuing a job — type, payload, priority, max attempts. */
 export interface EnqueueOptions {
@@ -21,6 +34,13 @@ export interface EnqueueOptions {
     readonly priority?: number;
     readonly payload: unknown;
     readonly maxAttempts?: number;
+    readonly exclusion?: EnqueueExclusion;
+}
+/** The exclusion values a claimed job carries — present when the queue configures exclusion. */
+export interface ClaimedExclusion {
+    readonly array: readonly string[] | null;
+    readonly blocksAll: boolean;
+    readonly tenant: string | null;
 }
 /** A job claimed by a worker — includes ID, type, payload, and created LSN. */
 export interface ClaimedJob {
@@ -29,6 +49,7 @@ export interface ClaimedJob {
     readonly priority: number;
     readonly payload: unknown;
     readonly createdLsn: string;
+    readonly exclusion?: ClaimedExclusion;
 }
 export interface JobResult {
     readonly status: 'completed' | 'failed' | 'cancelled' | 'timeout' | 'dead_letter';
@@ -37,8 +58,11 @@ export interface JobResult {
 }
 /** Job queue instance with claim/complete/fail lifecycle, LISTEN/NOTIFY, and cron scheduling. */
 export interface Queue {
+    /** The queue table as a pipe.define() definition — `pipework generate` emits its DDL. */
+    readonly definition: DefinedTable;
     enqueue(db: DB, opts: EnqueueOptions): Promise<string>;
-    claim(db: DB, workerId: string): Promise<ClaimedJob | null>;
+    /** Claims the next eligible job, retrying transient conflicts until clean. The signal ends the retry loop on shutdown — claim resolves null promptly. */
+    claim(db: DB, workerId: string, signal?: AbortSignal): Promise<ClaimedJob | null>;
     heartbeat(db: DB, jobId: string): Promise<void>;
     complete(db: DB, jobId: string, output?: unknown): Promise<void>;
     fail(db: DB, jobId: string, error: unknown): Promise<void>;

package/dist/async/jobs/queue.d.ts.map

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

package/dist/async/jobs/queue.js

@@ -1,7 +1,16 @@
 import { sql } from '../../data/db/sql.js';
 import { assertValidIdentifier, quoteIdentifier } from '../../data/db/identifiers.js';
+import { serializable, isTransientConcurrencyError } from '../../data/db/serializable.js';
+import { abortableDelay } from './abortable-delay.js';
 import { JobListener } from './listener.js';
 import { createScheduler } from './scheduler.js';
+import { resolveExclusion, exclusionClaimClause } from './exclusion.js';
+import { queueDefinition } from './table.js';
+/** Serializes values into a Postgres array literal (`{"a","b"}`) — sent as one text param and cast to the element type. */
+function pgArrayLiteral(values) {
+    const escaped = values.map(v => `"${v.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`);
+    return `{${escaped.join(',')}}`;
+}
 export function createQueue(config = {}) {
     const table = config.table ?? 'pipework_jobs';
     const staleTimeoutMs = config.staleTimeoutMs ?? 120_000;
@@ -12,56 +21,139 @@ export function createQueue(config = {}) {
     assertValidIdentifier(channel, 'notify channel');
     const tableQ = quoteIdentifier(table, 'queue table');
     const listener = new JobListener(channel, tableQ);
+    const exclusion = resolveExclusion(config.exclusion);
+    const definition = queueDefinition(table, exclusion);
     async function enqueue(db, opts) {
         const priority = opts.priority ?? 0;
         const payload = JSON.stringify(opts.payload);
         const attempts = opts.maxAttempts ?? maxAttempts;
-        const rows = await db.execute(sql `INSERT INTO ${sql.raw(tableQ)} (job_type, priority, payload, max_attempts)
-               VALUES (${opts.type}, ${priority}, ${payload}::jsonb, ${attempts})
+        const columns = ['job_type', 'priority', 'payload', 'max_attempts'];
+        const values = [sql `${opts.type}`, sql `${priority}`, sql `${payload}::jsonb`, sql `${attempts}`];
+        if (exclusion === undefined) {
+            if (opts.exclusion !== undefined) {
+                throw new Error(`[pipework] enqueue() received exclusion values, but queue "${table}" has no exclusion config.\n\n` +
+                    '  Silently dropping them would enqueue a job without its conflict data.\n' +
+                    '  Configure the queue: createQueue({ exclusion: { arrayColumn: ..., blocksAllColumn: ..., tenantColumn: ... } }).\n');
+            }
+        }
+        else {
+            const given = opts.exclusion ?? {};
+            if (given.array !== undefined && given.array !== null && exclusion.arrayColumn === undefined) {
+                throw new Error(`[pipework] enqueue() received exclusion.array, but queue "${table}" configures no arrayColumn.\n\n` +
+                    '  Add arrayColumn to the queue exclusion config, or drop the value.\n');
+            }
+            if (given.blocksAll !== undefined && exclusion.blocksAllColumn === undefined) {
+                throw new Error(`[pipework] enqueue() received exclusion.blocksAll, but queue "${table}" configures no blocksAllColumn.\n\n` +
+                    '  Add blocksAllColumn to the queue exclusion config, or drop the value.\n');
+            }
+            if (given.tenant !== undefined && exclusion.tenantColumn === undefined) {
+                throw new Error(`[pipework] enqueue() received exclusion.tenant, but queue "${table}" configures no tenantColumn.\n\n` +
+                    '  Add tenantColumn to the queue exclusion config, or drop the value.\n');
+            }
+            if (exclusion.tenantColumn !== undefined) {
+                if (given.tenant === undefined) {
+                    throw new Error(`[pipework] enqueue() requires exclusion.tenant — queue "${table}" scopes exclusion by "${exclusion.tenantColumn}".\n\n` +
+                        '  Every job needs a tenant: enqueue(db, { ..., exclusion: { tenant: <id> } }).\n');
+                }
+                columns.push(quoteIdentifier(exclusion.tenantColumn, 'exclusion column'));
+                values.push(sql `${given.tenant}::uuid`);
+            }
+            if (exclusion.arrayColumn !== undefined && given.array !== undefined && given.array !== null) {
+                columns.push(quoteIdentifier(exclusion.arrayColumn, 'exclusion column'));
+                values.push(sql `${pgArrayLiteral(given.array)}::${sql.raw(exclusion.arrayElementType)}[]`);
+            }
+            if (exclusion.blocksAllColumn !== undefined && given.blocksAll !== undefined) {
+                columns.push(quoteIdentifier(exclusion.blocksAllColumn, 'exclusion column'));
+                values.push(sql `${given.blocksAll}`);
+            }
+        }
+        const rows = await db.execute(sql `INSERT INTO ${sql.raw(tableQ)} (${sql.raw(columns.join(', '))})
+               VALUES (${sql.join(values, sql `, `)})
                RETURNING id::text`);
         return rows[0]['id'];
     }
-    async function claim(db, workerId) {
-        const maxRetries = 3;
-        for (let attempt = 0; attempt < maxRetries; attempt++) {
+    function buildClaimQuery(workerId) {
+        const claimFilterClause = config.claimFilter
+            ? ` AND (${config.claimFilter('candidate')})`
+            : '';
+        const exclusionClause = exclusion !== undefined
+            ? ` AND ${exclusionClaimClause(tableQ, exclusion)}`
+            : '';
+        const exclusionReturning = exclusion !== undefined
+            ? [exclusion.tenantColumn, exclusion.arrayColumn, exclusion.blocksAllColumn]
+                .filter((c) => c !== undefined)
+                .map(c => `, ${quoteIdentifier(c, 'exclusion column')}`)
+                .join('')
+            : '';
+        return sql `
+      UPDATE ${sql.raw(tableQ)} SET
+        status = 'claimed',
+        claimed_at = now(),
+        heartbeat_at = now(),
+        worker_id = ${workerId}
+      WHERE id = (
+        SELECT candidate.id FROM ${sql.raw(tableQ)} candidate
+        WHERE candidate.status = 'pending' AND (candidate.next_retry_at IS NULL OR candidate.next_retry_at <= now())${sql.raw(exclusionClause)}${sql.raw(claimFilterClause)}
+        ORDER BY candidate.priority DESC, candidate.queued_at ASC
+        FOR UPDATE SKIP LOCKED
+        LIMIT 1
+      )
+      RETURNING id::text, job_type, priority, payload, created_lsn::text${sql.raw(exclusionReturning)}`;
+    }
+    function mapClaimedRow(row) {
+        const base = {
+            id: row['id'],
+            type: row['job_type'],
+            priority: row['priority'],
+            payload: row['payload'],
+            createdLsn: row['created_lsn'],
+        };
+        if (exclusion === undefined)
+            return base;
+        return {
+            ...base,
+            exclusion: {
+                array: exclusion.arrayColumn !== undefined ? row[exclusion.arrayColumn] : null,
+                blocksAll: exclusion.blocksAllColumn !== undefined ? row[exclusion.blocksAllColumn] : false,
+                tenant: exclusion.tenantColumn !== undefined ? row[exclusion.tenantColumn] : null,
+            },
+        };
+    }
+    /** Full-jitter backoff for transient claim conflicts — identical schedules re-collide, jitter decorrelates the herd. */
+    function conflictDelay(attempt) {
+        return Math.random() * Math.min(1000, 50 * 2 ** attempt);
+    }
+    async function claim(db, workerId, signal) {
+        const query = buildClaimQuery(workerId);
+        // Serialization failures (40001) carry Postgres's safe-retry guarantee:
+        // the conflicting transaction committed, so every abort means another
+        // claimer made progress and a retry cannot fail the same way again.
+        // Retrying until a clean attempt keeps the contract exact — null means
+        // "nothing claimable", never "gave up under contention". A fixed retry
+        // budget here starves non-conflicting claimers under sustained load.
+        // The loop's only other exit is shutdown: the signal cancels the backoff
+        // sleep and the next attempt, returning null — without it a worker stuck
+        // under sustained contention can never observe shutdown.
+        for (let attempt = 0;; attempt++) {
+            if (signal?.aborted === true)
+                return null;
             try {
-                const claimFilterClause = config.claimFilter
-                    ? sql ` AND (${sql.raw(config.claimFilter(table))})`
-                    : sql ``;
-                const rows = await db.execute(sql `
-          UPDATE ${sql.raw(tableQ)} SET
-            status = 'claimed',
-            claimed_at = now(),
-            heartbeat_at = now(),
-            worker_id = ${workerId}
-          WHERE id = (
-            SELECT id FROM ${sql.raw(tableQ)}
-            WHERE status = 'pending' AND (next_retry_at IS NULL OR next_retry_at <= now())${claimFilterClause}
-            ORDER BY priority DESC, queued_at ASC
-            FOR UPDATE SKIP LOCKED
-            LIMIT 1
-          )
-          RETURNING id::text, job_type, priority, payload, created_lsn::text`);
+                // Two workers evaluating the exclusion NOT EXISTS checks against the
+                // same MVCC snapshot can both pass and claim conflicting jobs (write
+                // skew) — the exclusion claim query must run under SERIALIZABLE.
+                const rows = exclusion !== undefined
+                    ? await serializable(db, async (tx) => tx.execute(query), { maxAttempts: 1 })
+                    : await db.execute(query);
                 if (rows.length === 0)
                     return null;
-                const row = rows[0];
-                return {
-                    id: row['id'],
-                    type: row['job_type'],
-                    priority: row['priority'],
-                    payload: row['payload'],
-                    createdLsn: row['created_lsn'],
-                };
+                return mapClaimedRow(rows[0]);
             }
             catch (err) {
-                const code = err.code;
-                if ((code === '40001' || code === '40P01') && attempt < maxRetries - 1) {
-                    continue;
-                }
-                throw err;
+                if (!isTransientConcurrencyError(err))
+                    throw err;
+                await abortableDelay(conflictDelay(attempt), signal);
             }
         }
-        return null;
     }
     async function heartbeat(db, jobId) {
         await db.execute(sql `UPDATE ${sql.raw(tableQ)} SET heartbeat_at = now() WHERE id = ${jobId}::uuid`);
@@ -152,6 +244,7 @@ export function createQueue(config = {}) {
     }
     const sched = createScheduler({ enqueue }, tableQ);
     return {
+        definition,
         enqueue, claim, heartbeat, complete, fail, cancel, reap, requeueDeadLetter,
         startListener, stopListener, waitFor, enqueueAndWait,
         schedule: (db, spec) => sched.schedule(db, spec),

package/dist/async/jobs/queue.js.map

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

package/dist/async/jobs/table.d.ts

@@ -0,0 +1,14 @@
+import type { DefinedTable } from '../../data/domain/types.js';
+import type { ResolvedExclusion } from './exclusion.js';
+export declare const QUEUE_STATUSES: readonly ["pending", "claimed", "running", "completed", "failed", "cancelled", "dead_letter"];
+/** Column names every queue table owns — exclusion columns must not collide with these. */
+export declare const QUEUE_BASE_COLUMNS: ReadonlySet<string>;
+/**
+ * Builds (or reuses) the DefinedTable for a queue. Cached per table name so
+ * repeated createQueue() calls share one definition; the same name with a
+ * different shape is a config error, not a silent overwrite.
+ */
+export declare function queueDefinition(tableName: string, exclusion: ResolvedExclusion | undefined): DefinedTable;
+/** Registered queue definitions — merged into `pipework generate` via internalDefinitions. */
+export declare function queueDefinitions(): ReadonlyMap<string, DefinedTable>;
+//# sourceMappingURL=table.d.ts.map

package/dist/async/jobs/table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../../src/async/jobs/table.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,YAAY,EAAmB,MAAM,4BAA4B,CAAA;AAK/E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAEvD,eAAO,MAAM,cAAc,+FAAgG,CAAA;AAE3H,2FAA2F;AAC3F,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAIjD,CAAA;AA6CF;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,iBAAiB,GAAG,SAAS,GAAG,YAAY,CAwDzG;AAED,8FAA8F;AAC9F,wBAAgB,gBAAgB,IAAI,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAEpE"}