bunqueue 2.8.60 → 2.9.2

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

@@ -0,0 +1,95 @@
+/** Assign durable rotation positions to every pending group lacking one. */
+export async function ensurePostgresGroupStates(tx, ctx, queue, sequence) {
+    const assigned = await tx `
+    WITH unsequenced AS (
+      SELECT job.group_id, MIN(job.group_order) AS first_order
+      FROM bunqueue_jobs AS job
+      LEFT JOIN bunqueue_group_state AS groups
+        ON groups.namespace = job.namespace AND groups.queue = job.queue
+       AND groups.group_id = job.group_id
+      WHERE job.namespace = ${ctx.config.namespace} AND job.queue = ${queue}
+        AND job.group_id IS NOT NULL AND groups.last_served IS NULL
+        AND job.state IN ('waiting', 'prioritized', 'delayed')
+      GROUP BY job.group_id
+    ), ordered AS (
+      SELECT group_id,
+             row_number() OVER (ORDER BY first_order, group_id) AS position
+      FROM unsequenced
+    )
+    INSERT INTO bunqueue_group_state (namespace, queue, group_id, last_served)
+    SELECT ${ctx.config.namespace}, ${queue}, group_id, ${sequence} + position
+    FROM ordered
+    ON CONFLICT (namespace, queue, group_id) DO UPDATE
+    SET last_served = EXCLUDED.last_served
+    WHERE bunqueue_group_state.last_served IS NULL
+    RETURNING group_id
+  `;
+    if (assigned.length === 0)
+        return sequence;
+    const next = sequence + assigned.length;
+    await tx `
+    UPDATE bunqueue_queue_state SET group_sequence = ${next}
+    WHERE namespace = ${ctx.config.namespace} AND queue = ${queue}
+  `;
+    return next;
+}
+/** Reset fixed windows when they expire or a worker changes the effective defaults. */
+export async function refreshPostgresGroupRateWindows(tx, ctx, queue, options, now) {
+    if (!options?.limit)
+        return;
+    const { max, duration } = options.limit;
+    await tx `
+    UPDATE bunqueue_group_state AS groups
+    SET rate_window_started_at = ${now}, rate_count = 0,
+        rate_effective_max = COALESCE(groups.rate_limit, ${max}),
+        rate_effective_duration_ms = COALESCE(groups.rate_duration_ms, ${duration})
+    WHERE groups.namespace = ${ctx.config.namespace} AND groups.queue = ${queue}
+      AND EXISTS (
+        SELECT 1 FROM bunqueue_jobs AS job
+        WHERE job.namespace = groups.namespace AND job.queue = groups.queue
+          AND job.group_id = groups.group_id
+          AND job.state IN ('waiting', 'prioritized', 'delayed')
+      )
+      AND (
+        groups.rate_window_started_at IS NULL
+        OR groups.rate_effective_max IS DISTINCT FROM COALESCE(groups.rate_limit, ${max})
+        OR groups.rate_effective_duration_ms IS DISTINCT FROM
+             COALESCE(groups.rate_duration_ms, ${duration})
+        OR groups.rate_window_started_at + COALESCE(groups.rate_duration_ms, ${duration}) <= ${now}
+      )
+  `;
+}
+/** Consume group budgets and move the durable round-robin cursor after row locks are secured. */
+export async function commitPostgresGroupClaims(tx, ctx, input) {
+    const { queue, rows, options, sequence } = input;
+    const grouped = rows.filter((row) => row.group_id !== null);
+    if (grouped.length === 0)
+        return;
+    const turns = new Map();
+    for (let index = 0; index < grouped.length; index++) {
+        const groupId = grouped[index].group_id;
+        const current = turns.get(groupId);
+        turns.set(groupId, {
+            last: sequence + index + 1,
+            count: (current?.count ?? 0) + 1,
+        });
+    }
+    const entries = [...turns.entries()];
+    await tx `
+    UPDATE bunqueue_group_state AS groups
+    SET last_served = batch.last_served,
+        rate_count = groups.rate_count + CASE WHEN ${options?.limit !== undefined}
+          THEN batch.claimed_count ELSE 0 END
+    FROM unnest(
+      ${tx.array(entries.map(([groupId]) => groupId), 'TEXT')},
+      ${tx.array(entries.map(([, value]) => value.last), 'BIGINT')},
+      ${tx.array(entries.map(([, value]) => value.count), 'INTEGER')}
+    ) AS batch(group_id, last_served, claimed_count)
+    WHERE groups.namespace = ${ctx.config.namespace} AND groups.queue = ${queue}
+      AND groups.group_id = batch.group_id
+  `;
+    await tx `
+    UPDATE bunqueue_queue_state SET group_sequence = ${sequence + grouped.length}
+    WHERE namespace = ${ctx.config.namespace} AND queue = ${queue}
+  `;
+}

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

@@ -0,0 +1,2 @@
+/** Correctness-critical group schema and idempotent v19 repair operations. */
+export declare const POSTGRES_GROUP_SCHEMA = "\nCREATE SEQUENCE IF NOT EXISTS bunqueue_group_order_seq AS BIGINT CACHE 1;\nALTER SEQUENCE bunqueue_group_order_seq\n  AS BIGINT INCREMENT BY 1 NO MINVALUE NO MAXVALUE NO CYCLE CACHE 1;\n\nALTER TABLE bunqueue_jobs ADD COLUMN IF NOT EXISTS group_order BIGINT;\nALTER TABLE bunqueue_jobs\n  ALTER COLUMN group_order TYPE BIGINT USING group_order::bigint,\n  ALTER COLUMN group_order DROP DEFAULT,\n  ALTER COLUMN group_order DROP NOT NULL;\n\nDO $group_order_backfill$\nDECLARE\n  target RECORD;\nBEGIN\n  PERFORM setval(\n    'bunqueue_group_order_seq',\n    GREATEST(\n      (SELECT last_value FROM bunqueue_group_order_seq),\n      COALESCE((SELECT MAX(group_order) FROM bunqueue_jobs), 0),\n      1\n    ),\n    TRUE\n  );\n  FOR target IN\n    SELECT namespace, id\n    FROM bunqueue_jobs\n    WHERE group_id IS NOT NULL AND group_order IS NULL\n    ORDER BY created_at, id, namespace\n  LOOP\n    UPDATE bunqueue_jobs\n    SET group_order = nextval('bunqueue_group_order_seq')\n    WHERE namespace = target.namespace AND id = target.id;\n  END LOOP;\nEND;\n$group_order_backfill$;\n\nCREATE TABLE IF NOT EXISTS bunqueue_group_state (\n  namespace TEXT NOT NULL,\n  queue TEXT NOT NULL,\n  group_id TEXT NOT NULL,\n  rate_limit BIGINT,\n  rate_duration_ms BIGINT,\n  rate_window_started_at BIGINT,\n  rate_count BIGINT NOT NULL DEFAULT 0,\n  rate_effective_max BIGINT,\n  rate_effective_duration_ms BIGINT,\n  concurrency_limit BIGINT,\n  last_served BIGINT,\n  PRIMARY KEY (namespace, queue, group_id)\n);\nALTER TABLE bunqueue_group_state\n  ADD COLUMN IF NOT EXISTS namespace TEXT,\n  ADD COLUMN IF NOT EXISTS queue TEXT,\n  ADD COLUMN IF NOT EXISTS group_id TEXT,\n  ADD COLUMN IF NOT EXISTS rate_limit BIGINT,\n  ADD COLUMN IF NOT EXISTS rate_duration_ms BIGINT,\n  ADD COLUMN IF NOT EXISTS rate_window_started_at BIGINT,\n  ADD COLUMN IF NOT EXISTS rate_count BIGINT DEFAULT 0,\n  ADD COLUMN IF NOT EXISTS rate_effective_max BIGINT,\n  ADD COLUMN IF NOT EXISTS rate_effective_duration_ms BIGINT,\n  ADD COLUMN IF NOT EXISTS concurrency_limit BIGINT,\n  ADD COLUMN IF NOT EXISTS last_served BIGINT;\nALTER TABLE bunqueue_group_state\n  ALTER COLUMN namespace TYPE TEXT USING namespace::text,\n  ALTER COLUMN queue TYPE TEXT USING queue::text,\n  ALTER COLUMN group_id TYPE TEXT USING group_id::text,\n  ALTER COLUMN rate_limit TYPE BIGINT USING rate_limit::bigint,\n  ALTER COLUMN rate_duration_ms TYPE BIGINT USING rate_duration_ms::bigint,\n  ALTER COLUMN rate_window_started_at TYPE BIGINT USING rate_window_started_at::bigint,\n  ALTER COLUMN rate_count TYPE BIGINT USING rate_count::bigint,\n  ALTER COLUMN rate_effective_max TYPE BIGINT USING rate_effective_max::bigint,\n  ALTER COLUMN rate_effective_duration_ms TYPE BIGINT USING rate_effective_duration_ms::bigint,\n  ALTER COLUMN concurrency_limit TYPE BIGINT USING concurrency_limit::bigint,\n  ALTER COLUMN last_served TYPE BIGINT USING last_served::bigint;\nUPDATE bunqueue_group_state SET rate_count = 0 WHERE rate_count IS NULL;\nALTER TABLE bunqueue_group_state\n  ALTER COLUMN namespace DROP DEFAULT,\n  ALTER COLUMN namespace SET NOT NULL,\n  ALTER COLUMN queue DROP DEFAULT,\n  ALTER COLUMN queue SET NOT NULL,\n  ALTER COLUMN group_id DROP DEFAULT,\n  ALTER COLUMN group_id SET NOT NULL,\n  ALTER COLUMN rate_limit DROP DEFAULT,\n  ALTER COLUMN rate_limit DROP NOT NULL,\n  ALTER COLUMN rate_duration_ms DROP DEFAULT,\n  ALTER COLUMN rate_duration_ms DROP NOT NULL,\n  ALTER COLUMN rate_window_started_at DROP DEFAULT,\n  ALTER COLUMN rate_window_started_at DROP NOT NULL,\n  ALTER COLUMN rate_count SET DEFAULT 0,\n  ALTER COLUMN rate_count SET NOT NULL,\n  ALTER COLUMN rate_effective_max DROP DEFAULT,\n  ALTER COLUMN rate_effective_max DROP NOT NULL,\n  ALTER COLUMN rate_effective_duration_ms DROP DEFAULT,\n  ALTER COLUMN rate_effective_duration_ms DROP NOT NULL,\n  ALTER COLUMN concurrency_limit DROP DEFAULT,\n  ALTER COLUMN concurrency_limit DROP NOT NULL,\n  ALTER COLUMN last_served DROP DEFAULT,\n  ALTER COLUMN last_served DROP NOT NULL;\n\nDO $group_state_primary_key$\nDECLARE\n  constraint_name TEXT;\nBEGIN\n  IF NOT EXISTS (\n    SELECT 1\n    FROM pg_constraint AS constraint_state\n    JOIN pg_index AS index_state ON index_state.indexrelid = constraint_state.conindid\n    JOIN pg_class AS index_class ON index_class.oid = index_state.indexrelid\n    JOIN pg_am AS access_method ON access_method.oid = index_class.relam\n    WHERE constraint_state.conrelid = to_regclass('bunqueue_group_state')\n      AND constraint_state.contype = 'p'\n      AND constraint_state.convalidated\n      AND NOT constraint_state.condeferrable\n      AND NOT constraint_state.condeferred\n      AND index_state.indisprimary AND index_state.indisunique\n      AND index_state.indisvalid AND index_state.indisready\n      AND access_method.amname = 'btree'\n      AND ARRAY(\n        SELECT attribute.attname::text\n        FROM unnest(constraint_state.conkey) WITH ORDINALITY AS key(attnum, position)\n        JOIN pg_attribute AS attribute\n          ON attribute.attrelid = constraint_state.conrelid\n         AND attribute.attnum = key.attnum\n        ORDER BY key.position\n      ) = ARRAY['namespace', 'queue', 'group_id']\n  ) THEN\n    FOR constraint_name IN\n      SELECT conname FROM pg_constraint\n      WHERE conrelid = to_regclass('bunqueue_group_state')\n        AND (contype = 'p' OR conname = 'bunqueue_group_state_pkey')\n    LOOP\n      EXECUTE format(\n        'ALTER TABLE bunqueue_group_state DROP CONSTRAINT %I',\n        constraint_name\n      );\n    END LOOP;\n    IF to_regclass('bunqueue_group_state_pkey') IS NOT NULL THEN\n      DROP INDEX bunqueue_group_state_pkey;\n    END IF;\n    ALTER TABLE bunqueue_group_state\n      ADD CONSTRAINT bunqueue_group_state_pkey PRIMARY KEY (namespace, queue, group_id);\n  END IF;\nEND;\n$group_state_primary_key$;\n\nDROP INDEX IF EXISTS bunqueue_jobs_group_ready_idx;\nCREATE INDEX bunqueue_jobs_group_ready_idx\n  ON bunqueue_jobs(namespace, queue, group_id, run_at ASC, group_order ASC, id ASC)\n  WHERE group_id IS NOT NULL AND state IN ('waiting', 'prioritized', 'delayed');\nDROP INDEX IF EXISTS bunqueue_group_state_rotation_idx;\nCREATE INDEX bunqueue_group_state_rotation_idx\n  ON bunqueue_group_state(namespace, queue, last_served, group_id);\n";

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

@@ -0,0 +1,155 @@
+/** Correctness-critical group schema and idempotent v19 repair operations. */
+export const POSTGRES_GROUP_SCHEMA = `
+CREATE SEQUENCE IF NOT EXISTS bunqueue_group_order_seq AS BIGINT CACHE 1;
+ALTER SEQUENCE bunqueue_group_order_seq
+  AS BIGINT INCREMENT BY 1 NO MINVALUE NO MAXVALUE NO CYCLE CACHE 1;
+
+ALTER TABLE bunqueue_jobs ADD COLUMN IF NOT EXISTS group_order BIGINT;
+ALTER TABLE bunqueue_jobs
+  ALTER COLUMN group_order TYPE BIGINT USING group_order::bigint,
+  ALTER COLUMN group_order DROP DEFAULT,
+  ALTER COLUMN group_order DROP NOT NULL;
+
+DO $group_order_backfill$
+DECLARE
+  target RECORD;
+BEGIN
+  PERFORM setval(
+    'bunqueue_group_order_seq',
+    GREATEST(
+      (SELECT last_value FROM bunqueue_group_order_seq),
+      COALESCE((SELECT MAX(group_order) FROM bunqueue_jobs), 0),
+      1
+    ),
+    TRUE
+  );
+  FOR target IN
+    SELECT namespace, id
+    FROM bunqueue_jobs
+    WHERE group_id IS NOT NULL AND group_order IS NULL
+    ORDER BY created_at, id, namespace
+  LOOP
+    UPDATE bunqueue_jobs
+    SET group_order = nextval('bunqueue_group_order_seq')
+    WHERE namespace = target.namespace AND id = target.id;
+  END LOOP;
+END;
+$group_order_backfill$;
+
+CREATE TABLE IF NOT EXISTS bunqueue_group_state (
+  namespace TEXT NOT NULL,
+  queue TEXT NOT NULL,
+  group_id TEXT NOT NULL,
+  rate_limit BIGINT,
+  rate_duration_ms BIGINT,
+  rate_window_started_at BIGINT,
+  rate_count BIGINT NOT NULL DEFAULT 0,
+  rate_effective_max BIGINT,
+  rate_effective_duration_ms BIGINT,
+  concurrency_limit BIGINT,
+  last_served BIGINT,
+  PRIMARY KEY (namespace, queue, group_id)
+);
+ALTER TABLE bunqueue_group_state
+  ADD COLUMN IF NOT EXISTS namespace TEXT,
+  ADD COLUMN IF NOT EXISTS queue TEXT,
+  ADD COLUMN IF NOT EXISTS group_id TEXT,
+  ADD COLUMN IF NOT EXISTS rate_limit BIGINT,
+  ADD COLUMN IF NOT EXISTS rate_duration_ms BIGINT,
+  ADD COLUMN IF NOT EXISTS rate_window_started_at BIGINT,
+  ADD COLUMN IF NOT EXISTS rate_count BIGINT DEFAULT 0,
+  ADD COLUMN IF NOT EXISTS rate_effective_max BIGINT,
+  ADD COLUMN IF NOT EXISTS rate_effective_duration_ms BIGINT,
+  ADD COLUMN IF NOT EXISTS concurrency_limit BIGINT,
+  ADD COLUMN IF NOT EXISTS last_served BIGINT;
+ALTER TABLE bunqueue_group_state
+  ALTER COLUMN namespace TYPE TEXT USING namespace::text,
+  ALTER COLUMN queue TYPE TEXT USING queue::text,
+  ALTER COLUMN group_id TYPE TEXT USING group_id::text,
+  ALTER COLUMN rate_limit TYPE BIGINT USING rate_limit::bigint,
+  ALTER COLUMN rate_duration_ms TYPE BIGINT USING rate_duration_ms::bigint,
+  ALTER COLUMN rate_window_started_at TYPE BIGINT USING rate_window_started_at::bigint,
+  ALTER COLUMN rate_count TYPE BIGINT USING rate_count::bigint,
+  ALTER COLUMN rate_effective_max TYPE BIGINT USING rate_effective_max::bigint,
+  ALTER COLUMN rate_effective_duration_ms TYPE BIGINT USING rate_effective_duration_ms::bigint,
+  ALTER COLUMN concurrency_limit TYPE BIGINT USING concurrency_limit::bigint,
+  ALTER COLUMN last_served TYPE BIGINT USING last_served::bigint;
+UPDATE bunqueue_group_state SET rate_count = 0 WHERE rate_count IS NULL;
+ALTER TABLE bunqueue_group_state
+  ALTER COLUMN namespace DROP DEFAULT,
+  ALTER COLUMN namespace SET NOT NULL,
+  ALTER COLUMN queue DROP DEFAULT,
+  ALTER COLUMN queue SET NOT NULL,
+  ALTER COLUMN group_id DROP DEFAULT,
+  ALTER COLUMN group_id SET NOT NULL,
+  ALTER COLUMN rate_limit DROP DEFAULT,
+  ALTER COLUMN rate_limit DROP NOT NULL,
+  ALTER COLUMN rate_duration_ms DROP DEFAULT,
+  ALTER COLUMN rate_duration_ms DROP NOT NULL,
+  ALTER COLUMN rate_window_started_at DROP DEFAULT,
+  ALTER COLUMN rate_window_started_at DROP NOT NULL,
+  ALTER COLUMN rate_count SET DEFAULT 0,
+  ALTER COLUMN rate_count SET NOT NULL,
+  ALTER COLUMN rate_effective_max DROP DEFAULT,
+  ALTER COLUMN rate_effective_max DROP NOT NULL,
+  ALTER COLUMN rate_effective_duration_ms DROP DEFAULT,
+  ALTER COLUMN rate_effective_duration_ms DROP NOT NULL,
+  ALTER COLUMN concurrency_limit DROP DEFAULT,
+  ALTER COLUMN concurrency_limit DROP NOT NULL,
+  ALTER COLUMN last_served DROP DEFAULT,
+  ALTER COLUMN last_served DROP NOT NULL;
+
+DO $group_state_primary_key$
+DECLARE
+  constraint_name TEXT;
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+    FROM pg_constraint AS constraint_state
+    JOIN pg_index AS index_state ON index_state.indexrelid = constraint_state.conindid
+    JOIN pg_class AS index_class ON index_class.oid = index_state.indexrelid
+    JOIN pg_am AS access_method ON access_method.oid = index_class.relam
+    WHERE constraint_state.conrelid = to_regclass('bunqueue_group_state')
+      AND constraint_state.contype = 'p'
+      AND constraint_state.convalidated
+      AND NOT constraint_state.condeferrable
+      AND NOT constraint_state.condeferred
+      AND index_state.indisprimary AND index_state.indisunique
+      AND index_state.indisvalid AND index_state.indisready
+      AND access_method.amname = 'btree'
+      AND ARRAY(
+        SELECT attribute.attname::text
+        FROM unnest(constraint_state.conkey) WITH ORDINALITY AS key(attnum, position)
+        JOIN pg_attribute AS attribute
+          ON attribute.attrelid = constraint_state.conrelid
+         AND attribute.attnum = key.attnum
+        ORDER BY key.position
+      ) = ARRAY['namespace', 'queue', 'group_id']
+  ) THEN
+    FOR constraint_name IN
+      SELECT conname FROM pg_constraint
+      WHERE conrelid = to_regclass('bunqueue_group_state')
+        AND (contype = 'p' OR conname = 'bunqueue_group_state_pkey')
+    LOOP
+      EXECUTE format(
+        'ALTER TABLE bunqueue_group_state DROP CONSTRAINT %I',
+        constraint_name
+      );
+    END LOOP;
+    IF to_regclass('bunqueue_group_state_pkey') IS NOT NULL THEN
+      DROP INDEX bunqueue_group_state_pkey;
+    END IF;
+    ALTER TABLE bunqueue_group_state
+      ADD CONSTRAINT bunqueue_group_state_pkey PRIMARY KEY (namespace, queue, group_id);
+  END IF;
+END;
+$group_state_primary_key$;
+
+DROP INDEX IF EXISTS bunqueue_jobs_group_ready_idx;
+CREATE INDEX bunqueue_jobs_group_ready_idx
+  ON bunqueue_jobs(namespace, queue, group_id, run_at ASC, group_order ASC, id ASC)
+  WHERE group_id IS NOT NULL AND state IN ('waiting', 'prioritized', 'delayed');
+DROP INDEX IF EXISTS bunqueue_group_state_rotation_idx;
+CREATE INDEX bunqueue_group_state_rotation_idx
+  ON bunqueue_group_state(namespace, queue, last_served, group_id);
+`;

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

@@ -0,0 +1,3 @@
+import type { TransactionSQL } from 'bun';
+/** Verify every catalog property required by durable group scheduling. */
+export declare function hasCurrentPostgresGroupSchema(tx: TransactionSQL): Promise<boolean>;

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

@@ -0,0 +1,127 @@
+/** Verify every catalog property required by durable group scheduling. */
+export async function hasCurrentPostgresGroupSchema(tx) {
+    const [schema] = await tx `
+    WITH expected_columns(table_name, column_name, type_name, not_null, default_kind) AS (
+      VALUES
+        ('bunqueue_jobs', 'group_order', 'bigint', FALSE, 'none'),
+        ('bunqueue_group_state', 'namespace', 'text', TRUE, 'none'),
+        ('bunqueue_group_state', 'queue', 'text', TRUE, 'none'),
+        ('bunqueue_group_state', 'group_id', 'text', TRUE, 'none'),
+        ('bunqueue_group_state', 'rate_limit', 'bigint', FALSE, 'none'),
+        ('bunqueue_group_state', 'rate_duration_ms', 'bigint', FALSE, 'none'),
+        ('bunqueue_group_state', 'rate_window_started_at', 'bigint', FALSE, 'none'),
+        ('bunqueue_group_state', 'rate_count', 'bigint', TRUE, 'zero'),
+        ('bunqueue_group_state', 'rate_effective_max', 'bigint', FALSE, 'none'),
+        ('bunqueue_group_state', 'rate_effective_duration_ms', 'bigint', FALSE, 'none'),
+        ('bunqueue_group_state', 'concurrency_limit', 'bigint', FALSE, 'none'),
+        ('bunqueue_group_state', 'last_served', 'bigint', FALSE, 'none')
+    ), expected_indexes(
+      index_name, table_name, columns, descending, predicate
+    ) AS (
+      VALUES
+        ('bunqueue_jobs_group_ready_idx', 'bunqueue_jobs',
+         ARRAY['namespace', 'queue', 'group_id', 'run_at', 'group_order', 'id'],
+         ARRAY[FALSE, FALSE, FALSE, FALSE, FALSE, FALSE],
+         'group_idisnotnullandstate=anyarray[''waiting''::text,''prioritized''::text,' ||
+         '''delayed''::text]'),
+        ('bunqueue_group_state_rotation_idx', 'bunqueue_group_state',
+         ARRAY['namespace', 'queue', 'last_served', 'group_id'],
+         ARRAY[FALSE, FALSE, FALSE, FALSE], '')
+    )
+    SELECT
+      to_regclass('bunqueue_group_state') IS NOT NULL
+      AND EXISTS (
+        SELECT 1 FROM pg_sequence
+        WHERE seqrelid = to_regclass('bunqueue_group_order_seq')
+          AND seqtypid = to_regtype('bigint')
+          AND seqincrement = 1 AND seqmin = 1
+          AND seqmax = 9223372036854775807
+          AND NOT seqcycle AND seqcache = 1
+      )
+      AND (
+        SELECT COALESCE(bool_and(COALESCE(
+          attribute.atttypid = to_regtype(expected.type_name)
+          AND attribute.attnotnull = expected.not_null
+          AND CASE expected.default_kind
+            WHEN 'zero' THEN regexp_replace(
+              lower(COALESCE(pg_get_expr(defaults.adbin, defaults.adrelid), '')),
+              '[()[:space:]]', '', 'g'
+            ) IN ('0', '0::bigint')
+            ELSE defaults.oid IS NULL
+          END,
+          FALSE
+        )), FALSE)
+        FROM expected_columns AS expected
+        LEFT JOIN pg_attribute AS attribute
+          ON attribute.attrelid = to_regclass(expected.table_name)
+         AND attribute.attname = expected.column_name
+         AND NOT attribute.attisdropped
+        LEFT JOIN pg_attrdef AS defaults
+          ON defaults.adrelid = attribute.attrelid
+         AND defaults.adnum = attribute.attnum
+      )
+      AND (
+        SELECT COALESCE(bool_and(COALESCE(
+          indexes.indrelid = to_regclass(expected.table_name)
+          AND indexes.indisvalid AND indexes.indisready
+          AND NOT indexes.indisunique AND NOT indexes.indisexclusion
+          AND indexes.indnkeyatts = cardinality(expected.columns)
+          AND indexes.indnatts = indexes.indnkeyatts
+          AND indexes.indexprs IS NULL
+          AND access_method.amname = 'btree'
+          AND ARRAY(
+            SELECT attribute.attname::text
+            FROM unnest(indexes.indkey::smallint[]) WITH ORDINALITY AS key(attnum, position)
+            JOIN pg_attribute AS attribute
+              ON attribute.attrelid = indexes.indrelid
+             AND attribute.attnum = key.attnum
+            ORDER BY key.position
+          ) = expected.columns
+          AND ARRAY(
+            SELECT (option & 1) = 1
+            FROM unnest(indexes.indoption::smallint[])
+              WITH ORDINALITY AS ordering(option, position)
+            ORDER BY ordering.position
+          ) = expected.descending
+          AND regexp_replace(
+            lower(COALESCE(pg_get_expr(indexes.indpred, indexes.indrelid), '')),
+            '[()[:space:]]', '', 'g'
+          ) = expected.predicate,
+          FALSE
+        )), FALSE)
+        FROM expected_indexes AS expected
+        LEFT JOIN pg_class AS index_class
+          ON index_class.oid = to_regclass(expected.index_name)
+        LEFT JOIN pg_index AS indexes ON indexes.indexrelid = index_class.oid
+        LEFT JOIN pg_am AS access_method ON access_method.oid = index_class.relam
+      )
+      AND EXISTS (
+        SELECT 1
+        FROM pg_constraint AS constraint_state
+        JOIN pg_index AS index_state ON index_state.indexrelid = constraint_state.conindid
+        JOIN pg_class AS index_class ON index_class.oid = index_state.indexrelid
+        JOIN pg_am AS access_method ON access_method.oid = index_class.relam
+        WHERE constraint_state.conrelid = to_regclass('bunqueue_group_state')
+          AND constraint_state.contype = 'p'
+          AND constraint_state.convalidated
+          AND NOT constraint_state.condeferrable
+          AND NOT constraint_state.condeferred
+          AND index_state.indisprimary AND index_state.indisunique
+          AND index_state.indisvalid AND index_state.indisready
+          AND index_state.indimmediate
+          AND index_state.indnkeyatts = 3 AND index_state.indnatts = 3
+          AND index_state.indexprs IS NULL AND index_state.indpred IS NULL
+          AND access_method.amname = 'btree'
+          AND ARRAY(
+            SELECT attribute.attname::text
+            FROM unnest(constraint_state.conkey)
+              WITH ORDINALITY AS key(attnum, position)
+            JOIN pg_attribute AS attribute
+              ON attribute.attrelid = constraint_state.conrelid
+             AND attribute.attnum = key.attnum
+            ORDER BY key.position
+          ) = ARRAY['namespace', 'queue', 'group_id']
+      ) AS valid
+  `;
+    return schema.valid;
+}

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

@@ -0,0 +1,3 @@
+import { type PostgresContext } from './context';
+/** Reclaim bounded batches of inactive policyless group scheduler state. */
+export declare function prunePostgresGroupStates(ctx: PostgresContext, batchSize?: number, maxBatches?: number): Promise<number>;

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

@@ -0,0 +1,93 @@
+import { databaseNow } from './context';
+async function pruneBatch(tx, ctx, batchSize) {
+    const now = await databaseNow(tx);
+    const rows = await tx `
+    SELECT groups.queue, groups.group_id
+    FROM bunqueue_group_state AS groups
+    WHERE groups.namespace = ${ctx.config.namespace}
+      AND NOT EXISTS (
+        SELECT 1 FROM bunqueue_jobs AS job
+        WHERE job.namespace = groups.namespace
+          AND job.queue = groups.queue
+          AND job.group_id = groups.group_id
+          AND job.state IN (
+            'waiting', 'prioritized', 'delayed', 'waiting-children', 'active'
+          )
+      )
+      AND (
+        groups.last_served IS NOT NULL
+        OR (
+          groups.rate_limit IS NULL
+          AND groups.rate_duration_ms IS NULL
+          AND groups.concurrency_limit IS NULL
+          AND (
+            groups.rate_window_started_at IS NULL
+            OR (
+              groups.rate_effective_duration_ms IS NOT NULL
+              AND groups.rate_window_started_at + groups.rate_effective_duration_ms <= ${now}
+            )
+          )
+        )
+      )
+    ORDER BY groups.queue, groups.group_id
+    LIMIT ${batchSize}
+    FOR UPDATE OF groups SKIP LOCKED
+  `;
+    if (rows.length === 0)
+        return { deleted: 0, selected: 0 };
+    const queues = rows.map(({ queue }) => queue);
+    const groupIds = rows.map(({ group_id }) => group_id);
+    await tx `
+    UPDATE bunqueue_group_state AS groups
+    SET last_served = NULL
+    FROM unnest(
+      ${tx.array(queues, 'TEXT')},
+      ${tx.array(groupIds, 'TEXT')}
+    ) AS target(queue, group_id)
+    WHERE groups.namespace = ${ctx.config.namespace}
+      AND groups.queue = target.queue
+      AND groups.group_id = target.group_id
+  `;
+    const deleted = await tx `
+    DELETE FROM bunqueue_group_state AS groups
+    USING unnest(
+      ${tx.array(queues, 'TEXT')},
+      ${tx.array(groupIds, 'TEXT')}
+    ) AS target(queue, group_id)
+    WHERE groups.namespace = ${ctx.config.namespace}
+      AND groups.queue = target.queue
+      AND groups.group_id = target.group_id
+      AND groups.rate_limit IS NULL
+      AND groups.rate_duration_ms IS NULL
+      AND groups.concurrency_limit IS NULL
+      AND (
+        groups.rate_window_started_at IS NULL
+        OR (
+          groups.rate_effective_duration_ms IS NOT NULL
+          AND groups.rate_window_started_at + groups.rate_effective_duration_ms <= ${now}
+        )
+      )
+      AND NOT EXISTS (
+        SELECT 1 FROM bunqueue_jobs AS job
+        WHERE job.namespace = groups.namespace
+          AND job.queue = groups.queue
+          AND job.group_id = groups.group_id
+          AND job.state IN (
+            'waiting', 'prioritized', 'delayed', 'waiting-children', 'active'
+          )
+      )
+    RETURNING groups.group_id
+  `;
+    return { deleted: deleted.length, selected: rows.length };
+}
+/** Reclaim bounded batches of inactive policyless group scheduler state. */
+export async function prunePostgresGroupStates(ctx, batchSize = 1000, maxBatches = 10) {
+    let deleted = 0;
+    for (let batch = 0; batch < maxBatches; batch++) {
+        const result = await ctx.sql.begin((tx) => pruneBatch(tx, ctx, batchSize));
+        deleted += result.deleted;
+        if (result.selected < batchSize)
+            break;
+    }
+    return deleted;
+}

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

@@ -0,0 +1,11 @@
+import { type GroupRateLimitOverride } from '../../../domain/types/group';
+import { type PostgresContext } from './context';
+export declare function getPostgresGroupJobsCount(ctx: PostgresContext, queue: string, groupId?: string): Promise<number>;
+export declare function getPostgresGroupActiveCount(ctx: PostgresContext, queue: string, groupId: string): Promise<number>;
+export declare function setPostgresGroupRateLimit(ctx: PostgresContext, queue: string, groupId: string, max: number, duration: number): Promise<void>;
+export declare function getPostgresGroupRateLimit(ctx: PostgresContext, queue: string, groupId: string): Promise<GroupRateLimitOverride | null>;
+export declare function removePostgresGroupRateLimit(ctx: PostgresContext, queue: string, groupId: string): Promise<number>;
+export declare function getPostgresGroupRateLimitTtl(ctx: PostgresContext, queue: string, groupId: string, maxJobs?: number): Promise<number>;
+export declare function setPostgresGroupConcurrency(ctx: PostgresContext, queue: string, groupId: string, concurrency: number): Promise<void>;
+export declare function getPostgresGroupConcurrency(ctx: PostgresContext, queue: string, groupId: string): Promise<number | null>;
+export declare function removePostgresGroupConcurrency(ctx: PostgresContext, queue: string, groupId: string): Promise<number>;

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

@@ -0,0 +1,117 @@
+import { assertGroupId, assertPositiveSafeInteger, } from '../../../domain/types/group';
+import { databaseNow } from './context';
+export async function getPostgresGroupJobsCount(ctx, queue, groupId) {
+    if (groupId !== undefined)
+        assertGroupId(groupId);
+    const [row] = groupId === undefined
+        ? await ctx.sql `
+        SELECT COUNT(*)::bigint AS count FROM bunqueue_jobs
+        WHERE namespace = ${ctx.config.namespace} AND queue = ${queue}
+          AND group_id IS NOT NULL AND state IN ('waiting', 'prioritized', 'delayed')
+      `
+        : await ctx.sql `
+        SELECT COUNT(*)::bigint AS count FROM bunqueue_jobs
+        WHERE namespace = ${ctx.config.namespace} AND queue = ${queue}
+          AND group_id = ${groupId} AND state IN ('waiting', 'prioritized', 'delayed')
+      `;
+    return Number(row.count);
+}
+export async function getPostgresGroupActiveCount(ctx, queue, groupId) {
+    assertGroupId(groupId);
+    const now = await databaseNow(ctx.sql);
+    const [row] = await ctx.sql `
+    SELECT COUNT(*)::bigint AS count FROM bunqueue_jobs
+    WHERE namespace = ${ctx.config.namespace} AND queue = ${queue}
+      AND group_id = ${groupId} AND state = 'active' AND lease_until > ${now}
+  `;
+    return Number(row.count);
+}
+export async function setPostgresGroupRateLimit(ctx, queue, groupId, max, duration) {
+    assertGroupId(groupId);
+    assertPositiveSafeInteger(max, 'max');
+    assertPositiveSafeInteger(duration, 'duration');
+    await ctx.sql `
+    INSERT INTO bunqueue_group_state (
+      namespace, queue, group_id, rate_limit, rate_duration_ms
+    ) VALUES (${ctx.config.namespace}, ${queue}, ${groupId}, ${max}, ${duration})
+    ON CONFLICT (namespace, queue, group_id) DO UPDATE
+    SET rate_limit = EXCLUDED.rate_limit,
+        rate_duration_ms = EXCLUDED.rate_duration_ms,
+        rate_window_started_at = NULL,
+        rate_count = 0,
+        rate_effective_max = NULL,
+        rate_effective_duration_ms = NULL
+  `;
+}
+export async function getPostgresGroupRateLimit(ctx, queue, groupId) {
+    assertGroupId(groupId);
+    const rows = await ctx.sql `
+    SELECT rate_limit, rate_duration_ms, rate_window_started_at, rate_count,
+           rate_effective_duration_ms, concurrency_limit
+    FROM bunqueue_group_state
+    WHERE namespace = ${ctx.config.namespace} AND queue = ${queue} AND group_id = ${groupId}
+  `;
+    const row = rows[0];
+    if (!row || row.rate_limit === null || row.rate_duration_ms === null)
+        return null;
+    return { max: Number(row.rate_limit), duration: Number(row.rate_duration_ms) };
+}
+export async function removePostgresGroupRateLimit(ctx, queue, groupId) {
+    assertGroupId(groupId);
+    const rows = await ctx.sql `
+    UPDATE bunqueue_group_state
+    SET rate_limit = NULL, rate_duration_ms = NULL, rate_window_started_at = NULL,
+        rate_count = 0, rate_effective_max = NULL, rate_effective_duration_ms = NULL
+    WHERE namespace = ${ctx.config.namespace} AND queue = ${queue} AND group_id = ${groupId}
+      AND rate_limit IS NOT NULL
+    RETURNING group_id
+  `;
+    return rows.length;
+}
+export async function getPostgresGroupRateLimitTtl(ctx, queue, groupId, maxJobs) {
+    assertGroupId(groupId);
+    const rows = await ctx.sql `
+    SELECT rate_limit, rate_duration_ms, rate_window_started_at, rate_count,
+           rate_effective_duration_ms, concurrency_limit
+    FROM bunqueue_group_state
+    WHERE namespace = ${ctx.config.namespace} AND queue = ${queue} AND group_id = ${groupId}
+  `;
+    const row = rows[0];
+    if (!row?.rate_window_started_at || row.rate_effective_duration_ms === null)
+        return -2;
+    if (maxJobs !== undefined && Number(row.rate_count) < maxJobs)
+        return 0;
+    const remaining = Number(row.rate_window_started_at) +
+        Number(row.rate_effective_duration_ms) -
+        (await databaseNow(ctx.sql));
+    return remaining > 0 ? remaining : -2;
+}
+export async function setPostgresGroupConcurrency(ctx, queue, groupId, concurrency) {
+    assertGroupId(groupId);
+    assertPositiveSafeInteger(concurrency, 'concurrency');
+    await ctx.sql `
+    INSERT INTO bunqueue_group_state (namespace, queue, group_id, concurrency_limit)
+    VALUES (${ctx.config.namespace}, ${queue}, ${groupId}, ${concurrency})
+    ON CONFLICT (namespace, queue, group_id) DO UPDATE
+    SET concurrency_limit = EXCLUDED.concurrency_limit
+  `;
+}
+export async function getPostgresGroupConcurrency(ctx, queue, groupId) {
+    assertGroupId(groupId);
+    const rows = await ctx.sql `
+    SELECT concurrency_limit FROM bunqueue_group_state
+    WHERE namespace = ${ctx.config.namespace} AND queue = ${queue} AND group_id = ${groupId}
+  `;
+    const value = rows[0]?.concurrency_limit;
+    return value === undefined || value === null ? null : Number(value);
+}
+export async function removePostgresGroupConcurrency(ctx, queue, groupId) {
+    assertGroupId(groupId);
+    const rows = await ctx.sql `
+    UPDATE bunqueue_group_state SET concurrency_limit = NULL
+    WHERE namespace = ${ctx.config.namespace} AND queue = ${queue} AND group_id = ${groupId}
+      AND concurrency_limit IS NOT NULL
+    RETURNING group_id
+  `;
+    return rows.length;
+}

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

@@ -0,0 +1,3 @@
+import type { Job } from '../../../domain/types/job';
+/** Merge user data while retaining the flow metadata owned by the broker. */
+export declare function updatedPostgresJobData(job: Job, data: unknown): unknown;

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

@@ -0,0 +1,32 @@
+const FLOW_METADATA_KEYS = [
+    '__parentId',
+    '__parentQueue',
+    '__childrenIds',
+    '__flowParentId',
+    '__flowParentIds',
+];
+function dataRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** Merge user data while retaining the flow metadata owned by the broker. */
+export function updatedPostgresJobData(job, data) {
+    const current = dataRecord(job.data);
+    const metadata = current
+        ? Object.fromEntries(FLOW_METADATA_KEYS.filter((key) => Object.hasOwn(current, key)).map((key) => [
+            key,
+            current[key],
+        ]))
+        : {};
+    if (Object.keys(metadata).length === 0)
+        return data;
+    const next = dataRecord(data);
+    if (!next)
+        throw new Error('flow job data must be an object');
+    for (const key of Object.keys(next)) {
+        if (key.startsWith('__'))
+            throw new Error(`flow job data key is reserved: ${key}`);
+    }
+    return { ...next, ...metadata };
+}