node-firebird 2.3.1 → 2.3.3

package/lib/wire/xsqlvar.js

@@ -13,17 +13,79 @@ const
     TimeCoeff = 86400000,
     MsPerMinute = 60000;
 
+/**
+ * Maps Firebird character-set names (upper-case) to the Node.js Buffer
+ * encoding string used by Buffer.toString() / Buffer.from().
+ *
+ * Firebird stores CHAR/VARCHAR data in the on-wire character set of the
+ * column (or the connection character set for NONE/unspecified columns).
+ * We must decode raw bytes with the matching Node.js encoding so that
+ * characters outside ASCII are reproduced correctly.
+ *
+ * Commonly used Firebird charsets not listed here fall back to the
+ * connection-level DEFAULT_ENCODING (typically 'utf8').
+ */
+const FirebirdToNodeEncoding = Object.freeze({
+    UTF8:        'utf8',
+    UNICODE_FSS: 'utf8',
+    WIN1252:     'latin1',
+    ISO8859_1:   'latin1',
+    LATIN1:      'latin1',
+    ASCII:       'ascii',
+    NONE:        'latin1',   // unspecified charset – treat as binary-safe latin1
+});
+
+const FirebirdCharsetWidths = {
+    'UTF8': 4,
+    'UNICODE_FSS': 3,
+    'SJIS': 2,
+    'EUCJ': 2
+};
+
+function getFirebirdCharsetWidth(charset) {
+    if (!charset) return 4;
+    const upper = charset.toUpperCase();
+    return FirebirdCharsetWidths[upper] || 1;
+}
+
+/**
+ * Resolve the Node.js Buffer encoding to use when decoding text from a
+ * Firebird response buffer.
+ *
+ * @param {object|null} options  Connection options object (may be falsy).
+ * @returns {string}             A Node.js-compatible encoding string.
+ */
+function resolveTextEncoding(options) {
+    const encoding = (options && options.encoding)
+        ? options.encoding.toUpperCase()
+        : Const.DEFAULT_ENCODING;
+    return FirebirdToNodeEncoding[encoding] || Const.DEFAULT_ENCODING.toLowerCase();
+}
+
 //------------------------------------------------------
 
 class SQLVarText {
-    decode(data, lowerV13) {
+    decode(data, lowerV13, options) {
         let ret;
+        const textEncoding = resolveTextEncoding(options);
         if (this.subType > 1) {
             // ToDo: with column charset
-            ret = data.readText(this.length, Const.DEFAULT_ENCODING);
+            ret = data.readText(this.length, textEncoding);
+            const encoding = options && options.encoding ? options.encoding : 'UTF8';
+            const width = getFirebirdCharsetWidth(encoding);
+            const charLength = Math.floor(this.length / width);
+            if (ret.length > charLength) {
+                ret = ret.substring(0, charLength);
+            }
         } else if (this.subType === 0) {
             // without charset definition
-            ret = data.readText(this.length, Const.DEFAULT_ENCODING);
+            ret = data.readText(this.length, textEncoding);
+            const encoding = options && options.encoding ? options.encoding : 'UTF8';
+            const width = getFirebirdCharsetWidth(encoding);
+            const charLength = Math.floor(this.length / width);
+            if (ret.length > charLength) {
+                ret = ret.substring(0, charLength);
+            }
         } else {
             ret = data.readBuffer(this.length);
         }
@@ -49,14 +111,15 @@ class SQLVarNull extends SQLVarText {
 //------------------------------------------------------
 
 class SQLVarString {
-    decode(data, lowerV13) {
+    decode(data, lowerV13, options) {
         let ret;
+        const textEncoding = resolveTextEncoding(options);
         if (this.subType > 1) {
             // ToDo: with column charset
-            ret = data.readString(Const.DEFAULT_ENCODING);
+            ret = data.readString(textEncoding);
         } else if (this.subType === 0) {
             // without charset definition
-            ret = data.readString(Const.DEFAULT_ENCODING);
+            ret = data.readString(textEncoding);
         } else {
             ret = data.readBuffer();
         }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "node-firebird",
-    "version": "2.3.1",
+    "version": "2.3.3",
     "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/node_modules/.package-lock.json

@@ -0,0 +1,14 @@
+{
+  "name": "node-firebird-pool-poc",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "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/node_modules/node-firebird/.eslintrc.json

@@ -0,0 +1,12 @@
+{
+    "parserOptions": {
+        "ecmaVersion": 6,
+        "sourceType": "module",
+        "ecmaFeatures": {
+            "jsx": true
+        }
+    },
+    "rules": {
+        "semi": "error"
+    }
+}

package/poc/node_modules/node-firebird/.github/workflows/codeql.yml

@@ -0,0 +1,76 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [ "master" ]
+  schedule:
+    - cron: '26 2 * * 3'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'javascript' ]
+        # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ]
+        # Use only 'java' to analyze code written in Java, Kotlin or both
+        # Use only 'javascript' to analyze code written in JavaScript, TypeScript or both
+        # Learn more about CodeQL language support at https://aka.ms/codeql-docs/language-support
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v3
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v2
+      with:
+        languages: ${{ matrix.language }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+
+        # Details on CodeQL's query packs refer to : https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+        # queries: security-extended,security-and-quality
+
+
+    # Autobuild attempts to build any compiled languages  (C/C++, C#, Go, or Java).
+    # If this step fails, then you should remove it and run the build manually (see below)
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v2
+
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+
+    #   If the Autobuild fails above, remove it and uncomment the following three lines.
+    #   modify them (or add more) to build your code if your project, please refer to the EXAMPLE below for guidance.
+
+    # - run: |
+    #     echo "Run, Build Application using script"
+    #     ./location_of_script_within_repo/buildscript.sh
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v2
+      with:
+        category: "/language:${{matrix.language}}"

package/poc/node_modules/node-firebird/.github/workflows/node.js.yml

@@ -0,0 +1,95 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:        
+        node: [20, 22, 24]
+        firebird: [3, 4, 5]
+
+    steps:
+    - uses: actions/checkout@v6
+      with:
+        fetch-depth: 10
+
+    - name: Setup FirebirdSQL ${{ matrix.firebird }} container
+      run: |
+        # Create data directory
+        sudo mkdir -p /firebird/data
+        sudo chmod 755 /firebird/data
+        
+        # Start Firebird container
+        docker run -d \
+          --name firebird \
+          -e FIREBIRD_ROOT_PASSWORD="masterkey" \
+          -e FIREBIRD_CONF_WireCrypt="Enabled" \
+          -e FIREBIRD_CONF_AuthServer="Legacy_Auth;Srp;Win_Sspi" \
+          -p 3050:3050 \
+          -v /firebird/data:/firebird/data \
+          firebirdsql/firebird:${{ matrix.firebird }}
+        
+        # Wait for Firebird to be ready
+        MAX_RETRIES=30
+        RETRY_INTERVAL=2
+        echo "Waiting for Firebird to start..."
+        FIREBIRD_READY=false
+        for i in $(seq 1 $MAX_RETRIES); do
+          if docker exec firebird /opt/firebird/bin/isql -user SYSDBA -password masterkey -z 2>&1 | grep -q "ISQL Version"; then
+            echo "Firebird is ready!"
+            FIREBIRD_READY=true
+            break
+          fi
+          echo "Waiting... ($i/$MAX_RETRIES)"
+          sleep $RETRY_INTERVAL
+        done
+        
+        if [ "$FIREBIRD_READY" = false ]; then
+          echo "ERROR: Firebird failed to start within the timeout period"
+          docker ps -a
+          docker logs firebird
+          exit 1
+        fi
+        
+        # Verify Firebird is running
+        docker ps -a
+        docker logs firebird
+
+    - name: Use Node.js ${{ matrix.node }}
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ matrix.node }}
+
+
+    - name: Build
+      shell: bash
+      run: |
+        npm ci         
+
+    - name: Test (Linux)      
+      run: |
+        export FIREBIRD_DATA=/firebird/data
+        export FIREBIRD_DEBUG=1
+        npm test
+
+    - name: Show Firebird log on failure
+      if: failure()
+      run: |
+        echo "=========================================="
+        echo "Firebird Server Log (last 100 lines):"
+        echo "=========================================="
+        docker exec firebird tail -n 100 /firebird/log/firebird.log || echo "Could not read firebird.log"
+        echo ""
+        echo "=========================================="
+        echo "Docker container status:"
+        echo "=========================================="
+        docker ps -a
+        echo ""
+        echo "=========================================="
+        echo "Docker container logs:"
+        echo "=========================================="
+        docker logs firebird --tail 50