@kronos-ts/postgres 0.3.3 → 0.4.0

package/dist/postgres-transaction-manager.d.ts

@@ -14,7 +14,26 @@
 import { type TransactionManager } from "@kronos-ts/messaging";
 import type { PostgresAdapter, PostgresAdapterTransaction } from "./adapter.js";
 import { IsolationLevel } from "./adapter.js";
-export declare function postgresTransactionManager(adapter: PostgresAdapter, isolationLevel?: IsolationLevel): TransactionManager<PostgresAdapterTransaction>;
+/** Tuning for the safety timeouts applied to every UoW-scoped transaction. */
+export interface PostgresTransactionManagerOptions {
+    /**
+     * `idle_in_transaction_session_timeout` (ms) applied via `SET LOCAL` on every
+     * transaction. A UoW that begins a tx but stalls before commit/rollback would
+     * otherwise hold its connection — and pin `pg_snapshot_xmin`, which gates the
+     * gap-free tailing query in the event store — open indefinitely, stalling all
+     * streaming processors until the process restarts. This bounds that window:
+     * postgres aborts the idle transaction and the connection (and xmin) is freed.
+     * Default 30000 (30s). Set 0 to disable (postgres default — no timeout).
+     */
+    readonly idleInTransactionTimeoutMs?: number;
+    /**
+     * `statement_timeout` (ms) applied via `SET LOCAL` on every transaction.
+     * Bounds a single hung statement inside the tx. Default 0 (disabled) — large
+     * appends / replays can legitimately run long, so opt in per deployment.
+     */
+    readonly statementTimeoutMs?: number;
+}
+export declare function postgresTransactionManager(adapter: PostgresAdapter, isolationLevel?: IsolationLevel, options?: PostgresTransactionManagerOptions): TransactionManager<PostgresAdapterTransaction>;
 /**
  * Run `fn` inside a postgres tx, joining a UoW-scoped tx if one is active
  * (or installed lazily), otherwise opening an ad-hoc tx via `adapter.transaction`.

package/dist/postgres-transaction-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"postgres-transaction-manager.d.ts","sourceRoot":"","sources":["../src/postgres-transaction-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAA+B,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAC3F,OAAO,KAAK,EAAE,eAAe,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAA;AAC/E,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAsB7C,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,eAAe,EACxB,cAAc,GAAE,cAA8C,GAC7D,kBAAkB,CAAC,0BAA0B,CAAC,CAqDhD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,OAAO,EAAE,eAAe,EACxB,EAAE,EAAE,CAAC,EAAE,EAAE,0BAA0B,KAAK,OAAO,CAAC,CAAC,CAAC,EAClD,cAAc,GAAE,cAA8C,GAC7D,OAAO,CAAC,CAAC,CAAC,CAIZ"}
+{"version":3,"file":"postgres-transaction-manager.d.ts","sourceRoot":"","sources":["../src/postgres-transaction-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAA+B,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAC3F,OAAO,KAAK,EAAE,eAAe,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAA;AAC/E,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAsB7C,8EAA8E;AAC9E,MAAM,WAAW,iCAAiC;IAChD;;;;;;;;OAQG;IACH,QAAQ,CAAC,0BAA0B,CAAC,EAAE,MAAM,CAAA;IAC5C;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CACrC;AAID,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,eAAe,EACxB,cAAc,GAAE,cAA8C,EAC9D,OAAO,GAAE,iCAAsC,GAC9C,kBAAkB,CAAC,0BAA0B,CAAC,CAyFhD;AASD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,OAAO,EAAE,eAAe,EACxB,EAAE,EAAE,CAAC,EAAE,EAAE,0BAA0B,KAAK,OAAO,CAAC,CAAC,CAAC,EAClD,cAAc,GAAE,cAA8C,GAC7D,OAAO,CAAC,CAAC,CAAC,CAIZ"}

package/dist/postgres-transaction-manager.js

@@ -21,7 +21,22 @@ import { IsolationLevel } from "./adapter.js";
 const TX_CONTROL = Symbol("kronos.postgresTxControl");
 /** Marker error: signals an intentional rollback so the .catch can suppress it. */
 const ROLLBACK_MARKER = "__kronos_postgres_tx_rollback__";
-export function postgresTransactionManager(adapter, isolationLevel = IsolationLevel.READ_COMMITTED) {
+const DEFAULT_IDLE_IN_TRANSACTION_TIMEOUT_MS = 30_000;
+export function postgresTransactionManager(adapter, isolationLevel = IsolationLevel.READ_COMMITTED, options = {}) {
+    const idleTimeoutMs = normalizeTimeoutMs(options.idleInTransactionTimeoutMs ?? DEFAULT_IDLE_IN_TRANSACTION_TIMEOUT_MS);
+    const statementTimeoutMs = normalizeTimeoutMs(options.statementTimeoutMs ?? 0);
+    // GUCs cannot be parameterized ($1) — the value is a config-supplied integer,
+    // normalized to a non-negative whole number, so inlining is injection-safe.
+    // SET LOCAL auto-resets at COMMIT/ROLLBACK, so it never leaks onto pooled
+    // connections.
+    async function applyTimeouts(tx) {
+        if (idleTimeoutMs > 0) {
+            await tx.query(`SET LOCAL idle_in_transaction_session_timeout = ${idleTimeoutMs}`);
+        }
+        if (statementTimeoutMs > 0) {
+            await tx.query(`SET LOCAL statement_timeout = ${statementTimeoutMs}`);
+        }
+    }
     return {
         async begin() {
             let captureTx;
@@ -36,6 +51,9 @@ export function postgresTransactionManager(adapter, isolationLevel = IsolationLe
             });
             const txPromise = adapter
                 .transaction(isolationLevel, async (tx) => {
+                // Arm the per-transaction safety timeouts before handing the tx to
+                // the UoW, so even the very first awaited statement is bounded.
+                await applyTimeouts(tx);
                 captureTx(tx);
                 await completion;
             })
@@ -45,7 +63,18 @@ export function postgresTransactionManager(adapter, isolationLevel = IsolationLe
                     return;
                 throw err;
             });
-            const tx = (await txReady);
+            // If the transaction callback fails before it hands back the tx — BEGIN
+            // itself failing, or arming the safety timeouts throwing — `captureTx`
+            // never runs and `txReady` would never resolve. Race it against
+            // `txPromise` so an early failure rejects begin() instead of hanging it
+            // forever. In the happy path `txPromise` stays pending (parked on
+            // `completion` until commit/rollback), so `txReady` always wins.
+            const tx = (await Promise.race([txReady, txPromise]));
+            if (tx === undefined) {
+                // txPromise settled first by resolving — the tx ended before begin()
+                // returned, so the handle is unusable. Surface rather than return it.
+                throw new Error("postgresTransactionManager: transaction ended before begin() completed");
+            }
             tx[TX_CONTROL] = { resolveCommit, rejectRollback, txPromise };
             return tx;
         },
@@ -69,6 +98,13 @@ export function postgresTransactionManager(adapter, isolationLevel = IsolationLe
         },
     };
 }
+/** Coerce a config timeout to a non-negative whole number of milliseconds.
+ *  Non-finite or negative values disable the timeout (treated as 0). */
+function normalizeTimeoutMs(value) {
+    if (!Number.isFinite(value) || value <= 0)
+        return 0;
+    return Math.floor(value);
+}
 /**
  * Run `fn` inside a postgres tx, joining a UoW-scoped tx if one is active
  * (or installed lazily), otherwise opening an ad-hoc tx via `adapter.transaction`.

package/dist/postgres-transaction-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"postgres-transaction-manager.js","sourceRoot":"","sources":["../src/postgres-transaction-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,2BAA2B,EAA2B,MAAM,sBAAsB,CAAA;AAE3F,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAE7C;;;;GAIG;AACH,MAAM,UAAU,GAAG,MAAM,CAAC,0BAA0B,CAAC,CAAA;AAYrD,mFAAmF;AACnF,MAAM,eAAe,GAAG,iCAAiC,CAAA;AAEzD,MAAM,UAAU,0BAA0B,CACxC,OAAwB,EACxB,iBAAiC,cAAc,CAAC,cAAc;IAE9D,OAAO;QACL,KAAK,CAAC,KAAK;YACT,IAAI,SAAoD,CAAA;YACxD,MAAM,OAAO,GAAG,IAAI,OAAO,CAA6B,CAAC,GAAG,EAAE,EAAE;gBAC9D,SAAS,GAAG,GAAG,CAAA;YACjB,CAAC,CAAC,CAAA;YAEF,IAAI,aAA0B,CAAA;YAC9B,IAAI,cAAuC,CAAA;YAC3C,MAAM,UAAU,GAAG,IAAI,OAAO,CAAO,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;gBAChD,aAAa,GAAG,GAAG,CAAA;gBACnB,cAAc,GAAG,GAAG,CAAA;YACtB,CAAC,CAAC,CAAA;YAEF,MAAM,SAAS,GAAG,OAAO;iBACtB,WAAW,CAAC,cAAc,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE;gBACxC,SAAS,CAAC,EAAE,CAAC,CAAA;gBACb,MAAM,UAAU,CAAA;YAClB,CAAC,CAAC;iBACD,IAAI,CACH,GAAG,EAAE,CAAC,SAAS,EACf,CAAC,GAAG,EAAE,EAAE;gBACN,yDAAyD;gBACzD,IAAI,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,OAAO,KAAK,eAAe;oBAAE,OAAM;gBACnE,MAAM,GAAG,CAAA;YACX,CAAC,CACF,CAAA;YAEH,MAAM,EAAE,GAAG,CAAC,MAAM,OAAO,CAA+B,CAAA;YACxD,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,aAAa,EAAE,cAAc,EAAE,SAAS,EAAE,CAAA;YAC7D,OAAO,EAAE,CAAA;QACX,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,EAA8B;YACzC,MAAM,IAAI,GAAI,EAAiC,CAAC,UAAU,CAAC,CAAA;YAC3D,IAAI,CAAC,aAAa,EAAE,CAAA;YACpB,MAAM,IAAI,CAAC,SAAS,CAAA;QACtB,CAAC;QAED,KAAK,CAAC,QAAQ,CAAC,EAA8B;YAC3C,MAAM,IAAI,GAAI,EAAiC,CAAC,UAAU,CAAC,CAAA;YAC3D,IAAI,CAAC,cAAc,CAAC,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC,CAAA;YAC/C,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,SAAS,CAAA;YACtB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,gEAAgE;gBAChE,8DAA8D;gBAC9D,8CAA8C;gBAC9C,OAAO,CAAC,IAAI,CAAC,kDAAkD,EAAE,GAAG,CAAC,CAAA;YACvE,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAwB,EACxB,EAAkD,EAClD,iBAAiC,cAAc,CAAC,cAAc;IAE9D,MAAM,MAAM,GAAG,MAAM,2BAA2B,EAA8B,CAAA;IAC9E,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC,MAAM,CAAC,CAAA;IAC3C,OAAO,OAAO,CAAC,WAAW,CAAC,cAAc,EAAE,EAAE,CAAC,CAAA;AAChD,CAAC"}
+{"version":3,"file":"postgres-transaction-manager.js","sourceRoot":"","sources":["../src/postgres-transaction-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,2BAA2B,EAA2B,MAAM,sBAAsB,CAAA;AAE3F,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAE7C;;;;GAIG;AACH,MAAM,UAAU,GAAG,MAAM,CAAC,0BAA0B,CAAC,CAAA;AAYrD,mFAAmF;AACnF,MAAM,eAAe,GAAG,iCAAiC,CAAA;AAsBzD,MAAM,sCAAsC,GAAG,MAAM,CAAA;AAErD,MAAM,UAAU,0BAA0B,CACxC,OAAwB,EACxB,iBAAiC,cAAc,CAAC,cAAc,EAC9D,UAA6C,EAAE;IAE/C,MAAM,aAAa,GAAG,kBAAkB,CACtC,OAAO,CAAC,0BAA0B,IAAI,sCAAsC,CAC7E,CAAA;IACD,MAAM,kBAAkB,GAAG,kBAAkB,CAAC,OAAO,CAAC,kBAAkB,IAAI,CAAC,CAAC,CAAA;IAE9E,8EAA8E;IAC9E,4EAA4E;IAC5E,0EAA0E;IAC1E,eAAe;IACf,KAAK,UAAU,aAAa,CAAC,EAA8B;QACzD,IAAI,aAAa,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,EAAE,CAAC,KAAK,CAAC,mDAAmD,aAAa,EAAE,CAAC,CAAA;QACpF,CAAC;QACD,IAAI,kBAAkB,GAAG,CAAC,EAAE,CAAC;YAC3B,MAAM,EAAE,CAAC,KAAK,CAAC,iCAAiC,kBAAkB,EAAE,CAAC,CAAA;QACvE,CAAC;IACH,CAAC;IAED,OAAO;QACL,KAAK,CAAC,KAAK;YACT,IAAI,SAAoD,CAAA;YACxD,MAAM,OAAO,GAAG,IAAI,OAAO,CAA6B,CAAC,GAAG,EAAE,EAAE;gBAC9D,SAAS,GAAG,GAAG,CAAA;YACjB,CAAC,CAAC,CAAA;YAEF,IAAI,aAA0B,CAAA;YAC9B,IAAI,cAAuC,CAAA;YAC3C,MAAM,UAAU,GAAG,IAAI,OAAO,CAAO,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;gBAChD,aAAa,GAAG,GAAG,CAAA;gBACnB,cAAc,GAAG,GAAG,CAAA;YACtB,CAAC,CAAC,CAAA;YAEF,MAAM,SAAS,GAAG,OAAO;iBACtB,WAAW,CAAC,cAAc,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE;gBACxC,mEAAmE;gBACnE,gEAAgE;gBAChE,MAAM,aAAa,CAAC,EAAE,CAAC,CAAA;gBACvB,SAAS,CAAC,EAAE,CAAC,CAAA;gBACb,MAAM,UAAU,CAAA;YAClB,CAAC,CAAC;iBACD,IAAI,CACH,GAAG,EAAE,CAAC,SAAS,EACf,CAAC,GAAG,EAAE,EAAE;gBACN,yDAAyD;gBACzD,IAAI,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,OAAO,KAAK,eAAe;oBAAE,OAAM;gBACnE,MAAM,GAAG,CAAA;YACX,CAAC,CACF,CAAA;YAEH,wEAAwE;YACxE,uEAAuE;YACvE,gEAAgE;YAChE,wEAAwE;YACxE,kEAAkE;YAClE,iEAAiE;YACjE,MAAM,EAAE,GAAG,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAEvC,CAAA;YACb,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;gBACrB,qEAAqE;gBACrE,sEAAsE;gBACtE,MAAM,IAAI,KAAK,CACb,wEAAwE,CACzE,CAAA;YACH,CAAC;YACD,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,aAAa,EAAE,cAAc,EAAE,SAAS,EAAE,CAAA;YAC7D,OAAO,EAAE,CAAA;QACX,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,EAA8B;YACzC,MAAM,IAAI,GAAI,EAAiC,CAAC,UAAU,CAAC,CAAA;YAC3D,IAAI,CAAC,aAAa,EAAE,CAAA;YACpB,MAAM,IAAI,CAAC,SAAS,CAAA;QACtB,CAAC;QAED,KAAK,CAAC,QAAQ,CAAC,EAA8B;YAC3C,MAAM,IAAI,GAAI,EAAiC,CAAC,UAAU,CAAC,CAAA;YAC3D,IAAI,CAAC,cAAc,CAAC,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC,CAAA;YAC/C,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,SAAS,CAAA;YACtB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,gEAAgE;gBAChE,8DAA8D;gBAC9D,8CAA8C;gBAC9C,OAAO,CAAC,IAAI,CAAC,kDAAkD,EAAE,GAAG,CAAC,CAAA;YACvE,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED;wEACwE;AACxE,SAAS,kBAAkB,CAAC,KAAa;IACvC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,CAAC,CAAA;IACnD,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;AAC1B,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAwB,EACxB,EAAkD,EAClD,iBAAiC,cAAc,CAAC,cAAc;IAE9D,MAAM,MAAM,GAAG,MAAM,2BAA2B,EAA8B,CAAA;IAC9E,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC,MAAM,CAAC,CAAA;IAC3C,OAAO,OAAO,CAAC,WAAW,CAAC,cAAc,EAAE,EAAE,CAAC,CAAA;AAChD,CAAC"}

package/dist/postgres.d.ts

@@ -46,6 +46,14 @@ export interface PostgresConfig {
         readonly pollIntervalMs?: number;
         readonly batchSize?: number;
     };
+    /** Safety timeouts applied via `SET LOCAL` to every UoW-scoped transaction.
+     *  Guards against a stalled UoW holding a connection — and pinning
+     *  `pg_snapshot_xmin`, which would stall all streaming tailing — open until
+     *  restart. Defaults: 30s idle-in-transaction, statement timeout disabled. */
+    readonly transaction?: {
+        readonly idleInTransactionTimeoutMs?: number;
+        readonly statementTimeoutMs?: number;
+    };
 }
 export declare function postgres(config: PostgresConfig): (app: App) => void;
 //# sourceMappingURL=postgres.d.ts.map

package/dist/postgres.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../src/postgres.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAMzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAQnD,OAAO,EAAwC,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAEnF,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;IACjC;uCACmC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAA;IAChC;4CACwC;IACxC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAC/C,yDAAyD;IACzD,QAAQ,CAAC,SAAS,CAAC,EAAE;QACnB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;QAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAC5B,CAAA;CACF;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CAgEnE"}
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../src/postgres.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAMzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAQnD,OAAO,EAAwC,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAEnF,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;IACjC;uCACmC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAA;IAChC;4CACwC;IACxC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAC/C,yDAAyD;IACzD,QAAQ,CAAC,SAAS,CAAC,EAAE;QACnB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;QAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAC5B,CAAA;IACD;;;kFAG8E;IAC9E,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,0BAA0B,CAAC,EAAE,MAAM,CAAA;QAC5C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;KACrC,CAAA;CACF;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CAgEnE"}

package/dist/postgres.js

@@ -37,7 +37,7 @@ export function postgres(config) {
     const { adapter, resilience } = config;
     const bootstrap = config.bootstrap ?? true;
     const tables = config.tableNames ?? DEFAULT_TABLE_NAMES;
-    const txManager = postgresTransactionManager(adapter);
+    const txManager = postgresTransactionManager(adapter, undefined, config.transaction);
     return (app) => {
         app.set("eventStore", ({ serializer, tagResolver }) => createPostgresEventStore({ adapter, serializer, tagResolver, tableNames: tables }));
         app.set("snapshotStore", ({ serializer }) => createPostgresSnapshotStore({ adapter, serializer, tableNames: tables }));

package/dist/postgres.js.map

@@ -1 +1 @@
-{"version":3,"file":"postgres.js","sourceRoot":"","sources":["../src/postgres.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"postgres.js","sourceRoot":"","sources":["../src/postgres.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAC7C,OAAO,EACL,kCAAkC,EAClC,WAAW,GACZ,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAA;AACpE,OAAO,EAAE,2BAA2B,EAAE,MAAM,8BAA8B,CAAA;AAC1E,OAAO,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAA;AAC9E,OAAO,EACL,4BAA4B,GAE7B,MAAM,+BAA+B,CAAA;AACtC,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAmB,MAAM,aAAa,CAAA;AA4BnF,MAAM,UAAU,QAAQ,CAAC,MAAsB;IAC7C,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CAAA;IACtC,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,IAAI,CAAA;IAC1C,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,IAAI,mBAAmB,CAAA;IAEvD,MAAM,SAAS,GAAG,0BAA0B,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,WAAW,CAAC,CAAA;IAEpF,OAAO,CAAC,GAAQ,EAAE,EAAE;QAClB,GAAG,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC,EAAE,UAAU,EAAE,WAAW,EAAE,EAAE,EAAE,CACpD,wBAAwB,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CACnF,CAAA;QACD,GAAG,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CAC1C,2BAA2B,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CACzE,CAAA;QACD,GAAG,CAAC,GAAG,CAAC,oBAAoB,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;QAC9C,sEAAsE;QACtE,qEAAqE;QACrE,oEAAoE;QACpE,yEAAyE;QACzE,yEAAyE;QACzE,uEAAuE;QACvE,YAAY;QACZ,GAAG,CAAC,GAAG,CAAC,mBAAmB,EAAE,GAAG,EAAE,CAChC,kCAAkC,CAAC,WAAW,EAAE,SAAS,CAAC,CAC3D,CAAA;QAED,yEAAyE;QACzE,yEAAyE;QACzE,sBAAsB;QACtB,IAAI,SAA6C,CAAA;QACjD,GAAG,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAC,EAAE,UAAU,EAAE,iBAAiB,EAAE,WAAW,EAAE,EAAE,EAAE;YAC3E,SAAS,GAAG,4BAA4B,CAAC;gBACvC,OAAO;gBACP,UAAU;gBACV,UAAU,EAAE,iBAAiB;gBAC7B,WAAW;gBACX,UAAU,EAAE,MAAM;gBAClB,GAAG,MAAM,CAAC,SAAS;aACpB,CAAC,CAAA;YACF,OAAO,SAAS,CAAA;QAClB,CAAC,CAAC,CAAA;QAEF,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;YAChC,MAAM,SAAS,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,iBAAiB,EAAE,GAAG,UAAU,EAAE,CAAC,CAAA;YACrF,IAAI,SAAS,EAAE,CAAC;gBACd,MAAM,SAAS,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,EAAE;oBACtE,KAAK,EAAE,iBAAiB;oBACxB,GAAG,UAAU;iBACd,CAAC,CAAA;YACJ,CAAC;QACH,CAAC,CAAC,CAAA;QAEF,0EAA0E;QAC1E,uEAAuE;QACvE,+BAA+B;QAC/B,GAAG,CAAC,OAAO,CAAC,YAAY,EAAE,KAAK,IAAI,EAAE;YACnC,IAAI,SAAS;gBAAE,MAAM,SAAS,CAAC,KAAK,EAAE,CAAA;QACxC,CAAC,CAAC,CAAA;QAEF,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;YAC/B,IAAI,SAAS;gBAAE,MAAM,SAAS,CAAC,IAAI,EAAE,CAAA;YACrC,MAAM,OAAO,CAAC,UAAU,EAAE,CAAA;QAC5B,CAAC,CAAC,CAAA;IACJ,CAAC,CAAA;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kronos-ts/postgres",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "PostgreSQL extension for Kronos — event store and snapshot store adapters.",
   "license": "Apache-2.0",
   "type": "module",
@@ -68,9 +68,9 @@
   },
   "dependencies": {
     "@kronos-ts/common": "0.1.1",
-    "@kronos-ts/app": "0.3.3",
-    "@kronos-ts/eventsourcing": "0.2.0",
-    "@kronos-ts/messaging": "0.5.0"
+    "@kronos-ts/app": "0.3.4",
+    "@kronos-ts/eventsourcing": "0.2.1",
+    "@kronos-ts/messaging": "0.5.1"
   },
   "peerDependencies": {
     "pg": ">=8.0.0",

package/src/postgres-transaction-manager.ts

@@ -36,10 +36,51 @@ interface ManagedPostgresTransaction extends PostgresAdapterTransaction {
 /** Marker error: signals an intentional rollback so the .catch can suppress it. */
 const ROLLBACK_MARKER = "__kronos_postgres_tx_rollback__"
 
+/** Tuning for the safety timeouts applied to every UoW-scoped transaction. */
+export interface PostgresTransactionManagerOptions {
+  /**
+   * `idle_in_transaction_session_timeout` (ms) applied via `SET LOCAL` on every
+   * transaction. A UoW that begins a tx but stalls before commit/rollback would
+   * otherwise hold its connection — and pin `pg_snapshot_xmin`, which gates the
+   * gap-free tailing query in the event store — open indefinitely, stalling all
+   * streaming processors until the process restarts. This bounds that window:
+   * postgres aborts the idle transaction and the connection (and xmin) is freed.
+   * Default 30000 (30s). Set 0 to disable (postgres default — no timeout).
+   */
+  readonly idleInTransactionTimeoutMs?: number
+  /**
+   * `statement_timeout` (ms) applied via `SET LOCAL` on every transaction.
+   * Bounds a single hung statement inside the tx. Default 0 (disabled) — large
+   * appends / replays can legitimately run long, so opt in per deployment.
+   */
+  readonly statementTimeoutMs?: number
+}
+
+const DEFAULT_IDLE_IN_TRANSACTION_TIMEOUT_MS = 30_000
+
 export function postgresTransactionManager(
   adapter: PostgresAdapter,
   isolationLevel: IsolationLevel = IsolationLevel.READ_COMMITTED,
+  options: PostgresTransactionManagerOptions = {},
 ): TransactionManager<PostgresAdapterTransaction> {
+  const idleTimeoutMs = normalizeTimeoutMs(
+    options.idleInTransactionTimeoutMs ?? DEFAULT_IDLE_IN_TRANSACTION_TIMEOUT_MS,
+  )
+  const statementTimeoutMs = normalizeTimeoutMs(options.statementTimeoutMs ?? 0)
+
+  // GUCs cannot be parameterized ($1) — the value is a config-supplied integer,
+  // normalized to a non-negative whole number, so inlining is injection-safe.
+  // SET LOCAL auto-resets at COMMIT/ROLLBACK, so it never leaks onto pooled
+  // connections.
+  async function applyTimeouts(tx: PostgresAdapterTransaction): Promise<void> {
+    if (idleTimeoutMs > 0) {
+      await tx.query(`SET LOCAL idle_in_transaction_session_timeout = ${idleTimeoutMs}`)
+    }
+    if (statementTimeoutMs > 0) {
+      await tx.query(`SET LOCAL statement_timeout = ${statementTimeoutMs}`)
+    }
+  }
+
   return {
     async begin(): Promise<PostgresAdapterTransaction> {
       let captureTx!: (tx: PostgresAdapterTransaction) => void
@@ -56,6 +97,9 @@ export function postgresTransactionManager(
 
       const txPromise = adapter
         .transaction(isolationLevel, async (tx) => {
+          // Arm the per-transaction safety timeouts before handing the tx to
+          // the UoW, so even the very first awaited statement is bounded.
+          await applyTimeouts(tx)
           captureTx(tx)
           await completion
         })
@@ -68,7 +112,22 @@ export function postgresTransactionManager(
           },
         )
 
-      const tx = (await txReady) as ManagedPostgresTransaction
+      // If the transaction callback fails before it hands back the tx — BEGIN
+      // itself failing, or arming the safety timeouts throwing — `captureTx`
+      // never runs and `txReady` would never resolve. Race it against
+      // `txPromise` so an early failure rejects begin() instead of hanging it
+      // forever. In the happy path `txPromise` stays pending (parked on
+      // `completion` until commit/rollback), so `txReady` always wins.
+      const tx = (await Promise.race([txReady, txPromise])) as
+        | ManagedPostgresTransaction
+        | undefined
+      if (tx === undefined) {
+        // txPromise settled first by resolving — the tx ended before begin()
+        // returned, so the handle is unusable. Surface rather than return it.
+        throw new Error(
+          "postgresTransactionManager: transaction ended before begin() completed",
+        )
+      }
       tx[TX_CONTROL] = { resolveCommit, rejectRollback, txPromise }
       return tx
     },
@@ -94,6 +153,13 @@ export function postgresTransactionManager(
   }
 }
 
+/** Coerce a config timeout to a non-negative whole number of milliseconds.
+ *  Non-finite or negative values disable the timeout (treated as 0). */
+function normalizeTimeoutMs(value: number): number {
+  if (!Number.isFinite(value) || value <= 0) return 0
+  return Math.floor(value)
+}
+
 /**
  * Run `fn` inside a postgres tx, joining a UoW-scoped tx if one is active
  * (or installed lazily), otherwise opening an ad-hoc tx via `adapter.transaction`.

package/src/postgres.ts

@@ -60,6 +60,14 @@ export interface PostgresConfig {
     readonly pollIntervalMs?: number
     readonly batchSize?: number
   }
+  /** Safety timeouts applied via `SET LOCAL` to every UoW-scoped transaction.
+   *  Guards against a stalled UoW holding a connection — and pinning
+   *  `pg_snapshot_xmin`, which would stall all streaming tailing — open until
+   *  restart. Defaults: 30s idle-in-transaction, statement timeout disabled. */
+  readonly transaction?: {
+    readonly idleInTransactionTimeoutMs?: number
+    readonly statementTimeoutMs?: number
+  }
 }
 
 export function postgres(config: PostgresConfig): (app: App) => void {
@@ -67,7 +75,7 @@ export function postgres(config: PostgresConfig): (app: App) => void {
   const bootstrap = config.bootstrap ?? true
   const tables = config.tableNames ?? DEFAULT_TABLE_NAMES
 
-  const txManager = postgresTransactionManager(adapter)
+  const txManager = postgresTransactionManager(adapter, undefined, config.transaction)
 
   return (app: App) => {
     app.set("eventStore", ({ serializer, tagResolver }) =>