@lucaapp/service-utils 5.12.0 → 5.13.0

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

@@ -0,0 +1,73 @@
+import type { RequestHandler } from 'express';
+import type { Logger } from 'pino';
+import type { Sequelize } from 'sequelize';
+import type { QueueOptions } from 'pg-boss';
+/** pg-boss queue policy values. Accepted at runtime but missing from typed surface. */
+export type QueuePolicy = 'standard' | 'singleton' | 'short' | 'stately';
+/** Queue options extended with the runtime-accepted `policy` field. */
+export type BossQueueOptions = QueueOptions & {
+    policy?: QueuePolicy;
+};
+import type { Api } from '../api/api';
+import type { Middleware } from '../api/types/middleware';
+import type { PgBossContext } from './index';
+import type { QueueDefinition } from './types';
+/**
+ * Default queue options applied to every queue created via `bootstrapPgBoss`
+ * unless the caller overrides per-queue. Tuned for the operational profile
+ * we care about: singleton execution to prevent overlapping runs, exponential
+ * retry, and a small retry budget that's appropriate for short jobs.
+ *
+ * Override per-queue (e.g. `retryLimit: 5` for slow reconcile jobs) by
+ * passing `options` on the queue definition.
+ *
+ * `policy` is accepted at runtime by pg-boss but missing from the public
+ * `QueueOptions` type — cast via `unknown` to keep the type clean for callers.
+ */
+export declare const QUEUE_DEFAULTS: BossQueueOptions;
+export interface PgBossBootstrapOptions {
+    enabled: boolean;
+    sequelize: Sequelize;
+    /** PG schema. Defaults to `'pgboss'` (each service's own DB isolates it). */
+    schema?: string;
+    mattermostWebhookUrl?: string | null;
+    serviceName?: string;
+    /** Queue definitions created via `boss.createQueue` after start. */
+    queueDefinitions?: QueueDefinition[];
+    /** Optional callback invoked after start so callers can register workers. */
+    registerWorkers?: (context: PgBossContext) => void;
+    logger: Logger;
+}
+export interface PgBossBootstrap {
+    context: PgBossContext;
+    start: () => Promise<void>;
+    stop: () => Promise<void>;
+}
+/**
+ * One-call bootstrap for a service's pg-boss instance:
+ * `createPgBoss` → `startBoss` → `boss.createQueue` per definition →
+ * caller-provided `registerWorkers` callback.
+ *
+ * Returns `null` when `enabled` is false so callers can skip wiring without
+ * branching. Returns `{ context, start, stop }` otherwise — caller awaits
+ * `start()` after the database connection is up and registers `stop` as a
+ * shutdown handler.
+ */
+export declare const bootstrapPgBoss: (opts: PgBossBootstrapOptions) => PgBossBootstrap | null;
+/**
+ * Mount the pg-boss admin API on a parent `Api`. Wraps the
+ * `Api.child` + `PgBossService` + `mountPgBossApiRoutes` boilerplate.
+ *
+ * `middlewares` MUST contain the auth middleware that gates support
+ * access (`mountPgBossApiRoutes` rejects an empty list at mount time).
+ */
+export declare const mountPgBossDashboard: (parentApi: Api, context: PgBossContext, middlewares: Middleware<any, any, any, any, any, any>[]) => void;
+/**
+ * Wrap an Express request handler so the request is enqueued via pg-boss
+ * when a context is provided. On enqueue failure (or when pg-boss is
+ * disabled) the original handler runs synchronously.
+ *
+ * Useful for HTTP-triggered jobs that must keep working when pg-boss is
+ * off or temporarily unavailable.
+ */
+export declare const withPgBossFallback: (context: PgBossContext | undefined, queueName: string, handler: RequestHandler, buildPayload?: (request: Parameters<RequestHandler>[0]) => object) => RequestHandler;

package/dist/lib/pgBoss/bootstrap.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withPgBossFallback = exports.mountPgBossDashboard = exports.bootstrapPgBoss = exports.QUEUE_DEFAULTS = void 0;
+const index_1 = require("./index");
+const service_1 = require("./service");
+const routes_1 = require("./controller/routes");
+/**
+ * Default queue options applied to every queue created via `bootstrapPgBoss`
+ * unless the caller overrides per-queue. Tuned for the operational profile
+ * we care about: singleton execution to prevent overlapping runs, exponential
+ * retry, and a small retry budget that's appropriate for short jobs.
+ *
+ * Override per-queue (e.g. `retryLimit: 5` for slow reconcile jobs) by
+ * passing `options` on the queue definition.
+ *
+ * `policy` is accepted at runtime by pg-boss but missing from the public
+ * `QueueOptions` type — cast via `unknown` to keep the type clean for callers.
+ */
+exports.QUEUE_DEFAULTS = {
+    policy: 'singleton',
+    retryLimit: 3,
+    retryBackoff: true,
+};
+const DEFAULT_SCHEMA = 'pgboss';
+/**
+ * One-call bootstrap for a service's pg-boss instance:
+ * `createPgBoss` → `startBoss` → `boss.createQueue` per definition →
+ * caller-provided `registerWorkers` callback.
+ *
+ * Returns `null` when `enabled` is false so callers can skip wiring without
+ * branching. Returns `{ context, start, stop }` otherwise — caller awaits
+ * `start()` after the database connection is up and registers `stop` as a
+ * shutdown handler.
+ */
+const bootstrapPgBoss = (opts) => {
+    if (!opts.enabled)
+        return null;
+    const context = (0, index_1.createPgBoss)({
+        enabled: true,
+        sequelize: opts.sequelize,
+        schema: opts.schema ?? DEFAULT_SCHEMA,
+        mattermostWebhookUrl: opts.mattermostWebhookUrl ?? null,
+    }, opts.logger, opts.serviceName ?? opts.schema ?? DEFAULT_SCHEMA);
+    const start = async () => {
+        await (0, index_1.startBoss)(context);
+        if (opts.queueDefinitions) {
+            for (const queue of opts.queueDefinitions) {
+                await context.boss.createQueue(queue.name, {
+                    ...exports.QUEUE_DEFAULTS,
+                    ...queue.options,
+                });
+            }
+        }
+        opts.registerWorkers?.(context);
+    };
+    const stop = () => (0, index_1.stopBoss)(context);
+    return { context, start, stop };
+};
+exports.bootstrapPgBoss = bootstrapPgBoss;
+/**
+ * Mount the pg-boss admin API on a parent `Api`. Wraps the
+ * `Api.child` + `PgBossService` + `mountPgBossApiRoutes` boilerplate.
+ *
+ * `middlewares` MUST contain the auth middleware that gates support
+ * access (`mountPgBossApiRoutes` rejects an empty list at mount time).
+ */
+const mountPgBossDashboard = (parentApi, context, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+middlewares) => {
+    const childApi = parentApi.child({ tags: ['PgBoss'] });
+    const service = new service_1.PgBossService(context.boss, context.logger, context.config.schema);
+    (0, routes_1.mountPgBossApiRoutes)(childApi, service, middlewares);
+};
+exports.mountPgBossDashboard = mountPgBossDashboard;
+/**
+ * Wrap an Express request handler so the request is enqueued via pg-boss
+ * when a context is provided. On enqueue failure (or when pg-boss is
+ * disabled) the original handler runs synchronously.
+ *
+ * Useful for HTTP-triggered jobs that must keep working when pg-boss is
+ * off or temporarily unavailable.
+ */
+const withPgBossFallback = (context, queueName, handler, buildPayload = () => ({})) => {
+    return async (request, response, next) => {
+        if (context) {
+            try {
+                const jobId = await context.boss.send(queueName, buildPayload(request));
+                response.json({ queued: true, jobId });
+                return;
+            }
+            catch (error) {
+                context.logger.error({ error, queueName }, 'pg-boss enqueue failed, falling back to sync handler');
+            }
+        }
+        await handler(request, response, next);
+    };
+};
+exports.withPgBossFallback = withPgBossFallback;

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

@@ -3,9 +3,12 @@ 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.
+ * Create a pg-boss database adapter that runs SQL via Sequelize's raw pg
+ * client. Reuses Sequelize's connection pool, dialect options (TLS,
+ * fingerprint pinning), retries, and disconnect handling, but bypasses
+ * Sequelize's SQL parser — pg-boss's DDL is multi-statement and uses
+ * `GENERATED ALWAYS AS IDENTITY` syntax that breaks under prepared-statement
+ * mode.
  *
  * Used as pg-boss's `db` option so pg-boss does not open its own pool.
  */

package/dist/lib/pgBoss/helpers.js

@@ -3,23 +3,28 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.withDlqAlerting = exports.enqueueInTransaction = exports.enqueueJob = exports.createSequelizeDbAdapter = void 0;
 const metrics_1 = require("./metrics");
 /**
- * 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.
+ * Create a pg-boss database adapter that runs SQL via Sequelize's raw pg
+ * client. Reuses Sequelize's connection pool, dialect options (TLS,
+ * fingerprint pinning), retries, and disconnect handling, but bypasses
+ * Sequelize's SQL parser — pg-boss's DDL is multi-statement and uses
+ * `GENERATED ALWAYS AS IDENTITY` syntax that breaks under prepared-statement
+ * mode.
  *
  * Used as pg-boss's `db` option so pg-boss does not open its own pool.
  */
 const createSequelizeDbAdapter = (sequelize) => ({
     executeSql: async (text, values) => {
-        const [results] = await sequelize.query(text, {
-            bind: values,
-            raw: true,
-        });
-        return {
-            rows: Array.isArray(results)
-                ? results
-                : [],
-        };
+        const connectionManager = sequelize.connectionManager;
+        const connection = await connectionManager.getConnection({ type: 'write' });
+        try {
+            const result = await connection.query(text, values);
+            return {
+                rows: Array.isArray(result.rows) ? result.rows : [],
+            };
+        }
+        finally {
+            await connectionManager.releaseConnection(connection);
+        }
     },
 });
 exports.createSequelizeDbAdapter = createSequelizeDbAdapter;

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

@@ -11,6 +11,8 @@ export { PgBossService } from './service';
 export { registerPgBossMetrics } from './metrics';
 export { enqueueJob, enqueueInTransaction, withDlqAlerting } from './helpers';
 export { sendDlqAlert } from './metrics';
+export { bootstrapPgBoss, mountPgBossDashboard, withPgBossFallback, QUEUE_DEFAULTS, } from './bootstrap';
+export type { PgBossBootstrapOptions, PgBossBootstrap } from './bootstrap';
 export interface PgBossContext {
     boss: PgBoss;
     logger: Logger;

package/dist/lib/pgBoss/index.js

@@ -1,6 +1,6 @@
 "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 = void 0;
+exports.defaultRetention = exports.stopBoss = exports.startBoss = exports.createPgBoss = exports.QUEUE_DEFAULTS = exports.withPgBossFallback = exports.mountPgBossDashboard = exports.bootstrapPgBoss = 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");
 const config_1 = require("./config");
 const metrics_1 = require("./metrics");
@@ -20,6 +20,11 @@ Object.defineProperty(exports, "enqueueInTransaction", { enumerable: true, get:
 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; } });
+var bootstrap_1 = require("./bootstrap");
+Object.defineProperty(exports, "bootstrapPgBoss", { enumerable: true, get: function () { return bootstrap_1.bootstrapPgBoss; } });
+Object.defineProperty(exports, "mountPgBossDashboard", { enumerable: true, get: function () { return bootstrap_1.mountPgBossDashboard; } });
+Object.defineProperty(exports, "withPgBossFallback", { enumerable: true, get: function () { return bootstrap_1.withPgBossFallback; } });
+Object.defineProperty(exports, "QUEUE_DEFAULTS", { enumerable: true, get: function () { return bootstrap_1.QUEUE_DEFAULTS; } });
 const RESTART_DELAY_MIN_MS = 5_000;
 const RESTART_DELAY_MAX_MS = 60_000;
 const RESTART_MAX_ATTEMPTS = 10;

package/package.json

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