node-firebird 2.16.2 → 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';
@@ -1455,6 +1456,11 @@ If the server reports `0.0.0.0` or `::` as the aux address — usual when it lis
 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:

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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "node-firebird",
-    "version": "2.16.2",
+    "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) {