@lucaapp/service-utils 5.11.0 → 5.12.0

package/dist/lib/pgBoss/config.d.ts

@@ -1,7 +1,5 @@
 import type { PgBossConfig } from './types';
 export declare const PG_BOSS_DEFAULTS: {
-    readonly maxConnectionPoolSize: 3;
     readonly deleteAfterDays: 30;
-    readonly applicationName: "pgboss";
 };
 export declare const buildPgBossDefaults: (config: PgBossConfig) => Required<PgBossConfig>;

package/dist/lib/pgBoss/config.js

@@ -2,15 +2,20 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildPgBossDefaults = exports.PG_BOSS_DEFAULTS = void 0;
 exports.PG_BOSS_DEFAULTS = {
-    maxConnectionPoolSize: 3,
     deleteAfterDays: 30,
-    applicationName: 'pgboss',
 };
-const buildPgBossDefaults = (config) => ({
-    maxConnectionPoolSize: exports.PG_BOSS_DEFAULTS.maxConnectionPoolSize,
-    deleteAfterDays: exports.PG_BOSS_DEFAULTS.deleteAfterDays,
-    applicationName: exports.PG_BOSS_DEFAULTS.applicationName,
-    mattermostWebhookUrl: '',
-    ...config,
-});
+const MIN_DELETE_AFTER_DAYS = 1;
+const MAX_DELETE_AFTER_DAYS = 365;
+const buildPgBossDefaults = (config) => {
+    const merged = {
+        deleteAfterDays: exports.PG_BOSS_DEFAULTS.deleteAfterDays,
+        mattermostWebhookUrl: null,
+        ...config,
+    };
+    if (merged.deleteAfterDays < MIN_DELETE_AFTER_DAYS ||
+        merged.deleteAfterDays > MAX_DELETE_AFTER_DAYS) {
+        throw new Error(`pg-boss deleteAfterDays must be between ${MIN_DELETE_AFTER_DAYS} and ${MAX_DELETE_AFTER_DAYS}, got ${merged.deleteAfterDays}`);
+    }
+    return merged;
+};
 exports.buildPgBossDefaults = buildPgBossDefaults;

package/dist/lib/pgBoss/controller/routes.d.ts

@@ -7,4 +7,4 @@ import type { Middleware } from '../../api/types/middleware';
  * prefix MUST live on each path string to make routing work end-to-end.
  */
 export declare const PGBOSS_API_PATH_PREFIX = "/support/pgboss";
-export declare const mountPgBossApiRoutes: (api: Api, service: PgBossService, middlewares?: Middleware<any, any, any, any, any, any>[]) => void;
+export declare const mountPgBossApiRoutes: (api: Api, service: PgBossService, middlewares: Middleware<any, any, any, any, any, any>[]) => void;

package/dist/lib/pgBoss/controller/routes.js

@@ -13,9 +13,12 @@ exports.PGBOSS_API_PATH_PREFIX = '/support/pgboss';
 const mountPgBossApiRoutes = (api, service, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 middlewares) => {
+    if (!middlewares.length) {
+        throw new Error('mountPgBossApiRoutes requires at least one auth middleware — pg-boss admin routes must not be public');
+    }
     const pgBossApi = api.child({ tags: ['PgBoss'] });
     const p = (path) => `${exports.PGBOSS_API_PATH_PREFIX}${path}`;
-    const mw = middlewares?.length ? { middlewares } : {};
+    const mw = { middlewares };
     pgBossApi.get(p('/queues'), 'List all queues with stats', {
         ...mw,
         responses: [(0, response_1.okResponse)(routes_schema_1.queueStatsArraySchema)],
@@ -28,9 +31,10 @@ middlewares) => {
         responses: [(0, response_1.okResponse)(routes_schema_1.jobArraySchema)],
         schemas: {
             params: routes_schema_1.queueNameParamsSchema,
+            query: routes_schema_1.listJobsQuerySchema,
         },
     }, async (request, _context, respond) => {
-        const jobs = await service.listJobs(request.params.name);
+        const jobs = await service.listJobs(request.params.name, request.query.limit, request.query.offset);
         return respond((0, send_1.ok)(jobs));
     });
     pgBossApi.get(p('/queues/:queue/jobs/:id'), 'Get job details', {

package/dist/lib/pgBoss/controller/routes.schema.d.ts

@@ -30,43 +30,98 @@ export declare const warningsQuerySchema: z.ZodObject<{
 }, {
     limit?: number | undefined;
 }>;
+export declare const listJobsQuerySchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    offset: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    offset: number;
+}, {
+    limit?: number | undefined;
+    offset?: number | undefined;
+}>;
 export declare const enqueueBodySchema: z.ZodObject<{
     data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    options: z.ZodOptional<z.ZodObject<{
+        priority: z.ZodOptional<z.ZodNumber>;
+        startAfter: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodDate]>>;
+        singletonKey: z.ZodOptional<z.ZodString>;
+        singletonSeconds: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        priority?: number | undefined;
+        startAfter?: string | number | Date | undefined;
+        singletonKey?: string | undefined;
+        singletonSeconds?: number | undefined;
+    }, {
+        priority?: number | undefined;
+        startAfter?: string | number | Date | undefined;
+        singletonKey?: string | undefined;
+        singletonSeconds?: number | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
-    options?: Record<string, unknown> | undefined;
+    options?: {
+        priority?: number | undefined;
+        startAfter?: string | number | Date | undefined;
+        singletonKey?: string | undefined;
+        singletonSeconds?: number | undefined;
+    } | undefined;
     data?: Record<string, unknown> | undefined;
 }, {
-    options?: Record<string, unknown> | undefined;
+    options?: {
+        priority?: number | undefined;
+        startAfter?: string | number | Date | undefined;
+        singletonKey?: string | undefined;
+        singletonSeconds?: number | undefined;
+    } | undefined;
     data?: Record<string, unknown> | undefined;
 }>;
 export declare const scheduleBodySchema: z.ZodObject<{
     name: z.ZodString;
     cron: z.ZodString;
     data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    options: z.ZodOptional<z.ZodObject<{
+        tz: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        tz?: string | undefined;
+    }, {
+        tz?: string | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     name: string;
     cron: string;
-    options?: Record<string, unknown> | undefined;
+    options?: {
+        tz?: string | undefined;
+    } | undefined;
     data?: Record<string, unknown> | undefined;
 }, {
     name: string;
     cron: string;
-    options?: Record<string, unknown> | undefined;
+    options?: {
+        tz?: string | undefined;
+    } | undefined;
     data?: Record<string, unknown> | undefined;
 }>;
 export declare const updateScheduleBodySchema: z.ZodObject<{
     cron: z.ZodString;
     data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    options: z.ZodOptional<z.ZodObject<{
+        tz: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        tz?: string | undefined;
+    }, {
+        tz?: string | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     cron: string;
-    options?: Record<string, unknown> | undefined;
+    options?: {
+        tz?: string | undefined;
+    } | undefined;
     data?: Record<string, unknown> | undefined;
 }, {
     cron: string;
-    options?: Record<string, unknown> | undefined;
+    options?: {
+        tz?: string | undefined;
+    } | undefined;
     data?: Record<string, unknown> | undefined;
 }>;
 export declare const queueStatsSchema: z.ZodObject<{

package/dist/lib/pgBoss/controller/routes.schema.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.successResponseSchema = exports.warningArraySchema = exports.warningSchema = exports.scheduleArraySchema = exports.scheduleSchema = exports.jobArraySchema = exports.jobDetailSchema = exports.queueStatsArraySchema = exports.queueStatsSchema = exports.updateScheduleBodySchema = exports.scheduleBodySchema = exports.enqueueBodySchema = exports.warningsQuerySchema = exports.scheduleNameParamsSchema = exports.queueJobParamsSchema = exports.queueNameParamsSchema = void 0;
+exports.successResponseSchema = exports.warningArraySchema = exports.warningSchema = exports.scheduleArraySchema = exports.scheduleSchema = exports.jobArraySchema = exports.jobDetailSchema = exports.queueStatsArraySchema = exports.queueStatsSchema = exports.updateScheduleBodySchema = exports.scheduleBodySchema = exports.enqueueBodySchema = exports.listJobsQuerySchema = exports.warningsQuerySchema = exports.scheduleNameParamsSchema = exports.queueJobParamsSchema = exports.queueNameParamsSchema = void 0;
 const zod_1 = require("zod");
 // ── Param schemas ────────────────────────────────────────────────────
 exports.queueNameParamsSchema = zod_1.z.object({
@@ -15,23 +15,46 @@ exports.scheduleNameParamsSchema = zod_1.z.object({
 });
 // ── Query schemas ────────────────────────────────────────────────────
 exports.warningsQuerySchema = zod_1.z.object({
-    limit: zod_1.z.coerce.number().int().positive().optional().default(100),
+    limit: zod_1.z.coerce.number().int().positive().max(1000).optional().default(100),
+});
+exports.listJobsQuerySchema = zod_1.z.object({
+    limit: zod_1.z.coerce.number().int().positive().max(1000).optional().default(100),
+    offset: zod_1.z.coerce.number().int().nonnegative().optional().default(0),
 });
 // ── Body schemas ─────────────────────────────────────────────────────
+/**
+ * Whitelisted enqueue options. Disallows infrastructure-touching keys
+ * (`deadLetter`, explicit `id`, `retentionSeconds`) so the support API
+ * cannot reroute jobs or rewrite retention from outside.
+ */
+const enqueueOptionsSchema = zod_1.z
+    .object({
+    priority: zod_1.z.number().int().optional(),
+    startAfter: zod_1.z.union([zod_1.z.string(), zod_1.z.number(), zod_1.z.date()]).optional(),
+    singletonKey: zod_1.z.string().optional(),
+    singletonSeconds: zod_1.z.number().int().positive().optional(),
+})
+    .strict();
+/** Whitelisted cron schedule options. Only timezone is exposed. */
+const scheduleOptionsSchema = zod_1.z
+    .object({
+    tz: zod_1.z.string().optional(),
+})
+    .strict();
 exports.enqueueBodySchema = zod_1.z.object({
     data: zod_1.z.record(zod_1.z.unknown()).optional(),
-    options: zod_1.z.record(zod_1.z.unknown()).optional(),
+    options: enqueueOptionsSchema.optional(),
 });
 exports.scheduleBodySchema = zod_1.z.object({
     name: zod_1.z.string(),
     cron: zod_1.z.string(),
     data: zod_1.z.record(zod_1.z.unknown()).optional(),
-    options: zod_1.z.record(zod_1.z.unknown()).optional(),
+    options: scheduleOptionsSchema.optional(),
 });
 exports.updateScheduleBodySchema = zod_1.z.object({
     cron: zod_1.z.string(),
     data: zod_1.z.record(zod_1.z.unknown()).optional(),
-    options: zod_1.z.record(zod_1.z.unknown()).optional(),
+    options: scheduleOptionsSchema.optional(),
 });
 // ── Response schemas ─────────────────────────────────────────────────
 exports.queueStatsSchema = zod_1.z.object({

package/dist/lib/pgBoss/helpers.d.ts

@@ -1,7 +1,15 @@
 import { PgBoss } from 'pg-boss';
-import type { Job, SendOptions } from 'pg-boss';
+import type { Db, Job, SendOptions } from 'pg-boss';
 import type { Logger } from 'pino';
 import type { Sequelize, Transaction } from 'sequelize';
+/**
+ * Create a pg-boss database adapter that runs SQL through the given Sequelize
+ * instance. Reuses Sequelize's connection pool, dialect options (TLS,
+ * fingerprint pinning), retries, and disconnect handling.
+ *
+ * Used as pg-boss's `db` option so pg-boss does not open its own pool.
+ */
+export declare const createSequelizeDbAdapter: (sequelize: Sequelize) => Db;
 /**
  * Enqueue a job via pg-boss with logging.
  */
@@ -9,10 +17,10 @@ export declare const enqueueJob: (boss: PgBoss, queueName: string, data: object,
 /**
  * Enqueue a job inside an existing Sequelize transaction.
  *
- * Uses pg-boss's public `send()` API with a transactional database adapter
- * instead of calling internal SQL functions directly.
+ * Builds a transactional `Db` adapter from the transaction's own Sequelize
+ * instance so the pg-boss insert participates in the surrounding transaction.
  */
-export declare const enqueueInTransaction: (boss: PgBoss, queueName: string, data: object, options: SendOptions, transaction: Transaction, sequelize: Sequelize) => Promise<string | null>;
+export declare const enqueueInTransaction: (boss: PgBoss, queueName: string, data: object, options: SendOptions, transaction: Transaction) => Promise<string | null>;
 /**
  * Wrap a pg-boss worker handler so that, when the final retry attempt fails,
  * a Mattermost DLQ alert is fired before the error is re-thrown.

package/dist/lib/pgBoss/helpers.js

@@ -1,28 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.withDlqAlerting = exports.enqueueInTransaction = exports.enqueueJob = void 0;
+exports.withDlqAlerting = exports.enqueueInTransaction = exports.enqueueJob = exports.createSequelizeDbAdapter = void 0;
 const metrics_1 = require("./metrics");
 /**
- * Enqueue a job via pg-boss with logging.
- */
-const enqueueJob = async (boss, queueName, data, options = {}, logger) => {
-    const jobId = await boss.send(queueName, data, options);
-    logger.info({ queueName, jobId }, 'Job enqueued via pg-boss');
-    return jobId;
-};
-exports.enqueueJob = enqueueJob;
-/**
- * Create a pg-boss–compatible database adapter backed by a Sequelize transaction.
+ * Create a pg-boss database adapter that runs SQL through the given Sequelize
+ * instance. Reuses Sequelize's connection pool, dialect options (TLS,
+ * fingerprint pinning), retries, and disconnect handling.
  *
- * Bridges Sequelize's transaction with pg-boss's `ConnectionOptions.db`
- * so that `boss.send()` executes within the same database transaction
- * as surrounding Sequelize operations.
+ * Used as pg-boss's `db` option so pg-boss does not open its own pool.
  */
-const createTransactionalDb = (sequelize, transaction) => ({
+const createSequelizeDbAdapter = (sequelize) => ({
     executeSql: async (text, values) => {
         const [results] = await sequelize.query(text, {
             bind: values,
-            transaction,
             raw: true,
         });
         return {
@@ -32,14 +22,39 @@ const createTransactionalDb = (sequelize, transaction) => ({
         };
     },
 });
+exports.createSequelizeDbAdapter = createSequelizeDbAdapter;
+/**
+ * Enqueue a job via pg-boss with logging.
+ */
+const enqueueJob = async (boss, queueName, data, options = {}, logger) => {
+    const jobId = await boss.send(queueName, data, options);
+    logger.info({ queueName, jobId }, 'Job enqueued via pg-boss');
+    return jobId;
+};
+exports.enqueueJob = enqueueJob;
 /**
  * Enqueue a job inside an existing Sequelize transaction.
  *
- * Uses pg-boss's public `send()` API with a transactional database adapter
- * instead of calling internal SQL functions directly.
+ * Builds a transactional `Db` adapter from the transaction's own Sequelize
+ * instance so the pg-boss insert participates in the surrounding transaction.
  */
-const enqueueInTransaction = async (boss, queueName, data, options, transaction, sequelize) => {
-    const db = createTransactionalDb(sequelize, transaction);
+const enqueueInTransaction = async (boss, queueName, data, options, transaction) => {
+    const sequelize = transaction
+        .sequelize;
+    const db = {
+        executeSql: async (text, values) => {
+            const [results] = await sequelize.query(text, {
+                bind: values,
+                transaction,
+                raw: true,
+            });
+            return {
+                rows: Array.isArray(results)
+                    ? results
+                    : [],
+            };
+        },
+    };
     return boss.send(queueName, data, { ...options, db });
 };
 exports.enqueueInTransaction = enqueueInTransaction;
@@ -62,7 +77,9 @@ const withDlqAlerting = (queueName, handler, logger, mattermostWebhookUrl) => {
             const isFinalFailure = retryLimit > 0 && retryCount >= retryLimit;
             if (isFinalFailure && mattermostWebhookUrl && job) {
                 const message = error instanceof Error ? error.message : String(error);
-                await (0, metrics_1.sendDlqAlert)(mattermostWebhookUrl, queueName, job.id, message, logger);
+                // Fire-and-forget: webhook errors are swallowed inside sendDlqAlert,
+                // and we must not block the worker on a flaky webhook.
+                void (0, metrics_1.sendDlqAlert)(mattermostWebhookUrl, queueName, job.id, message, logger);
             }
             throw error;
         }

package/dist/lib/pgBoss/index.d.ts

@@ -1,7 +1,8 @@
 import { PgBoss } from 'pg-boss';
 import type { Logger } from 'pino';
 import type { PgBossConfig } from './types';
-export { PgBoss };
+import { type PgBossMetricsRegistration } from './metrics';
+export type { PgBoss };
 export type { Job, SendOptions } from 'pg-boss';
 export type { PgBossConfig, QueueDefinition, WorkerRegistration, PgBossInstance, } from './types';
 export { PG_BOSS_DEFAULTS, buildPgBossDefaults } from './config';
@@ -15,11 +16,13 @@ export interface PgBossContext {
     logger: Logger;
     config: Required<PgBossConfig>;
     serviceName: string;
-    metricsInterval?: NodeJS.Timeout;
+    metricsRegistration?: PgBossMetricsRegistration;
 }
 /**
- * Creates a pg-boss instance with error recovery (auto-restart on connection loss).
- * Issue #510 mitigation: on error, waits 5s then restarts.
+ * Creates a pg-boss instance with bounded auto-restart on connection loss.
+ * After RESTART_MAX_ATTEMPTS consecutive failures the loop gives up and
+ * relies on the orchestrator (k8s) to replace the pod via failing health
+ * checks.
  */
 export declare const createPgBoss: (config: PgBossConfig, logger: Logger, serviceName?: string) => PgBossContext;
 /**
@@ -28,13 +31,15 @@ export declare const createPgBoss: (config: PgBossConfig, logger: Logger, servic
  */
 export declare const startBoss: (ctx: PgBossContext) => Promise<void>;
 /**
- * Gracefully stops the pg-boss instance and clears metrics polling.
- * Suitable as a shutdown handler.
+ * Gracefully stops the pg-boss instance:
+ * 1. Stop scheduling new metrics ticks.
+ * 2. Drain any in-flight metrics tick (so it doesn't race boss.stop).
+ * 3. Stop pg-boss with a 30s graceful drain.
  */
 export declare const stopBoss: (ctx: PgBossContext) => Promise<void>;
 /**
- * Maps the legacy `deleteAfterDays` setting to pg-boss v12's
- * per-queue `deleteAfterSeconds` option. Use this when calling
+ * Maps the legacy `deleteAfterDays` setting to pg-boss v12's per-queue
+ * `deleteAfterSeconds` option. Use this when calling
  * `boss.createQueue(name, { ...defaultRetention(ctx), policy: 'singleton' })`.
  */
 export declare const defaultRetention: (ctx: PgBossContext) => {

package/dist/lib/pgBoss/index.js

@@ -1,10 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defaultRetention = exports.stopBoss = exports.startBoss = exports.createPgBoss = exports.sendDlqAlert = exports.withDlqAlerting = exports.enqueueInTransaction = exports.enqueueJob = exports.registerPgBossMetrics = exports.PgBossService = exports.mountPgBossApiRoutes = exports.buildPgBossDefaults = exports.PG_BOSS_DEFAULTS = exports.PgBoss = void 0;
+exports.defaultRetention = exports.stopBoss = exports.startBoss = exports.createPgBoss = exports.sendDlqAlert = exports.withDlqAlerting = exports.enqueueInTransaction = exports.enqueueJob = exports.registerPgBossMetrics = exports.PgBossService = exports.mountPgBossApiRoutes = exports.buildPgBossDefaults = exports.PG_BOSS_DEFAULTS = void 0;
 const pg_boss_1 = require("pg-boss");
-Object.defineProperty(exports, "PgBoss", { enumerable: true, get: function () { return pg_boss_1.PgBoss; } });
 const config_1 = require("./config");
 const metrics_1 = require("./metrics");
+const helpers_1 = require("./helpers");
 var config_2 = require("./config");
 Object.defineProperty(exports, "PG_BOSS_DEFAULTS", { enumerable: true, get: function () { return config_2.PG_BOSS_DEFAULTS; } });
 Object.defineProperty(exports, "buildPgBossDefaults", { enumerable: true, get: function () { return config_2.buildPgBossDefaults; } });
@@ -14,30 +14,53 @@ var service_1 = require("./service");
 Object.defineProperty(exports, "PgBossService", { enumerable: true, get: function () { return service_1.PgBossService; } });
 var metrics_2 = require("./metrics");
 Object.defineProperty(exports, "registerPgBossMetrics", { enumerable: true, get: function () { return metrics_2.registerPgBossMetrics; } });
-var helpers_1 = require("./helpers");
-Object.defineProperty(exports, "enqueueJob", { enumerable: true, get: function () { return helpers_1.enqueueJob; } });
-Object.defineProperty(exports, "enqueueInTransaction", { enumerable: true, get: function () { return helpers_1.enqueueInTransaction; } });
-Object.defineProperty(exports, "withDlqAlerting", { enumerable: true, get: function () { return helpers_1.withDlqAlerting; } });
+var helpers_2 = require("./helpers");
+Object.defineProperty(exports, "enqueueJob", { enumerable: true, get: function () { return helpers_2.enqueueJob; } });
+Object.defineProperty(exports, "enqueueInTransaction", { enumerable: true, get: function () { return helpers_2.enqueueInTransaction; } });
+Object.defineProperty(exports, "withDlqAlerting", { enumerable: true, get: function () { return helpers_2.withDlqAlerting; } });
 var metrics_3 = require("./metrics");
 Object.defineProperty(exports, "sendDlqAlert", { enumerable: true, get: function () { return metrics_3.sendDlqAlert; } });
-const RESTART_DELAY_MS = 5000;
+const RESTART_DELAY_MIN_MS = 5_000;
+const RESTART_DELAY_MAX_MS = 60_000;
+const RESTART_MAX_ATTEMPTS = 10;
 const SECONDS_PER_DAY = 86_400;
 /**
- * Creates a pg-boss instance with error recovery (auto-restart on connection loss).
- * Issue #510 mitigation: on error, waits 5s then restarts.
+ * Creates a pg-boss instance with bounded auto-restart on connection loss.
+ * After RESTART_MAX_ATTEMPTS consecutive failures the loop gives up and
+ * relies on the orchestrator (k8s) to replace the pod via failing health
+ * checks.
  */
 const createPgBoss = (config, logger, serviceName = config.schema) => {
     const resolvedConfig = (0, config_1.buildPgBossDefaults)(config);
     const boss = new pg_boss_1.PgBoss({
-        connectionString: resolvedConfig.connectionString,
+        db: (0, helpers_1.createSequelizeDbAdapter)(resolvedConfig.sequelize),
         schema: resolvedConfig.schema,
-        application_name: resolvedConfig.applicationName,
-        max: resolvedConfig.maxConnectionPoolSize,
         migrate: true,
     });
+    let restartAttempts = 0;
+    const scheduleRestart = () => {
+        if (restartAttempts >= RESTART_MAX_ATTEMPTS) {
+            logger.fatal({ attempts: restartAttempts }, 'pg-boss restart limit exceeded — giving up');
+            return;
+        }
+        const delay = Math.min(RESTART_DELAY_MIN_MS * 2 ** restartAttempts, RESTART_DELAY_MAX_MS);
+        restartAttempts += 1;
+        setTimeout(async () => {
+            try {
+                logger.info({ attempt: restartAttempts }, 'Attempting pg-boss restart');
+                await boss.start();
+                restartAttempts = 0;
+                logger.info('pg-boss restarted successfully');
+            }
+            catch (restartError) {
+                logger.error({ error: restartError, attempt: restartAttempts }, 'pg-boss restart failed — will retry with backoff');
+                scheduleRestart();
+            }
+        }, delay);
+    };
     boss.on('error', (error) => {
         logger.error({ error }, 'pg-boss error — will attempt restart');
-        scheduleRestart(boss, logger);
+        scheduleRestart();
     });
     boss.on('warning', warning => {
         logger.warn({ warning }, 'pg-boss warning');
@@ -52,43 +75,33 @@ exports.createPgBoss = createPgBoss;
 const startBoss = async (ctx) => {
     ctx.logger.info({ schema: ctx.config.schema }, 'Starting pg-boss');
     await ctx.boss.start();
-    ctx.metricsInterval = (0, metrics_1.registerPgBossMetrics)(ctx.boss, ctx.serviceName, ctx.logger, ctx.config.mattermostWebhookUrl || undefined);
+    ctx.metricsRegistration = (0, metrics_1.registerPgBossMetrics)(ctx.boss, ctx.serviceName, ctx.logger, ctx.config.mattermostWebhookUrl ?? undefined);
     ctx.logger.info({ schema: ctx.config.schema }, 'pg-boss started successfully');
 };
 exports.startBoss = startBoss;
 /**
- * Gracefully stops the pg-boss instance and clears metrics polling.
- * Suitable as a shutdown handler.
+ * Gracefully stops the pg-boss instance:
+ * 1. Stop scheduling new metrics ticks.
+ * 2. Drain any in-flight metrics tick (so it doesn't race boss.stop).
+ * 3. Stop pg-boss with a 30s graceful drain.
  */
 const stopBoss = async (ctx) => {
     ctx.logger.info({ schema: ctx.config.schema }, 'Stopping pg-boss');
-    if (ctx.metricsInterval) {
-        clearInterval(ctx.metricsInterval);
-        ctx.metricsInterval = undefined;
+    if (ctx.metricsRegistration) {
+        clearInterval(ctx.metricsRegistration.intervalHandle);
+        await ctx.metricsRegistration.awaitInFlight();
+        ctx.metricsRegistration = undefined;
     }
     await ctx.boss.stop({ graceful: true, timeout: 30_000 });
     ctx.logger.info({ schema: ctx.config.schema }, 'pg-boss stopped');
 };
 exports.stopBoss = stopBoss;
 /**
- * Maps the legacy `deleteAfterDays` setting to pg-boss v12's
- * per-queue `deleteAfterSeconds` option. Use this when calling
+ * Maps the legacy `deleteAfterDays` setting to pg-boss v12's per-queue
+ * `deleteAfterSeconds` option. Use this when calling
  * `boss.createQueue(name, { ...defaultRetention(ctx), policy: 'singleton' })`.
  */
 const defaultRetention = (ctx) => ({
     deleteAfterSeconds: ctx.config.deleteAfterDays * SECONDS_PER_DAY,
 });
 exports.defaultRetention = defaultRetention;
-const scheduleRestart = (boss, logger) => {
-    setTimeout(async () => {
-        try {
-            logger.info('Attempting pg-boss restart after error');
-            await boss.start();
-            logger.info('pg-boss restarted successfully');
-        }
-        catch (restartError) {
-            logger.error({ error: restartError }, 'pg-boss restart failed — will retry');
-            scheduleRestart(boss, logger);
-        }
-    }, RESTART_DELAY_MS);
-};

package/dist/lib/pgBoss/metrics.d.ts

@@ -1,15 +1,22 @@
 import { PgBoss } from 'pg-boss';
 import type { Logger } from 'pino';
+export interface PgBossMetricsRegistration {
+    intervalHandle: NodeJS.Timeout;
+    /** Resolve once any in-flight collectMetrics tick finishes. */
+    awaitInFlight: () => Promise<void>;
+}
 /**
  * Register Prometheus metrics by polling pg-boss queue stats.
  *
  * pg-boss v12 removed the `monitor-states` event, so we poll
  * `getQueues()` + `getQueueStats()` on a timer instead.
  *
- * Returns the interval handle so callers can clear it on shutdown.
+ * Returns the interval handle plus an `awaitInFlight` so callers can drain a
+ * running tick before stopping pg-boss on shutdown.
  */
-export declare const registerPgBossMetrics: (boss: PgBoss, serviceName: string, logger: Logger, mattermostWebhookUrl?: string) => NodeJS.Timeout;
+export declare const registerPgBossMetrics: (boss: PgBoss, serviceName: string, logger: Logger, mattermostWebhookUrl?: string) => PgBossMetricsRegistration;
 /**
- * Send a Mattermost alert for a dead-letter job.
+ * Send a Mattermost alert for a dead-letter job. Errors are swallowed and
+ * logged so callers can fire-and-forget without affecting job semantics.
  */
 export declare const sendDlqAlert: (webhookUrl: string, queueName: string, jobId: string, error: string, logger: Logger) => Promise<void>;

package/dist/lib/pgBoss/metrics.js

@@ -55,46 +55,73 @@ const queueTotal = new promClient.Gauge({
     labelNames: ['queue', 'service'],
 });
 const POLL_INTERVAL_MS = 30_000;
+const MATTERMOST_TIMEOUT_MS = 5000;
 /**
  * Register Prometheus metrics by polling pg-boss queue stats.
  *
  * pg-boss v12 removed the `monitor-states` event, so we poll
  * `getQueues()` + `getQueueStats()` on a timer instead.
  *
- * Returns the interval handle so callers can clear it on shutdown.
+ * Returns the interval handle plus an `awaitInFlight` so callers can drain a
+ * running tick before stopping pg-boss on shutdown.
  */
 const registerPgBossMetrics = (boss, serviceName, logger, mattermostWebhookUrl) => {
+    let inflight;
+    let knownQueues = new Set();
     const collectMetrics = async () => {
         try {
             const queues = await boss.getQueues();
+            const currentQueues = new Set();
             for (const queue of queues) {
                 const stats = await boss.getQueueStats(queue.name);
                 const labels = { queue: queue.name, service: serviceName };
+                currentQueues.add(queue.name);
                 queueDepth.set(labels, stats.queuedCount ?? 0);
                 queueActive.set(labels, stats.activeCount ?? 0);
                 queueTotal.set(labels, stats.totalCount ?? 0);
             }
+            for (const stale of knownQueues) {
+                if (currentQueues.has(stale))
+                    continue;
+                const labels = { queue: stale, service: serviceName };
+                queueDepth.remove(labels);
+                queueActive.remove(labels);
+                queueTotal.remove(labels);
+            }
+            knownQueues = currentQueues;
         }
         catch (error) {
             logger.error({ error }, 'Failed to collect pg-boss metrics');
         }
     };
+    const tick = () => {
+        inflight = collectMetrics().finally(() => {
+            inflight = undefined;
+        });
+    };
     if (mattermostWebhookUrl) {
         logger.info('Mattermost DLQ alerting enabled');
     }
-    // Initial collection + interval
-    void collectMetrics();
-    return setInterval(collectMetrics, POLL_INTERVAL_MS);
+    tick();
+    const intervalHandle = setInterval(tick, POLL_INTERVAL_MS);
+    return {
+        intervalHandle,
+        awaitInFlight: async () => {
+            if (inflight)
+                await inflight;
+        },
+    };
 };
 exports.registerPgBossMetrics = registerPgBossMetrics;
 /**
- * Send a Mattermost alert for a dead-letter job.
+ * Send a Mattermost alert for a dead-letter job. Errors are swallowed and
+ * logged so callers can fire-and-forget without affecting job semantics.
  */
 const sendDlqAlert = async (webhookUrl, queueName, jobId, error, logger) => {
     try {
         await axios_1.default.post(webhookUrl, {
             text: `🚨 **pg-boss DLQ Alert**\n**Queue:** \`${queueName}\`\n**Job ID:** \`${jobId}\`\n**Error:** ${error}`,
-        });
+        }, { timeout: MATTERMOST_TIMEOUT_MS });
     }
     catch (webhookError) {
         logger.error({ error: webhookError }, 'Failed to send Mattermost DLQ alert');

package/dist/lib/pgBoss/service/getWarnings.d.ts

@@ -5,5 +5,7 @@ import { PgBoss } from 'pg-boss';
  * pg-boss v12 persists warnings (slow queries, queue backlogs, clock skew)
  * when `persistWarnings: true` is set. There is no public class method,
  * so we query the warning table via `getDb()`.
+ *
+ * The schema name is interpolated into raw SQL — guard against injection.
  */
 export declare const getWarnings: (boss: PgBoss, schema: string, limit?: number) => Promise<Record<string, unknown>[]>;

package/dist/lib/pgBoss/service/getWarnings.js

@@ -1,14 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getWarnings = void 0;
+const SCHEMA_NAME_RE = /^[a-z_][a-z0-9_]*$/;
 /**
  * Retrieve persisted warnings from the pg-boss warning table.
  *
  * pg-boss v12 persists warnings (slow queries, queue backlogs, clock skew)
  * when `persistWarnings: true` is set. There is no public class method,
  * so we query the warning table via `getDb()`.
+ *
+ * The schema name is interpolated into raw SQL — guard against injection.
  */
 const getWarnings = async (boss, schema, limit = 100) => {
+    if (!SCHEMA_NAME_RE.test(schema)) {
+        throw new Error(`Invalid pg-boss schema name: ${schema}`);
+    }
     const db = boss.getDb();
     const result = await db.executeSql(`SELECT id, type, message, data, created_on
      FROM "${schema}".warning

package/dist/lib/pgBoss/service/listJobs.d.ts

@@ -1,2 +1,9 @@
 import { PgBoss } from 'pg-boss';
-export declare const listJobs: (boss: PgBoss, queueName: string) => Promise<Record<string, unknown>[]>;
+/**
+ * List jobs in a queue with mandatory pagination.
+ *
+ * pg-boss `findJobs` does not support limit/offset directly, so we slice
+ * client-side. Callers must pass `limit` (clamped to MAX_LIMIT) and
+ * `offset` to avoid loading 1M rows into memory.
+ */
+export declare const listJobs: (boss: PgBoss, queueName: string, limit?: number, offset?: number) => Promise<Record<string, unknown>[]>;

package/dist/lib/pgBoss/service/listJobs.js

@@ -1,8 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.listJobs = void 0;
-const listJobs = async (boss, queueName) => {
+const DEFAULT_LIMIT = 100;
+const MAX_LIMIT = 1000;
+/**
+ * List jobs in a queue with mandatory pagination.
+ *
+ * pg-boss `findJobs` does not support limit/offset directly, so we slice
+ * client-side. Callers must pass `limit` (clamped to MAX_LIMIT) and
+ * `offset` to avoid loading 1M rows into memory.
+ */
+const listJobs = async (boss, queueName, limit = DEFAULT_LIMIT, offset = 0) => {
+    const cappedLimit = Math.min(Math.max(limit, 1), MAX_LIMIT);
+    const safeOffset = Math.max(offset, 0);
     const jobs = await boss.findJobs(queueName);
-    return jobs.map(j => ({ ...j }));
+    return jobs
+        .slice(safeOffset, safeOffset + cappedLimit)
+        .map(job => ({ ...job }));
 };
 exports.listJobs = listJobs;

package/dist/lib/pgBoss/service/schedules.js

@@ -12,7 +12,6 @@ const createSchedule = async (boss, logger, name, cron, data, options) => {
 };
 exports.createSchedule = createSchedule;
 const updateSchedule = async (boss, logger, name, cron, data, options) => {
-    await boss.unschedule(name);
     await boss.schedule(name, cron, data || {}, options || {});
     logger.info({ name, cron }, 'Schedule updated');
 };

package/dist/lib/pgBoss/service.d.ts

@@ -4,9 +4,9 @@ export declare class PgBossService {
     private readonly boss;
     private readonly logger;
     private readonly schema;
-    constructor(boss: PgBoss, logger: Logger, schema?: string);
+    constructor(boss: PgBoss, logger: Logger, schema: string);
     getQueueStats: () => Promise<import("./service/getQueueStats").QueueStats[]>;
-    listJobs: (queueName: string) => Promise<Record<string, unknown>[]>;
+    listJobs: (queueName: string, limit?: number, offset?: number) => Promise<Record<string, unknown>[]>;
     getJob: (queueName: string, jobId: string) => Promise<Record<string, unknown> | null>;
     retryJob: (queueName: string, jobId: string) => Promise<void>;
     cancelJob: (queueName: string, jobId: string) => Promise<void>;

package/dist/lib/pgBoss/service.js

@@ -6,15 +6,15 @@ const listJobs_1 = require("./service/listJobs");
 const getJob_1 = require("./service/getJob");
 const manageJob_1 = require("./service/manageJob");
 const schedules_1 = require("./service/schedules");
-const enqueue_1 = require("./service/enqueue");
+const helpers_1 = require("./helpers");
 const getWarnings_1 = require("./service/getWarnings");
 class PgBossService {
-    constructor(boss, logger, schema = 'pgboss') {
+    constructor(boss, logger, schema) {
         this.boss = boss;
         this.logger = logger;
         this.schema = schema;
         this.getQueueStats = () => (0, getQueueStats_1.getQueueStats)(this.boss);
-        this.listJobs = (queueName) => (0, listJobs_1.listJobs)(this.boss, queueName);
+        this.listJobs = (queueName, limit, offset) => (0, listJobs_1.listJobs)(this.boss, queueName, limit, offset);
         this.getJob = (queueName, jobId) => (0, getJob_1.getJob)(this.boss, queueName, jobId);
         this.retryJob = (queueName, jobId) => (0, manageJob_1.manageJob)(this.boss, this.logger, 'retry', queueName, jobId);
         this.cancelJob = (queueName, jobId) => (0, manageJob_1.manageJob)(this.boss, this.logger, 'cancel', queueName, jobId);
@@ -23,7 +23,7 @@ class PgBossService {
         this.createSchedule = (name, cron, data, options) => (0, schedules_1.createSchedule)(this.boss, this.logger, name, cron, data, options);
         this.updateSchedule = (name, cron, data, options) => (0, schedules_1.updateSchedule)(this.boss, this.logger, name, cron, data, options);
         this.deleteSchedule = (name) => (0, schedules_1.deleteSchedule)(this.boss, this.logger, name);
-        this.enqueueJob = (queueName, data, options) => (0, enqueue_1.enqueue)(this.boss, this.logger, queueName, data, options);
+        this.enqueueJob = (queueName, data, options) => (0, helpers_1.enqueueJob)(this.boss, queueName, data ?? {}, options, this.logger);
         this.getWarnings = (limit) => (0, getWarnings_1.getWarnings)(this.boss, this.schema, limit);
     }
 }

package/dist/lib/pgBoss/types.d.ts

@@ -1,18 +1,19 @@
 import type { QueueOptions, Job, WorkOptions } from 'pg-boss';
 import type { PgBoss } from 'pg-boss';
+import type { Sequelize } from 'sequelize';
 export type { SendOptions, QueueOptions, WorkOptions, Job } from 'pg-boss';
 export interface PgBossConfig {
     enabled: boolean;
-    connectionString: string;
+    /**
+     * Existing Sequelize instance. pg-boss reuses its connection pool, dialect
+     * options (TLS, fingerprint pinning), and retry config — no separate pool.
+     */
+    sequelize: Sequelize;
     schema: string;
-    /** Max connections in the pg-boss pool. Default: 3 */
-    maxConnectionPoolSize?: number;
     /** Days to keep completed/failed jobs. Default: 30 (GDPR-aligned) */
     deleteAfterDays?: number;
-    /** Application name for PG connections. Default: "pgboss" */
-    applicationName?: string;
     /** Mattermost webhook URL for DLQ alerts (optional) */
-    mattermostWebhookUrl?: string;
+    mattermostWebhookUrl?: string | null;
 }
 export interface QueueDefinition {
     name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lucaapp/service-utils",
-  "version": "5.11.0",
+  "version": "5.12.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [

package/dist/lib/pgBoss/service/enqueue.d.ts

@@ -1,3 +0,0 @@
-import { PgBoss } from 'pg-boss';
-import type { Logger } from 'pino';
-export declare const enqueue: (boss: PgBoss, logger: Logger, queueName: string, data?: Record<string, unknown>, options?: Record<string, unknown>) => Promise<string | null>;

package/dist/lib/pgBoss/service/enqueue.js

@@ -1,9 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.enqueue = void 0;
-const enqueue = async (boss, logger, queueName, data, options) => {
-    const jobId = await boss.send(queueName, data || {}, options || {});
-    logger.info({ queue: queueName, jobId }, 'Job enqueued');
-    return jobId;
-};
-exports.enqueue = enqueue;