@lucaapp/service-utils 5.9.0 → 5.10.0

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

@@ -1,20 +1,10 @@
 import { Api } from '../../api/api';
 import { PgBossService } from '../service';
+import type { Middleware } from '../../api/types/middleware';
 /**
- * Mounts pg-boss dashboard API routes onto an Api instance.
- *
- * Endpoints:
- * - GET  /queues                          — list queues with stats
- * - GET  /queues/:name/jobs               — list jobs in a queue
- * - GET  /queues/:queue/jobs/:id          — job detail
- * - POST /queues/:queue/jobs/:id/retry    — retry a job
- * - POST /queues/:queue/jobs/:id/cancel   — cancel a job
- * - DELETE /queues/:queue/jobs/:id        — delete a job
- * - GET  /schedules                       — list cron schedules
- * - POST /schedules                       — create a schedule
- * - PUT  /schedules/:name                 — update a schedule
- * - DELETE /schedules/:name               — delete a schedule
- * - POST /queues/:name/jobs               — enqueue a new job
- * - GET  /warnings                        — recent warnings
+ * Express path prefix for every pg-boss admin route. `Api.child()` only
+ * affects OpenAPI documentation, not the underlying express router, so the
+ * prefix MUST live on each path string to make routing work end-to-end.
  */
-export declare const mountPgBossApiRoutes: (api: Api, service: PgBossService) => void;
+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;

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

@@ -1,37 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.mountPgBossApiRoutes = void 0;
+exports.mountPgBossApiRoutes = exports.PGBOSS_API_PATH_PREFIX = void 0;
 const send_1 = require("../../api/send");
 const response_1 = require("../../api/response");
 const routes_schema_1 = require("./routes.schema");
 /**
- * Mounts pg-boss dashboard API routes onto an Api instance.
- *
- * Endpoints:
- * - GET  /queues                          — list queues with stats
- * - GET  /queues/:name/jobs               — list jobs in a queue
- * - GET  /queues/:queue/jobs/:id          — job detail
- * - POST /queues/:queue/jobs/:id/retry    — retry a job
- * - POST /queues/:queue/jobs/:id/cancel   — cancel a job
- * - DELETE /queues/:queue/jobs/:id        — delete a job
- * - GET  /schedules                       — list cron schedules
- * - POST /schedules                       — create a schedule
- * - PUT  /schedules/:name                 — update a schedule
- * - DELETE /schedules/:name               — delete a schedule
- * - POST /queues/:name/jobs               — enqueue a new job
- * - GET  /warnings                        — recent warnings
+ * Express path prefix for every pg-boss admin route. `Api.child()` only
+ * affects OpenAPI documentation, not the underlying express router, so the
+ * prefix MUST live on each path string to make routing work end-to-end.
  */
-const mountPgBossApiRoutes = (api, service) => {
+exports.PGBOSS_API_PATH_PREFIX = '/support/pgboss';
+const mountPgBossApiRoutes = (api, service, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+middlewares) => {
     const pgBossApi = api.child({ tags: ['PgBoss'] });
-    // GET /queues — list queues with stats
-    pgBossApi.get('/queues', 'List all queues with stats', {
+    const p = (path) => `${exports.PGBOSS_API_PATH_PREFIX}${path}`;
+    const mw = middlewares?.length ? { middlewares } : {};
+    pgBossApi.get(p('/queues'), 'List all queues with stats', {
+        ...mw,
         responses: [(0, response_1.okResponse)(routes_schema_1.queueStatsArraySchema)],
     }, async (_request, _context, respond) => {
         const stats = await service.getQueueStats();
         return respond((0, send_1.ok)(stats));
     });
-    // GET /queues/:name/jobs — list jobs in a queue
-    pgBossApi.get('/queues/:name/jobs', 'List jobs in a queue', {
+    pgBossApi.get(p('/queues/:name/jobs'), 'List jobs in a queue', {
+        ...mw,
         responses: [(0, response_1.okResponse)(routes_schema_1.jobArraySchema)],
         schemas: {
             params: routes_schema_1.queueNameParamsSchema,
@@ -40,8 +33,8 @@ const mountPgBossApiRoutes = (api, service) => {
         const jobs = await service.listJobs(request.params.name);
         return respond((0, send_1.ok)(jobs));
     });
-    // GET /queues/:queue/jobs/:id — job detail
-    pgBossApi.get('/queues/:queue/jobs/:id', 'Get job details', {
+    pgBossApi.get(p('/queues/:queue/jobs/:id'), 'Get job details', {
+        ...mw,
         responses: [(0, response_1.okResponse)(routes_schema_1.jobDetailSchema)],
         schemas: {
             params: routes_schema_1.queueJobParamsSchema,
@@ -54,8 +47,8 @@ const mountPgBossApiRoutes = (api, service) => {
         }
         return respond((0, send_1.ok)(job));
     });
-    // POST /queues/:queue/jobs/:id/retry — retry a failed job
-    pgBossApi.post('/queues/:queue/jobs/:id/retry', 'Retry a failed job', {
+    pgBossApi.post(p('/queues/:queue/jobs/:id/retry'), 'Retry a failed job', {
+        ...mw,
         responses: [(0, response_1.okResponse)(routes_schema_1.successResponseSchema)],
         schemas: {
             params: routes_schema_1.queueJobParamsSchema,
@@ -65,8 +58,8 @@ const mountPgBossApiRoutes = (api, service) => {
         await service.retryJob(queue, id);
         return respond((0, send_1.ok)({ success: true, jobId: id }));
     });
-    // POST /queues/:queue/jobs/:id/cancel — cancel a job
-    pgBossApi.post('/queues/:queue/jobs/:id/cancel', 'Cancel a job', {
+    pgBossApi.post(p('/queues/:queue/jobs/:id/cancel'), 'Cancel a job', {
+        ...mw,
         responses: [(0, response_1.okResponse)(routes_schema_1.successResponseSchema)],
         schemas: {
             params: routes_schema_1.queueJobParamsSchema,
@@ -76,8 +69,8 @@ const mountPgBossApiRoutes = (api, service) => {
         await service.cancelJob(queue, id);
         return respond((0, send_1.ok)({ success: true, jobId: id }));
     });
-    // DELETE /queues/:queue/jobs/:id — delete a job
-    pgBossApi.delete('/queues/:queue/jobs/:id', 'Delete a job', {
+    pgBossApi.delete(p('/queues/:queue/jobs/:id'), 'Delete a job', {
+        ...mw,
         responses: [(0, response_1.okResponse)(routes_schema_1.successResponseSchema)],
         schemas: {
             params: routes_schema_1.queueJobParamsSchema,
@@ -87,15 +80,15 @@ const mountPgBossApiRoutes = (api, service) => {
         await service.deleteJob(queue, id);
         return respond((0, send_1.ok)({ success: true, deleted: id }));
     });
-    // GET /schedules — list cron schedules
-    pgBossApi.get('/schedules', 'List all cron schedules', {
+    pgBossApi.get(p('/schedules'), 'List all cron schedules', {
+        ...mw,
         responses: [(0, response_1.okResponse)(routes_schema_1.scheduleArraySchema)],
     }, async (_request, _context, respond) => {
         const schedules = await service.getSchedules();
         return respond((0, send_1.ok)(schedules));
     });
-    // POST /schedules — create a cron schedule
-    pgBossApi.post('/schedules', 'Create a cron schedule', {
+    pgBossApi.post(p('/schedules'), 'Create a cron schedule', {
+        ...mw,
         responses: [(0, response_1.createdResponse)(routes_schema_1.successResponseSchema)],
         schemas: {
             body: routes_schema_1.scheduleBodySchema,
@@ -105,8 +98,8 @@ const mountPgBossApiRoutes = (api, service) => {
         await service.createSchedule(name, cron, data, options);
         return respond((0, send_1.created)({ success: true, name }));
     });
-    // PUT /schedules/:name — update a cron schedule
-    pgBossApi.put('/schedules/:name', 'Update a cron schedule', {
+    pgBossApi.put(p('/schedules/:name'), 'Update a cron schedule', {
+        ...mw,
         responses: [(0, response_1.okResponse)(routes_schema_1.successResponseSchema)],
         schemas: {
             params: routes_schema_1.scheduleNameParamsSchema,
@@ -117,8 +110,8 @@ const mountPgBossApiRoutes = (api, service) => {
         await service.updateSchedule(request.params.name, cron, data, options);
         return respond((0, send_1.ok)({ success: true, name: request.params.name }));
     });
-    // DELETE /schedules/:name — delete a cron schedule
-    pgBossApi.delete('/schedules/:name', 'Delete a cron schedule', {
+    pgBossApi.delete(p('/schedules/:name'), 'Delete a cron schedule', {
+        ...mw,
         responses: [(0, response_1.okResponse)(routes_schema_1.successResponseSchema)],
         schemas: {
             params: routes_schema_1.scheduleNameParamsSchema,
@@ -127,8 +120,8 @@ const mountPgBossApiRoutes = (api, service) => {
         await service.deleteSchedule(request.params.name);
         return respond((0, send_1.ok)({ success: true, deleted: request.params.name }));
     });
-    // POST /queues/:name/jobs — enqueue a new job
-    pgBossApi.post('/queues/:name/jobs', 'Enqueue a new job', {
+    pgBossApi.post(p('/queues/:name/jobs'), 'Enqueue a new job', {
+        ...mw,
         responses: [(0, response_1.createdResponse)(routes_schema_1.successResponseSchema)],
         schemas: {
             params: routes_schema_1.queueNameParamsSchema,
@@ -139,8 +132,8 @@ const mountPgBossApiRoutes = (api, service) => {
         const jobId = await service.enqueueJob(request.params.name, data, options);
         return respond((0, send_1.created)({ success: true, jobId: jobId ?? undefined }));
     });
-    // GET /warnings — recent warnings
-    pgBossApi.get('/warnings', 'List recent warnings', {
+    pgBossApi.get(p('/warnings'), 'List recent warnings', {
+        ...mw,
         responses: [(0, response_1.okResponse)(routes_schema_1.warningArraySchema)],
         schemas: {
             query: routes_schema_1.warningsQuerySchema,

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

@@ -1,5 +1,5 @@
 import { PgBoss } from 'pg-boss';
-import type { SendOptions } from 'pg-boss';
+import type { Job, SendOptions } from 'pg-boss';
 import type { Logger } from 'pino';
 import type { Sequelize, Transaction } from 'sequelize';
 /**
@@ -13,3 +13,11 @@ export declare const enqueueJob: (boss: PgBoss, queueName: string, data: object,
  * instead of calling internal SQL functions directly.
  */
 export declare const enqueueInTransaction: (boss: PgBoss, queueName: string, data: object, options: SendOptions, transaction: Transaction, sequelize: Sequelize) => 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.
+ *
+ * Requires the worker to be registered with `{ includeMetadata: true }` so
+ * `retryCount` and `retryLimit` are populated on each job.
+ */
+export declare const withDlqAlerting: <T = object>(queueName: string, handler: (jobs: Job<T>[]) => Promise<void>, logger: Logger, mattermostWebhookUrl?: string) => ((jobs: Job<T>[]) => Promise<void>);

package/dist/lib/pgBoss/helpers.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.enqueueInTransaction = exports.enqueueJob = void 0;
+exports.withDlqAlerting = exports.enqueueInTransaction = exports.enqueueJob = void 0;
+const metrics_1 = require("./metrics");
 /**
  * Enqueue a job via pg-boss with logging.
  */
@@ -42,3 +43,29 @@ const enqueueInTransaction = async (boss, queueName, data, options, transaction,
     return boss.send(queueName, data, { ...options, db });
 };
 exports.enqueueInTransaction = enqueueInTransaction;
+/**
+ * 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.
+ *
+ * Requires the worker to be registered with `{ includeMetadata: true }` so
+ * `retryCount` and `retryLimit` are populated on each job.
+ */
+const withDlqAlerting = (queueName, handler, logger, mattermostWebhookUrl) => {
+    return async (jobs) => {
+        try {
+            await handler(jobs);
+        }
+        catch (error) {
+            const job = jobs[0];
+            const retryCount = job?.retryCount ?? 0;
+            const retryLimit = job?.retryLimit ?? 0;
+            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);
+            }
+            throw error;
+        }
+    };
+};
+exports.withDlqAlerting = withDlqAlerting;

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

@@ -2,28 +2,41 @@ import { PgBoss } from 'pg-boss';
 import type { Logger } from 'pino';
 import type { PgBossConfig } from './types';
 export { PgBoss };
+export type { Job, SendOptions } from 'pg-boss';
 export type { PgBossConfig, QueueDefinition, WorkerRegistration, PgBossInstance, } from './types';
 export { PG_BOSS_DEFAULTS, buildPgBossDefaults } from './config';
 export { mountPgBossApiRoutes } from './controller/routes';
 export { PgBossService } from './service';
 export { registerPgBossMetrics } from './metrics';
-export { enqueueJob, enqueueInTransaction } from './helpers';
+export { enqueueJob, enqueueInTransaction, withDlqAlerting } from './helpers';
 export { sendDlqAlert } from './metrics';
 export interface PgBossContext {
     boss: PgBoss;
     logger: Logger;
     config: Required<PgBossConfig>;
+    serviceName: string;
+    metricsInterval?: NodeJS.Timeout;
 }
 /**
  * Creates a pg-boss instance with error recovery (auto-restart on connection loss).
  * Issue #510 mitigation: on error, waits 5s then restarts.
  */
-export declare const createPgBoss: (config: PgBossConfig, logger: Logger) => PgBossContext;
+export declare const createPgBoss: (config: PgBossConfig, logger: Logger, serviceName?: string) => PgBossContext;
 /**
- * Starts the pg-boss instance. Call after database is connected.
+ * Starts the pg-boss instance and registers Prometheus metrics polling.
+ * Call after database is connected.
  */
 export declare const startBoss: (ctx: PgBossContext) => Promise<void>;
 /**
- * Gracefully stops the pg-boss instance. Suitable as a shutdown handler.
+ * Gracefully stops the pg-boss instance and clears metrics polling.
+ * Suitable as a shutdown handler.
  */
 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
+ * `boss.createQueue(name, { ...defaultRetention(ctx), policy: 'singleton' })`.
+ */
+export declare const defaultRetention: (ctx: PgBossContext) => {
+    deleteAfterSeconds: number;
+};

package/dist/lib/pgBoss/index.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stopBoss = exports.startBoss = exports.createPgBoss = exports.sendDlqAlert = 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 = exports.PgBoss = 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");
 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; } });
@@ -11,24 +12,27 @@ var routes_1 = require("./controller/routes");
 Object.defineProperty(exports, "mountPgBossApiRoutes", { enumerable: true, get: function () { return routes_1.mountPgBossApiRoutes; } });
 var service_1 = require("./service");
 Object.defineProperty(exports, "PgBossService", { enumerable: true, get: function () { return service_1.PgBossService; } });
-var metrics_1 = require("./metrics");
-Object.defineProperty(exports, "registerPgBossMetrics", { enumerable: true, get: function () { return metrics_1.registerPgBossMetrics; } });
+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; } });
-var metrics_2 = require("./metrics");
-Object.defineProperty(exports, "sendDlqAlert", { enumerable: true, get: function () { return metrics_2.sendDlqAlert; } });
+Object.defineProperty(exports, "withDlqAlerting", { enumerable: true, get: function () { return helpers_1.withDlqAlerting; } });
+var metrics_3 = require("./metrics");
+Object.defineProperty(exports, "sendDlqAlert", { enumerable: true, get: function () { return metrics_3.sendDlqAlert; } });
 const RESTART_DELAY_MS = 5000;
+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.
  */
-const createPgBoss = (config, logger) => {
+const createPgBoss = (config, logger, serviceName = config.schema) => {
     const resolvedConfig = (0, config_1.buildPgBossDefaults)(config);
     const boss = new pg_boss_1.PgBoss({
         connectionString: resolvedConfig.connectionString,
         schema: resolvedConfig.schema,
         application_name: resolvedConfig.applicationName,
+        max: resolvedConfig.maxConnectionPoolSize,
         migrate: true,
     });
     boss.on('error', (error) => {
@@ -38,27 +42,43 @@ const createPgBoss = (config, logger) => {
     boss.on('warning', warning => {
         logger.warn({ warning }, 'pg-boss warning');
     });
-    return { boss, logger, config: resolvedConfig };
+    return { boss, logger, config: resolvedConfig, serviceName };
 };
 exports.createPgBoss = createPgBoss;
 /**
- * Starts the pg-boss instance. Call after database is connected.
+ * Starts the pg-boss instance and registers Prometheus metrics polling.
+ * Call after database is connected.
  */
 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.logger.info({ schema: ctx.config.schema }, 'pg-boss started successfully');
 };
 exports.startBoss = startBoss;
 /**
- * Gracefully stops the pg-boss instance. Suitable as a shutdown handler.
+ * Gracefully stops the pg-boss instance and clears metrics polling.
+ * Suitable as a shutdown handler.
  */
 const stopBoss = async (ctx) => {
     ctx.logger.info({ schema: ctx.config.schema }, 'Stopping pg-boss');
+    if (ctx.metricsInterval) {
+        clearInterval(ctx.metricsInterval);
+        ctx.metricsInterval = 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
+ * `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 {

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

@@ -4,7 +4,7 @@ exports.manageJob = void 0;
 const manageJob = async (boss, logger, action, queueName, jobId) => {
     switch (action) {
         case 'retry':
-            await boss.resume(queueName, jobId);
+            await boss.retry(queueName, jobId);
             break;
         case 'cancel':
             await boss.cancel(queueName, jobId);

package/package.json

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