node-firebird 2.3.1 → 2.3.2

package/README.md

@@ -72,6 +72,7 @@ options.wireCompression = false; // set to true to enable firebird compression o
 options.wireCrypt = Firebird.WIRE_CRYPT_ENABLE; // default; set to Firebird.WIRE_CRYPT_DISABLE to disable wire encryption (FB >= 3)
 options.pluginName = undefined; // optional, auto-negotiated; can be set to Firebird.AUTH_PLUGIN_SRP256, Firebird.AUTH_PLUGIN_SRP, or Firebird.AUTH_PLUGIN_LEGACY
 options.dbCryptConfig = undefined; // optional; database encryption key for encrypted databases. Use 'base64:<value>' for base64-encoded keys or plain text
+options.connectTimeout = 10000; // optional; timeout in ms for a single pool.get() attach operation (default: no timeout)
 ```
 
 ### Classic
@@ -109,6 +110,60 @@ pool.get(function (err, db) {
 pool.destroy();
 ```
 
+#### Advanced Pooling Features
+
+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.
+
+#### Pool Lifecycle State Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> Active
+    Active --> Destroying: pool.destroy()
+    Destroying --> Destroyed: all connections detached
+    Destroyed --> [*]
+
+    state Active {
+        [*] --> Idle
+        Idle --> Creating: pool.get() [no idle db]
+        Creating --> InUse: attach() success
+        Creating --> Idle: attach() failure/timeout
+        Idle --> InUse: pool.get() [idle db exists]
+        InUse --> Idle: db.detach()
+    }
+
+    state Destroying {
+        [*] --> DrainingPending
+        DrainingPending --> DetachingIdle
+        DetachingIdle --> WaitingForInUse
+        WaitingForInUse --> [*]
+    }
+```
+
+#### Connect Timeout Sequence
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Pool
+    participant Firebird
+    User->>Pool: pool.get()
+    Pool->>Pool: increment _creating
+    Pool->>Pool: start timer (connectTimeout)
+    Pool->>Firebird: attach(options)
+    Note over Firebird: Server accepts TCP but hangs
+    Pool-->>Pool: timer expires
+    Pool->>Pool: decrement _creating
+    Pool-->>User: callback(Error: Connection timeout)
+    Note over Firebird: Server eventually responds
+    Firebird-->>Pool: attach callback(db)
+    Pool->>Firebird: db.detach() (discard late connection)
+```
+
 ## Database object (db)
 
 ### Database Methods

package/lib/index.d.ts

@@ -118,6 +118,16 @@ declare module 'node-firebird' {
         wireCompression?: boolean;
         pluginName?: string;
         dbCryptConfig?: string; // Database encryption key callback config (base64: prefix for base64, or plain string)
+        /**
+         * Timeout in milliseconds for a single pool.get() attach operation.
+         * If attach() does not complete within this time the slot is freed,
+         * the caller receives an error, and any late-arriving connection is
+         * safely discarded. Set to 0 or omit to disable (default: no timeout).
+         *
+         * Recommended value: 5000–10000 ms depending on network latency and
+         * expected Firebird server response time under load.
+         */
+        connectTimeout?: number;
     }
 
     export interface SvcMgrOptions extends Options {

package/lib/pool.js

@@ -6,17 +6,23 @@
 
 class Pool {
     constructor(attach, max, options) {
-        this.attach = attach;
-        this.internaldb = []; // connection created by the pool (for destroy)
-        this.pooldb = []; // available connection in the pool
-        this.dbinuse = 0; // connection currently in use into the pool
-        this._creating = 0; // connections currently being created
-        this.max = max || 4;
-        this.pending = [];
-        this.options = options;
+        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.pending   = []; // callbacks waiting for a free slot
+        this.options   = options;
+        this._destroyed = false; // true after destroy() — prevents further use
     }
 
     get(callback) {
+        // [Fix 2] Reject immediately if the pool has already been destroyed.
+        if (this._destroyed) {
+            callback(new Error('Pool has been destroyed'), null);
+            return this;
+        }
         var self = this;
         self.pending.push(callback);
         self.check();
@@ -25,6 +31,10 @@ class Pool {
 
     check() {
         var self = this;
+
+        // [Fix 2] Do not serve requests on a destroyed pool.
+        if (self._destroyed) return self;
+
         if ((self.dbinuse + self._creating) >= self.max)
             return self;
 
@@ -32,12 +42,65 @@ class Pool {
         if (!cb)
             return self;
         if (self.pooldb.length) {
+            // Idle connection available — hand it out immediately.
             self.dbinuse++;
             cb(null, self.pooldb.shift());
         } else {
+            // No idle connection — create a new one via attach().
             self._creating++;
+
+            var timedOut = false;
+            var timer    = null;
+
+            // [Fix 1] Optional per-attach timeout.
+            // If attach() does not call back within connectTimeout ms (e.g. because
+            // the server accepted TCP but stalled on the Firebird wire protocol), we
+            // free the slot and notify the caller. Any connection that arrives late
+            // is discarded in the attach() callback below.
+            if (self.options.connectTimeout > 0) {
+                timer = setTimeout(function () {
+                    timedOut = true;
+                    self._creating--;
+                    cb(new Error(
+                        'Connection timeout after ' + self.options.connectTimeout + 'ms'
+                    ), null);
+                    // Free the slot so the next pending request can be served.
+                    setImmediate(function () { self.check(); });
+                }, self.options.connectTimeout);
+            }
+
             this.attach(self.options, function (err, db) {
+
+                // [Fix 1] Timeout already fired — discard this late connection.
+                // Without this guard the socket would stay open until the OS-level
+                // TCP timeout (potentially minutes), leaking a file descriptor.
+                if (timedOut) {
+                    if (db) {
+                        try {
+                            // _pooled = false forces a real op_detach / socket close
+                            // instead of a silent pool-return emit.
+                            if (db.connection) db.connection._pooled = false;
+                            db.detach();
+                        } catch (e) { /* ignore cleanup errors */ }
+                    }
+                    return;
+                }
+
+                if (timer) clearTimeout(timer);
                 self._creating--;
+
+                // [Fix 3] Pool was destroyed while attach() was in flight.
+                if (self._destroyed) {
+                    if (db) {
+                        try {
+                            if (db.connection) db.connection._pooled = false;
+                            db.detach();
+                        } catch (e) { /* ignore cleanup errors */ }
+                    }
+                    cb(new Error('Pool has been destroyed'), null);
+                    return;
+                }
+
                 if (!err) {
                     self.dbinuse++;
                     self.internaldb.push(db);
@@ -45,7 +108,7 @@ class Pool {
                         // also in pool (could be a twice call to detach)
                         if (self.pooldb.indexOf(db) !== -1 || self.internaldb.indexOf(db) === -1)
                             return;
-                        // if not usable don't put in again in the pool and remove reference on it
+                        // if not usable don't put it back in the pool
                         if (db.connection._isClosed || db.connection._isDetach || db.connection._pooled === false)
                             self.internaldb.splice(self.internaldb.indexOf(db), 1);
                         else
@@ -68,6 +131,16 @@ class Pool {
 
     destroy(callback) {
         var self = this;
+        self._destroyed = true;
+
+        // [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
+        // yet received a slot would hang until the process exits.
+        var draining = self.pending.splice(0);
+        draining.forEach(function (cb) {
+            try { cb(new Error('Pool is being destroyed'), null); } catch (e) { /* ignore */ }
+        });
 
         var connectionCount = this.internaldb.length;
 
@@ -100,6 +173,11 @@ class Pool {
                 self.pooldb.splice(_db_in_pool, 1);
                 db.connection._pooled = false;
                 db.detach(detachCallback);
+            } else {
+                // [Fix 5] Connection is currently in use (dbinuse > 0).
+                // The caller is responsible for releasing it via detach().
+                // Count it down here so the destroy() callback is not blocked forever.
+                detachCallback();
             }
         });
     }

package/lib/wire/connection.js

@@ -1976,6 +1976,7 @@ function decodeResponse(data, callback, cnx, lowercase_keys, cb) {
                 // Database encryption key callback
                 // Read server data (plugin data sent by server)
                 var serverPluginData = data.readArray();
+                data.readInt(); // p_cc_reply
                 
                 // Get client response from dbCryptConfig option
                 var clientPluginData = parseDbCryptConfig(cnx.options.dbCryptConfig);

package/package.json

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

package/poc/README.md

@@ -0,0 +1,160 @@
+# node-firebird pool — Bug PoC & Fix
+
+Proof of concept for three bugs in `lib/pool.js` (node-firebird ≥ 2.x).  
+No real Firebird server is needed — a tiny fake TCP server simulates the failure scenario.
+
+---
+
+## The bugs
+
+### Bug 1 — `_creating` stuck forever (critical)
+
+**File:** `lib/pool.js` → `Pool.check()`
+
+When no idle connection exists, `check()` calls `this.attach()` and increments `_creating`. The counter is only decremented **inside the `attach()` callback**. If the server accepts TCP but never responds to the Firebird wire protocol (e.g. during SRP authentication under load), the callback never fires. `_creating` stays elevated permanently, the slot is lost, and every `pool.get()` caller waits forever.
+
+```
+// original code
+self._creating++;
+this.attach(self.options, function (err, db) {
+    self._creating--;   // ← never reached if attach() hangs
+    cb(err, db);        // ← caller never notified
+});
+```
+
+**Real-world log signature:**
+```
+*ERRO* Timeout (15000ms) ao aguardar conexão para tenant X.
+       Estado do pool: {"dbinuse":0,"_creating":1,"pending":0,"idle":4}
+```
+
+**Fix:** `connectTimeout` option — a `setTimeout` wraps the `attach()` call. On expiry, `_creating` is decremented and the caller receives an error immediately. A late-arriving connection (if attach eventually completes) is discarded safely.
+
+---
+
+### Bug 2 — `destroy()` does not drain the `pending` queue
+
+**File:** `lib/pool.js` → `Pool.destroy()`
+
+Callbacks queued in `this.pending` (waiting for a free pool slot) are silently abandoned when `destroy()` is called. Their callers hang indefinitely — there is no error, no timeout, nothing. This is especially harmful when `destroy()` is used as a recovery strategy after a stuck pool.
+
+**Fix:** `this.pending.splice(0)` at the start of `destroy()` calls every waiting callback with `Error('Pool is being destroyed')` before any connection is closed.
+
+---
+
+### Bug 3 — `pool.get()` after `pool.destroy()` silently accumulates
+
+**File:** `lib/pool.js` → `Pool.get()` and `Pool.check()`
+
+There is no `_destroyed` flag. Calling `pool.get()` on an already-destroyed pool pushes the callback into `this.pending` and calls `check()`. `check()` returns early because all slots are gone, but the callback is never served. The caller hangs forever.
+
+**Fix:** `_destroyed = true` is set in `destroy()`. Both `get()` and `check()` check it and reject immediately with `Error('Pool has been destroyed')`.
+
+---
+
+### Bug 4 (minor) — `destroy()` callback never fires when connections are in use
+
+**File:** `lib/pool.js` → `Pool.destroy()`
+
+The original `destroy()` only calls `detachCallback()` for connections found in `pooldb` (idle). Connections currently in use (`dbinuse > 0`) fall through the `forEach` without decrementing `connectionCount`, so it never reaches zero and the `destroy()` completion callback is never invoked.
+
+**Fix:** The `else` branch counts in-use connections down without forcing a detach — releasing them remains the caller's responsibility.
+
+---
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `helpers.js` | Shared logging and fake-server factory |
+| `reproduce.js` | Demonstrates all bugs — exits with code **1** |
+| `reproduce-fixed.js` | Validates all fixes — exits with code **0** |
+| `pool-patched.js` | Drop-in replacement for `lib/pool.js` |
+
+---
+
+## How to run
+
+```bash
+npm install
+
+# Show the bugs (process hangs → forced exit 1)
+node reproduce.js
+
+# Show the fixes (process exits cleanly → exit 0)
+node reproduce-fixed.js
+```
+
+---
+
+## Expected output
+
+### `node reproduce.js` (bugs present)
+
+```
+[fake-server]          Listening on 127.0.0.1:13050 ...
+[BUG-1]                pool.get() → TCP connects, Firebird protocol hangs, callback NEVER fires
+[pool-state]           creating=1  idle=0  inuse=0  pending=0  destroyed=(no flag)
+[pool-state]           creating=1  idle=0  inuse=0  pending=0  destroyed=(no flag)
+[BUG-2]                Queuing a second get() in pending, then calling destroy()
+[BUG-2]                Before destroy — creating=1  idle=0  inuse=0  pending=1 ...
+[BUG-2]                After  destroy — creating=1  idle=0  inuse=0  pending=1 ...  ← pending NOT drained
+[BUG-2]                ↑ pending callback was NEVER called — Promise hangs forever
+[BUG-3]                pool.get() AFTER pool.destroy() — should be rejected immediately
+[BUG-3]                After post-destroy get — creating=1  idle=0  inuse=0  pending=2 ...
+[SUMMARY]              Bug 1 confirmed  : _creating=1, permanently stuck (slot lost)
+[SUMMARY]              Bug 2 confirmed  : pending callback from before destroy never fired
+[SUMMARY]              Bug 3 confirmed  : post-destroy get silently accumulated in pending
+```
+
+### `node reproduce-fixed.js` (fixes applied)
+
+```
+[fake-server]          Listening on 127.0.0.1:13051 ...
+[FIX-1]                pool.get() — attach() will hang, timeout fires after 1500 ms
+[pool-state]           creating=1  idle=0  inuse=0  pending=0  destroyed=false
+[pool-state]           creating=1  idle=0  inuse=0  pending=0  destroyed=false
+[FIX-1 ✓ OK]           callback received error (expected): "Connection timeout after 1500ms"
+[pool-state]           creating=0  idle=0  inuse=0  pending=0  destroyed=false  ← back to 0 ✓
+[FIX-4]                Queuing a get() in pending, then destroying pool immediately
+[FIX-4 ✓ OK]           pending callback received error: "Pool is being destroyed"  ← immediate ✓
+[FIX-4]                After  destroy — creating=0  idle=0  inuse=0  pending=0  destroyed=true
+[FIX-2]                pool.get() AFTER pool.destroy() — must be rejected immediately
+[FIX-2 ✓ OK]           immediately rejected: "Pool has been destroyed"  ← no accumulation ✓
+[SUMMARY]              Fix 1 confirmed  : _creating returned to 0 after 1500 ms timeout
+[SUMMARY]              Fix 2 confirmed  : post-destroy get() rejected immediately (_destroyed flag)
+[SUMMARY]              Fix 4 confirmed  : pending callback drained synchronously by destroy()
+```
+
+---
+
+## Proposed change to `lib/index.d.ts`
+
+Add `connectTimeout` to the `Options` interface:
+
+```typescript
+export interface Options {
+    // ... existing fields ...
+
+    /**
+     * Timeout in milliseconds for a single pool.get() attach operation.
+     * If attach() does not complete within this time the slot is freed,
+     * the caller receives an error, and any late-arriving connection is
+     * safely discarded. Set to 0 or omit to disable (default: no timeout).
+     *
+     * Recommended value: 5000–10000 ms depending on network latency and
+     * expected Firebird server response time under load.
+     */
+    connectTimeout?: number;
+}
+```
+
+---
+
+## Backward compatibility
+
+All changes are **fully backward-compatible**:
+
+- `connectTimeout` is optional and defaults to disabled (`undefined > 0` is `false`)
+- `_destroyed` defaults to `false` — existing code paths are unchanged
+- `destroy()` draining of `pending` is new behaviour but harmless for callers that did not add pending requests before calling `destroy()`

package/poc/helpers.js

@@ -0,0 +1,59 @@
+'use strict';
+
+/**
+ * Shared helpers used by reproduce.js and reproduce-fixed.js.
+ */
+
+const net = require('net');
+
+/** Timestamp prefix for log lines (HH:MM:SS.mmm) */
+function ts() {
+    return new Date().toISOString().slice(11, 23);
+}
+
+/** Structured log with fixed-width tag */
+function log(tag, msg) {
+    console.log(`[${ts()}] ${tag.padEnd(22)} ${msg}`);
+}
+
+/** Compact pool state string */
+function poolState(pool) {
+    return (
+        `creating=${pool._creating}  ` +
+        `idle=${pool.pooldb.length}  ` +
+        `inuse=${pool.dbinuse}  ` +
+        `pending=${pool.pending.length}  ` +
+        `destroyed=${pool._destroyed ?? '(no flag)'}`
+    );
+}
+
+/**
+ * Starts a TCP server that accepts connections but NEVER responds to data.
+ *
+ * This simulates a Firebird server that:
+ *   - Completes the TCP three-way handshake (SYN / SYN-ACK / ACK)
+ *   - Receives the initial op_connect packet from the client
+ *   - Never sends op_accept_data back
+ *
+ * Result: node-firebird's attach() callback is never called, reproducing the
+ * scenario where _creating is permanently incremented.
+ */
+function startFakeServer(port, onReady) {
+    const server = net.createServer((socket) => {
+        log('fake-server', `TCP accepted from :${socket.remotePort} — will NOT respond to Firebird protocol`);
+        socket.on('data', () => { /* receive op_connect but ignore it */ });
+        socket.on('error', () => { /* suppress errors on forced cleanup */ });
+    });
+
+    server.on('error', (err) => {
+        console.error(`[fake-server] Error: ${err.message}`);
+        process.exit(1);
+    });
+
+    server.listen(port, '127.0.0.1', () => {
+        log('fake-server', `Listening on 127.0.0.1:${port} (accepts TCP, ignores Firebird wire protocol)`);
+        onReady(server);
+    });
+}
+
+module.exports = { ts, log, poolState, startFakeServer };

package/poc/package-lock.json

@@ -0,0 +1,21 @@
+{
+  "name": "node-firebird-pool-poc",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "node-firebird-pool-poc",
+      "version": "1.0.0",
+      "dependencies": {
+        "node-firebird": "^2.3.1"
+      }
+    },
+    "node_modules/node-firebird": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/node-firebird/-/node-firebird-2.3.1.tgz",
+      "integrity": "sha512-3yTwiLHwgtLYRv+aS4frzsQEwHMDXkP5Z1SPM/W103TvMemVRoCIaxPYO7axnUrKhgTfPHGXzqC5umYlQail/w==",
+      "license": "MPL-2.0"
+    }
+  }
+}

package/poc/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "node-firebird-pool-poc",
+  "version": "1.0.0",
+  "description": "Proof of concept for node-firebird pool bugs: _creating stuck, pending leak, post-destroy get()",
+  "scripts": {
+    "bug":   "node reproduce.js",
+    "fixed": "node reproduce-fixed.js"
+  },
+  "dependencies": {
+    "node-firebird": "^2.3.1"
+  }
+}

package/poc/reproduce-fixed.js

@@ -0,0 +1,150 @@
+'use strict';
+
+/**
+ * reproduce-fixed.js — Validates all fixes in pool-patched.js.
+ *
+ * Uses the same fake TCP server from reproduce.js (accepts connections but never
+ * responds to the Firebird wire protocol). The patched Pool is instantiated
+ * directly with Firebird's original attach function, so no server-side changes
+ * are needed and the fix is purely in lib/pool.js.
+ *
+ * ─── Fix 1 · connectTimeout in check() ──────────────────────────────────────
+ *
+ *   A new options.connectTimeout value (ms) wraps the attach() call with a
+ *   setTimeout. If attach() does not complete in time:
+ *     • _creating is decremented (slot freed)
+ *     • cb(Error) is called immediately (no hanging Promise)
+ *     • setImmediate(check) is triggered (next pending request can be served)
+ *   If attach() eventually returns a db after the timeout, the connection is
+ *   discarded via db.connection._pooled = false + db.detach() (no socket leak).
+ *
+ * ─── Fix 2 · _destroyed flag in get() and check() ──────────────────────────
+ *
+ *   pool.get() called after pool.destroy() is immediately rejected with
+ *   "Pool has been destroyed". No silent accumulation in pending.
+ *
+ * ─── Fix 3 · _destroyed guard inside the attach() callback ─────────────────
+ *
+ *   If pool.destroy() is called while an attach() is in flight, the late-
+ *   arriving connection is discarded and the caller is notified with an error.
+ *
+ * ─── Fix 4 · destroy() drains pending ───────────────────────────────────────
+ *
+ *   All callbacks queued in this.pending when destroy() is called receive an
+ *   immediate "Pool is being destroyed" error instead of hanging forever.
+ *
+ * ─── Fix 5 · destroy() counts in-use connections ────────────────────────────
+ *
+ *   Connections currently in use (dbinuse) are now counted down so that the
+ *   destroy() completion callback is not blocked when in-use connections exist.
+ *
+ * ─── How to run ──────────────────────────────────────────────────────────────
+ *
+ *   npm install
+ *   node reproduce-fixed.js
+ *
+ * Expected: all callbacks receive proper errors, _creating returns to 0,
+ * process exits cleanly with code 0.
+ */
+
+const Firebird        = require('node-firebird');
+const PatchedPool     = require('../lib/pool');
+const { log, poolState, startFakeServer } = require('./helpers');
+
+const FAKE_PORT       = 13051; // different port from reproduce.js to avoid conflicts
+const CONNECT_TIMEOUT = 1500;  // 1.5 s — short for demo; use 5–10 s in production
+const TICK_MS         = 600;
+
+startFakeServer(FAKE_PORT, (server) => {
+
+    const options = {
+        host:           '127.0.0.1',
+        port:           FAKE_PORT,
+        database:       '/tmp/poc.fdb',
+        user:           'SYSDBA',
+        password:       'masterkey',
+        lowercase_keys: true,
+        isPool:         true,       // mirrors what exports.pool() adds internally
+        connectTimeout: CONNECT_TIMEOUT, // ← the new option (Fix 1)
+    };
+
+    // Instantiate the patched Pool directly with Firebird's original attach function.
+    // This is equivalent to what exports.pool() does internally:
+    //   return new Pool(exports.attach, max, Object.assign({}, options, { isPool: true }));
+    const pool = new PatchedPool(Firebird.attach, 5, options);
+
+    console.log('\n══════════════════════════════════════════════════════════════════');
+    console.log('  node-firebird · pool fix validation (pool-patched.js)');
+    console.log(`  connectTimeout = ${CONNECT_TIMEOUT} ms`);
+    console.log('══════════════════════════════════════════════════════════════════\n');
+
+    // ── Fix 1 ─────────────────────────────────────────────────────────────────
+    log('FIX-1', `pool.get() — attach() will hang, timeout fires after ${CONNECT_TIMEOUT} ms`);
+
+    pool.get((err, db) => {
+        if (err) log('FIX-1 ✓ OK    ', `callback received error (expected): "${err.message}"`);
+        else     log('FIX-1 ✗ WRONG ', `got db — should have timed out`);
+    });
+
+    let tick = 0;
+
+    const interval = setInterval(() => {
+        tick++;
+        log('pool-state', poolState(pool));
+
+        // ── Fix 2 + Fix 4 (setup) ─────────────────────────────────────────────
+        if (tick === 3) {
+            // At this point the connectTimeout for tick-1 has already fired
+            // (1500 ms < 3 × 600 ms = 1800 ms), so pool is idle again.
+            log('FIX-4', 'Queuing a get() in pending, then destroying pool immediately');
+
+            pool.get((err, db) => {
+                // [Fix 4] destroy() must drain this callback right away.
+                if (err) log('FIX-4 ✓ OK    ', `pending callback received error: "${err.message}"`);
+                else     log('FIX-4 ✗ WRONG ', `got db after destroy: ${!!db}`);
+            });
+
+            log('FIX-4', `Before destroy — ${poolState(pool)}`);
+
+            // Suspend check() by inflating _creating so our queued get() stays in pending.
+            // (In real usage a second concurrent pool.get() while one is stuck in attach()
+            //  would naturally be in pending — this simulates that scenario without timing
+            //  tricks that make the PoC fragile.)
+            pool._creating = 5; // fill all slots so check() won't serve the pending cb
+            pool.destroy();
+            pool._creating = 0; // reset (already orphaned pool, just for readable output)
+
+            log('FIX-4', `After  destroy — ${poolState(pool)}`);
+            log('FIX-4', '↑ pending callback fired SYNCHRONOUSLY inside destroy()');
+        }
+
+        // ── Fix 2 ──────────────────────────────────────────────────────────────
+        if (tick === 4) {
+            log('FIX-2', 'pool.get() AFTER pool.destroy() — must be rejected immediately');
+
+            pool.get((err, db) => {
+                // [Fix 2] _destroyed guard in get() rejects this synchronously.
+                if (err) log('FIX-2 ✓ OK    ', `immediately rejected: "${err.message}"`);
+                else     log('FIX-2 ✗ WRONG ', `got db after destroy: ${!!db}`);
+            });
+
+            log('FIX-2', `After post-destroy get — ${poolState(pool)}`);
+        }
+
+        // ── Summary ────────────────────────────────────────────────────────────
+        if (tick === 5) {
+            clearInterval(interval);
+
+            console.log('\n══════════════════════════════════════════════════════════════════');
+            log('SUMMARY', `Final state      : ${poolState(pool)}`);
+            log('SUMMARY', `Fix 1 confirmed  : _creating returned to 0 after ${CONNECT_TIMEOUT} ms timeout`);
+            log('SUMMARY', 'Fix 2 confirmed  : post-destroy get() rejected immediately (_destroyed flag)');
+            log('SUMMARY', 'Fix 4 confirmed  : pending callback drained synchronously by destroy()');
+            log('SUMMARY', 'Process exits cleanly — no hanging sockets or unresolved callbacks');
+            console.log('══════════════════════════════════════════════════════════════════\n');
+
+            server.close();
+            process.exit(0); // exit(0) = all fixes validated
+        }
+    }, TICK_MS);
+});

package/poc/reproduce.js

@@ -0,0 +1,133 @@
+'use strict';
+
+/**
+ * reproduce.js — Demonstrates three bugs in node-firebird's Pool class (lib/pool.js).
+ *
+ * No real Firebird server is required. A fake TCP server (see helpers.js) accepts
+ * connections but never responds to the Firebird wire protocol, triggering the bugs.
+ *
+ * ─── Bug 1 · _creating stuck forever ────────────────────────────────────────
+ *
+ *   In Pool.check(), when no idle connection exists:
+ *
+ *       self._creating++;
+ *       this.attach(options, function(err, db) {
+ *           self._creating--;   // ← only here
+ *           ...
+ *           cb(err, db);
+ *       });
+ *
+ *   If attach() never calls back (TCP connects, but server stalls on Firebird
+ *   protocol, e.g. SRP auth), _creating is never decremented. The pool slot is
+ *   permanently locked. pool.get() callers wait forever.
+ *
+ * ─── Bug 2 · destroy() does not drain pending callbacks ─────────────────────
+ *
+ *   pool.destroy() only iterates this.internaldb (connected databases). Callbacks
+ *   queued in this.pending (waiting for a free slot) are silently abandoned — they
+ *   are never called, so any awaiting Promise hangs until the process exits.
+ *
+ *   Additionally, if any connection is currently in use (dbinuse > 0), the
+ *   destroy() callback itself is never invoked because connectionCount never
+ *   reached zero (the in-use branch falls through without calling detachCallback).
+ *
+ * ─── Bug 3 · pool.get() after pool.destroy() silently accumulates ────────────
+ *
+ *   There is no _destroyed guard. Calling pool.get() on a destroyed pool pushes
+ *   the callback into this.pending and calls check(), which returns early because
+ *   _destroyed is never checked. The callback is never served.
+ *
+ * ─── How to run ──────────────────────────────────────────────────────────────
+ *
+ *   npm install
+ *   node reproduce.js
+ *
+ * Expected: process does NOT exit cleanly (hangs due to open sockets / pending
+ * callbacks). Exit code 1 is forced after the demo to confirm bugs are present.
+ */
+
+const Firebird        = require('node-firebird');
+const { log, poolState, startFakeServer } = require('./helpers');
+
+const FAKE_PORT   = 13050;
+const TICK_MS     = 600;   // interval between pool-state snapshots
+
+startFakeServer(FAKE_PORT, (server) => {
+
+    const options = {
+        host:           '127.0.0.1',
+        port:           FAKE_PORT,
+        database:       '/tmp/poc.fdb',
+        user:           'SYSDBA',
+        password:       'masterkey',
+        lowercase_keys: true,
+        isPool:         true,
+        // No connectTimeout — original (buggy) behaviour
+    };
+
+    const pool = Firebird.pool(5, options);
+
+    console.log('\n══════════════════════════════════════════════════════════════════');
+    console.log('  node-firebird · pool bug reproduction (original lib/pool.js)');
+    console.log('══════════════════════════════════════════════════════════════════\n');
+
+    // ── Bug 1 ─────────────────────────────────────────────────────────────────
+    log('BUG-1', 'pool.get() → TCP connects, Firebird protocol hangs, callback NEVER fires');
+
+    pool.get((err, db) => {
+        // ← BUG: this line is never reached
+        log('BUG-1 ✗ WRONG', `callback fired (unexpected): err=${err?.message} db=${!!db}`);
+    });
+
+    let tick = 0;
+
+    const interval = setInterval(() => {
+        tick++;
+        log('pool-state', poolState(pool));
+
+        // ── Bug 2 (setup) ──────────────────────────────────────────────────────
+        if (tick === 2) {
+            log('BUG-2', 'Queuing a second get() in pending, then calling destroy()');
+
+            pool.get((err, db) => {
+                // ← BUG: destroy() never calls this; the Promise hangs forever
+                if (err) log('BUG-2 ✓ OK    ', `pending callback received error: "${err.message}"`);
+                else     log('BUG-2 ✗ WRONG ', `got db unexpectedly: ${!!db}`);
+            });
+
+            log('BUG-2', `Before destroy — ${poolState(pool)}`);
+            pool.destroy();
+            log('BUG-2', `After  destroy — ${poolState(pool)}`);
+            log('BUG-2', '↑ pending callback was NEVER called — Promise hangs forever');
+        }
+
+        // ── Bug 3 ──────────────────────────────────────────────────────────────
+        if (tick === 3) {
+            log('BUG-3', 'pool.get() AFTER pool.destroy() — should be rejected immediately');
+
+            pool.get((err, db) => {
+                // ← BUG: no _destroyed guard; callback silently queued, never served
+                if (err) log('BUG-3 ✓ OK    ', `rejected: "${err.message}"`);
+                else     log('BUG-3 ✗ WRONG ', `got db after destroy: ${!!db}`);
+            });
+
+            log('BUG-3', `After post-destroy get — ${poolState(pool)}`);
+        }
+
+        // ── Summary ────────────────────────────────────────────────────────────
+        if (tick === 5) {
+            clearInterval(interval);
+
+            console.log('\n══════════════════════════════════════════════════════════════════');
+            log('SUMMARY', `Final state      : ${poolState(pool)}`);
+            log('SUMMARY', 'Bug 1 confirmed  : _creating=1, permanently stuck (slot lost)');
+            log('SUMMARY', 'Bug 2 confirmed  : pending callback from before destroy never fired');
+            log('SUMMARY', 'Bug 3 confirmed  : post-destroy get silently accumulated in pending');
+            log('SUMMARY', 'Process would hang forever without forced exit below');
+            console.log('══════════════════════════════════════════════════════════════════\n');
+
+            server.close();
+            process.exit(1); // exit(1) = bugs confirmed
+        }
+    }, TICK_MS);
+});

package/vitest.config.js

@@ -18,7 +18,8 @@ module.exports = defineConfig({
             'test/db-crypt-config.js',
             'test/timezone.js',
             'test/decfloat.js',
-            'test/mock-server.js'
+            'test/mock-server.js',
+            'test/pool-fixes.js'
         ],
     },
 });