@pxp-nd/core 1.2.89 → 1.2.91

package/README.md

@@ -1,2 +1,95 @@
 # PXP-ND core
-- Core module for pxp-nd
+- Core module for pxp-nd
+
+## 1.2.91
+
+Correcciones encontradas en las pruebas de carga con la base de datos caída. Sin cambios de API ni de configuración.
+
+### A. La respuesta de error ya no se cuelga si falla el log
+
+Antes, en ambos handlers de ruta (con y sin autenticación), el `insertLog` del error se esperaba antes de llamar a `errorMiddleware`. Con la base caída `insertLog` fallaba, la excepción escapaba del `catch`, nunca se enviaba la respuesta y la request quedaba colgada hasta el timeout del cliente/ALB (en el log: `unhandledRejection PxpError: connect ECONNREFUSED`).
+
+Ahora el log de error va en su propio `try/catch`: `errorMiddleware` **siempre** responde con el error original. Si el log falla se escribe `[pxp-core] error log failed <mensaje>` en consola y la respuesta sale sin `logId`.
+
+### B. El log de éxito ya no genera `unhandledRejection`
+
+El `insertLog` del camino de éxito de `ormMethodWrapper` no se espera (fire-and-forget) y no tenía `.catch`: si fallaba, el rechazo quedaba sin manejar y en Node ≥15 sin handler mata el proceso. Ahora tiene `.catch` que escribe `[pxp-core] success log failed <mensaje>`. (Los wrappers `Procedure` y `Sql` no registran log, no aplica.)
+
+### C. La conexión que llega tarde tras un acquire timeout vuelve al pool
+
+Con `db.acquireTimeoutMs`, cuando la conexión llegaba después del timeout se destruía. Esa conexión está limpia (nunca se abrió transacción), así que destruirla obligaba a mysql2 a abrir otra y dejaba una cola residual (observado: health en 503 unos 6 s después de una ráfaga de 40 requests). Ahora se devuelve al pool con `queryRunner.release()`. El timeout de request (`@Timeout`) sigue destruyendo la conexión, porque ahí sí puede haber una transacción abierta.
+
+## 1.2.90
+
+Release de resiliencia de conexiones a base de datos. **Sin configurar nada, el comportamiento es idéntico a 1.2.89**: todas las opciones nuevas son opt-in.
+
+### `db.acquireTimeoutMs` (opcional)
+
+Tiempo máximo, en milisegundos, que una ruta no-readonly espera para obtener una conexión del pool antes de fallar.
+
+```ts
+new PxpApp({
+  // ...
+  db: { acquireTimeoutMs: 5000 },
+});
+```
+
+- Si vence, la request responde **503** con el mensaje `Database acquire timeout after N ms`.
+- Solo se dispara cuando el pool está agotado; con conexiones libres no agrega latencia.
+- `undefined` o `0` = comportamiento legacy (espera indefinida).
+
+### Decorador `@Timeout(ms)` y opción de ruta `timeoutMs`
+
+Límite de duración por ruta. Se puede usar el decorador o la opción en la definición de la ruta:
+
+```ts
+@Post('/save')
+@Timeout(30000)
+async save(params: any) { /* ... */ }
+
+// o bien
+@Post('/save', { timeoutMs: 30000 })
+```
+
+Al vencer el tiempo:
+- La request responde **503**.
+- La conexión física se destruye, por lo que MySQL hace rollback de la transacción abierta.
+- El handler puede seguir ejecutándose en segundo plano, pero ya sin acceso a la base de datos.
+- Se registra la línea de log `[pxp-core] timeout-abandoned <transactionCode>`.
+
+Sin decorador ni `timeoutMs`, la ruta no tiene límite (igual que 1.2.89).
+
+### Fix: fuga de conexiones si falla `startTransaction()`
+
+Antes, si `startTransaction()` lanzaba un error, la conexión obtenida del pool nunca se liberaba y con el tiempo el pool quedaba agotado. Ahora la conexión se libera siempre.
+
+### Clon del controlador por request (`controllerForRequest`)
+
+Portado desde 1.2.89: cada request trabaja sobre un clon del controlador, de modo que requests concurrentes ya no se pisan `user`, `headers` ni `transactionCode`.
+
+### Proyectos afectados
+
+Dependen de core con `^1.2.x`, así que tomarán esta versión en su próximo `npm install`:
+
+- tempo
+- conductor-nd
+- go-pxp-nd
+- Api_Boa_ND
+- electrica360_nd
+- cleaners-pxp-nd
+
+Sin configurar `db.acquireTimeoutMs` ni `@Timeout`/`timeoutMs`, ninguno de ellos cambia de comportamiento respecto a 1.2.89.
+
+### Tests (`npm test`)
+
+`test/db-timeouts.test.ts` (jest + ts-jest) prueba contra un MySQL **real y desechable**: comportamiento legado sin `db`, `db.acquireTimeoutMs` con un pool `write` de 1 conexión, y `@Timeout` (503, sin transacción abierta en `innodb_trx`, nada commiteado, el pool se recupera).
+
+```bash
+docker run --rm -d --name pxp-core-test-mysql -e MYSQL_ROOT_PASSWORD=test -e MYSQL_DATABASE=pxptest -p 33306:3306 mysql:8
+npm test
+docker stop pxp-core-test-mysql
+```
+
+Variables: `TEST_DB_HOST` (127.0.0.1), `TEST_DB_PORT` (33306), `TEST_DB_USER` (root), `TEST_DB_PASSWORD` (test), `TEST_DB_NAME` (pxptest). Usar solo una BD desechable: los tests crean las tablas `tsec_log` y `pxp_timeout_probe` y ocupan el pool con `SLEEP`, así que no apuntarlos a dev/beta/prod compartidas. Si la BD no responde, la suite se marca `skipped` (nunca falla por falta de BD).
+
+`test/error-path.test.ts` no necesita MySQL: `insertLog` está mockeado para fallar y verifica que una ruta que lanza `PxpError(400)` responde 400 con el mensaje original (sin colgarse) y que el fallo del log de éxito no produce `unhandledRejection`.

package/dist/interfaces.d.ts

@@ -49,5 +49,10 @@ export interface IConfigPxpApp {
     expressJsonConfig?: IConfigExpress;
     expressUrlEncodedConfig?: IConfigExpress;
     permissionFunction?: boolean | ((user: any, transaction: string) => Promise<boolean>);
+    /** Database safety options. All optional; when omitted the behaviour is identical to <=1.2.89. */
+    db?: {
+        /** Max ms to wait for a pool connection before a non-readonly route fails with 503. Undefined/0 = wait forever (legacy). */
+        acquireTimeoutMs?: number;
+    };
 }
 export {};

package/dist/lib/pxp/Controller.d.ts

@@ -12,6 +12,9 @@
  * Last modified  : 2020-10-13 15:36:31
  * Last modified  : 2021-03-10 15:36:31 - Favio Figueroa
  * Last modified  : 2021-05-01 18:35:31 - Favio Figueroa
+ * Last modified  : 2026-10-08 - Favio Figueroa - EF-23 per-request controller clone (from 1.2.89), startTransaction inside try
+ * Last modified  : 2026-10-08 - Favio Figueroa - EF-23 acquire timeout + @Timeout decorator
+ * Last modified  : 2026-10-08 - Favio Figueroa - EF-23 log failures never block or crash the response (1.2.91)
  */
 import { EntityManager } from 'typeorm';
 import { Request, Response, NextFunction } from 'express';
@@ -37,8 +40,8 @@ export declare class Controller implements ControllerInterface {
     private basicReadOnly;
     constructor(module: string, Entity?: any, config?: IConfigPxpApp, io?: any);
     private initializeRoutes;
-    genericMethodWrapper(params: Record<string, unknown>, req: Request, next: NextFunction, res: Response, methodName: string, dbsettings: string, readonly: boolean, permission: boolean, log: boolean, logConfig: {}, isHtml: boolean, isFile: boolean): Promise<void>;
-    ormMethodWrapper(params: Record<string, unknown>, req: Request | any, next: NextFunction, res: Response, methodName: string, readonly: boolean, permission?: boolean, log?: boolean, logConfig?: {}, isHtml?: boolean, isFile?: boolean): Promise<void>;
+    genericMethodWrapper(params: Record<string, unknown>, req: Request, next: NextFunction, res: Response, methodName: string, dbsettings: string, readonly: boolean, permission: boolean, log: boolean, logConfig: {}, isHtml: boolean, isFile: boolean, timeoutMs?: number): Promise<void>;
+    ormMethodWrapper(params: Record<string, unknown>, req: Request | any, next: NextFunction, res: Response, methodName: string, readonly: boolean, permission?: boolean, log?: boolean, logConfig?: {}, isHtml?: boolean, isFile?: boolean, timeoutMs?: number): Promise<void>;
     list(params: Record<string, unknown>): Promise<unknown>;
     add(params: Record<string, unknown>, manager: EntityManager): Promise<unknown>;
     edit(params: Record<string, unknown>, manager: EntityManager): Promise<unknown>;

package/dist/lib/pxp/Controller.js

@@ -37,6 +37,9 @@ exports.Controller = void 0;
  * Last modified  : 2020-10-13 15:36:31
  * Last modified  : 2021-03-10 15:36:31 - Favio Figueroa
  * Last modified  : 2021-05-01 18:35:31 - Favio Figueroa
+ * Last modified  : 2026-10-08 - Favio Figueroa - EF-23 per-request controller clone (from 1.2.89), startTransaction inside try
+ * Last modified  : 2026-10-08 - Favio Figueroa - EF-23 acquire timeout + @Timeout decorator
+ * Last modified  : 2026-10-08 - Favio Figueroa - EF-23 log failures never block or crash the response (1.2.91)
  */
 const typeorm_1 = require("typeorm");
 const class_validator_1 = require("class-validator");
@@ -51,6 +54,7 @@ const ParseParams_1 = require("./middlewares/ParseParams");
 const isReportMiddleware_1 = require("./middlewares/isReportMiddleware");
 const pdf_1 = require("../reports/pdf");
 const xlsx_1 = require("../reports/xlsx");
+const DbTimeouts_1 = require("./utils/DbTimeouts");
 // import * as entities from '@pxp-nd/entities';
 // const pxpEntities: any = entities;
 class Controller {
@@ -128,6 +132,8 @@ class Controller {
         // get type return
         let ishtml = Reflect.getMetadata('ishtml', this.constructor) || {};
         let isfile = Reflect.getMetadata('isfile', this.constructor) || {};
+        // get request timeouts (@Timeout)
+        const timeouts = Reflect.getMetadata('timeout', this.constructor) || {};
         const defaultConfig = Reflect.getMetadata('optionsRoute', this.constructor) || {};
         // define basic routes
         if (this.modelString !== '') {
@@ -146,6 +152,8 @@ class Controller {
             const isHtmlMethod = ishtml[route.methodName] !== undefined ? ishtml[route.methodName] : (defaultConfig[route.methodName] ? defaultConfig[route.methodName].ishtml : false);
             // is file
             const isFileMethod = isfile[route.methodName] !== undefined ? isfile[route.methodName] : (defaultConfig[route.methodName] ? defaultConfig[route.methodName].isfile : false);
+            // request timeout (ms), undefined = no timeout
+            const timeoutMethod = timeouts[route.methodName] !== undefined ? timeouts[route.methodName] : (defaultConfig[route.methodName] ? defaultConfig[route.methodName].timeoutMs : undefined);
             if (readOnlyMethod === null || readOnlyMethod === undefined) {
                 throw new index_1.PxpError(500, 'ReadOnly decorator was not defined for ' +
                     route.methodName +
@@ -175,14 +183,21 @@ class Controller {
                         .toLowerCase();
                     controllerForRequest.validated = false;
                     try {
-                        await index_1.__(controllerForRequest.genericMethodWrapper(params, req, next, res, route.methodName, methodDbSettings, readOnlyMethod, false, logKey, logValue, isHtmlMethod, isFileMethod));
+                        await index_1.__(controllerForRequest.genericMethodWrapper(params, req, next, res, route.methodName, methodDbSettings, readOnlyMethod, false, logKey, logValue, isHtmlMethod, isFileMethod, timeoutMethod));
                     }
                     catch (ex) {
                         const now = new Date();
                         const iniAt = req.start;
                         const endsAt = now.valueOf() - iniAt.valueOf();
-                        res.logId = await index_1.__(index_1.insertLog('nouser', 'mac', req.ip, 'error', ex.tecMessage, this.module, this.transactionCode, '', // query
-                        params, ex.stack, ex.statusCode, endsAt, logValue));
+                        // A failing error log (e.g. database down) must never prevent the response.
+                        try {
+                            res.logId = await index_1.__(index_1.insertLog('nouser', 'mac', req.ip, 'error', ex.tecMessage, controllerForRequest.module, controllerForRequest.transactionCode, '', // query
+                            params, ex.stack, ex.statusCode, endsAt, logValue));
+                        }
+                        catch (logErr) {
+                            // __ wraps driver errors in PxpError(500) with a generic message; the real cause is tecMessage.
+                            console.error('[pxp-core] error log failed', logErr && (logErr.tecMessage || logErr.message));
+                        }
                         index_1.errorMiddleware(ex, req, res);
                     }
                 });
@@ -209,23 +224,30 @@ class Controller {
                         .toLowerCase();
                     controllerForRequest.validated = false;
                     try {
-                        await index_1.__(controllerForRequest.genericMethodWrapper(params, req, next, res, route.methodName, methodDbSettings, readOnlyMethod, permission[route.methodName], logKey, logValue, isHtmlMethod, isFileMethod));
+                        await index_1.__(controllerForRequest.genericMethodWrapper(params, req, next, res, route.methodName, methodDbSettings, readOnlyMethod, permission[route.methodName], logKey, logValue, isHtmlMethod, isFileMethod, timeoutMethod));
                     }
                     catch (ex) {
                         const now = new Date();
                         const iniAt = req.start;
                         const endsAt = now.valueOf() - iniAt.valueOf();
-                        res.logId = (await index_1.__(index_1.insertLog(controllerForRequest.user && controllerForRequest.user.username ? controllerForRequest.user.username : 'nouser', 'mac', req.ip, 'error', ex.tecMessage, this.module, this.transactionCode, '', // query
-                        params, ex.stack, ex.statusCode, endsAt, logValue)));
+                        // A failing error log (e.g. database down) must never prevent the response.
+                        try {
+                            res.logId = (await index_1.__(index_1.insertLog(controllerForRequest.user && controllerForRequest.user.username ? controllerForRequest.user.username : 'nouser', 'mac', req.ip, 'error', ex.tecMessage, controllerForRequest.module, controllerForRequest.transactionCode, '', // query
+                            params, ex.stack, ex.statusCode, endsAt, logValue)));
+                        }
+                        catch (logErr) {
+                            // __ wraps driver errors in PxpError(500) with a generic message; the real cause is tecMessage.
+                            console.error('[pxp-core] error log failed', logErr && (logErr.tecMessage || logErr.message));
+                        }
                         index_1.errorMiddleware(ex, req, res);
                     }
                 });
             }
         });
     }
-    async genericMethodWrapper(params, req, next, res, methodName, dbsettings, readonly, permission = true, log = true, logConfig = {}, isHtml, isFile) {
+    async genericMethodWrapper(params, req, next, res, methodName, dbsettings, readonly, permission = true, log = true, logConfig = {}, isHtml, isFile, timeoutMs) {
         if (dbsettings === 'Orm') {
-            await index_1.__(this.ormMethodWrapper(params, req, next, res, methodName, readonly, permission, log, logConfig, isHtml, isFile));
+            await index_1.__(this.ormMethodWrapper(params, req, next, res, methodName, readonly, permission, log, logConfig, isHtml, isFile, timeoutMs));
         }
         else if (dbsettings === 'Procedure') {
             await index_1.__(this.procedureMethodWrapper(params, next, res, methodName, readonly, permission, log, logConfig));
@@ -234,7 +256,8 @@ class Controller {
             await this.sqlMethodWrapper(params, next, res, methodName, readonly, permission, log, logConfig);
         }
     }
-    async ormMethodWrapper(params, req, next, res, methodName, readonly, permission = true, log = true, logConfig = {}, isHtml = false, isFile = false) {
+    async ormMethodWrapper(params, req, next, res, methodName, readonly, permission = true, log = true, logConfig = {}, isHtml = false, isFile = false, timeoutMs) {
+        var _a;
         let metResponse;
         if (permission) {
             if (this.user) {
@@ -250,26 +273,63 @@ class Controller {
         else {
             const connection = typeorm_1.getConnection(process.env.DB_WRITE_CONNECTION_NAME);
             const queryRunner = connection.createQueryRunner();
-            // establish real database connection using our new query runner
-            await index_1.__(queryRunner.connect());
-            await index_1.__(queryRunner.startTransaction());
+            // establish real database connection using our new query runner.
+            // `db` is added to IConfigPxpApp by a later change; without it this is a plain connect().
+            const acquireTimeoutMs = (_a = this.config.db) === null || _a === void 0 ? void 0 : _a.acquireTimeoutMs;
+            await index_1.__(DbTimeouts_1.connectWithTimeout(queryRunner, acquireTimeoutMs, this.transactionCode));
+            let timedOut = false;
+            let timer;
             try {
-                metResponse = (await eval(`this.${methodName}(params, queryRunner.manager, res, req)`));
+                // Start the transaction inside try so a failure here still releases the connection
+                await index_1.__(queryRunner.startTransaction());
+                const work = Promise.resolve(eval(`this.${methodName}(params, queryRunner.manager, res, req)`));
+                if (timeoutMs && timeoutMs > 0) {
+                    metResponse = await Promise.race([
+                        work,
+                        new Promise((_, reject) => {
+                            timer = setTimeout(() => {
+                                timedOut = true;
+                                reject(new DbTimeouts_1.DbTimeoutError('request', timeoutMs, this.transactionCode));
+                            }, timeoutMs);
+                        })
+                    ]);
+                }
+                else {
+                    metResponse = await work;
+                }
                 await queryRunner.commitTransaction();
             }
             catch (err) {
-                await queryRunner.rollbackTransaction();
+                // On request timeout skip rollback: it would queue behind the abandoned statement and delay the 503 (destroy rolls back server-side).
+                if (!timedOut && queryRunner.isTransactionActive) {
+                    try {
+                        await queryRunner.rollbackTransaction();
+                    }
+                    catch (_) {
+                        // keep the original error; the connection is released or destroyed below
+                    }
+                }
                 throw err;
             }
             finally {
-                await index_1.__(queryRunner.release());
+                if (timer)
+                    clearTimeout(timer);
+                if (timedOut) {
+                    // The handler may keep running in background; its connection is destroyed so it cannot commit.
+                    console.warn(`[pxp-core] timeout-abandoned ${this.transactionCode}`);
+                    await DbTimeouts_1.destroyQueryRunner(queryRunner);
+                }
+                else {
+                    await index_1.__(queryRunner.release());
+                }
             }
         }
         if (log) {
             const now = new Date();
             const iniAt = req.start;
             const endsAt = now.valueOf() - iniAt.valueOf();
-            index_1.__(index_1.insertLog(this.user && this.user.username ? this.user.username : 'nouser', 'mac', req.ip, 'success', 'successful transaction', this.module, this.transactionCode, '', params, JSON.stringify(metResponse), '200', endsAt, logConfig));
+            // Fire-and-forget: without the catch a failing log is an unhandledRejection (fatal on Node >= 15).
+            index_1.__(index_1.insertLog(this.user && this.user.username ? this.user.username : 'nouser', 'mac', req.ip, 'success', 'successful transaction', this.module, this.transactionCode, '', params, JSON.stringify(metResponse), '200', endsAt, logConfig)).catch(err => console.error('[pxp-core] success log failed', err && (err.tecMessage || err.message)));
         }
         //PARA REPORTES
         if (req.report && req.report.type === 'pdf') {

package/dist/lib/pxp/Decorators.d.ts

@@ -8,6 +8,7 @@ export declare interface IOptionsRoute {
     dbSettings?: 'Procedure' | 'Orm' | 'Query';
     authentication?: boolean;
     log?: boolean | ILog;
+    timeoutMs?: number;
 }
 declare const Get: (path?: string, options?: IOptionsRoute) => (target: any, propertyKey: string) => void;
 declare const Post: (path?: string, options?: IOptionsRoute) => (target: any, propertyKey: string) => void;
@@ -19,9 +20,10 @@ declare const Model: (model: string) => ClassDecorator;
 declare const StoredProcedure: (storedProcedure: string) => ClassDecorator;
 declare const Authentication: (authentication?: boolean) => (target: any, propertyKey: string) => void;
 declare const ReadOnly: (ronly?: boolean) => (target: any, propertyKey: string) => void;
+declare const Timeout: (ms: number) => (target: any, propertyKey: string) => void;
 declare const IsHtml: (ishtml?: boolean) => (target: any, propertyKey: string) => void;
 declare const IsFile: (isFile?: boolean) => (target: any, propertyKey: string) => void;
 declare const DbSettings: (modelType: 'Procedure' | 'Orm' | 'Query') => (target: any, propertyKey: string) => void;
 declare const Permission: (permission?: boolean) => (target: any, propertyKey: string) => void;
 declare const Log: (log?: boolean, config?: Record<string, unknown>) => (target: any, propertyKey: string) => void;
-export { Get, Post, Put, Delete, Patch, Route, Authentication, Log, Permission, DbSettings, ReadOnly, IsHtml, IsFile, Model, StoredProcedure };
+export { Get, Post, Put, Delete, Patch, Route, Authentication, Log, Permission, DbSettings, ReadOnly, Timeout, IsHtml, IsFile, Model, StoredProcedure };

package/dist/lib/pxp/Decorators.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StoredProcedure = exports.Model = exports.IsFile = exports.IsHtml = exports.ReadOnly = exports.DbSettings = exports.Permission = exports.Log = exports.Authentication = exports.Route = exports.Patch = exports.Delete = exports.Put = exports.Post = exports.Get = void 0;
+exports.StoredProcedure = exports.Model = exports.IsFile = exports.IsHtml = exports.Timeout = exports.ReadOnly = exports.DbSettings = exports.Permission = exports.Log = exports.Authentication = exports.Route = exports.Patch = exports.Delete = exports.Put = exports.Post = exports.Get = void 0;
 /**
  * Kplian Ltda 2020
  *
@@ -13,6 +13,7 @@ exports.StoredProcedure = exports.Model = exports.IsFile = exports.IsHtml = expo
  *
  * Created at     : 2020-06-13 18:09:48
  * Last modified  : 2020-09-17 18:29:51
+ * Last modified  : 2026-10-08 - Favio Figueroa - EF-23 acquire timeout + @Timeout decorator
  */
 const RouteDefinition_1 = require("./RouteDefinition");
 ;
@@ -102,6 +103,10 @@ const Authentication = (authentication = true) => (target, propertyKey) => setPr
 exports.Authentication = Authentication;
 const ReadOnly = (ronly = true) => (target, propertyKey) => setProperty(target, propertyKey)(ronly, 'readonly');
 exports.ReadOnly = ReadOnly;
+// Request timeout (ms) for a write transaction: on expiry the request fails with 503,
+// the transaction is rolled back and the physical connection is destroyed.
+const Timeout = (ms) => (target, propertyKey) => setProperty(target, propertyKey)(ms, 'timeout');
+exports.Timeout = Timeout;
 const IsHtml = (ishtml = false) => (target, propertyKey) => setProperty(target, propertyKey)(ishtml, 'ishtml');
 exports.IsHtml = IsHtml;
 const IsFile = (isFile = false) => (target, propertyKey) => setProperty(target, propertyKey)(isFile, 'isfile');

package/dist/lib/pxp/utils/DbTimeouts.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Kplian Ltda 2020
+ *
+ * MIT
+ *
+ * Database timeout helpers.
+ *
+ * @summary Connection acquire timeout, request timeout error and physical connection destroy.
+ * @author Favio Figueroa
+ *
+ * Created at     : 2026-10-08 - Favio Figueroa - EF-23 acquire timeout + @Timeout decorator
+ * Last modified  : 2026-10-08 - Favio Figueroa - EF-23 late acquired connection is released to the pool, not destroyed (1.2.91)
+ */
+import { QueryRunner } from 'typeorm';
+import { PxpError } from '../PxpError';
+export declare class DbTimeoutError extends PxpError {
+    kind: 'acquire' | 'request';
+    timeoutMs: number;
+    transactionCode: string | undefined;
+    constructor(kind: 'acquire' | 'request', ms: number, transactionCode?: string);
+}
+/**
+ * Destroys the physical driver connection behind the query runner (so it never
+ * goes back to the pool with an open transaction) and then releases the runner.
+ * mysql2 removes a destroyed connection from its pool on its own.
+ */
+export declare function destroyQueryRunner(queryRunner: QueryRunner): Promise<void>;
+/**
+ * Acquires the query runner connection with an upper bound.
+ * When ms is undefined or <= 0 this is exactly `await queryRunner.connect()`.
+ */
+export declare function connectWithTimeout(queryRunner: QueryRunner, ms: number | undefined, transactionCode?: string): Promise<void>;

package/dist/lib/pxp/utils/DbTimeouts.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.connectWithTimeout = exports.destroyQueryRunner = exports.DbTimeoutError = void 0;
+const PxpError_1 = require("../PxpError");
+class DbTimeoutError extends PxpError_1.PxpError {
+    constructor(kind, ms, transactionCode) {
+        super(503, `Database ${kind} timeout after ${ms} ms`);
+        this.kind = kind;
+        this.timeoutMs = ms;
+        this.transactionCode = transactionCode;
+    }
+}
+exports.DbTimeoutError = DbTimeoutError;
+/**
+ * Destroys the physical driver connection behind the query runner (so it never
+ * goes back to the pool with an open transaction) and then releases the runner.
+ * mysql2 removes a destroyed connection from its pool on its own.
+ */
+async function destroyQueryRunner(queryRunner) {
+    const databaseConnection = queryRunner.databaseConnection;
+    if (databaseConnection && typeof databaseConnection.destroy === 'function') {
+        databaseConnection.destroy();
+    }
+    try {
+        await queryRunner.release();
+    }
+    catch (_) {
+        // the connection was already destroyed; release failures are expected here
+    }
+}
+exports.destroyQueryRunner = destroyQueryRunner;
+/**
+ * Acquires the query runner connection with an upper bound.
+ * When ms is undefined or <= 0 this is exactly `await queryRunner.connect()`.
+ */
+async function connectWithTimeout(queryRunner, ms, transactionCode) {
+    if (!ms || ms <= 0) {
+        await queryRunner.connect();
+        return;
+    }
+    let timer;
+    let timedOut = false;
+    const connectPromise = queryRunner.connect();
+    const timeoutPromise = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            timedOut = true;
+            reject(new DbTimeoutError('acquire', ms, transactionCode));
+        }, ms);
+    });
+    try {
+        await Promise.race([connectPromise, timeoutPromise]);
+    }
+    catch (err) {
+        if (timedOut) {
+            // A late connection is pristine (no transaction was started on it), so it is returned
+            // to the pool instead of destroyed: destroying it would force the driver to open a new
+            // one and keep a residual queue after a burst. destroyQueryRunner stays for the
+            // request-timeout path, where a transaction may still be open.
+            connectPromise
+                .then(async () => {
+                try {
+                    await queryRunner.release();
+                }
+                catch (releaseErr) {
+                    console.error('[pxp-core] late connection release failed', releaseErr && releaseErr.message);
+                }
+            })
+                .catch(() => { });
+        }
+        throw err;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+exports.connectWithTimeout = connectWithTimeout;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pxp-nd/core",
-  "version": "1.2.89",
+  "version": "1.2.91",
   "description": "Contains main files for pxp-nd",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,7 +12,7 @@
     "prod:publish": "npm publish",
     "start": "npm run build && node dist/index.js",
     "dev": "tsc-watch --target es2017 --outDir ./dist --onSuccess \"node .\"",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "jest --runInBand"
   },
   "keywords": [
     "pxp-nd"
@@ -28,6 +28,7 @@
     "@types/express-fileupload": "^1.1.6",
     "@types/express-session": "^1.17.3",
     "@types/figlet": "^1.5.1",
+    "@types/jest": "^27.5.2",
     "@types/joi": "^17.2.3",
     "@types/lodash": "^4.14.170",
     "@types/node": "^15.3.1",
@@ -35,7 +36,10 @@
     "@types/socket.io": "^3.0.2",
     "@types/swagger-jsdoc": "^6.0.1",
     "@types/swagger-ui-express": "^4.1.3",
+    "jest": "^27.5.1",
+    "mysql2": "^2.3.3",
     "rimraf": "^3.0.2",
+    "ts-jest": "^27.1.5",
     "tsc-watch": "^4.2.9",
     "typescript": "^4.2.4"
   },
@@ -61,5 +65,23 @@
     "typeorm-store": "^2.0.0",
     "xlsx": "^0.17.0"
   },
-  "peerDependencies": {}
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "roots": [
+      "<rootDir>/test"
+    ],
+    "testTimeout": 30000,
+    "globals": {
+      "ts-jest": {
+        "tsconfig": "<rootDir>/test/tsconfig.json"
+      }
+    },
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.*)\\.js$": "$1"
+    }
+  },
+  "overrides": {
+    "@types/babel__traverse": "7.17.1"
+  }
 }

package/test/db-timeouts.test.ts

@@ -0,0 +1,239 @@
+/**
+ * Regression and timeout tests for write transactions in ormMethodWrapper:
+ *   1. no `db` config and no @Timeout: legacy behaviour (connect -> transaction -> commit -> release)
+ *   2. `db.acquireTimeoutMs`: waiting for a busy pool fails with 503 and the pool recovers
+ *   3. `@Timeout(ms)`: the request fails with 503, no transaction stays open, nothing is committed
+ *
+ * Requires a REAL, disposable MySQL. Connection settings (defaults target a local throwaway container):
+ *   TEST_DB_HOST (127.0.0.1) TEST_DB_PORT (33306) TEST_DB_USER (root) TEST_DB_PASSWORD (test) TEST_DB_NAME (pxptest)
+ *   docker run --rm -d -e MYSQL_ROOT_PASSWORD=test -e MYSQL_DATABASE=pxptest -p 33306:3306 mysql:8
+ * If the database is not reachable the whole suite is skipped (it never fails for lack of a database).
+ *
+ * Harness: a Controller subclass mounted on a bare express app. A full PxpApp is not used because
+ * its run() pulls in sessions, auth modules, swagger and dist/modules folder scanning, none of which
+ * is involved in the code under test (Controller.initializeRoutes + ormMethodWrapper).
+ */
+import 'reflect-metadata';
+import { execFileSync } from 'child_process';
+import http from 'http';
+import { AddressInfo } from 'net';
+import express from 'express';
+import { createConnections, Connection, EntityManager, getConnection } from 'typeorm';
+import { Controller } from '../src/lib/pxp/Controller';
+import { Post, ReadOnly, Timeout } from '../src/lib/pxp/Decorators';
+import { IConfigPxpApp } from '../src/interfaces';
+import Log from '../src/entities/Log';
+
+const DB = {
+  host: process.env.TEST_DB_HOST || '127.0.0.1',
+  port: Number(process.env.TEST_DB_PORT || 33306),
+  username: process.env.TEST_DB_USER || 'root',
+  password: process.env.TEST_DB_PASSWORD || 'test',
+  database: process.env.TEST_DB_NAME || 'pxptest',
+};
+
+// Synchronous reachability probe so the suite can be declared with describe.skip.
+const probeDb = (): string | null => {
+  const script = `
+    const mysql = require('mysql2');
+    const c = mysql.createConnection({ host: process.argv[1], port: +process.argv[2], user: process.argv[3],
+      password: process.argv[4], database: process.argv[5], connectTimeout: 3000 });
+    c.query('SELECT 1', (err) => { c.destroy(); if (err) { console.error(err.message); process.exit(1); } process.exit(0); });
+  `;
+  try {
+    execFileSync(process.execPath, ['-e', script, DB.host, String(DB.port), DB.username, DB.password, DB.database], {
+      cwd: __dirname,
+      stdio: 'pipe',
+      timeout: 10000,
+    });
+    return null;
+  } catch (e) {
+    return String((e as any).stderr || (e as any).message).trim();
+  }
+};
+
+const dbError = probeDb();
+if (dbError) {
+  // eslint-disable-next-line no-console
+  console.warn(
+    `[db-timeouts.test] SKIPPED: test MySQL not reachable at ${DB.host}:${DB.port}/${DB.database} (${dbError}). ` +
+      'Start one with: docker run --rm -d -e MYSQL_ROOT_PASSWORD=test -e MYSQL_DATABASE=pxptest -p 33306:3306 mysql:8'
+  );
+}
+const describeDb = dbError ? describe.skip : describe;
+
+class Slow extends Controller {
+  @Post()
+  @ReadOnly(false)
+  async hold(params: any, manager: EntityManager) {
+    await manager.query('SELECT SLEEP(?)', [Number(params.secs)]);
+    return { ok: true };
+  }
+
+  // Writes a row first so the transaction is a real InnoDB transaction (visible in innodb_trx),
+  // then outlives its @Timeout.
+  @Post()
+  @ReadOnly(false)
+  @Timeout(500)
+  async fast(params: any, manager: EntityManager) {
+    await manager.query('INSERT INTO pxp_timeout_probe (marker) VALUES (?)', [String(params.marker)]);
+    await manager.query('SELECT SLEEP(2)');
+    return { ok: true };
+  }
+}
+
+const baseConfig: IConfigPxpApp = {
+  apiPrefix: '/api',
+  defaultDbSettings: 'Orm',
+  middlewares: [],
+  entities: {},
+};
+
+const startApp = async (config: IConfigPxpApp) => {
+  const app = express();
+  app.use(express.json());
+  app.use((req: any, _res, next) => {
+    req.start = new Date();
+    next();
+  });
+  const controller = new Slow('test', null, config);
+  app.use('/', controller.router);
+  const server = http.createServer(app);
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const { port } = server.address() as AddressInfo;
+  return { server, base: `http://127.0.0.1:${port}/api/test/Slow` };
+};
+
+// Plain http client (the jest node environment does not expose global fetch).
+const call = (url: string, body: Record<string, unknown>) =>
+  new Promise<{ status: number; json: any; ms: number }>((resolve, reject) => {
+    const t0 = Date.now();
+    const payload = JSON.stringify(body);
+    const req = http.request(
+      url,
+      { method: 'POST', headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) } },
+      (res) => {
+        let raw = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => (raw += chunk));
+        res.on('end', () => resolve({ status: res.statusCode as number, json: JSON.parse(raw), ms: Date.now() - t0 }));
+      }
+    );
+    req.on('error', reject);
+    req.end(payload);
+  });
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+describeDb('ormMethodWrapper db timeouts (real MySQL)', () => {
+  let connections: Connection[] = [];
+  const servers: http.Server[] = [];
+  const timings: string[] = [];
+
+  beforeAll(async () => {
+    process.env.DB_WRITE_CONNECTION_NAME = 'write';
+    process.env.DB_LOG_CONNECTION_NAME = 'default';
+    connections = await createConnections([
+      { name: 'default', type: 'mysql', ...DB, entities: [Log], synchronize: true, logging: false },
+      { name: 'write', type: 'mysql', ...DB, entities: [], synchronize: false, logging: false, extra: { connectionLimit: 1 } },
+    ]);
+    const def = getConnection('default');
+    await def.query(
+      'CREATE TABLE IF NOT EXISTS pxp_timeout_probe (id INT AUTO_INCREMENT PRIMARY KEY, marker VARCHAR(64) NOT NULL) ENGINE=InnoDB'
+    );
+  });
+
+  afterAll(async () => {
+    for (const s of servers) await new Promise((r) => s.close(r));
+    // ormMethodWrapper writes the success log fire-and-forget (not awaited); let in-flight inserts finish
+    // before closing the log connection, otherwise they reject unhandled and crash the runner.
+    await sleep(1000);
+    for (const c of connections) if (c.isConnected) await c.close();
+    // eslint-disable-next-line no-console
+    console.log(`[db-timeouts.test] timings:\n  ${timings.join('\n  ')}`);
+  });
+
+  test('1. legacy: no db config, no @Timeout -> hold secs=1 returns 200 in ~1 s', async () => {
+    const { server, base } = await startApp({ ...baseConfig });
+    servers.push(server);
+
+    const r = await call(`${base}/hold`, { secs: 1 });
+    timings.push(`case1 hold(1): ${r.status} in ${r.ms} ms`);
+
+    expect(r.status).toBe(200);
+    expect(r.json).toEqual({ ok: true });
+    expect(r.ms).toBeGreaterThanOrEqual(950);
+    expect(r.ms).toBeLessThan(2000);
+  });
+
+  test('2. db.acquireTimeoutMs=1000 -> second write on a busy 1-connection pool gets 503 in ~1 s; pool recovers', async () => {
+    const { server, base } = await startApp({ ...baseConfig, db: { acquireTimeoutMs: 1000 } });
+    servers.push(server);
+
+    const first = call(`${base}/hold`, { secs: 5 });
+    await sleep(200);
+    const second = await call(`${base}/hold`, { secs: 0 });
+    timings.push(`case2 second hold(0): ${second.status} in ${second.ms} ms -> ${second.json?.error?.message}`);
+
+    expect(second.status).toBe(503);
+    expect(second.json.error.message).toBe('Database acquire timeout after 1000 ms');
+    expect(second.ms).toBeGreaterThanOrEqual(950);
+    expect(second.ms).toBeLessThan(1800);
+
+    const firstRes = await first;
+    timings.push(`case2 first hold(5): ${firstRes.status} in ${firstRes.ms} ms`);
+    expect(firstRes.status).toBe(200);
+    expect(firstRes.ms).toBeGreaterThanOrEqual(4500);
+
+    // The late connection handed to the timed-out waiter is released back to the pool (not leaked): a new call succeeds.
+    const third = await call(`${base}/hold`, { secs: 0 });
+    timings.push(`case2 third hold(0): ${third.status} in ${third.ms} ms`);
+    expect(third.status).toBe(200);
+    expect(third.ms).toBeLessThan(1000);
+
+    const pool: any = (getConnection('write').driver as any).pool;
+    timings.push(
+      `case2 write pool after: all=${pool._allConnections.length} free=${pool._freeConnections.length} queued=${pool._connectionQueue.length}`
+    );
+    expect(pool._connectionQueue.length).toBe(0);
+    expect(pool._allConnections.length).toBeLessThanOrEqual(1);
+    expect(pool._freeConnections.length).toBe(pool._allConnections.length);
+  });
+
+  test('3. @Timeout(500) -> 503 in ~0.5 s, no open transaction, nothing committed, pool recovers', async () => {
+    const { server, base } = await startApp({ ...baseConfig });
+    servers.push(server);
+    const warn = jest.spyOn(console, 'warn');
+    const marker = `t${Date.now()}`;
+
+    const r = await call(`${base}/fast`, { marker });
+    timings.push(`case3 fast: ${r.status} in ${r.ms} ms -> ${r.json?.error?.message}`);
+
+    expect(r.status).toBe(503);
+    expect(r.json.error.message).toBe('Database request timeout after 500 ms');
+    expect(r.ms).toBeGreaterThanOrEqual(450);
+    expect(r.ms).toBeLessThan(1200);
+    expect(warn).toHaveBeenCalledWith('[pxp-core] timeout-abandoned test.slow.fast');
+    warn.mockRestore();
+
+    const def = getConnection('default');
+    let open = -1;
+    const t0 = Date.now();
+    while (Date.now() - t0 < 3000) {
+      const [row] = await def.query('SELECT COUNT(*) AS n FROM information_schema.innodb_trx');
+      open = Number(row.n);
+      if (open === 0) break;
+      await sleep(100);
+    }
+    timings.push(`case3 innodb_trx open after ${Date.now() - t0} ms: ${open}`);
+    expect(open).toBe(0);
+
+    // MySQL rolled the abandoned transaction back server-side: the row was never committed.
+    const [committed] = await def.query('SELECT COUNT(*) AS n FROM pxp_timeout_probe WHERE marker = ?', [marker]);
+    expect(Number(committed.n)).toBe(0);
+
+    const after = await call(`${base}/hold`, { secs: 0 });
+    timings.push(`case3 hold(0) after: ${after.status} in ${after.ms} ms`);
+    expect(after.status).toBe(200);
+  });
+});

package/test/error-path.test.ts

@@ -0,0 +1,145 @@
+/**
+ * Error/log path tests for Controller route handlers. No database needed.
+ *
+ * `insertLog` (src/lib/pxp/utils/Security) is mocked to reject, simulating a log database that is down:
+ *   1. a route that throws PxpError(400) must still answer 400 with the original message, in both
+ *      the unauthenticated and the authenticated route handler (before 1.2.91 the request hung forever)
+ *   2. a successful route must answer 200 and the failed fire-and-forget success log must not become
+ *      an unhandledRejection
+ *
+ * Harness: same as db-timeouts.test.ts (Controller subclass mounted on a bare express app). All routes
+ * are @ReadOnly(true), so ormMethodWrapper never touches a connection.
+ */
+import 'reflect-metadata';
+import http from 'http';
+import { AddressInfo } from 'net';
+import express from 'express';
+
+jest.mock('../src/lib/pxp/utils/Security', () => ({
+  ...jest.requireActual('../src/lib/pxp/utils/Security'),
+  insertLog: jest.fn(),
+}));
+
+import { insertLog } from '../src/lib/pxp/utils/Security';
+import { Controller } from '../src/lib/pxp/Controller';
+import { Authentication, Post, ReadOnly } from '../src/lib/pxp/Decorators';
+import { PxpError } from '../src/lib/pxp/PxpError';
+import { IConfigPxpApp } from '../src/interfaces';
+
+const insertLogMock = insertLog as jest.MockedFunction<typeof insertLog>;
+
+class Broken extends Controller {
+  @Post()
+  @ReadOnly(true)
+  @Authentication(false)
+  async publicFail() {
+    throw new PxpError(400, 'public route failed on purpose');
+  }
+
+  @Post()
+  @ReadOnly(true)
+  async privateFail() {
+    throw new PxpError(400, 'private route failed on purpose');
+  }
+
+  @Post()
+  @ReadOnly(true)
+  async ok() {
+    return { ok: true };
+  }
+}
+
+const config: IConfigPxpApp = {
+  apiPrefix: '/api',
+  defaultDbSettings: 'Orm',
+  middlewares: [],
+  entities: {},
+};
+
+// Plain http client with a hard deadline so a hanging handler fails the test instead of the runner.
+const call = (url: string, deadlineMs = 2000) =>
+  new Promise<{ status: number; json: any; ms: number }>((resolve, reject) => {
+    const t0 = Date.now();
+    const payload = '{}';
+    const req = http.request(
+      url,
+      { method: 'POST', headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) } },
+      (res) => {
+        let raw = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => (raw += chunk));
+        res.on('end', () => resolve({ status: res.statusCode as number, json: JSON.parse(raw), ms: Date.now() - t0 }));
+      }
+    );
+    req.setTimeout(deadlineMs, () => {
+      req.destroy(new Error(`no response within ${deadlineMs} ms (handler hung)`));
+    });
+    req.on('error', reject);
+    req.end(payload);
+  });
+
+describe('Controller error path with a failing insertLog (no database)', () => {
+  let server: http.Server;
+  let base: string;
+  const unhandled: unknown[] = [];
+  const onUnhandled = (reason: unknown) => unhandled.push(reason);
+  let consoleError: jest.SpyInstance;
+
+  beforeAll(async () => {
+    process.on('unhandledRejection', onUnhandled);
+    const app = express();
+    app.use(express.json());
+    app.use((req: any, _res, next) => {
+      req.start = new Date();
+      next();
+    });
+    app.use('/', new Broken('test', null, config).router);
+    server = http.createServer(app);
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const { port } = server.address() as AddressInfo;
+    base = `http://127.0.0.1:${port}/api/test/Broken`;
+  });
+
+  beforeEach(() => {
+    insertLogMock.mockReset();
+    insertLogMock.mockRejectedValue(new Error('connect ECONNREFUSED 127.0.0.1:3306'));
+    consoleError = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+  });
+
+  afterEach(() => consoleError.mockRestore());
+
+  afterAll(async () => {
+    process.removeListener('unhandledRejection', onUnhandled);
+    await new Promise((r) => server.close(r));
+  });
+
+  test.each([
+    ['unauthenticated handler', 'publicFail', 'public route failed on purpose'],
+    ['authenticated handler', 'privateFail', 'private route failed on purpose'],
+  ])('%s: PxpError(400) is answered with 400 and the original message', async (_label, path, message) => {
+    const r = await call(`${base}/${path}`);
+
+    expect(r.status).toBe(400);
+    expect(r.json.error.code).toBe(400);
+    expect(r.json.error.message).toBe(message);
+    expect(r.json.error.logId).toBeUndefined();
+    expect(r.ms).toBeLessThan(2000);
+    expect(insertLogMock).toHaveBeenCalledTimes(1);
+    expect(insertLogMock.mock.calls[0][3]).toBe('error');
+    expect(consoleError).toHaveBeenCalledWith('[pxp-core] error log failed', 'connect ECONNREFUSED 127.0.0.1:3306');
+  });
+
+  test('success path: 200 and the failed success log is caught (no unhandledRejection)', async () => {
+    const r = await call(`${base}/ok`);
+
+    expect(r.status).toBe(200);
+    expect(r.json).toEqual({ ok: true });
+    // let the rejected fire-and-forget log settle
+    await new Promise((resolve) => setImmediate(resolve));
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(insertLogMock).toHaveBeenCalledTimes(1);
+    expect(insertLogMock.mock.calls[0][3]).toBe('success');
+    expect(consoleError).toHaveBeenCalledWith('[pxp-core] success log failed', 'connect ECONNREFUSED 127.0.0.1:3306');
+    expect(unhandled).toEqual([]);
+  });
+});