@pxp-nd/core 1.2.90 → 1.2.92

package/README.md

@@ -1,6 +1,42 @@
 # PXP-ND core
 - Core module for pxp-nd
 
+## 1.2.92
+
+Destino del audit de request. **Sin configurar nada, el comportamiento es idéntico a 1.2.91**: el default sigue siendo insertar en `tsec_log`.
+
+### `logSink` (opcional)
+
+```ts
+new PxpApp({
+  logSink: 'stdout', // 'db' | 'stdout' | 'both'
+});
+```
+
+- `db` (default): insert en `tsec_log` por `DB_LOG_CONNECTION_NAME`. El `logId` del JSON de error es el id numérico.
+- `stdout`: una línea JSON por request (`pxpLog: true`). El `logId` es un uuid, generado antes de escribir, y no se toca la base. `request`, `response` y `query` se cortan a 8 KB (`truncated: true`). CloudWatch descarta un evento de más de 256 KB.
+- `both`: la línea JSON y, en segundo plano, el insert. El uuid viaja dentro del request guardado como `__logId`. La respuesta no espera a la base.
+
+Las máscaras de `@Log` (`cc_mask`, `complete_mask`, campo en null) se aplican en los tres modos. Los decoradores existentes no hay que tocarlos.
+
+## 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.
@@ -61,3 +97,17 @@ Dependen de core con `^1.2.x`, así que tomarán esta versión en su próximo `n
 - 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

@@ -32,10 +32,23 @@ declare interface IModules {
 declare interface IConfigExpress {
     [name: string]: any;
 }
+/**
+ * Where a request audit line is written.
+ * `db` (default) inserts into tsec_log and returns the numeric id.
+ * `stdout` writes one JSON line and returns a uuid. No database.
+ * `both` writes the line and inserts in the background; the uuid is stored
+ * inside the row's request JSON as `__logId`.
+ */
+export declare type LogSink = 'db' | 'stdout' | 'both';
 export interface IConfigPxpApp {
     defaultDbSettings?: string;
     apiPrefix?: string;
     logDuration?: boolean;
+    /**
+     * Audit destination. Omitted or `db` matches <=1.2.91 (insert into tsec_log).
+     * `stdout` is one JSON line per request. `both` is the line plus a background insert.
+     */
+    logSink?: LogSink;
     showRoutes?: boolean;
     controllers?: any[];
     entities?: any;

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

@@ -14,6 +14,8 @@
  * 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)
+ * Last modified  : 2026-10-21 - logSink db | stdout | both (1.2.92)
  */
 import { EntityManager } from 'typeorm';
 import { Request, Response, NextFunction } from 'express';

package/dist/lib/pxp/Controller.js

@@ -39,6 +39,8 @@ exports.Controller = void 0;
  * 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)
+ * Last modified  : 2026-10-21 - logSink db | stdout | both (1.2.92)
  */
 const typeorm_1 = require("typeorm");
 const class_validator_1 = require("class-validator");
@@ -188,8 +190,15 @@ class Controller {
                         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, controllerForRequest.module, controllerForRequest.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, controllerForRequest.config.logSink));
+                        }
+                        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);
                     }
                 });
@@ -222,8 +231,15 @@ class Controller {
                         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, controllerForRequest.module, controllerForRequest.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, controllerForRequest.config.logSink)));
+                        }
+                        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);
                     }
                 });
@@ -313,7 +329,8 @@ class Controller {
             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, this.config.logSink)).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/utils/DbTimeouts.d.ts

@@ -9,6 +9,7 @@
  * @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';

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

@@ -52,8 +52,20 @@ async function connectWithTimeout(queryRunner, ms, transactionCode) {
     }
     catch (err) {
         if (timedOut) {
-            // A late connection must be destroyed, not leaked into the pool.
-            connectPromise.then(() => destroyQueryRunner(queryRunner)).catch(() => { });
+            // 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;
     }

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

@@ -13,11 +13,14 @@
  */
 import 'reflect-metadata';
 import { EntityManager } from 'typeorm';
+import { LogSink } from '../../../interfaces';
+/** Max characters kept for request, response and query on a stdout line. CloudWatch drops an event past 256 KB. */
+declare const STDOUT_LOG_FIELD_MAX = 8192;
 interface ScriptInterface {
     scriptCode: string;
     scriptFunction: (manager: EntityManager) => void;
 }
 declare const userHasPermission: (user: any, transaction: string, permissionFunction: boolean | ((user: any, transaction: string) => Promise<boolean>)) => Promise<boolean>;
-declare const insertLog: (username: string, macaddres: string, ip: string, logType: string, desc: string, proc: string, trans: string, query: string, req: Record<string, unknown>, resp: string, err: string, timeEx: number, logConfig: Record<string, unknown>) => Promise<number>;
-export { userHasPermission, insertLog };
+declare const insertLog: (username: string, macaddres: string, ip: string, logType: string, desc: string, proc: string, trans: string, query: string, req: Record<string, unknown>, resp: string, err: string, timeEx: number, logConfig: Record<string, unknown>, logSink?: LogSink) => Promise<number | string>;
+export { userHasPermission, insertLog, STDOUT_LOG_FIELD_MAX };
 export type { ScriptInterface };

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

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.insertLog = exports.userHasPermission = void 0;
+exports.STDOUT_LOG_FIELD_MAX = exports.insertLog = exports.userHasPermission = void 0;
 /**
  * Kplian Ltda 2020
  *
@@ -18,9 +18,13 @@ exports.insertLog = exports.userHasPermission = void 0;
  * Last modified  : 2020-10-20 17:46:24
  */
 require("reflect-metadata");
+const crypto_1 = __importDefault(require("crypto"));
 const typeorm_1 = require("typeorm");
 // import { Role } from '@pxp-nd/entities';
 const Log_1 = __importDefault(require("../../../entities/Log"));
+/** Max characters kept for request, response and query on a stdout line. CloudWatch drops an event past 256 KB. */
+const STDOUT_LOG_FIELD_MAX = 8192;
+exports.STDOUT_LOG_FIELD_MAX = STDOUT_LOG_FIELD_MAX;
 const userHasPermission = async (user, transaction, permissionFunction) => {
     if (typeof permissionFunction === 'function') {
         return await permissionFunction(user, transaction);
@@ -42,24 +46,71 @@ const userHasPermission = async (user, transaction, permissionFunction) => {
     }
 };
 exports.userHasPermission = userHasPermission;
-const insertLog = async (username, macaddres, ip, logType, desc, proc, trans, query, req, resp, err, timeEx, logConfig) => {
-    if (logConfig) {
-        for (const [key, value] of Object.entries(logConfig)) {
-            if (key in req) {
-                if (!value) {
-                    delete req[key];
-                }
-                else if (value === 'cc_mask') {
-                    const aux = req[key];
-                    req[key] = '************' + aux.substr(-4);
-                }
-                else if (value === 'complete_mask') {
-                    const aux = req[key];
-                    req[key] = aux.replace(/./g, '*');
-                }
+/** uuid v4. @types/node 15 does not declare crypto.randomUUID. */
+const newLogId = () => {
+    const bytes = crypto_1.default.randomBytes(16);
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = bytes.toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+};
+const applyLogMask = (req, logConfig) => {
+    if (!logConfig || !req) {
+        return;
+    }
+    for (const [key, value] of Object.entries(logConfig)) {
+        if (key in req) {
+            if (!value) {
+                delete req[key];
+            }
+            else if (value === 'cc_mask') {
+                const aux = req[key];
+                req[key] = '************' + aux.substr(-4);
+            }
+            else if (value === 'complete_mask') {
+                const aux = req[key];
+                req[key] = aux.replace(/./g, '*');
             }
         }
     }
+};
+const capField = (value) => {
+    const text = value == null ? '' : String(value);
+    if (text.length <= STDOUT_LOG_FIELD_MAX) {
+        return { text, truncated: false };
+    }
+    return { text: text.slice(0, STDOUT_LOG_FIELD_MAX), truncated: true };
+};
+const serializeForLog = (value) => {
+    try {
+        return JSON.stringify(value);
+    }
+    catch (_a) {
+        return '{"error":"unserializable"}';
+    }
+};
+const emitStdoutLog = (logId, username, ip, logType, desc, proc, trans, query, req, resp, err, timeEx) => {
+    const request = capField(serializeForLog(req));
+    const response = capField(resp);
+    const queryField = capField(query);
+    console.log(JSON.stringify({
+        pxpLog: true,
+        logId,
+        type: logType,
+        user: username,
+        ip,
+        module: proc,
+        transaction: trans,
+        status: err,
+        ms: timeEx,
+        message: desc,
+        query: queryField.text,
+        request: request.text,
+        response: response.text,
+        truncated: request.truncated || response.truncated || queryField.truncated,
+    }));
+};
+const insertLogRow = async (username, macaddres, ip, logType, desc, proc, trans, query, req, resp, err, timeEx) => {
     const log = new Log_1.default();
     log.username = username;
     log.macaddres = macaddres;
@@ -74,7 +125,7 @@ const insertLog = async (username, macaddres, ip, logType, desc, proc, trans, qu
     log.execTime = timeEx;
     log.errorCode = err;
     log.shortRequest = JSON.stringify(req).substring(0, 150);
-    log.shortResponse = resp.substring(0, 150);
+    log.shortResponse = (resp || '').substring(0, 150);
     const logIds = await typeorm_1.getManager(process.env.DB_LOG_CONNECTION_NAME)
         .createQueryBuilder()
         .insert()
@@ -83,4 +134,21 @@ const insertLog = async (username, macaddres, ip, logType, desc, proc, trans, qu
         .execute();
     return logIds.identifiers[0].logId;
 };
+const insertLog = async (username, macaddres, ip, logType, desc, proc, trans, query, req, resp, err, timeEx, logConfig, logSink = 'db') => {
+    const sink = logSink || 'db';
+    if (sink === 'stdout' || sink === 'both') {
+        const snapshot = Object.assign({}, (req || {}));
+        applyLogMask(snapshot, logConfig);
+        const logId = newLogId();
+        emitStdoutLog(logId, username, ip, logType, desc, proc, trans, query, snapshot, resp, err, timeEx);
+        if (sink === 'both') {
+            const dbReq = Object.assign(Object.assign({}, snapshot), { __logId: logId });
+            insertLogRow(username, macaddres, ip, logType, desc, proc, trans, query, dbReq, resp, err, timeEx)
+                .catch((dbErr) => console.error('[pxp-core] db log failed', dbErr && (dbErr.tecMessage || dbErr.message)));
+        }
+        return logId;
+    }
+    applyLogMask(req, logConfig);
+    return insertLogRow(username, macaddres, ip, logType, desc, proc, trans, query, req, resp, err, timeEx);
+};
 exports.insertLog = insertLog;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pxp-nd/core",
-  "version": "1.2.90",
+  "version": "1.2.92",
   "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([]);
+  });
+});

package/test/stdout-log.test.ts

@@ -0,0 +1,242 @@
+/**
+ * logSink tests. No database.
+ *
+ * stdout writes one JSON line and returns a uuid without calling getManager.
+ * both writes the line and inserts in the background; the caller is not blocked on the insert.
+ * db (the default) still inserts and returns the numeric id.
+ */
+import 'reflect-metadata';
+import http from 'http';
+import { AddressInfo } from 'net';
+import express from 'express';
+import * as typeorm from 'typeorm';
+import { insertLog, STDOUT_LOG_FIELD_MAX } 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 UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+const baseArgs = (req: Record<string, unknown>, logConfig: Record<string, unknown> = {}) =>
+  ['user', 'mac', '127.0.0.1', 'success', 'ok', 'mod', 'mod.tx', '', req, '{"ok":true}', '200', 12, logConfig] as const;
+
+const pxpLines = (spy: jest.SpyInstance): any[] =>
+  spy.mock.calls
+    .map((call) => call[0])
+    .filter((line) => typeof line === 'string' && line.includes('"pxpLog":true'))
+    .map((line) => JSON.parse(line));
+
+describe('insertLog sinks', () => {
+  let logSpy: jest.SpyInstance;
+  let getManager: jest.SpyInstance;
+  let execute: jest.Mock;
+  let values: jest.Mock;
+
+  beforeEach(() => {
+    logSpy = jest.spyOn(console, 'log').mockImplementation(() => undefined);
+    execute = jest.fn().mockResolvedValue({ identifiers: [{ logId: 7 }] });
+    values = jest.fn();
+    const qb = {
+      insert: jest.fn(),
+      into: jest.fn(),
+      values,
+      execute,
+    };
+    qb.insert.mockReturnValue(qb);
+    qb.into.mockReturnValue(qb);
+    values.mockReturnValue(qb);
+    getManager = jest.spyOn(typeorm, 'getManager').mockReturnValue({ createQueryBuilder: () => qb } as any);
+  });
+
+  afterEach(() => {
+    logSpy.mockRestore();
+    getManager.mockRestore();
+  });
+
+  test('stdout returns a uuid, writes one line, and does not touch the database', async () => {
+    const req = { card: '4111111111111111', keep: 'yes' };
+    const id = await insertLog(...baseArgs(req, { card: 'cc_mask' }), 'stdout');
+
+    expect(id).toMatch(UUID);
+    expect(getManager).not.toHaveBeenCalled();
+    expect(req).toEqual({ card: '4111111111111111', keep: 'yes' });
+
+    const [line] = pxpLines(logSpy);
+    expect(line.logId).toBe(id);
+    expect(line.type).toBe('success');
+    expect(line.user).toBe('user');
+    expect(line.transaction).toBe('mod.tx');
+    expect(line.status).toBe('200');
+    expect(line.truncated).toBe(false);
+    expect(line.request).toContain('************1111');
+    expect(line.request).not.toContain('4111111111111111');
+    expect(line.request).toContain('yes');
+  });
+
+  test('stdout drops masked-out fields and caps oversized bodies', async () => {
+    const req = { favicon: 'png', note: 'x'.repeat(STDOUT_LOG_FIELD_MAX + 500) };
+    await insertLog(...baseArgs(req, { favicon: null }), 'stdout');
+
+    const [line] = pxpLines(logSpy);
+    expect(line.request.startsWith('{"note":')).toBe(true);
+    expect(line.request).not.toContain('favicon');
+    expect(line.request.length).toBe(STDOUT_LOG_FIELD_MAX);
+    expect(line.truncated).toBe(true);
+    expect(req.favicon).toBe('png');
+  });
+
+  test('both returns the uuid before the insert finishes and stores __logId on the row', async () => {
+    let release: (value: unknown) => void = () => undefined;
+    execute.mockReturnValue(new Promise((resolve) => {
+      release = resolve;
+    }));
+
+    const id = await Promise.race([
+      insertLog(...baseArgs({ a: 1 }), 'both'),
+      new Promise((_resolve, reject) => setTimeout(() => reject(new Error('waited for the database')), 200)),
+    ]);
+
+    expect(id).toMatch(UUID);
+    const [line] = pxpLines(logSpy);
+    expect(line.logId).toBe(id);
+    expect(execute).toHaveBeenCalledTimes(1);
+
+    const row = values.mock.calls[0][0][0];
+    expect(JSON.parse(row.request).__logId).toBe(id);
+
+    release({ identifiers: [{ logId: 7 }] });
+  });
+
+  test('db stays on the numeric id and writes no stdout line', async () => {
+    const id = await insertLog(...baseArgs({ a: 1 }));
+
+    expect(id).toBe(7);
+    expect(getManager).toHaveBeenCalledTimes(1);
+    expect(pxpLines(logSpy)).toEqual([]);
+  });
+
+  test('a failing background insert does not reject', async () => {
+    execute.mockRejectedValue(new Error('connect ECONNREFUSED'));
+    const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+    const unhandled: unknown[] = [];
+    const onUnhandled = (reason: unknown) => unhandled.push(reason);
+    process.on('unhandledRejection', onUnhandled);
+
+    const id = await insertLog(...baseArgs({ a: 1 }), 'both');
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(id).toMatch(UUID);
+    expect(errorSpy).toHaveBeenCalledWith('[pxp-core] db log failed', 'connect ECONNREFUSED');
+    expect(unhandled).toEqual([]);
+
+    process.removeListener('unhandledRejection', onUnhandled);
+    errorSpy.mockRestore();
+  });
+});
+
+class Audited extends Controller {
+  @Post()
+  @ReadOnly(true)
+  @Authentication(false)
+  async fail() {
+    throw new PxpError(400, 'audit me');
+  }
+
+  @Post()
+  @ReadOnly(true)
+  @Authentication(false)
+  async ok() {
+    return { ok: true };
+  }
+}
+
+const call = (url: string) =>
+  new Promise<{ status: number; json: any }>((resolve, reject) => {
+    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) }));
+      }
+    );
+    req.on('error', reject);
+    req.end(payload);
+  });
+
+describe('controller with logSink stdout', () => {
+  let server: http.Server;
+  let base: string;
+  let logSpy: jest.SpyInstance;
+  let getManager: jest.SpyInstance;
+
+  beforeAll(async () => {
+    const config: IConfigPxpApp = {
+      apiPrefix: '/api',
+      defaultDbSettings: 'Orm',
+      middlewares: [],
+      entities: {},
+      logSink: 'stdout',
+    };
+    const app = express();
+    app.use(express.json());
+    app.use((req: any, _res, next) => {
+      req.start = new Date();
+      next();
+    });
+    app.use('/', new Audited('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/Audited`;
+  });
+
+  beforeEach(() => {
+    logSpy = jest.spyOn(console, 'log').mockImplementation(() => undefined);
+    getManager = jest.spyOn(typeorm, 'getManager').mockImplementation(() => {
+      throw new Error('stdout sink must not ask for a connection');
+    });
+  });
+
+  afterEach(() => {
+    logSpy.mockRestore();
+    getManager.mockRestore();
+  });
+
+  afterAll(async () => {
+    await new Promise((resolve) => server.close(resolve));
+  });
+
+  test('an error response carries the same uuid that was written to stdout', async () => {
+    const r = await call(`${base}/fail`);
+
+    expect(r.status).toBe(400);
+    expect(r.json.error.message).toBe('audit me');
+    expect(r.json.error.logId).toMatch(UUID);
+    expect(getManager).not.toHaveBeenCalled();
+
+    const [line] = pxpLines(logSpy);
+    expect(line.logId).toBe(r.json.error.logId);
+    expect(line.type).toBe('error');
+    expect(line.status).toBe(400);
+  });
+
+  test('a successful request is logged and still answers 200', async () => {
+    const r = await call(`${base}/ok`);
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(r.status).toBe(200);
+    expect(r.json).toEqual({ ok: true });
+    expect(r.json.logId).toBeUndefined();
+    expect(getManager).not.toHaveBeenCalled();
+
+    const [line] = pxpLines(logSpy);
+    expect(line.logId).toMatch(UUID);
+    expect(line.type).toBe('success');
+    expect(line.status).toBe('200');
+  });
+});