bunqueue 2.8.60 → 2.9.2

package/dist/infrastructure/persistence/postgres/batchCompletion.js

@@ -0,0 +1,174 @@
+import { createJob, generateJobId, MAX_TIMELINE_ENTRIES } from '../../../domain/types/job';
+import { buildRepeatSuccessor } from '../../../application/repeatJobs';
+import { decodePostgresJob, encodePostgresValue, postgresByteaBase64 } from './codec';
+import { databaseNow } from './context';
+import { admitPostgresJob } from './admission';
+import { recordPostgresCompletionEvents } from './completionEvents';
+import { planPostgresDependencyCompletion } from './dependencyPromotion';
+import { runPostgresTransactionWithRetry } from './transactionRetry';
+import { tryLockPostgresRepeatQueues } from './queueLifecycle';
+function invalidToken(id) {
+    return new Error(`Invalid or expired lock token for job ${id}`);
+}
+function prepareCompletions(rows, inputs, now) {
+    const byId = new Map(rows.map((row) => [row.id, row]));
+    const applied = [];
+    const results = inputs.map((input) => {
+        const row = byId.get(String(input.id));
+        if (!row)
+            throw invalidToken(String(input.id));
+        if (row.state === 'completed' || row.state === 'failed') {
+            return {
+                applied: false,
+                alreadyFinalized: true,
+                job: decodePostgresJob(row).job,
+                state: row.state,
+                removed: false,
+            };
+        }
+        if (row.state !== 'active' ||
+            row.lease_token !== input.token ||
+            Number(row.lease_until ?? 0) <= now) {
+            throw invalidToken(String(input.id));
+        }
+        const job = decodePostgresJob(row).job;
+        job.completedAt = now;
+        job.progress = 100;
+        if (job.timeline.length < MAX_TIMELINE_ENTRIES) {
+            job.timeline.push({ state: 'completed', timestamp: now });
+        }
+        const removed = job.removeOnComplete || input.removeOnComplete === true;
+        applied.push({
+            input,
+            job,
+            payload: encodePostgresValue(job),
+            resultPayload: encodePostgresValue(input.result),
+            removed,
+        });
+        return { applied: true, alreadyFinalized: false, job, state: 'completed', removed };
+    });
+    return { applied, results };
+}
+async function lockRows(tx, ctx, inputs) {
+    const ids = inputs.map((input) => String(input.id)).sort();
+    return await tx `
+    SELECT * FROM bunqueue_jobs
+    WHERE namespace = ${ctx.config.namespace}
+      AND id = ANY(${tx.array(ids, 'TEXT')})
+    ORDER BY id
+    FOR UPDATE
+  `;
+}
+async function storeResults(tx, ctx, applied, now) {
+    await tx `
+    INSERT INTO bunqueue_completions (namespace, job_id, queue, completed_at, result)
+    SELECT
+      ${ctx.config.namespace}, batch.id, batch.queue, ${now},
+      decode(batch.result_base64, 'base64')
+    FROM unnest(
+      ${tx.array(applied.map(({ job }) => String(job.id)), 'TEXT')},
+      ${tx.array(applied.map(({ job }) => job.queue), 'TEXT')},
+      ${tx.array(applied.map(({ resultPayload }) => postgresByteaBase64(resultPayload)), 'TEXT')}
+    ) AS batch(id, queue, result_base64)
+    ON CONFLICT (namespace, job_id) DO UPDATE SET
+      queue = excluded.queue,
+      completed_at = excluded.completed_at,
+      result = excluded.result
+  `;
+}
+async function updateRetainedJobs(tx, ctx, applied, now) {
+    const retained = applied.filter((item) => !item.removed);
+    if (retained.length === 0)
+        return;
+    await tx `
+    UPDATE bunqueue_jobs AS job
+    SET payload = decode(batch.payload_base64, 'base64'),
+        state = 'completed',
+        completed_at = ${now},
+        result = decode(batch.result_base64, 'base64'),
+        lease_owner = NULL,
+        lease_token = NULL,
+        lease_broker_id = NULL, lease_broker_session_id = NULL,
+        lease_until = NULL,
+        dlq_retry_state = NULL,
+        version = job.version + 1
+    FROM unnest(
+      ${tx.array(retained.map(({ job }) => String(job.id)), 'TEXT')},
+      ${tx.array(retained.map(({ payload }) => postgresByteaBase64(payload)), 'TEXT')},
+      ${tx.array(retained.map(({ resultPayload }) => postgresByteaBase64(resultPayload)), 'TEXT')}
+    ) AS batch(id, payload_base64, result_base64)
+    WHERE job.namespace = ${ctx.config.namespace} AND job.id = batch.id
+  `;
+}
+async function deleteRemovedJobs(tx, ctx, applied) {
+    const ids = applied.filter((item) => item.removed).map(({ job }) => String(job.id));
+    if (ids.length === 0)
+        return;
+    await tx `
+    DELETE FROM bunqueue_job_logs
+    WHERE namespace = ${ctx.config.namespace} AND job_id = ANY(${tx.array(ids, 'TEXT')})
+  `;
+    await tx `
+    DELETE FROM bunqueue_dependencies
+    WHERE namespace = ${ctx.config.namespace} AND job_id = ANY(${tx.array(ids, 'TEXT')})
+  `;
+    await tx `
+    DELETE FROM bunqueue_jobs
+    WHERE namespace = ${ctx.config.namespace} AND id = ANY(${tx.array(ids, 'TEXT')})
+  `;
+}
+async function createRepeatSuccessors(tx, ctx, applied, now) {
+    for (const { job } of applied) {
+        const shouldRepeat = job.repeat !== null &&
+            (job.repeat.limit === undefined || job.repeat.count < job.repeat.limit);
+        const successorInput = shouldRepeat ? buildRepeatSuccessor(job, now) : null;
+        if (!successorInput)
+            continue;
+        const successor = createJob(generateJobId(), job.queue, successorInput, now);
+        const admitted = await admitPostgresJob(tx, ctx, successor, {
+            linkParent: false,
+            queueLifecycleLocksHeld: true,
+        });
+        await tx `
+      INSERT INTO bunqueue_repeat_links (namespace, original_id, successor_id)
+      VALUES (${ctx.config.namespace}, ${String(job.id)}, ${String(admitted.job.id)})
+      ON CONFLICT (namespace, original_id) DO UPDATE SET successor_id = excluded.successor_id
+    `;
+    }
+}
+/** Complete a unique ACK batch atomically with set-based persistence. */
+export async function completePostgresJobs(ctx, inputs) {
+    if (inputs.length === 0)
+        return [];
+    if (new Set(inputs.map((input) => String(input.id))).size !== inputs.length) {
+        throw new Error('PostgreSQL batch completion requires unique job IDs');
+    }
+    return await runPostgresTransactionWithRetry(ctx, async (tx) => {
+        const now = await databaseNow(tx);
+        const dependencyCompletion = await planPostgresDependencyCompletion(tx, ctx, inputs.map(({ id }) => id));
+        const rows = await lockRows(tx, ctx, inputs);
+        const { applied, results } = prepareCompletions(rows, inputs, now);
+        if (applied.length === 0)
+            return results;
+        const repeatQueues = applied.flatMap(({ job }) => {
+            const repeats = job.repeat !== null &&
+                (job.repeat.limit === undefined || job.repeat.count < job.repeat.limit);
+            return repeats ? [job.queue] : [];
+        });
+        if (!(await tryLockPostgresRepeatQueues(tx, ctx, repeatQueues))) {
+            throw new Error('A repeat queue is being obliterated; retry batch completion');
+        }
+        const ids = applied.map(({ job }) => String(job.id));
+        await tx `
+      DELETE FROM bunqueue_flow_failures
+      WHERE namespace = ${ctx.config.namespace} AND parent_id = ANY(${tx.array(ids, 'TEXT')})
+    `;
+        await storeResults(tx, ctx, applied, now);
+        await updateRetainedJobs(tx, ctx, applied, now);
+        await deleteRemovedJobs(tx, ctx, applied);
+        await recordPostgresCompletionEvents(tx, ctx, applied.map(({ job, input, removed }) => ({ job, result: input.result, removed })), now);
+        await dependencyCompletion.promote(now);
+        await createRepeatSuccessors(tx, ctx, applied, now);
+        return results;
+    });
+}

package/dist/infrastructure/persistence/postgres/batchEvents.d.ts

@@ -0,0 +1,14 @@
+import type { TransactionSQL } from 'bun';
+import type { Job } from '../../../domain/types/job';
+import type { PostgresContext } from './context';
+import type { PostgresJobState } from './types';
+export interface PostgresBatchJobEventInput {
+    readonly job: Job;
+    readonly type: string;
+    readonly state?: PostgresJobState;
+    readonly result?: unknown;
+    readonly error?: string;
+    readonly removed?: boolean;
+}
+/** Persist job events while amortizing retention and wakeups per affected queue. */
+export declare function recordPostgresJobEvents(tx: TransactionSQL, ctx: PostgresContext, inputs: readonly PostgresBatchJobEventInput[], now: number): Promise<void>;

package/dist/infrastructure/persistence/postgres/batchEvents.js

@@ -0,0 +1,72 @@
+import { eventPayload, postgresByteaBase64 } from './codec';
+import { recordPostgresEventPruneWatermarks, summarizePostgresPrunedEvents, } from './eventPruneWatermarks';
+import { prunePostgresQueueEvents, tryLockPostgresEventRetention } from './eventRetention';
+import { POSTGRES_EVENT_CHANNEL } from './schema';
+function payloadForEvent(input) {
+    return eventPayload({
+        job: input.job,
+        ...(input.state && { state: input.state }),
+        ...(Object.hasOwn(input, 'result') && { result: input.result }),
+        ...(input.error !== undefined && { error: input.error }),
+        ...(input.removed !== undefined && { removed: input.removed }),
+    });
+}
+async function insertEvents(tx, ctx, inputs, now) {
+    const inserted = await tx `
+    INSERT INTO bunqueue_events
+      (namespace, queue, event_type, job_id, occurred_at, payload)
+    SELECT
+      ${ctx.config.namespace}, batch.queue, batch.event_type, batch.job_id, ${now},
+      decode(batch.payload_base64, 'base64')
+    FROM unnest(
+      ${tx.array(inputs.map((input) => input.job.queue), 'TEXT')},
+      ${tx.array(inputs.map((input) => input.type), 'TEXT')},
+      ${tx.array(inputs.map((input) => String(input.job.id)), 'TEXT')},
+      ${tx.array(inputs.map((input) => postgresByteaBase64(payloadForEvent(input))), 'TEXT')}
+    ) WITH ORDINALITY AS batch(queue, event_type, job_id, payload_base64, position)
+    ORDER BY batch.position
+    RETURNING id
+  `;
+    const ids = inserted.map((row) => Number(row.id));
+    return { startId: Math.min(...ids), endId: Math.max(...ids) };
+}
+async function trimEvents(tx, ctx, queues, sourceEventId) {
+    const watermarks = [];
+    const skippedQueues = new Set();
+    for (const queue of [...queues].sort()) {
+        if (!(await tryLockPostgresEventRetention(tx, ctx, queue))) {
+            skippedQueues.add(queue);
+            continue;
+        }
+        const pruned = await prunePostgresQueueEvents(tx, ctx, queue, ctx.config.maxQueueEvents);
+        const prune = summarizePostgresPrunedEvents(pruned);
+        if (prune.prunedThrough > 0)
+            watermarks.push({ queue, sourceEventId, ...prune });
+    }
+    await recordPostgresEventPruneWatermarks(tx, ctx, watermarks);
+    return {
+        watermarks: new Map(watermarks.map(({ queue, prunedThrough }) => [queue, prunedThrough])),
+        skippedQueues,
+    };
+}
+/** Persist job events while amortizing retention and wakeups per affected queue. */
+export async function recordPostgresJobEvents(tx, ctx, inputs, now) {
+    if (inputs.length === 0)
+        return;
+    const queues = [...new Set(inputs.map((input) => input.job.queue))];
+    const eventRange = await insertEvents(tx, ctx, inputs, now);
+    const { watermarks, skippedQueues } = await trimEvents(tx, ctx, queues, eventRange.endId);
+    for (const queue of queues) {
+        const prunedThrough = watermarks.get(queue);
+        await tx.notify(POSTGRES_EVENT_CHANNEL, JSON.stringify({
+            namespace: ctx.config.namespace,
+            queue,
+            brokerId: ctx.config.brokerId,
+            eventStartId: eventRange.startId,
+            eventEndId: eventRange.endId,
+            ...(prunedThrough !== undefined && { prunedThrough }),
+            ...(skippedQueues.has(queue) && { retentionRequested: true }),
+            ...(watermarks.size > 0 && { scanPruneWatermarks: true }),
+        }));
+    }
+}

package/dist/infrastructure/persistence/postgres/brokerSessions.d.ts

@@ -0,0 +1,14 @@
+import type { TransactionSQL } from 'bun';
+import { type PostgresContext } from './context';
+export declare class PostgresBrokerIdentityInUseError extends Error {
+    constructor(brokerId: string);
+}
+export declare class PostgresBrokerSessionFencedError extends Error {
+    constructor(brokerId: string);
+}
+export declare function postgresBrokerStaleMs(ctx: PostgresContext): number;
+export declare function registerPostgresBroker(ctx: PostgresContext): Promise<void>;
+export declare function lockPostgresBrokerSession(tx: TransactionSQL, ctx: PostgresContext): Promise<void>;
+export declare function heartbeatPostgresBroker(ctx: PostgresContext): Promise<void>;
+export declare function unregisterPostgresBroker(ctx: PostgresContext): Promise<void>;
+export declare function purgeStalePostgresBrokers(ctx: PostgresContext): Promise<number>;

package/dist/infrastructure/persistence/postgres/brokerSessions.js

@@ -0,0 +1,94 @@
+import { databaseNow } from './context';
+export class PostgresBrokerIdentityInUseError extends Error {
+    constructor(brokerId) {
+        super(`PostgreSQL brokerId "${brokerId}" is already active`);
+        this.name = 'PostgresBrokerIdentityInUseError';
+    }
+}
+export class PostgresBrokerSessionFencedError extends Error {
+    constructor(brokerId) {
+        super(`PostgreSQL broker session for "${brokerId}" has been fenced`);
+        this.name = 'PostgresBrokerSessionFencedError';
+    }
+}
+export function postgresBrokerStaleMs(ctx) {
+    const heartbeatMs = Math.max(1000, Math.floor(ctx.config.leaseDurationMs / 3));
+    return Math.max(ctx.config.leaseDurationMs, heartbeatMs * 3);
+}
+export async function registerPostgresBroker(ctx) {
+    const now = await databaseNow(ctx.sql);
+    const staleBefore = now - postgresBrokerStaleMs(ctx);
+    const [existing] = await ctx.sql `
+    SELECT broker_id, session_id, heartbeat_at FROM bunqueue_brokers
+    WHERE namespace = ${ctx.config.namespace} AND broker_id = ${ctx.config.brokerId}
+  `;
+    if (existing &&
+        existing.session_id !== ctx.config.brokerSessionId &&
+        Number(existing.heartbeat_at) > staleBefore) {
+        throw new PostgresBrokerIdentityInUseError(ctx.config.brokerId);
+    }
+    const rows = await ctx.sql.begin(async (tx) => {
+        const transactionNow = await databaseNow(tx);
+        return await tx `
+      INSERT INTO bunqueue_brokers AS broker
+        (namespace, broker_id, session_id, started_at, heartbeat_at)
+      VALUES
+        (${ctx.config.namespace}, ${ctx.config.brokerId}, ${ctx.config.brokerSessionId},
+         ${transactionNow}, ${transactionNow})
+      ON CONFLICT (namespace, broker_id) DO UPDATE SET
+        session_id = excluded.session_id,
+        started_at = excluded.started_at,
+        heartbeat_at = excluded.heartbeat_at
+      WHERE broker.session_id IS NOT DISTINCT FROM excluded.session_id
+         OR broker.heartbeat_at <= ${transactionNow - postgresBrokerStaleMs(ctx)}
+      RETURNING broker_id
+    `;
+    });
+    if (rows.length === 0)
+        throw new PostgresBrokerIdentityInUseError(ctx.config.brokerId);
+}
+export async function lockPostgresBrokerSession(tx, ctx) {
+    const rows = await tx `
+    SELECT broker_id FROM bunqueue_brokers
+    WHERE namespace = ${ctx.config.namespace}
+      AND broker_id = ${ctx.config.brokerId}
+      AND session_id = ${ctx.config.brokerSessionId}
+    FOR SHARE
+  `;
+    if (rows.length === 0)
+        throw new PostgresBrokerSessionFencedError(ctx.config.brokerId);
+}
+export async function heartbeatPostgresBroker(ctx) {
+    const now = await databaseNow(ctx.sql);
+    const rows = await ctx.sql `
+    UPDATE bunqueue_brokers SET heartbeat_at = ${now}
+    WHERE namespace = ${ctx.config.namespace}
+      AND broker_id = ${ctx.config.brokerId}
+      AND session_id = ${ctx.config.brokerSessionId}
+    RETURNING broker_id
+  `;
+    if (rows.length === 0)
+        throw new PostgresBrokerSessionFencedError(ctx.config.brokerId);
+}
+export async function unregisterPostgresBroker(ctx) {
+    await ctx.sql `
+    DELETE FROM bunqueue_brokers
+    WHERE namespace = ${ctx.config.namespace}
+      AND broker_id = ${ctx.config.brokerId}
+      AND session_id = ${ctx.config.brokerSessionId}
+  `;
+}
+export async function purgeStalePostgresBrokers(ctx) {
+    const now = await databaseNow(ctx.sql);
+    const rows = await ctx.sql `
+    DELETE FROM bunqueue_brokers
+    WHERE namespace = ${ctx.config.namespace}
+      AND heartbeat_at <= ${now - postgresBrokerStaleMs(ctx)}
+      AND NOT (
+        broker_id = ${ctx.config.brokerId}
+        AND session_id IS NOT DISTINCT FROM ${ctx.config.brokerSessionId}
+      )
+    RETURNING broker_id
+  `;
+    return rows.length;
+}

package/dist/infrastructure/persistence/postgres/claimBatch.d.ts

@@ -0,0 +1,14 @@
+import type { TransactionSQL } from 'bun';
+import type { GroupPullOptions } from '../../../domain/types/group';
+import type { PostgresContext } from './context';
+import type { ClaimedPostgresJob } from './types';
+/** Claim one queue batch after its queue-state row has been locked. */
+export declare function claimPostgresCandidates(tx: TransactionSQL, ctx: PostgresContext, input: {
+    queue: string;
+    capacity: number;
+    owner: string;
+    requestedLeaseMs: number;
+    now: number;
+    groupOptions?: GroupPullOptions;
+    groupSequence: number;
+}): Promise<ClaimedPostgresJob[]>;

package/dist/infrastructure/persistence/postgres/claimBatch.js

@@ -0,0 +1,69 @@
+import { generateLockToken, MAX_TIMELINE_ENTRIES } from '../../../domain/types/job';
+import { recordPostgresJobEvents } from './batchEvents';
+import { selectPostgresClaimCandidates } from './claimSelection';
+import { decodePostgresJob, encodePostgresValue, postgresByteaBase64 } from './codec';
+import { commitPostgresGroupClaims } from './groupClaims';
+function prepareClaims(rows, input) {
+    const { owner, requestedLeaseMs, now, brokerId } = input;
+    return rows.map((row) => {
+        const job = decodePostgresJob(row).job;
+        const token = String(generateLockToken());
+        const leaseDuration = Math.max(1, Math.min(requestedLeaseMs, job.timeout === null ? requestedLeaseMs : job.timeout, job.stallTimeout === null ? requestedLeaseMs : job.stallTimeout));
+        const leaseUntil = now + leaseDuration;
+        job.startedAt = now;
+        job.lastHeartbeat = now;
+        if (job.timeline.length < MAX_TIMELINE_ENTRIES) {
+            job.timeline.push({ state: 'active', timestamp: now, worker: owner });
+        }
+        return { job, token, owner, brokerId, leaseUntil };
+    });
+}
+async function persistClaims(tx, ctx, claimed, now) {
+    await tx `
+    UPDATE bunqueue_jobs AS job
+    SET state = 'active',
+        payload = decode(batch.payload_base64, 'base64'),
+        started_at = ${now},
+        lease_owner = ${claimed[0].owner},
+        lease_broker_id = ${ctx.config.brokerId},
+        lease_broker_session_id = ${ctx.config.brokerSessionId},
+        lease_token = batch.token,
+        lease_until = batch.lease_until,
+        lease_renewals = 0,
+        version = job.version + 1
+    FROM unnest(
+      ${tx.array(claimed.map(({ job }) => String(job.id)), 'TEXT')},
+      ${tx.array(claimed.map(({ job }) => postgresByteaBase64(encodePostgresValue(job))), 'TEXT')},
+      ${tx.array(claimed.map(({ token }) => token), 'TEXT')},
+      ${tx.array(claimed.map(({ leaseUntil }) => leaseUntil), 'BIGINT')}
+    ) AS batch(id, payload_base64, token, lease_until)
+    WHERE job.namespace = ${ctx.config.namespace} AND job.id = batch.id
+  `;
+    await recordPostgresJobEvents(tx, ctx, claimed.map(({ job }) => ({ job, type: 'pulled', state: 'active' })), now);
+}
+/** Claim one queue batch after its queue-state row has been locked. */
+export async function claimPostgresCandidates(tx, ctx, input) {
+    const { queue, capacity, owner, requestedLeaseMs, now, groupOptions, groupSequence } = input;
+    const rows = await selectPostgresClaimCandidates(tx, ctx, {
+        queue,
+        now,
+        capacity,
+        options: groupOptions,
+    });
+    const claimed = prepareClaims(rows, {
+        owner,
+        requestedLeaseMs,
+        now,
+        brokerId: ctx.config.brokerId,
+    });
+    if (claimed.length > 0) {
+        await commitPostgresGroupClaims(tx, ctx, {
+            queue,
+            rows,
+            options: groupOptions,
+            sequence: groupSequence,
+        });
+        await persistClaims(tx, ctx, claimed, now);
+    }
+    return claimed;
+}

package/dist/infrastructure/persistence/postgres/claimSelection.d.ts

@@ -0,0 +1,11 @@
+import type { TransactionSQL } from 'bun';
+import type { GroupPullOptions } from '../../../domain/types/group';
+import type { PostgresContext } from './context';
+import type { PostgresJobRow } from './types';
+export declare function hasClaimablePostgresGroup(tx: TransactionSQL, ctx: PostgresContext, queue: string, now: number): Promise<boolean>;
+export declare function selectPostgresClaimCandidates(tx: TransactionSQL, ctx: PostgresContext, input: {
+    queue: string;
+    now: number;
+    capacity: number;
+    options?: GroupPullOptions;
+}): Promise<PostgresJobRow[]>;

package/dist/infrastructure/persistence/postgres/claimSelection.js

@@ -0,0 +1,140 @@
+export async function hasClaimablePostgresGroup(tx, ctx, queue, now) {
+    const [row] = await tx `
+    SELECT EXISTS (
+      SELECT 1 FROM bunqueue_jobs AS job
+      WHERE job.namespace = ${ctx.config.namespace} AND job.queue = ${queue}
+        AND job.group_id IS NOT NULL
+        AND job.state IN ('waiting', 'prioritized', 'delayed')
+        AND job.run_at <= ${now}
+        AND (job.ttl IS NULL OR job.created_at + job.ttl >= ${now})
+        AND NOT EXISTS (
+          SELECT 1 FROM bunqueue_dependencies AS dependency
+          WHERE dependency.namespace = job.namespace AND dependency.job_id = job.id
+            AND NOT EXISTS (
+              SELECT 1 FROM bunqueue_completions AS completion
+              WHERE completion.namespace = dependency.namespace
+                AND completion.job_id = dependency.dependency_id
+            )
+        )
+    ) AS exists
+  `;
+    return row.exists;
+}
+async function selectUngroupedCandidates(tx, ctx, queue, now, capacity) {
+    return await tx `
+    WITH selected AS (
+      SELECT job.id, job.priority, job.lifo, job.run_at
+      FROM bunqueue_jobs AS job
+      WHERE job.namespace = ${ctx.config.namespace} AND job.queue = ${queue}
+        AND job.group_id IS NULL
+        AND job.state IN ('waiting', 'prioritized', 'delayed')
+        AND job.run_at <= ${now}
+        AND (job.ttl IS NULL OR job.created_at + job.ttl >= ${now})
+        AND NOT EXISTS (
+          SELECT 1 FROM bunqueue_dependencies AS dependency
+          WHERE dependency.namespace = job.namespace AND dependency.job_id = job.id
+            AND NOT EXISTS (
+              SELECT 1 FROM bunqueue_completions AS completion
+              WHERE completion.namespace = dependency.namespace
+                AND completion.job_id = dependency.dependency_id
+            )
+        )
+      ORDER BY job.priority DESC,
+        CASE WHEN job.lifo THEN 0 ELSE 1 END,
+        CASE WHEN job.lifo THEN job.id END DESC,
+        CASE WHEN NOT job.lifo THEN job.run_at END,
+        job.id
+      LIMIT ${capacity}
+      FOR UPDATE OF job SKIP LOCKED
+    )
+    SELECT job.* FROM bunqueue_jobs AS job
+    JOIN selected ON selected.id = job.id
+    WHERE job.namespace = ${ctx.config.namespace}
+    ORDER BY selected.priority DESC,
+      CASE WHEN selected.lifo THEN 0 ELSE 1 END,
+      CASE WHEN selected.lifo THEN selected.id END DESC,
+      CASE WHEN NOT selected.lifo THEN selected.run_at END,
+      selected.id
+  `;
+}
+async function selectGroupedCandidates(tx, ctx, input) {
+    const { queue, now, capacity, options } = input;
+    const concurrency = options?.concurrency ?? null;
+    const rateMax = options?.limit?.max ?? null;
+    return await tx `
+    WITH ready AS (
+      SELECT job.id, job.group_id,
+        row_number() OVER (
+          PARTITION BY job.group_id ORDER BY job.run_at, job.group_order, job.id
+        ) AS group_position
+      FROM bunqueue_jobs AS job
+      WHERE job.namespace = ${ctx.config.namespace} AND job.queue = ${queue}
+        AND job.group_id IS NOT NULL
+        AND job.state IN ('waiting', 'prioritized', 'delayed')
+        AND job.run_at <= ${now}
+        AND (job.ttl IS NULL OR job.created_at + job.ttl >= ${now})
+        AND NOT EXISTS (
+          SELECT 1 FROM bunqueue_dependencies AS dependency
+          WHERE dependency.namespace = job.namespace AND dependency.job_id = job.id
+            AND NOT EXISTS (
+              SELECT 1 FROM bunqueue_completions AS completion
+              WHERE completion.namespace = dependency.namespace
+                AND completion.job_id = dependency.dependency_id
+            )
+        )
+    ), active AS (
+      SELECT group_id, COUNT(*)::integer AS count
+      FROM bunqueue_jobs
+      WHERE namespace = ${ctx.config.namespace} AND queue = ${queue}
+        AND group_id IS NOT NULL AND state = 'active' AND lease_until > ${now}
+      GROUP BY group_id
+    ), capacities AS (
+      SELECT groups.group_id, groups.last_served,
+        LEAST(
+          ${capacity},
+          CASE WHEN CAST(${concurrency} AS BIGINT) IS NULL THEN ${capacity}
+            ELSE GREATEST(
+              0,
+              COALESCE(groups.concurrency_limit, CAST(${concurrency} AS BIGINT))
+                - COALESCE(active.count, 0)
+            )
+          END,
+          CASE WHEN CAST(${rateMax} AS BIGINT) IS NULL THEN ${capacity}
+            ELSE GREATEST(
+              0,
+              COALESCE(groups.rate_limit, CAST(${rateMax} AS BIGINT)) - groups.rate_count
+            )
+          END
+        ) AS available
+      FROM bunqueue_group_state AS groups
+      LEFT JOIN active ON active.group_id = groups.group_id
+      WHERE groups.namespace = ${ctx.config.namespace} AND groups.queue = ${queue}
+    ), selected AS (
+      SELECT ready.id, ready.group_id, ready.group_position, capacities.last_served
+      FROM ready JOIN capacities ON capacities.group_id = ready.group_id
+      WHERE ready.group_position <= capacities.available
+      ORDER BY ready.group_position, capacities.last_served NULLS FIRST, ready.group_id
+      LIMIT ${capacity}
+    )
+    SELECT job.* FROM bunqueue_jobs AS job
+    JOIN selected ON selected.id = job.id
+    WHERE job.namespace = ${ctx.config.namespace}
+      AND job.state IN ('waiting', 'prioritized', 'delayed')
+      AND job.run_at <= ${now}
+    ORDER BY selected.group_position, selected.last_served NULLS FIRST, selected.group_id
+    FOR UPDATE OF job SKIP LOCKED
+  `;
+}
+export async function selectPostgresClaimCandidates(tx, ctx, input) {
+    const { queue, now, capacity, options } = input;
+    const ungrouped = await selectUngroupedCandidates(tx, ctx, queue, now, capacity);
+    if (ungrouped.length >= capacity)
+        return ungrouped;
+    const grouped = await selectGroupedCandidates(tx, ctx, {
+        queue,
+        now,
+        capacity: capacity - ungrouped.length,
+        options,
+    });
+    return [...ungrouped, ...grouped];
+}

package/dist/infrastructure/persistence/postgres/claims.d.ts

@@ -0,0 +1,10 @@
+import type { GroupPullOptions } from '../../../domain/types/group';
+import { type PostgresContext } from './context';
+import type { ClaimedPostgresJob } from './types';
+export declare function claimPostgresJobs(ctx: PostgresContext, input: {
+    queue: string;
+    count: number;
+    owner: string;
+    leaseDurationMs: number;
+    groupOptions?: GroupPullOptions;
+}): Promise<ClaimedPostgresJob[]>;