v2.17.0

Minor release introducing the eventHost connection option and connection URI parameter, allowing callers to override the server-advertised host for Firebird auxiliary event connections (attachEvent() / attachEventAsync()).

Features

• Auxiliary Event Host Override (eventHost): Firebird events operate over a secondary TCP connection (EventConnection) rather than the primary database wire channel. During attachEvent(), the server sends back an auxiliary port and IP address via op_connect_request. In containerized environments, Kubernetes clusters, SSH tunnels, NAT networks, or behind reverse proxies and load balancers, the address advertised by Firebird may not be directly reachable by the client. Callers can now set options.eventHost (or the ?eventHost=... URI query parameter) to override only the auxiliary host while preserving the server-selected port.
• Connection URI Support: eventHost is recognized in both firebird:// and inet:// (as well as inet4:// / inet6://) connection URIs (e.g. firebird://user:pass@db.example.com/database.fdb?eventHost=events.example.com).
• TypeScript Declarations: Added eventHost?: string with JSDoc documentation to the exported Options interface.

Host Resolution Precedence

Host resolution for auxiliary event connections in resolveEventHost() now strictly follows this precedence:

1. Explicit options.eventHost: When provided, unconditionally used for the auxiliary event connection.
2. Reachable Advertised Host: When eventHost is omitted and the server advertises a non-wildcard IP or hostname, the driver connects to that advertised host.
3. Database Host / Default Fallback: When the server advertises a wildcard address (0.0.0.0 or ::), the driver falls back to options.host, or defaults to 127.0.0.1 (Const.DEFAULT_HOST) if host was not specified in the options.

Auxiliary Port Handling

The auxiliary port continues to be dynamically chosen and reported by the Firebird server. eventHost overrides only the host portion. If the auxiliary port also needs to be fixed to a specific port (e.g. for firewall or container port-forwarding rules), configure RemoteAuxPort in the server's firebird.conf.

Testing

• Added comprehensive unit test coverage in test/unit/utils.test.ts for resolveEventHost across reachable advertised addresses, IPv4/IPv6 wildcard fallbacks, omitted host defaults, and explicit eventHost precedence.
• Added URI query parameter parsing tests in test/uri.js.
• CI passed all 16 jobs across Node.js 20, 22, 24, and 26 against Firebird 3, 4, 5, and 6-snapshot.
• 220 unit tests pass locally with 0 TypeScript and 0 linting errors.

Documentation

• Updated README.md connection options examples and added guidance in The auxiliary connection, and when attachEvent fails.

Upgrading

Drop-in replacement for 2.16.2 with no breaking changes. Existing event connections with reachable advertised addresses or wildcard fallbacks continue to function unchanged.

Thanks to @Gobbo89 for #435.