node-firebird 2.16.2 → 2.17.1

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';
@@ -1403,6 +1404,12 @@ Firebird.attach(options, function (err, db) {
   db.attachEvent(function (err, evtmgr) {
     if (err) throw err;
 
+    // Auxiliary socket/protocol failures after attachment are reported here.
+    // Install this listener before registering events.
+    evtmgr.on('error', function (err) {
+      console.error('event connection failed:', err);
+    });
+
     // 2. Subscribe to one or more named events (names must match POST_EVENT('name') in your
     //    PSQL triggers/procedures). Resolves once op_que_events is acknowledged by the server.
     evtmgr.registerEvent(['MY_EVENT'], function (err) {
@@ -1455,6 +1462,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:
@@ -1473,9 +1485,20 @@ db.attachEvent(function (err, evtmgr) {
 });
 ```
 
-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.
+Errors on the aux socket *after* it connects are delivered through the manager's `error`
+event. Install the listener before calling `registerEvent()`:
+
+```js
+evtmgr.on('error', function (err) {
+  // The manager is now CLOSED. Reattach explicitly if the application wants
+  // to resume event delivery; the driver does not reconnect automatically.
+  console.error('event connection failed:', err);
+});
+```
+
+When no manager error listener is installed, the driver forwards the failure to guarded
+database `error` listeners when present. It never emits an unhandled EventEmitter `error`.
+The primary database attachment remains available for ordinary queries.
 
 ### Escaping Query values
 

package/lib/types.d.ts

@@ -1,4 +1,5 @@
 import type { Readable, Writable } from 'stream';
+import type { EventEmitter } from 'events';
 import type { SqlTag } from './sql-template';
 export type { SqlTag, SqlQuery, SqlIdentifier, CompiledQuery } from './sql-template';
 export type DatabaseCallback = (err: any, db: Database) => void;
@@ -6,6 +7,27 @@ export type TransactionCallback = (err: any, transaction: Transaction) => void;
 export type QueryCallback = (err: any, result: any[]) => void;
 export type SimpleCallback = (err: any) => void;
 export type SequentialCallback = (row: any, index: number, next?: (err?: any) => void) => void | Promise<void>;
+export interface FbEventState {
+    state: 'IDLE' | 'SUBSCRIBED' | 'CLOSED';
+    hasActiveSubscription: boolean;
+    registeredEvents: Record<string, number>;
+    eventId: number;
+    isEventConnectionOpen: boolean;
+    isDatabaseConnectionClosed: boolean;
+}
+export interface FbEventManager extends EventEmitter {
+    readonly eventid: number;
+    readonly events: Record<string, number>;
+    registerEvent(events: string[], callback: SimpleCallback): void;
+    unregisterEvent(events: string[], callback: SimpleCallback): void;
+    close(callback?: SimpleCallback): void;
+    getState(): FbEventState;
+    on(event: 'post_event', listener: (name: string, count: number) => void): this;
+    on(event: 'error', listener: (error: Error) => void): this;
+    once(event: 'post_event', listener: (name: string, count: number) => void): this;
+    once(event: 'error', listener: (error: Error) => void): this;
+}
+export type FbEventManagerCallback = (err: any, manager?: FbEventManager) => void;
 /**
  * Describes a single column in a prepared statement's result set or
  * parameter list.  The properties here are populated by the
@@ -250,7 +272,7 @@ export interface Database {
     batchStream(query: string, options?: BatchStreamOptions): BatchStream;
     drop(callback: SimpleCallback): void;
     escape(value: any): string;
-    attachEvent(callback: any): this;
+    attachEvent(callback: FbEventManagerCallback): this;
     createTablespace(name: string, filePath: string, callback?: QueryCallback): Database;
     alterTablespace(name: string, filePath: string, callback?: QueryCallback): Database;
     dropTablespace(name: string, callback?: QueryCallback): Database;
@@ -271,7 +293,7 @@ export interface Database {
     newStatementAsync(query: string): Promise<Statement>;
     detachAsync(force?: boolean): Promise<void>;
     dropAsync(): Promise<void>;
-    attachEventAsync(): Promise<any>;
+    attachEventAsync(): Promise<FbEventManager>;
     /** Starts a transaction, commits when `work` resolves, rolls back when it rejects. */
     withTransaction<T>(work: (transaction: Transaction) => Promise<T> | T, options?: TransactionOptions | Isolation): Promise<T>;
     /**
@@ -352,6 +374,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

@@ -390,6 +390,13 @@ class Database extends events_1.default.EventEmitter {
     attachEvent(callback) {
         var self = this;
         const eventid = self.eventid++;
+        let completed = false;
+        const complete = function (err, manager) {
+            if (completed)
+                return;
+            completed = true;
+            callback(err, manager);
+        };
         if (process.env.FIREBIRD_DEBUG) {
             console.log('[fb-debug] Database.attachEvent: calling auxConnection, eventid=%d queue=%d', eventid, self.connection._queue.length);
         }
@@ -398,21 +405,19 @@ class Database extends events_1.default.EventEmitter {
                 if (process.env.FIREBIRD_DEBUG) {
                     console.log('[fb-debug] Database.attachEvent: auxConnection error:', err.message);
                 }
-                (0, callback_1.doError)(err, callback);
+                (0, callback_1.doError)(err, complete);
                 return;
             }
             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) {
                         console.log('[fb-debug] Database.attachEvent: EventConnection error:', err.message);
                     }
-                    (0, callback_1.doError)(err, callback);
+                    (0, callback_1.doError)(err, complete);
                     return;
                 }
                 if (process.env.FIREBIRD_DEBUG) {
@@ -420,13 +425,13 @@ class Database extends events_1.default.EventEmitter {
                 }
                 const evt = new fbEventManager_1.default(self, eventConnection, eventid, function (err) {
                     if (err) {
-                        (0, callback_1.doError)(err, callback);
+                        (0, callback_1.doError)(err, complete);
                         return;
                     }
                     if (process.env.FIREBIRD_DEBUG) {
                         console.log('[fb-debug] Database.attachEvent: FbEventManager ready, eventid=%d', evt.eventid);
                     }
-                    callback(err, evt);
+                    complete(err, evt);
                 });
             }, self);
         });

package/lib/wire/eventConnection.d.ts

@@ -10,6 +10,8 @@ declare class EventConnection {
     error: any;
     eventcallback: ((err: any, ret?: any) => void) | null;
     _connectSettled: boolean;
+    _terminalErrorReported: boolean;
+    _intentionalClose: 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;

package/lib/wire/eventConnection.js

@@ -14,6 +14,8 @@ class EventConnection {
         this._isClosed = false;
         this._isOpened = false;
         this._connectSettled = false;
+        this._terminalErrorReported = false;
+        this._intentionalClose = false;
         this._socket = net_1.default.createConnection(port, host);
         this._bind_events(host, port, callback);
         this.error = null;
@@ -28,19 +30,41 @@ class EventConnection {
             if (callback)
                 callback(err);
         }
+        function reportTerminalError(err) {
+            if (self._terminalErrorReported)
+                return;
+            self._terminalErrorReported = true;
+            const wasOpened = self._isOpened;
+            self.error = err;
+            self._isClosed = true;
+            self._isOpened = false;
+            // An error during a caller-initiated shutdown is part of tearing
+            // down the auxiliary socket, not a database error.
+            if (!self._intentionalClose && !wasOpened) {
+                finishConnect(err);
+            }
+            else if (!self._intentionalClose && self.eventcallback) {
+                self.eventcallback(err);
+            }
+            else if (!self._intentionalClose && self.db && self.db.connection &&
+                typeof self.db.connection._emitError === 'function') {
+                self.db.connection._emitError(err);
+            }
+            if (!self._socket.destroyed)
+                self._socket.destroy();
+        }
         self._socket.on('close', function () {
             self._isClosed = true;
             if (!self._isOpened) {
                 finishConnect(self.error || new Error(`Event connection to ${host}:${port} closed before connecting.`));
             }
+            else if (!self._intentionalClose && self.eventcallback && !self._terminalErrorReported) {
+                reportTerminalError(new Error(`Event connection to ${host}:${port} closed unexpectedly.`));
+            }
+            self._isOpened = false;
         });
         self._socket.on('error', function (e) {
-            self.error = e;
-            if (!self._isOpened) {
-                if (!self._socket.destroyed)
-                    self._socket.destroy();
-                finishConnect(e);
-            }
+            reportTerminalError(e);
         });
         self._socket.on('connect', function () {
             self._isClosed = false;
@@ -64,6 +88,7 @@ class EventConnection {
             try {
                 var tmp_event;
                 while (xdr.pos < xdr.buffer.length) {
+                    op_pos = xdr.pos;
                     do {
                         var r = xdr.readInt();
                     } while (r === const_1.default.op_dummy);
@@ -80,7 +105,9 @@ class EventConnection {
                             var eventcount = 0;
                             var pos = 1;
                             while (pos < buf.length) {
-                                var len = buf.readInt8(pos++);
+                                var len = buf.readUInt8(pos++);
+                                if (pos + len + 4 > buf.length)
+                                    throw new RangeError('Incomplete event payload');
                                 eventname = buf.toString(DEFAULT_ENCODING, pos, pos + len);
                                 var prevcount = self.emgr.events[eventname] || 0;
                                 pos += len;
@@ -105,7 +132,7 @@ class EventConnection {
                                 self.eventcallback(null, { eventid: event_id, events: lst_event });
                             break;
                         default:
-                            // Unknown opcode on the event connection – stop processing.
+                            reportTerminalError(new Error('Unexpected event connection opcode: ' + r));
                             return;
                     }
                 }
@@ -117,14 +144,13 @@ class EventConnection {
                     self._xdr = xdr;
                 }
                 else {
-                    throw err;
+                    reportTerminalError(err instanceof Error ? err : new Error(String(err)));
                 }
             }
         });
     }
     throwClosed(callback) {
         var err = new Error('Event Connection is closed.');
-        this.db.emit('error', err);
         if (callback)
             callback(err);
         return this;

package/lib/wire/fbEventManager.d.ts

@@ -6,7 +6,16 @@ declare class FbEventManager extends Events.EventEmitter {
     eventid: number;
     _subscriptionVersion: number;
     _hasActiveSubscription: boolean;
+    _readySettled: boolean;
+    _terminalErrorReported: boolean;
+    _readyCallback: (err: any, ret?: any) => void;
     constructor(db: any, eventconnection: any, eventid: number, callback: (err: any, ret?: any) => void);
+    on(event: 'post_event', listener: (name: string, count: number) => void): this;
+    on(event: 'error', listener: (error: Error) => void): this;
+    once(event: 'post_event', listener: (name: string, count: number) => void): this;
+    once(event: 'error', listener: (error: Error) => void): this;
+    _finishReady(err?: Error): void;
+    _handleAsyncError(err: any): void;
     /**
      * Returns a snapshot of the current state for debugging.
      * Useful for tracing the state machine during development.
@@ -36,7 +45,7 @@ declare class FbEventManager extends Events.EventEmitter {
         isEventConnectionOpen: boolean;
         isDatabaseConnectionClosed: boolean;
     };
-    _createEventLoop(callback: (err: any, ret?: any) => void): void;
+    _createEventLoop(): void;
     _changeEvent(callback: (err: any, ret?: any) => void): void;
     registerEvent(events: string[], callback: (err: any, ret?: any) => void): any;
     unregisterEvent(events: string[], callback: (err: any, ret?: any) => void): any;

package/lib/wire/fbEventManager.js

@@ -64,6 +64,7 @@
 // Asynchronous notifications on the AUX (EventConnection) socket
 // ───────────────────────────────────────────────────────────────
 //   Server → Client : op_event  (fired by Firebird POST_EVENT trigger)
+//   Error / unexpected close → CLOSED; emit manager 'error' once
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -83,7 +84,50 @@ class FbEventManager extends events_1.default.EventEmitter {
         // main connection (so close() and _changeEvent know whether to send
         // op_cancel_events before tearing down or re-subscribing).
         this._hasActiveSubscription = false;
-        this._createEventLoop(callback);
+        this._readySettled = false;
+        this._terminalErrorReported = false;
+        this._readyCallback = callback;
+        this._createEventLoop();
+        process.nextTick(() => this._finishReady());
+    }
+    on(event, listener) {
+        return super.on(event, listener);
+    }
+    once(event, listener) {
+        return super.once(event, listener);
+    }
+    _finishReady(err) {
+        if (this._readySettled)
+            return;
+        this._readySettled = true;
+        if (err)
+            (0, callback_1.doError)(err, this._readyCallback);
+        else
+            this._readyCallback(null);
+    }
+    _handleAsyncError(err) {
+        if (this._terminalErrorReported)
+            return;
+        this._terminalErrorReported = true;
+        const error = err instanceof Error ? err : new Error(String(err));
+        this._hasActiveSubscription = false;
+        this._subscriptionVersion++;
+        this.eventconnection._isClosed = true;
+        this.eventconnection._isOpened = false;
+        this.eventconnection.eventcallback = null;
+        if (this.eventconnection._socket && !this.eventconnection._socket.destroyed &&
+            typeof this.eventconnection._socket.destroy === 'function') {
+            this.eventconnection._socket.destroy();
+        }
+        if (!this._readySettled) {
+            this._finishReady(error);
+        }
+        else if (this.listenerCount('error') > 0) {
+            this.emit('error', error);
+        }
+        else if (this.db.connection && typeof this.db.connection._emitError === 'function') {
+            this.db.connection._emitError(error);
+        }
     }
     /**
      * Returns a snapshot of the current state for debugging.
@@ -136,7 +180,7 @@ class FbEventManager extends events_1.default.EventEmitter {
             isDatabaseConnectionClosed: dbConnClosed,
         };
     }
-    _createEventLoop(callback) {
+    _createEventLoop() {
         var self = this;
         var cnx = this.db.connection;
         this.eventconnection.emgr = this;
@@ -157,15 +201,15 @@ class FbEventManager extends events_1.default.EventEmitter {
             }
             cnx.queEvents(self.events, self.eventid, function (err) {
                 if (err) {
-                    (0, callback_1.doError)(err, callback);
+                    self._handleAsyncError(err);
                     return;
                 }
                 // subscription renewed, nothing else to do
             });
         }
         this.eventconnection.eventcallback = function (err, ret) {
-            if (err || (self.eventid !== ret.eventid)) {
-                (0, callback_1.doError)(err || new Error('Bad eventid'), callback);
+            if (err || !ret || (self.eventid !== ret.eventid)) {
+                self._handleAsyncError(err || new Error('Bad eventid'));
                 return;
             }
             ret.events.forEach(function (event) {
@@ -173,11 +217,6 @@ class FbEventManager extends events_1.default.EventEmitter {
             });
             loop();
         };
-        // Resolve attachEvent on the next tick – no subscription is needed
-        // until the caller registers at least one event name via registerEvent().
-        // process.nextTick ensures the outer `const evt = new FbEventManager(...)`
-        // assignment in database.js completes before this callback fires.
-        process.nextTick(function () { callback(null); });
     }
     _changeEvent(callback) {
         var self = this;
@@ -246,6 +285,7 @@ class FbEventManager extends events_1.default.EventEmitter {
         }
         // Prevent the event loop from re-queuing on stale op_event notifications
         // that may arrive between closeEvents and socket.end()
+        self.eventconnection._intentionalClose = true;
         self.eventconnection.eventcallback = null;
         // Gracefully close the event socket using a FIN (end()) rather than a RST
         // (destroy()), then wait for the 'close' event which confirms both sides have

package/package.json

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

package/src/types.ts

@@ -6,6 +6,7 @@
 // published declaration files.
 
 import type { Readable, Writable } from 'stream';
+import type { EventEmitter } from 'events';
 import type { SqlTag } from './sql-template';
 
 export type { SqlTag, SqlQuery, SqlIdentifier, CompiledQuery } from './sql-template';
@@ -16,6 +17,30 @@ export type QueryCallback = (err: any, result: any[]) => void;
 export type SimpleCallback = (err: any) => void;
 export type SequentialCallback = (row: any, index: number, next?: (err?: any) => void) => void | Promise<void>;
 
+export interface FbEventState {
+    state: 'IDLE' | 'SUBSCRIBED' | 'CLOSED';
+    hasActiveSubscription: boolean;
+    registeredEvents: Record<string, number>;
+    eventId: number;
+    isEventConnectionOpen: boolean;
+    isDatabaseConnectionClosed: boolean;
+}
+
+export interface FbEventManager extends EventEmitter {
+    readonly eventid: number;
+    readonly events: Record<string, number>;
+    registerEvent(events: string[], callback: SimpleCallback): void;
+    unregisterEvent(events: string[], callback: SimpleCallback): void;
+    close(callback?: SimpleCallback): void;
+    getState(): FbEventState;
+    on(event: 'post_event', listener: (name: string, count: number) => void): this;
+    on(event: 'error', listener: (error: Error) => void): this;
+    once(event: 'post_event', listener: (name: string, count: number) => void): this;
+    once(event: 'error', listener: (error: Error) => void): this;
+}
+
+export type FbEventManagerCallback = (err: any, manager?: FbEventManager) => void;
+
 /**
  * Describes a single column in a prepared statement's result set or
  * parameter list.  The properties here are populated by the
@@ -272,7 +297,7 @@ export interface Database {
     batchStream(query: string, options?: BatchStreamOptions): BatchStream;
     drop(callback: SimpleCallback): void;
     escape(value: any): string;
-    attachEvent(callback: any): this;
+    attachEvent(callback: FbEventManagerCallback): this;
     createTablespace(name: string, filePath: string, callback?: QueryCallback): Database;
     alterTablespace(name: string, filePath: string, callback?: QueryCallback): Database;
     dropTablespace(name: string, callback?: QueryCallback): Database;
@@ -293,7 +318,7 @@ export interface Database {
     newStatementAsync(query: string): Promise<Statement>;
     detachAsync(force?: boolean): Promise<void>;
     dropAsync(): Promise<void>;
-    attachEventAsync(): Promise<any>;
+    attachEventAsync(): Promise<FbEventManager>;
     /** Starts a transaction, commits when `work` resolves, rolls back when it rejects. */
     withTransaction<T>(work: (transaction: Transaction) => Promise<T> | T, options?: TransactionOptions | Isolation): Promise<T>;
     /**
@@ -413,6 +438,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';
@@ -464,6 +464,12 @@ class Database extends Events.EventEmitter {
     attachEvent(callback: Callback<FbEventManager>): this {
         var self = this;
         const eventid = self.eventid++;
+        let completed = false;
+        const complete: Callback<FbEventManager> = function(err?: any, manager?: FbEventManager) {
+            if (completed) return;
+            completed = true;
+            callback(err, manager);
+        };
         if (process.env.FIREBIRD_DEBUG) {
             console.log('[fb-debug] Database.attachEvent: calling auxConnection, eventid=%d queue=%d', eventid, self.connection._queue.length);
         }
@@ -473,7 +479,7 @@ class Database extends Events.EventEmitter {
                 if (process.env.FIREBIRD_DEBUG) {
                     console.log('[fb-debug] Database.attachEvent: auxConnection error:', err.message);
                 }
-                doError(err, callback);
+                doError(err, complete);
                 return;
             }
 
@@ -481,9 +487,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) {
@@ -491,7 +495,7 @@ class Database extends Events.EventEmitter {
                     if (process.env.FIREBIRD_DEBUG) {
                         console.log('[fb-debug] Database.attachEvent: EventConnection error:', err.message);
                     }
-                    doError(err, callback);
+                    doError(err, complete);
                     return;
                 }
 
@@ -501,14 +505,14 @@ class Database extends Events.EventEmitter {
 
                 const evt = new FbEventManager(self, eventConnection, eventid, function (err: any) {
                     if (err) {
-                        doError(err, callback);
+                        doError(err, complete);
                         return;
                     }
 
                     if (process.env.FIREBIRD_DEBUG) {
                         console.log('[fb-debug] Database.attachEvent: FbEventManager ready, eventid=%d', evt.eventid);
                     }
-                callback(err, evt);
+                complete(err, evt);
                 });
             }, self);
         });

package/src/wire/eventConnection.ts

@@ -14,6 +14,8 @@ class EventConnection {
     error: any;
     eventcallback: ((err: any, ret?: any) => void) | null;
     _connectSettled: boolean;
+    _terminalErrorReported: boolean;
+    _intentionalClose: boolean;
 
     constructor(host: string, port: number, callback: ((err?: Error) => void) | undefined, db: any) {
         var self = this;
@@ -22,6 +24,8 @@ class EventConnection {
         this._isClosed = false;
         this._isOpened = false;
         this._connectSettled = false;
+        this._terminalErrorReported = false;
+        this._intentionalClose = false;
         this._socket = net.createConnection(port, host);
         this._bind_events(host, port, callback);
         this.error = null;
@@ -37,19 +41,40 @@ class EventConnection {
             if (callback) callback(err);
         }
 
+        function reportTerminalError(err: Error) {
+            if (self._terminalErrorReported) return;
+            self._terminalErrorReported = true;
+            const wasOpened = self._isOpened;
+            self.error = err;
+            self._isClosed = true;
+            self._isOpened = false;
+
+            // An error during a caller-initiated shutdown is part of tearing
+            // down the auxiliary socket, not a database error.
+            if (!self._intentionalClose && !wasOpened) {
+                finishConnect(err);
+            } else if (!self._intentionalClose && self.eventcallback) {
+                self.eventcallback(err);
+            } else if (!self._intentionalClose && self.db && self.db.connection &&
+                typeof self.db.connection._emitError === 'function') {
+                self.db.connection._emitError(err);
+            }
+
+            if (!self._socket.destroyed) self._socket.destroy();
+        }
+
         self._socket.on('close', function () {
             self._isClosed = true;
             if (!self._isOpened) {
                 finishConnect(self.error || new Error(`Event connection to ${host}:${port} closed before connecting.`));
+            } else if (!self._intentionalClose && self.eventcallback && !self._terminalErrorReported) {
+                reportTerminalError(new Error(`Event connection to ${host}:${port} closed unexpectedly.`));
             }
+            self._isOpened = false;
         })
 
         self._socket.on('error', function (e) {
-            self.error = e;
-            if (!self._isOpened) {
-                if (!self._socket.destroyed) self._socket.destroy();
-                finishConnect(e);
-            }
+            reportTerminalError(e);
         })
 
         self._socket.on('connect', function () {
@@ -78,6 +103,7 @@ class EventConnection {
 
                 var tmp_event: Record<string, number>;
                 while (xdr.pos < xdr.buffer.length) {
+                    op_pos = xdr.pos;
                     do {
                         var r = xdr.readInt();
                     } while (r === Const.op_dummy);
@@ -95,7 +121,8 @@ class EventConnection {
                             var eventcount = 0;
                             var pos = 1;
                             while (pos < buf.length) {
-                                var len = buf.readInt8(pos++);
+                                var len = buf.readUInt8(pos++);
+                                if (pos + len + 4 > buf.length) throw new RangeError('Incomplete event payload');
                                 eventname = buf.toString(DEFAULT_ENCODING, pos, pos + len);
                                 var prevcount = self.emgr.events[eventname] || 0;
                                 pos += len;
@@ -120,7 +147,7 @@ class EventConnection {
                                 self.eventcallback(null, { eventid: event_id, events: lst_event });
                             break;
                         default:
-                            // Unknown opcode on the event connection – stop processing.
+                            reportTerminalError(new Error('Unexpected event connection opcode: ' + r));
                             return;
                     }
                 }
@@ -130,7 +157,7 @@ class EventConnection {
                     xdr.pos = 0;
                     self._xdr = xdr;
                 } else {
-                    throw err;
+                    reportTerminalError(err instanceof Error ? err : new Error(String(err)));
                 }
             }
         })
@@ -138,7 +165,6 @@ class EventConnection {
 
     throwClosed(callback?: (err: any) => void): this {
         var err = new Error('Event Connection is closed.');
-        this.db.emit('error', err);
         if (callback)
             callback(err);
         return this;

package/src/wire/fbEventManager.ts

@@ -63,6 +63,7 @@
 // Asynchronous notifications on the AUX (EventConnection) socket
 // ───────────────────────────────────────────────────────────────
 //   Server → Client : op_event  (fired by Firebird POST_EVENT trigger)
+//   Error / unexpected close → CLOSED; emit manager 'error' once
 
 import Events from 'events';
 import { doError } from '../callback';
@@ -74,6 +75,9 @@ class FbEventManager extends Events.EventEmitter {
     eventid: number;
     _subscriptionVersion: number;
     _hasActiveSubscription: boolean;
+    _readySettled: boolean;
+    _terminalErrorReported: boolean;
+    _readyCallback: (err: any, ret?: any) => void;
 
     constructor(db: any, eventconnection: any, eventid: number, callback: (err: any, ret?: any) => void) {
         super();
@@ -88,7 +92,53 @@ class FbEventManager extends Events.EventEmitter {
         // main connection (so close() and _changeEvent know whether to send
         // op_cancel_events before tearing down or re-subscribing).
         this._hasActiveSubscription = false;
-        this._createEventLoop(callback);
+        this._readySettled = false;
+        this._terminalErrorReported = false;
+        this._readyCallback = callback;
+        this._createEventLoop();
+        process.nextTick(() => this._finishReady());
+    }
+
+    on(event: 'post_event', listener: (name: string, count: number) => void): this;
+    on(event: 'error', listener: (error: Error) => void): this;
+    on(event: string | symbol, listener: (...args: any[]) => void): this {
+        return super.on(event, listener);
+    }
+
+    once(event: 'post_event', listener: (name: string, count: number) => void): this;
+    once(event: 'error', listener: (error: Error) => void): this;
+    once(event: string | symbol, listener: (...args: any[]) => void): this {
+        return super.once(event, listener);
+    }
+
+    _finishReady(err?: Error): void {
+        if (this._readySettled) return;
+        this._readySettled = true;
+        if (err) doError(err, this._readyCallback);
+        else this._readyCallback(null);
+    }
+
+    _handleAsyncError(err: any): void {
+        if (this._terminalErrorReported) return;
+        this._terminalErrorReported = true;
+        const error = err instanceof Error ? err : new Error(String(err));
+        this._hasActiveSubscription = false;
+        this._subscriptionVersion++;
+        this.eventconnection._isClosed = true;
+        this.eventconnection._isOpened = false;
+        this.eventconnection.eventcallback = null;
+        if (this.eventconnection._socket && !this.eventconnection._socket.destroyed &&
+            typeof this.eventconnection._socket.destroy === 'function') {
+            this.eventconnection._socket.destroy();
+        }
+
+        if (!this._readySettled) {
+            this._finishReady(error);
+        } else if (this.listenerCount('error') > 0) {
+            this.emit('error', error);
+        } else if (this.db.connection && typeof this.db.connection._emitError === 'function') {
+            this.db.connection._emitError(error);
+        }
     }
 
     /**
@@ -143,7 +193,7 @@ class FbEventManager extends Events.EventEmitter {
         };
     }
 
-    _createEventLoop(callback: (err: any, ret?: any) => void): void {
+    _createEventLoop(): void {
         var self = this;
         var cnx = this.db.connection;
         this.eventconnection.emgr = this;
@@ -166,7 +216,7 @@ class FbEventManager extends Events.EventEmitter {
             }
             cnx.queEvents(self.events, self.eventid, function (err: any) {
                 if (err) {
-                    doError(err, callback);
+                    self._handleAsyncError(err);
                     return;
                 }
                 // subscription renewed, nothing else to do
@@ -174,8 +224,8 @@ class FbEventManager extends Events.EventEmitter {
         }
 
         this.eventconnection.eventcallback = function (err: any, ret?: any) {
-            if (err || (self.eventid !== ret.eventid)) {
-                doError(err || new Error('Bad eventid'), callback);
+            if (err || !ret || (self.eventid !== ret.eventid)) {
+                self._handleAsyncError(err || new Error('Bad eventid'));
                 return;
             }
 
@@ -186,11 +236,6 @@ class FbEventManager extends Events.EventEmitter {
             loop();
         };
 
-        // Resolve attachEvent on the next tick – no subscription is needed
-        // until the caller registers at least one event name via registerEvent().
-        // process.nextTick ensures the outer `const evt = new FbEventManager(...)`
-        // assignment in database.js completes before this callback fires.
-        process.nextTick(function() { callback(null); });
     }
 
     _changeEvent(callback: (err: any, ret?: any) => void): void {
@@ -271,6 +316,7 @@ class FbEventManager extends Events.EventEmitter {
 
         // Prevent the event loop from re-queuing on stale op_event notifications
         // that may arrive between closeEvents and socket.end()
+        self.eventconnection._intentionalClose = true;
         self.eventconnection.eventcallback = null;
 
         // Gracefully close the event socket using a FIN (end()) rather than a RST