node-firebird 2.16.1 → 2.17.0

package/README.md

@@ -181,6 +181,7 @@ same way `PGUSER`/`PGPASSWORD` work with pg.
 var options = {};
 
 options.host = '127.0.0.1';
+options.eventHost = undefined; // optional; override the server-advertised host for the auxiliary event connection
 options.port = 3050;
 options.database = 'database.fdb';
 options.user = 'SYSDBA';
@@ -1434,6 +1435,54 @@ Firebird.attach(options, function (err, db) {
 });
 ```
 
+#### The auxiliary connection, and when `attachEvent` fails
+
+Events do **not** travel over the connection you attached with. `db.attachEvent()` sends
+`op_connect_request`; the server opens a fresh listening socket, replies with its address and
+port, and the driver dials that address as a **second, independent TCP connection**. Only once
+that aux socket is up is the `FbEventManager` created and handed to your callback.
+
+The aux port is chosen by the server and is *not* the port you connected to, so it has to be
+reachable from the client in its own right. Two deployments commonly get this wrong:
+
+- **Containers.** A Firebird container that publishes only `3050` answers `op_connect_request`
+  with an aux port nothing outside the container can reach. Pin it with `RemoteAuxPort` in
+  `firebird.conf` and publish that port too, or run the client on the same network.
+- **Firewalls.** A rule that DROPs the aux port (rather than REJECTing it) leaves the dial
+  waiting out the operating system's connect timeout — around two minutes on Linux — before
+  the failure is reported.
+
+If the server reports `0.0.0.0` or `::` as the aux address — usual when it listens on all
+interfaces — the driver dials the host from your connection options instead, so that host must
+be the one reaching the aux port.
+
+Behind NAT, a tunnel, container networking, or a load balancer, the advertised
+address may not be reachable from the client. Set `options.eventHost` to override
+only the host used for the auxiliary event connection. The auxiliary port is
+still selected by Firebird; use `RemoteAuxPort` when it also needs to be fixed.
+
+Since **2.16.2** a failed dial is reported to the attachment callback as an `Error`, exactly
+once, carrying Node's socket `code`. Earlier versions recorded it internally and never called
+back, so `attachEvent()` and `attachEventAsync()` hung indefinitely:
+
+```js
+db.attachEvent(function (err, evtmgr) {
+  if (err) {
+    // ECONNREFUSED  → aux port not reachable (unpublished container port, nothing listening)
+    // ETIMEDOUT     → aux port filtered by a firewall
+    // EHOSTUNREACH  → wrong host: the address the server reported, or your connection host
+    //                 when the server reported 0.0.0.0/::
+    console.error('event attachment failed:', err.code || err.message);
+    return;
+  }
+  // ...
+});
+```
+
+Errors on the aux socket *after* it connects are not delivered to this callback. Poll
+`evtmgr.getState().isEventConnectionOpen` if you need to detect an aux connection that dies
+mid-subscription.
+
 ### Escaping Query values
 
 ```js
@@ -2429,6 +2478,21 @@ If the failure is intermittent — the same code with the same credentials succe
 
 If the failure is consistent, the credentials really don't match an account for the authentication plugin in use: check `AuthServer`/`UserManager` in `firebird.conf` and remember that SRP and Legacy user managers keep separate password stores — a user created under one plugin does not automatically exist for the other.
 
+#### `db.attachEvent()` never calls back, or hangs, in Docker or behind a firewall
+
+Upgrade to **2.16.2 or later**: before that release the driver recorded a failure to open the
+auxiliary event connection internally and never invoked the attachment callback, so
+`attachEvent()` silently stalled and `attachEventAsync()` returned a promise that never settled.
+From 2.16.2 the failure reaches your callback as an `Error` carrying Node's socket `code`.
+
+The failure itself is a reachability problem, not a driver bug, and upgrading only makes it
+visible. Firebird events use a **second TCP connection** to a port the *server* chooses, which
+is not the port you connected to, so publishing `3050` alone is not enough: pin `RemoteAuxPort`
+in `firebird.conf` and publish that port too. See
+[§ The auxiliary connection](#the-auxiliary-connection-and-when-attachevent-fails) for the full
+picture, including the `0.0.0.0`/`::` case and why a DROP firewall rule delays the error by
+roughly two minutes.
+
 ## Contributing
 
 Contributions are welcome — code, documentation, and bug reports alike.

package/lib/types.d.ts

@@ -352,6 +352,8 @@ export interface Statement {
 export type SupportedCharacterSet = 'NONE' | 'CP943C' | 'DOS737' | 'DOS775' | 'DOS858' | 'DOS862' | 'DOS864' | 'DOS866' | 'DOS869' | 'GB18030' | 'GBK' | 'ISO8859_1' | 'ISO8859_2' | 'ISO8859_3' | 'ISO8859_4' | 'ISO8859_5' | 'ISO8859_6' | 'ISO8859_7' | 'ISO8859_8' | 'ISO8859_9' | 'ISO8859_13' | 'KOI8R' | 'KOI8U' | 'TIS620' | 'UTF8' | 'WIN1251' | 'WIN1252' | 'WIN1253' | 'WIN1254' | 'WIN1255' | 'WIN1256' | 'WIN1257' | 'WIN1258' | 'WIN_1258';
 export interface Options {
     host?: string;
+    /** Override the server-advertised auxiliary event host (for NAT, tunnels and load balancers). */
+    eventHost?: string;
     port?: number;
     database?: string;
     user?: string;

package/lib/utils.d.ts

@@ -1,4 +1,9 @@
 import type { FbStatusItem } from './callback';
+/** Resolve the address used for Firebird's auxiliary event connection. */
+export declare function resolveEventHost(options: {
+    host?: string;
+    eventHost?: string;
+}, advertisedHost: string): string;
 /**
  * Parse date from string
  */

package/lib/utils.js

@@ -4,10 +4,19 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.escape = exports.lookupMessages = exports.batchResultToError = exports.parseDate = void 0;
+exports.resolveEventHost = resolveEventHost;
 exports.noop = noop;
 const firebird_msg_json_1 = __importDefault(require("./firebird.msg.json"));
 const const_1 = __importDefault(require("./wire/const"));
 const MessagesError = firebird_msg_json_1.default;
+/** Resolve the address used for Firebird's auxiliary event connection. */
+function resolveEventHost(options, advertisedHost) {
+    if (options.eventHost)
+        return options.eventHost;
+    if (advertisedHost === '0.0.0.0' || advertisedHost === '::')
+        return options.host || const_1.default.DEFAULT_HOST;
+    return advertisedHost;
+}
 /**
  * Parse date from string
  */

package/lib/wire/database.js

@@ -404,9 +404,7 @@ class Database extends events_1.default.EventEmitter {
             if (process.env.FIREBIRD_DEBUG) {
                 console.log('[fb-debug] Database.attachEvent: auxConnection ok, connecting to aux port %s:%d', socket_info.host, socket_info.port);
             }
-            const host = (socket_info.host === '0.0.0.0' || socket_info.host === '::')
-                ? self.connection.options.host
-                : socket_info.host;
+            const host = (0, utils_1.resolveEventHost)(self.connection.options, socket_info.host);
             const eventConnection = new eventConnection_1.default(host, socket_info.port, function (err) {
                 if (err) {
                     if (process.env.FIREBIRD_DEBUG) {

package/lib/wire/eventConnection.d.ts

@@ -9,8 +9,9 @@ declare class EventConnection {
     _xdr?: XdrReader;
     error: any;
     eventcallback: ((err: any, ret?: any) => void) | null;
-    constructor(host: string, port: number, callback: (() => void) | undefined, db: any);
-    _bind_events(host: string, port: number, callback?: () => void): void;
+    _connectSettled: boolean;
+    constructor(host: string, port: number, callback: ((err?: Error) => void) | undefined, db: any);
+    _bind_events(host: string, port: number, callback?: (err?: Error) => void): void;
     throwClosed(callback?: (err: any) => void): this;
 }
 export = EventConnection;

package/lib/wire/eventConnection.js

@@ -13,6 +13,7 @@ class EventConnection {
         this.emgr = null;
         this._isClosed = false;
         this._isOpened = false;
+        this._connectSettled = false;
         this._socket = net_1.default.createConnection(port, host);
         this._bind_events(host, port, callback);
         this.error = null;
@@ -20,17 +21,31 @@ class EventConnection {
     }
     _bind_events(host, port, callback) {
         var self = this;
+        function finishConnect(err) {
+            if (self._connectSettled)
+                return;
+            self._connectSettled = true;
+            if (callback)
+                callback(err);
+        }
         self._socket.on('close', function () {
             self._isClosed = true;
+            if (!self._isOpened) {
+                finishConnect(self.error || new Error(`Event connection to ${host}:${port} closed before connecting.`));
+            }
         });
         self._socket.on('error', function (e) {
             self.error = e;
+            if (!self._isOpened) {
+                if (!self._socket.destroyed)
+                    self._socket.destroy();
+                finishConnect(e);
+            }
         });
         self._socket.on('connect', function () {
             self._isClosed = false;
             self._isOpened = true;
-            if (callback)
-                callback();
+            finishConnect();
         });
         self._socket.on('data', function (data) {
             var xdr, buf;

package/package.json

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

package/src/types.ts

@@ -413,6 +413,8 @@ export type SupportedCharacterSet = |
 
 export interface Options {
     host?: string;
+    /** Override the server-advertised auxiliary event host (for NAT, tunnels and load balancers). */
+    eventHost?: string;
     port?: number;
     database?: string;
     user?: string;

package/src/utils.ts

@@ -4,6 +4,13 @@ import type { FbStatusItem } from './callback';
 
 const MessagesError = messagesJson as Record<string, string>;
 
+/** Resolve the address used for Firebird's auxiliary event connection. */
+export function resolveEventHost(options: { host?: string; eventHost?: string }, advertisedHost: string): string {
+    if (options.eventHost) return options.eventHost;
+    if (advertisedHost === '0.0.0.0' || advertisedHost === '::') return options.host || Const.DEFAULT_HOST;
+    return advertisedHost;
+}
+
 /**
  * Parse date from string
  */

package/src/wire/database.ts

@@ -1,6 +1,6 @@
 import Events from 'events';
 import { doError, fromCallback, type Callback, type SimpleCallback } from '../callback';
-import { batchResultToError, escape } from '../utils';
+import { batchResultToError, escape, resolveEventHost } from '../utils';
 import Const from './const';
 import { makeSqlTag, type SqlTag } from '../sql-template';
 import { computeColumnKeys, nestCell, resolveKeyTransform, resolveNestTables } from './xsqlvar';
@@ -481,9 +481,7 @@ class Database extends Events.EventEmitter {
                 console.log('[fb-debug] Database.attachEvent: auxConnection ok, connecting to aux port %s:%d', socket_info.host, socket_info.port);
             }
 
-            const host = (socket_info.host === '0.0.0.0' || socket_info.host === '::')
-                ? self.connection.options.host
-                : socket_info.host;
+            const host = resolveEventHost(self.connection.options, socket_info.host);
 
             const eventConnection = new EventConnection(
                 host, socket_info.port, function(err?: any) {

package/src/wire/eventConnection.ts

@@ -13,37 +13,49 @@ class EventConnection {
     _xdr?: XdrReader;
     error: any;
     eventcallback: ((err: any, ret?: any) => void) | null;
+    _connectSettled: boolean;
 
-    constructor(host: string, port: number, callback: (() => void) | undefined, db: any) {
+    constructor(host: string, port: number, callback: ((err?: Error) => void) | undefined, db: any) {
         var self = this;
         this.db = db;
         this.emgr = null;
         this._isClosed = false;
         this._isOpened = false;
+        this._connectSettled = false;
         this._socket = net.createConnection(port, host);
         this._bind_events(host, port, callback);
         this.error = null;
         this.eventcallback = null;
     }
 
-    _bind_events(host: string, port: number, callback?: () => void): void {
+    _bind_events(host: string, port: number, callback?: (err?: Error) => void): void {
         var self = this;
 
-        self._socket.on('close', function () {
+        function finishConnect(err?: Error) {
+            if (self._connectSettled) return;
+            self._connectSettled = true;
+            if (callback) callback(err);
+        }
 
+        self._socket.on('close', function () {
             self._isClosed = true;
+            if (!self._isOpened) {
+                finishConnect(self.error || new Error(`Event connection to ${host}:${port} closed before connecting.`));
+            }
         })
 
         self._socket.on('error', function (e) {
-
             self.error = e;
+            if (!self._isOpened) {
+                if (!self._socket.destroyed) self._socket.destroy();
+                finishConnect(e);
+            }
         })
 
         self._socket.on('connect', function () {
             self._isClosed = false;
             self._isOpened = true;
-            if (callback)
-                callback();
+            finishConnect();
         });
 
         self._socket.on('data', function (data: Buffer) {