node-firebird 2.7.0 → 2.8.0

package/README.md

@@ -217,6 +217,44 @@ pool.get(function (err, db) {
 pool.destroy();
 ```
 
+#### Pool events and metrics
+
+The pool is an `EventEmitter` and exposes live counters, following the
+`pg.Pool` conventions:
+
+```js
+const pool = Firebird.pool(10, {
+    ...options,
+    idleTimeoutMillis: 30000, // close connections idle for 30s…
+    min: 2,                   // …but always keep 2 alive
+    connectTimeout: 5000,
+});
+
+pool.on('connect', (db) => console.log('new server connection'));
+pool.on('acquire', (db) => console.log('connection handed to a caller'));
+pool.on('release', (db) => console.log('connection returned to the pool'));
+pool.on('remove',  (db) => console.log('connection closed & removed'));
+pool.on('error',   (err, db) => console.error('background pool error', err));
+
+// live metrics — e.g. for a /health endpoint or periodic monitoring
+console.log({
+    total:   pool.totalCount,   // physical connections (idle + in use)
+    idle:    pool.idleCount,    // available in the pool
+    active:  pool.activeCount,  // handed out to callers
+    waiting: pool.waitingCount, // get() calls queued for a free slot
+});
+```
+
+- `idleTimeoutMillis` closes connections that sat idle in the pool for that
+  long, never shrinking below `min` — long-lived pools no longer hold every
+  connection they ever created (issue [#329](https://github.com/hgourvest/node-firebird/issues/329)).
+  The sweep also evicts idle connections whose socket has died, so callers
+  don't receive them after a server restart (issue [#343](https://github.com/hgourvest/node-firebird/issues/343)).
+- `error` is a background-error channel (idle eviction failures and the
+  like); unlike a plain `EventEmitter`, it is only emitted when a listener
+  is attached, so existing applications keep working unchanged.
+- Metrics are plain getters — reading them has no side effects.
+
 #### Advanced Pooling Features
 
 The pool implementation includes several safeguards for reliability:
@@ -224,6 +262,7 @@ The pool implementation includes several safeguards for reliability:
 1.  **Connection Timeout**: Use `options.connectTimeout` to prevent the pool from hanging if a server accepts the TCP connection but fails to respond to the Firebird wire protocol (e.g., during high load or authentication stalls).
 2.  **Pool Destruction**: Calling `pool.destroy()` now immediately drains the `pending` queue, notifying all waiting callers with an error. It also prevents any further `pool.get()` calls.
 3.  **Slot Recovery**: If a connection attempt times out, the pool slot is correctly freed so subsequent requests can be served. Late-arriving connections are automatically discarded to prevent resource leaks.
+4.  **Idle Reaping & Health**: `idleTimeoutMillis`/`min` shrink the pool when traffic drops and evict dead idle connections (see [Pool events and metrics](#pool-events-and-metrics)).
 
 #### Pool Lifecycle State Diagram
 

package/lib/pool.d.ts

@@ -3,19 +3,61 @@
  *   Simple Pooling
  *
  ***************************************/
+import Events from 'events';
 import type { Callback } from './callback';
 type AttachFn = (options: any, callback: Callback) => void;
-declare class Pool {
+/**
+ * Connection pool with pg.Pool-style observability.
+ *
+ * Events (all optional to listen to):
+ *   'connect' (db)      — a new physical connection was established
+ *   'acquire' (db)      — a connection was handed to a caller
+ *   'release' (db)      — a connection was returned to the idle pool
+ *   'remove'  (db)      — a physical connection left the pool for good
+ *   'error'   (err, db) — a background error (idle eviction, reaper detach);
+ *                         only emitted when a listener is attached, so
+ *                         existing applications never crash on it
+ *
+ * Metrics: totalCount, idleCount, activeCount, waitingCount.
+ *
+ * Options: max (factory argument), options.min (floor the reaper never
+ * shrinks below), options.idleTimeoutMillis (close idle connections after
+ * this many ms; 0/absent = never), options.connectTimeout.
+ */
+declare class Pool extends Events.EventEmitter {
     attach: AttachFn;
     internaldb: any[];
     pooldb: any[];
     dbinuse: number;
     _creating: number;
     max: number;
+    min: number;
+    idleTimeoutMillis: number;
     pending: Callback[];
     options: any;
     _destroyed: boolean;
+    _reaper: NodeJS.Timeout | null;
     constructor(attach: AttachFn, max: number, options: any);
+    /** Physical connections owned by the pool (idle + in use). */
+    get totalCount(): number;
+    /** Connections sitting idle in the pool. */
+    get idleCount(): number;
+    /** Connections currently handed out to callers. */
+    get activeCount(): number;
+    /** get() requests queued for a free slot. */
+    get waitingCount(): number;
+    /** True when the connection can no longer be used. */
+    _isDead(db: any): boolean;
+    /** Drop a physical connection from the pool's books and emit 'remove'. */
+    _forget(db: any): void;
+    /** Emit 'error' only when someone listens — never crash the app. */
+    _emitError(err: any, db?: any): void;
+    /**
+     * Idle sweep: evict dead idle connections immediately and close healthy
+     * ones that have been idle longer than idleTimeoutMillis, keeping at
+     * least `min` physical connections. (issue #329)
+     */
+    _reap(): void;
     get(callback: Callback): this;
     check(): this;
     destroy(callback?: (err?: any) => void): void;

package/lib/pool.js

@@ -4,18 +4,124 @@
  *   Simple Pooling
  *
  ***************************************/
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const events_1 = __importDefault(require("events"));
 const callback_1 = require("./callback");
-class Pool {
+/**
+ * Connection pool with pg.Pool-style observability.
+ *
+ * Events (all optional to listen to):
+ *   'connect' (db)      — a new physical connection was established
+ *   'acquire' (db)      — a connection was handed to a caller
+ *   'release' (db)      — a connection was returned to the idle pool
+ *   'remove'  (db)      — a physical connection left the pool for good
+ *   'error'   (err, db) — a background error (idle eviction, reaper detach);
+ *                         only emitted when a listener is attached, so
+ *                         existing applications never crash on it
+ *
+ * Metrics: totalCount, idleCount, activeCount, waitingCount.
+ *
+ * Options: max (factory argument), options.min (floor the reaper never
+ * shrinks below), options.idleTimeoutMillis (close idle connections after
+ * this many ms; 0/absent = never), options.connectTimeout.
+ */
+class Pool extends events_1.default.EventEmitter {
     constructor(attach, max, options) {
+        super();
         this.attach = attach;
         this.internaldb = []; // connections created by the pool (for destroy)
         this.pooldb = []; // connections available in the pool (idle)
         this.dbinuse = 0; // connections currently handed out to callers
         this._creating = 0; // connections currently being created (attach in flight)
         this.max = max || 4;
+        this.min = (options && options.min > 0) ? Math.min(options.min, this.max) : 0;
+        this.idleTimeoutMillis = (options && options.idleTimeoutMillis > 0) ? options.idleTimeoutMillis : 0;
         this.pending = []; // callbacks waiting for a free slot
         this.options = options;
         this._destroyed = false; // true after destroy() — prevents further use
+        this._reaper = null;
+        if (this.idleTimeoutMillis) {
+            var self = this;
+            // Sweep at half the idle timeout (bounded to 100ms..30s) so a
+            // connection lives at most ~1.5x idleTimeoutMillis. unref() keeps
+            // the timer from holding the process open.
+            var interval = Math.min(Math.max(this.idleTimeoutMillis / 2, 100), 30000);
+            this._reaper = setInterval(function () { self._reap(); }, interval);
+            if (this._reaper.unref)
+                this._reaper.unref();
+        }
+    }
+    /** Physical connections owned by the pool (idle + in use). */
+    get totalCount() {
+        return this.internaldb.length;
+    }
+    /** Connections sitting idle in the pool. */
+    get idleCount() {
+        return this.pooldb.length;
+    }
+    /** Connections currently handed out to callers. */
+    get activeCount() {
+        return this.dbinuse;
+    }
+    /** get() requests queued for a free slot. */
+    get waitingCount() {
+        return this.pending.length;
+    }
+    /** True when the connection can no longer be used. */
+    _isDead(db) {
+        return !db.connection || db.connection._isClosed || db.connection._isDetach ||
+            !db.connection._socket || db.connection._socket.destroyed;
+    }
+    /** Drop a physical connection from the pool's books and emit 'remove'. */
+    _forget(db) {
+        var idx = this.internaldb.indexOf(db);
+        if (idx !== -1)
+            this.internaldb.splice(idx, 1);
+        idx = this.pooldb.indexOf(db);
+        if (idx !== -1)
+            this.pooldb.splice(idx, 1);
+        this.emit('remove', db);
+    }
+    /** Emit 'error' only when someone listens — never crash the app. */
+    _emitError(err, db) {
+        if (this.listenerCount('error') > 0)
+            this.emit('error', err, db);
+    }
+    /**
+     * Idle sweep: evict dead idle connections immediately and close healthy
+     * ones that have been idle longer than idleTimeoutMillis, keeping at
+     * least `min` physical connections. (issue #329)
+     */
+    _reap() {
+        if (this._destroyed)
+            return;
+        var self = this;
+        var now = Date.now();
+        // iterate over a copy — we splice from pooldb while walking
+        this.pooldb.slice().forEach(function (db) {
+            if (self._isDead(db)) {
+                self._forget(db);
+                return;
+            }
+            if (self.internaldb.length <= self.min)
+                return;
+            var idleSince = typeof db.__poolIdleSince === 'number' ? db.__poolIdleSince : now;
+            if (now - idleSince < self.idleTimeoutMillis)
+                return;
+            self._forget(db);
+            db.connection._pooled = false;
+            try {
+                db.detach(function (err) {
+                    if (err)
+                        self._emitError(err, db);
+                });
+            }
+            catch (e) {
+                self._emitError(e, db);
+            }
+        });
     }
     get(callback) {
         // [Fix 2] Reject immediately if the pool has already been destroyed.
@@ -41,16 +147,15 @@ class Pool {
         if (self.pooldb.length) {
             var db = self.pooldb.shift();
             // Discard connections that have been closed or destroyed while idle
-            if (db.connection && (db.connection._isClosed || db.connection._isDetach || !db.connection._socket || db.connection._socket.destroyed)) {
-                var idx = self.internaldb.indexOf(db);
-                if (idx !== -1)
-                    self.internaldb.splice(idx, 1);
+            if (self._isDead(db)) {
+                self._forget(db);
                 self.pending.unshift(cb);
                 setImmediate(function () { self.check(); });
                 return self;
             }
             // Idle connection available — hand it out immediately.
             self.dbinuse++;
+            self.emit('acquire', db);
             cb(null, db);
         }
         else {
@@ -113,13 +218,20 @@ class Pool {
                         if (self.pooldb.indexOf(db) !== -1 || self.internaldb.indexOf(db) === -1)
                             return;
                         // if not usable don't put it back in the pool
-                        if (db.connection._isClosed || db.connection._isDetach || db.connection._pooled === false)
+                        if (db.connection._isClosed || db.connection._isDetach || db.connection._pooled === false) {
                             self.internaldb.splice(self.internaldb.indexOf(db), 1);
-                        else
+                            self.emit('remove', db);
+                        }
+                        else {
+                            db.__poolIdleSince = Date.now();
                             self.pooldb.push(db);
+                            self.emit('release', db);
+                        }
                         self.dbinuse--;
                         self.check();
                     });
+                    self.emit('connect', db);
+                    self.emit('acquire', db);
                 }
                 cb(err, db);
             });
@@ -132,6 +244,10 @@ class Pool {
     destroy(callback) {
         var self = this;
         self._destroyed = true;
+        if (self._reaper) {
+            clearInterval(self._reaper);
+            self._reaper = null;
+        }
         // [Fix 4] Drain pending callbacks so callers are not left hanging.
         // This is critical when destroy() is called as a recovery measure after
         // a timeout: without draining, every concurrent pool.get() that had not
@@ -170,6 +286,7 @@ class Pool {
                 self.pooldb.splice(_db_in_pool, 1);
                 db.connection._pooled = false;
                 db.detach(detachCallback);
+                self.emit('remove', db);
             }
             else {
                 // [Fix 5] Connection is currently in use (dbinuse > 0).

package/lib/types.d.ts

@@ -224,6 +224,19 @@ export interface Options {
      * expected Firebird server response time under load.
      */
     connectTimeout?: number;
+    /**
+     * Pool only: minimum number of physical connections the idle reaper
+     * keeps alive. Only meaningful together with `idleTimeoutMillis`.
+     * Default 0 (the pool may shrink to no connections).
+     */
+    min?: number;
+    /**
+     * Pool only: close connections that have been idle in the pool for this
+     * many milliseconds, never shrinking below `min`. Dead idle connections
+     * (server restarts, dropped sockets) are evicted on the same sweep.
+     * Default 0 (idle connections are kept forever).
+     */
+    idleTimeoutMillis?: number;
     /**
      * **Firebird 6.0+ only (Protocol 20+)**
      *
@@ -265,9 +278,24 @@ export interface Options {
 export interface SvcMgrOptions extends Options {
     manager: true;
 }
+export type PoolEvent = 'connect' | 'acquire' | 'release' | 'remove' | 'error';
 export interface ConnectionPool {
     get(callback: DatabaseCallback): void;
     destroy(callback?: SimpleCallback): void;
+    /** Physical connections owned by the pool (idle + in use). */
+    readonly totalCount: number;
+    /** Connections sitting idle in the pool. */
+    readonly idleCount: number;
+    /** Connections currently handed out to callers. */
+    readonly activeCount: number;
+    /** get() requests queued for a free slot. */
+    readonly waitingCount: number;
+    on(event: 'connect' | 'acquire' | 'release' | 'remove', listener: (db: Database) => void): this;
+    on(event: 'error', listener: (err: Error, db?: Database) => void): this;
+    once(event: 'connect' | 'acquire' | 'release' | 'remove', listener: (db: Database) => void): this;
+    once(event: 'error', listener: (err: Error, db?: Database) => void): this;
+    off(event: PoolEvent, listener: (...args: any[]) => void): this;
+    removeListener(event: PoolEvent, listener: (...args: any[]) => void): this;
     getAsync(): Promise<Database>;
     destroyAsync(): Promise<void>;
     /** Acquire a connection, run `work`, always return the connection to the pool. */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "node-firebird",
-    "version": "2.7.0",
+    "version": "2.8.0",
     "description": "Pure JavaScript and Asynchronous Firebird client for Node.js.",
     "keywords": [
         "firebird",

package/src/pool.ts

@@ -4,32 +4,140 @@
  *
  ***************************************/
 
+import Events from 'events';
 import { fromCallback } from './callback';
 import type { Callback } from './callback';
 
 type AttachFn = (options: any, callback: Callback) => void;
 
-class Pool {
+/**
+ * Connection pool with pg.Pool-style observability.
+ *
+ * Events (all optional to listen to):
+ *   'connect' (db)      — a new physical connection was established
+ *   'acquire' (db)      — a connection was handed to a caller
+ *   'release' (db)      — a connection was returned to the idle pool
+ *   'remove'  (db)      — a physical connection left the pool for good
+ *   'error'   (err, db) — a background error (idle eviction, reaper detach);
+ *                         only emitted when a listener is attached, so
+ *                         existing applications never crash on it
+ *
+ * Metrics: totalCount, idleCount, activeCount, waitingCount.
+ *
+ * Options: max (factory argument), options.min (floor the reaper never
+ * shrinks below), options.idleTimeoutMillis (close idle connections after
+ * this many ms; 0/absent = never), options.connectTimeout.
+ */
+class Pool extends Events.EventEmitter {
     attach: AttachFn;
     internaldb: any[];
     pooldb: any[];
     dbinuse: number;
     _creating: number;
     max: number;
+    min: number;
+    idleTimeoutMillis: number;
     pending: Callback[];
     options: any;
     _destroyed: boolean;
+    _reaper: NodeJS.Timeout | null;
 
     constructor(attach: AttachFn, max: number, options: any) {
+        super();
         this.attach    = attach;
         this.internaldb = []; // connections created by the pool (for destroy)
         this.pooldb    = []; // connections available in the pool (idle)
         this.dbinuse   = 0;  // connections currently handed out to callers
         this._creating = 0;  // connections currently being created (attach in flight)
         this.max       = max || 4;
+        this.min       = (options && options.min > 0) ? Math.min(options.min, this.max) : 0;
+        this.idleTimeoutMillis = (options && options.idleTimeoutMillis > 0) ? options.idleTimeoutMillis : 0;
         this.pending   = []; // callbacks waiting for a free slot
         this.options   = options;
         this._destroyed = false; // true after destroy() — prevents further use
+        this._reaper   = null;
+
+        if (this.idleTimeoutMillis) {
+            var self = this;
+            // Sweep at half the idle timeout (bounded to 100ms..30s) so a
+            // connection lives at most ~1.5x idleTimeoutMillis. unref() keeps
+            // the timer from holding the process open.
+            var interval = Math.min(Math.max(this.idleTimeoutMillis / 2, 100), 30000);
+            this._reaper = setInterval(function() { self._reap(); }, interval);
+            if (this._reaper.unref) this._reaper.unref();
+        }
+    }
+
+    /** Physical connections owned by the pool (idle + in use). */
+    get totalCount(): number {
+        return this.internaldb.length;
+    }
+
+    /** Connections sitting idle in the pool. */
+    get idleCount(): number {
+        return this.pooldb.length;
+    }
+
+    /** Connections currently handed out to callers. */
+    get activeCount(): number {
+        return this.dbinuse;
+    }
+
+    /** get() requests queued for a free slot. */
+    get waitingCount(): number {
+        return this.pending.length;
+    }
+
+    /** True when the connection can no longer be used. */
+    _isDead(db: any): boolean {
+        return !db.connection || db.connection._isClosed || db.connection._isDetach ||
+            !db.connection._socket || db.connection._socket.destroyed;
+    }
+
+    /** Drop a physical connection from the pool's books and emit 'remove'. */
+    _forget(db: any): void {
+        var idx = this.internaldb.indexOf(db);
+        if (idx !== -1) this.internaldb.splice(idx, 1);
+        idx = this.pooldb.indexOf(db);
+        if (idx !== -1) this.pooldb.splice(idx, 1);
+        this.emit('remove', db);
+    }
+
+    /** Emit 'error' only when someone listens — never crash the app. */
+    _emitError(err: any, db?: any): void {
+        if (this.listenerCount('error') > 0) this.emit('error', err, db);
+    }
+
+    /**
+     * Idle sweep: evict dead idle connections immediately and close healthy
+     * ones that have been idle longer than idleTimeoutMillis, keeping at
+     * least `min` physical connections. (issue #329)
+     */
+    _reap(): void {
+        if (this._destroyed) return;
+        var self = this;
+        var now = Date.now();
+
+        // iterate over a copy — we splice from pooldb while walking
+        this.pooldb.slice().forEach(function(db) {
+            if (self._isDead(db)) {
+                self._forget(db);
+                return;
+            }
+            if (self.internaldb.length <= self.min) return;
+            var idleSince = typeof db.__poolIdleSince === 'number' ? db.__poolIdleSince : now;
+            if (now - idleSince < self.idleTimeoutMillis) return;
+
+            self._forget(db);
+            db.connection._pooled = false;
+            try {
+                db.detach(function(err?: any) {
+                    if (err) self._emitError(err, db);
+                });
+            } catch (e) {
+                self._emitError(e, db);
+            }
+        });
     }
 
     get(callback: Callback): this {
@@ -59,15 +167,15 @@ class Pool {
         if (self.pooldb.length) {
             var db = self.pooldb.shift();
             // Discard connections that have been closed or destroyed while idle
-            if (db.connection && (db.connection._isClosed || db.connection._isDetach || !db.connection._socket || db.connection._socket.destroyed)) {
-                var idx = self.internaldb.indexOf(db);
-                if (idx !== -1) self.internaldb.splice(idx, 1);
+            if (self._isDead(db)) {
+                self._forget(db);
                 self.pending.unshift(cb);
                 setImmediate(function () { self.check(); });
                 return self;
             }
             // Idle connection available — hand it out immediately.
             self.dbinuse++;
+            self.emit('acquire', db);
             cb(null, db);
         } else {
             // No idle connection — create a new one via attach().
@@ -133,14 +241,20 @@ class Pool {
                         if (self.pooldb.indexOf(db) !== -1 || self.internaldb.indexOf(db) === -1)
                             return;
                         // if not usable don't put it back in the pool
-                        if (db.connection._isClosed || db.connection._isDetach || db.connection._pooled === false)
+                        if (db.connection._isClosed || db.connection._isDetach || db.connection._pooled === false) {
                             self.internaldb.splice(self.internaldb.indexOf(db), 1);
-                        else
+                            self.emit('remove', db);
+                        } else {
+                            db.__poolIdleSince = Date.now();
                             self.pooldb.push(db);
+                            self.emit('release', db);
+                        }
 
                         self.dbinuse--;
                         self.check();
                     });
+                    self.emit('connect', db);
+                    self.emit('acquire', db);
                 }
 
                 cb(err, db);
@@ -157,6 +271,11 @@ class Pool {
         var self = this;
         self._destroyed = true;
 
+        if (self._reaper) {
+            clearInterval(self._reaper);
+            self._reaper = null;
+        }
+
         // [Fix 4] Drain pending callbacks so callers are not left hanging.
         // This is critical when destroy() is called as a recovery measure after
         // a timeout: without draining, every concurrent pool.get() that had not
@@ -197,6 +316,7 @@ class Pool {
                 self.pooldb.splice(_db_in_pool, 1);
                 db.connection._pooled = false;
                 db.detach(detachCallback);
+                self.emit('remove', db);
             } else {
                 // [Fix 5] Connection is currently in use (dbinuse > 0).
                 // The caller is responsible for releasing it via detach().

package/src/types.ts

@@ -281,6 +281,19 @@ export interface Options {
      * expected Firebird server response time under load.
      */
     connectTimeout?: number;
+    /**
+     * Pool only: minimum number of physical connections the idle reaper
+     * keeps alive. Only meaningful together with `idleTimeoutMillis`.
+     * Default 0 (the pool may shrink to no connections).
+     */
+    min?: number;
+    /**
+     * Pool only: close connections that have been idle in the pool for this
+     * many milliseconds, never shrinking below `min`. Dead idle connections
+     * (server restarts, dropped sockets) are evicted on the same sweep.
+     * Default 0 (idle connections are kept forever).
+     */
+    idleTimeoutMillis?: number;
     /**
      * **Firebird 6.0+ only (Protocol 20+)**
      *
@@ -324,10 +337,30 @@ export interface SvcMgrOptions extends Options {
     manager: true; // Attach to ServiceManager
 }
 
+export type PoolEvent = 'connect' | 'acquire' | 'release' | 'remove' | 'error';
+
 export interface ConnectionPool {
     get(callback: DatabaseCallback): void;
     destroy(callback?: SimpleCallback): void;
 
+    // Metrics (live counters, pg.Pool-style)
+    /** Physical connections owned by the pool (idle + in use). */
+    readonly totalCount: number;
+    /** Connections sitting idle in the pool. */
+    readonly idleCount: number;
+    /** Connections currently handed out to callers. */
+    readonly activeCount: number;
+    /** get() requests queued for a free slot. */
+    readonly waitingCount: number;
+
+    // Events
+    on(event: 'connect' | 'acquire' | 'release' | 'remove', listener: (db: Database) => void): this;
+    on(event: 'error', listener: (err: Error, db?: Database) => void): this;
+    once(event: 'connect' | 'acquire' | 'release' | 'remove', listener: (db: Database) => void): this;
+    once(event: 'error', listener: (err: Error, db?: Database) => void): this;
+    off(event: PoolEvent, listener: (...args: any[]) => void): this;
+    removeListener(event: PoolEvent, listener: (...args: any[]) => void): this;
+
     // Promise / async-await API
     getAsync(): Promise<Database>;
     destroyAsync(): Promise<void>;