jsgar 4.0.1 → 4.0.2

package/gar.js

@@ -0,0 +1,1466 @@
+/**
+ * A client implementation for the Generic Active Records (GAR) protocol using WebSockets.
+ * See trsgar.js for example usage.
+ *
+ * The GARClient class provides a JavaScript interface for connecting to a GAR server
+ * using WebSockets as the transport layer. It handles protocol details including
+ * message serialization, heartbeat management, topic and key enumeration, record
+ * updates, and subscription management.
+ *
+ * Key features:
+ * - Automatic heartbeat management to maintain connection
+ * - Support for topic and key int <-> string introductions
+ * - Record creation, updating, and deletion
+ * - Subscription management with filtering options
+ * - Customizable message handlers for all protocol message types
+ * - Automatic reconnection on WebSocket connection loss
+ *
+ * See the full documentation at https://trinityriversystems.com/docs/ for detailed
+ * protocol specifications and usage instructions.
+ */
+
+// WebSocket environment shim:
+// - In browsers, uses window.WebSocket
+// - In Node.js, dynamically imports 'ws' and assigns globalThis.WebSocket
+// All client code references the constructor via helper methods, not a top-level binding.
+
+class GARClient {
+    /**
+     * Initialize the GAR client.
+     * @param {string} wsEndpoint - WebSocket endpoint (e.g., "ws://localhost:8765")
+     * @param {string} user - Client username for identification
+     * @param {number} [heartbeatTimeoutInterval=4000] - Heartbeat interval in milliseconds
+     * @param {boolean} [allowSelfSignedCertificate=false] - Allow self-signed certificates
+     * @param {string} [logLevel='INFO'] - Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+     * @param {boolean} [uniqueKeyAndRecordUpdates=false] - Only one update per key/record
+     */
+    constructor(wsEndpoint, user, working_namespace = null, heartbeatTimeoutInterval = 4000, allowSelfSignedCertificate = false, logLevel = 'INFO', uniqueKeyAndRecordUpdates = false) {
+        this.wsEndpoint = wsEndpoint;
+        this.websocket = null;
+        this.messageQueue = [];
+        this.connected = false;
+        this.reconnectDelay = 5000; // Milliseconds
+        this.user = user;
+        this.working_namespace = working_namespace;
+        this.timeoutScale = (typeof process !== 'undefined' && process.env && process.env.TRS_TIMEOUT_SCALE) ? parseFloat(process.env.TRS_TIMEOUT_SCALE) : 1.0;
+        this.scaledHeartbeatTimeoutInterval = heartbeatTimeoutInterval;
+        if (this.timeoutScale !== 1.0) {
+            this.scaledHeartbeatTimeoutInterval *= this.timeoutScale;
+        }
+        this.unique_key_and_record_updates = uniqueKeyAndRecordUpdates;
+        this.version = 650708;
+        this.uuid = GARClient._generateUUID();
+
+        if (typeof window !== 'undefined' && window.location) {
+            this.application = window.location.href;
+        } else if (typeof require !== 'undefined' && require.main) {
+            this.application = require.main.filename;
+        } else {
+            this.application = 'unknown-js';
+        }
+
+        this.serverTopicIdToName = new Map();
+        this.serverTopicNameToId = new Map();
+        this.serverKeyIdToName = new Map();
+        this.serverKeyNameToId = new Map();
+        this.localTopicMap = new Map();
+        this.localKeyMap = new Map();
+        this.recordMap = new Map();
+
+        this.running = false;
+        this.heartbeatIntervalId = null;
+        this.messageHandlers = new Map();
+        this.lastHeartbeatTime = Date.now() / 1000;
+
+        this.heartbeatTimeoutCallback = null;
+        this.stoppedCallback = null;
+        this.allowSelfSignedCertificate = allowSelfSignedCertificate;
+        this.exitCode = 0;
+
+        this.clearConnectionState()
+
+        // Initialize log levels and set logLevel
+        this.logLevels = ['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'];
+        this.logLevel = logLevel.toUpperCase();
+        if (!this.logLevels.includes(this.logLevel)) {
+            console.warn(`Invalid logLevel "${logLevel}" provided; defaulting to INFO`);
+            this.logLevel = 'INFO';
+        }
+
+        this.registerDefaultHandlers();
+
+        // First-heartbeat latch: resolved on the first Heartbeat after an Introduction
+        this._firstHeartbeatResolve = null;
+        this._firstHeartbeatPromise = null;
+        this._resetFirstHeartbeatLatch();
+    }
+
+    /**
+     * Log messages with a specific level, only if the level is at or above the configured logLevel.
+     * @param {string} level - Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+     * @param {string} message - Message to log
+     * @param {...any} args - Additional arguments
+     */
+    log(level, message, ...args) {
+        const levelUpper = level.toUpperCase();
+        if (!this.logLevels.includes(levelUpper)) {
+            console.warn(`Invalid log level "${level}" in log call`);
+            return;
+        }
+        if (this.logLevels.indexOf(levelUpper) >= this.logLevels.indexOf(this.logLevel)) {
+            const timestamp = new Date().toISOString();
+            console.log(`${timestamp} ${levelUpper} gar.js - ${message}`, ...args);
+        }
+    }
+
+    /**
+     * Reset all connection-related state:
+     * server/client topic/key mappings, counters, grace flags, and records.
+     */
+    clearConnectionState() {
+        // Server assigned topic/key <-> name mappings
+        this.serverTopicIdToName.clear();
+        this.serverTopicNameToId.clear();
+        this.serverKeyIdToName.clear();
+        this.serverKeyNameToId.clear();
+
+        // Client assigned topic/key counters and name <-> ID maps
+        this.localTopicCounter = 1;
+        this.localKeyCounter = 1;
+        this.localTopicMap.clear();
+        this.localKeyMap.clear();
+
+        // Heartbeat grace period flags
+        this._initialGracePeriod = false;
+        this._initialGraceDeadline = 0;
+
+        // Cached records
+        this.recordMap.clear();
+
+        this.activeSubscriptionGroup = 0;
+
+        // Do NOT recreate the first-heartbeat promise here; callers might already be awaiting it.
+        // We only flip grace flags and let the existing promise resolve on the first Heartbeat.
+    }
+
+    /**
+     * Establish WebSocket connection with reconnection logic.
+     * @param {number} [openTimeout=20] - Connection timeout in seconds
+     */
+    async connect(openTimeout = 20) {
+        // Before attempting a new connection, clear any previous state
+        this.clearConnectionState();
+
+        let scaledOpenTimeout = openTimeout * this.timeoutScale;
+
+        while (this.running && !this.connected) {
+            try {
+                const WS = await this._ensureWebSocketCtor();
+                const isNode = typeof process !== 'undefined' && process.versions && process.versions.node;
+
+                this.log('INFO', `Connecting to WebSocket server at ${this.wsEndpoint}`);
+
+                const connectionPromise = new Promise((resolve, reject) => {
+                    let websocket;
+                    if (this.allowSelfSignedCertificate && isNode) {
+                        // Node.js 'ws' supports options for TLS; browsers do not.
+                        websocket = new WS(this.wsEndpoint, ['gar-protocol'], { rejectUnauthorized: false });
+                    } else {
+                        websocket = new WS(this.wsEndpoint, ['gar-protocol']);
+                    }
+
+                    const timeoutId = setTimeout(() => {
+                        websocket.onopen = null;
+                        websocket.onclose = null;
+                        websocket.onerror = null;
+                        if (websocket.terminate) websocket.terminate();
+                        else if (websocket.close) websocket.close();
+                        reject(new Error(`Connection timed out after ${scaledOpenTimeout}s`));
+                    }, scaledOpenTimeout * 1000);
+
+                    websocket.onopen = () => {
+                        clearTimeout(timeoutId);
+                        resolve(websocket);
+                    };
+                    websocket.onerror = (error) => {
+                        clearTimeout(timeoutId);
+                        reject(new Error(error.message || 'Unknown WebSocket error'));
+                    };
+                    websocket.onclose = () => {
+                        clearTimeout(timeoutId);
+                        reject(new Error('WebSocket closed during connection attempt'));
+                    };
+                });
+
+                this.websocket = await connectionPromise;
+                this.connected = true;
+                this.log('INFO', `Connected to WebSocket server at ${this.wsEndpoint} using gar-protocol`);
+
+                this.websocket.onclose = () => {
+                    this.log('WARNING', 'WebSocket connection closed.');
+                    this.connected = false;
+                    this.websocket = null;
+                    this._reconnect();
+                };
+                this.websocket.onerror = (error) => {
+                    this.log('ERROR', `WebSocket error: ${error.message || 'Unknown error'}`);
+                    this.connected = false;
+                    this.websocket = null;
+                };
+
+                this._sendMessages();
+                this._receiveMessages();
+
+            } catch (e) {
+                this.log('ERROR', `WebSocket connection failed: ${e.message}. Reconnecting in ${this.reconnectDelay / 1000} seconds...`);
+                this.connected = false;
+                this.websocket = null;
+                await new Promise(resolve => setTimeout(resolve, this.reconnectDelay));
+            }
+        }
+    }
+
+    /**
+     * Attempt to reconnect after a delay.
+     */
+    _reconnect() {
+        if (this.running && !this.connected) {
+            setTimeout(() => this.connect(), this.reconnectDelay);
+        }
+    }
+
+    /**
+     * Send messages from the queue to the WebSocket server.
+     */
+    async _sendMessages() {
+        while (this.connected && (this.running || this.messageQueue.length > 0)) {
+            if (this.messageQueue.length === 0) {
+                await new Promise(resolve => setTimeout(resolve, 100));
+                continue;
+            }
+            try {
+                const message = this.messageQueue.shift();
+                if (message === null) break;
+                if (this._isSocketOpen()) {
+                    this.websocket.send(JSON.stringify(message));
+                    this.log('DEBUG', `Sent: ${JSON.stringify(message)}`);
+                }
+            } catch (e) {
+                this.log('WARNING', `Error sending message: ${e.message}`);
+                this.halt();
+                break;
+            }
+        }
+        this.log('INFO', 'Done sending messages.');
+        this.stop()
+        this.connected = false;
+    }
+
+    /**
+     * Receive and process messages from the WebSocket server.
+     */
+    _receiveMessages() {
+        this.websocket.onmessage = (event) => {
+            const message = JSON.parse(event.data);
+            this._processMessage(message);
+        };
+    }
+
+    /**
+     * Register a callback handler for a specific message type.
+     * @param {string} messageType - Type of message
+     * @param {Function} handler - Callback function
+     * @param subscriptionGroup - Subscription group for callback (default 0)
+     */
+    registerHandler(messageType, handler, subscriptionGroup = 0) {
+        this.messageHandlers.set(subscriptionGroup ? `${messageType} ${subscriptionGroup}` : messageType, handler);
+    }
+
+    /**
+     * Register handler for Introduction message.
+     * @param {Function} handler - Callback with (version, heartbeatTimeoutInterval, user, _schema)
+     */
+    registerIntroductionHandler(handler) {
+        this.registerHandler('Introduction', (msg) => {
+            const value = msg.value;
+            handler(value.version, value.heartbeat_timeout_interval, value.user, value.schema || null);
+        });
+    }
+
+    clearIntroductionHandler() {
+        this.messageHandlers.delete('Introduction');
+    }
+
+    /**
+     * Register handler for Heartbeat message.
+     * @param {Function} handler - Callback with no arguments
+     */
+    registerHeartbeatHandler(handler) {
+        this.registerHandler('Heartbeat', (msg) => {
+            const value = msg.value;
+            handler(value.u_milliseconds);
+        });
+    }
+
+    clearHeartbeatHandler() {
+        this.messageHandlers.delete('Heartbeat');
+    }
+
+    /**
+     * Register handler for Logoff message.
+     * @param {Function} handler - Callback with no arguments
+     */
+    registerLogoffHandler(handler) {
+        this.registerHandler('Logoff', () => handler());
+    }
+
+    clearLogoffHandler() {
+        this.messageHandlers.delete('Logoff');
+    }
+
+    /**
+     * Register handler for Error message.
+     * @param {Function} handler - Callback with (message)
+     */
+    registerErrorHandler(handler) {
+        this.registerHandler('Error', (msg) => handler(msg.value.message));
+    }
+
+    clearErrorHandler() {
+        this.messageHandlers.delete('Error');
+    }
+
+    /**
+     * Register handler for TopicIntroduction message.
+     * @param {Function} handler - Callback with (topicId, name)
+     */
+    registerTopicIntroductionHandler(handler) {
+        this.registerHandler('TopicIntroduction', (msg) => {
+            const value = msg.value;
+            handler(value.topic_id, value.name);
+        });
+    }
+
+    clearTopicIntroductionHandler() {
+        this.messageHandlers.delete('TopicIntroduction');
+    }
+
+    /**
+     * Register handler for KeyIntroduction message.
+     * @param {Function} handler - Callback with (keyId, name, class_list, deleted_class)
+     * @param subscriptionGroup - The subscription group for callback (default 0)
+     */
+    registerKeyIntroductionHandler(handler, subscriptionGroup = 0) {
+        this.registerHandler('KeyIntroduction', (msg) => {
+            const value = msg.value;
+            handler(value.key_id, value.name, value.class_list || null, value.deleted_class || null);
+        }, subscriptionGroup);
+    }
+
+    /**
+     * Register handler for DeleteKey message.
+     * @param {Function} handler - Callback with (keyId, keyName)
+     * @param subscriptionGroup - The subscription group for callback (default 0)
+     */
+    registerDeleteKeyHandler(handler, subscriptionGroup = 0) {
+        this.registerHandler('DeleteKey', (msg) => handler(msg.value.key_id, (msg.value && ('name' in msg.value)) ? msg.value.name : null), subscriptionGroup);
+    }
+
+    /**
+     * Register handler for SubscriptionStatus message.
+     * @param {Function} handler - Callback with (name, status)
+     * @param {number} [subscriptionGroup=0] - The subscription group for callback
+     */
+    registerSubscriptionStatusHandler(handler, subscriptionGroup = 0) {
+        this.registerHandler('SubscriptionStatus', (msg) => handler(msg.value.name, msg.value.status), subscriptionGroup);
+    }
+
+    /**
+     * Clear handler for SubscriptionStatus message.
+     * @param {number} [subscriptionGroup=0] - The subscription group to clear
+     */
+    clearSubscriptionStatusHandler(subscriptionGroup = 0) {
+        const key = subscriptionGroup ? `SubscriptionStatus ${subscriptionGroup}` : 'SubscriptionStatus';
+        this.messageHandlers.delete(key);
+    }
+
+    /**
+     * Register handler for DeleteRecord message.
+     * @param {Function} handler - Callback with (keyId, topicId)
+     * @param subscriptionGroup - The subscription group for callback (default 0)
+     */
+    registerDeleteRecordHandler(handler, subscriptionGroup = 0) {
+        this.registerHandler('DeleteRecord', (msg) => {
+            handler(msg.value.key_id, msg.value.topic_id);
+        }, subscriptionGroup);
+    }
+
+    /**
+     * Register handler for JSONRecordUpdate message.
+     * @param {Function} handler - Callback with (keyId, topicId, value)
+     * @param subscriptionGroup - The subscription group for callback (default 0)
+     */
+    registerRecordUpdateHandler(handler, subscriptionGroup = 0) {
+        this.registerHandler('JSONRecordUpdate', (msg) => {
+            const recordId = msg.value.record_id;
+            handler(recordId.key_id, recordId.topic_id, msg.value.value);
+        }, subscriptionGroup);
+    }
+
+    /**
+     * Register handler for JSONCompareExchangeResult message.
+     * @param {Function} handler - Callback with (message)
+     * @param {number} [subscriptionGroup=0] - The subscription group for callback
+     */
+    registerCompareExchangeResultHandler(handler, subscriptionGroup = 0) {
+        this.registerHandler('JSONCompareExchangeResult', handler, subscriptionGroup);
+    }
+
+    /**
+     * Register handler for BatchUpdate message.
+     * If a batch handler is registered it is expected to process all the updates in the batch.
+     * If no batch handler is registered, individual key introductions and record updates will be fanned out to their respective handlers.
+     * @param {Function} handler - Callback with (batchData, subscriptionGroup)
+     * @param {number} [subscriptionGroup=0] - The subscription group for callback
+     */
+    registerBatchUpdateHandler(handler, subscriptionGroup = 0) {
+        this.registerHandler('BatchUpdate', (msg) => {
+            handler(msg.value, subscriptionGroup);
+        }, subscriptionGroup);
+    }
+
+    /**
+     * Register handler for EchoResponse message.
+     * @param {Function} handler - Callback with (msgRef)
+     */
+    registerEchoResponseHandler(handler) {
+        this.registerHandler('EchoResponse', (msg) => {
+            handler(msg.value.msg_ref);
+        });
+    }
+
+    clearEchoResponseHandler() {
+        this.messageHandlers.delete('EchoResponse');
+    }
+
+    /**
+     * Register a callback to handle heartbeat timeout events.
+     * @param {Function} handler - Callback with no arguments
+     */
+    registerHeartbeatTimeoutHandler(handler) {
+        this.heartbeatTimeoutCallback = handler;
+    }
+
+    clearHeartbeatTimeoutHandler() {
+        this.heartbeatTimeoutCallback = null;
+    }
+
+    /**
+     * Register a callback to handle client stopped events.
+     * @param {Function} handler - Callback with no arguments
+     */
+    registerStoppedHandler(handler) {
+        this.stoppedCallback = handler;
+    }
+
+    clearStoppedHandler() {
+        this.stoppedCallback = null;
+    }
+
+    /**
+     * Register default logging handlers for all message types.
+     */
+    registerDefaultHandlers() {
+        this.registerIntroductionHandler((version, interval, user, _schema) =>
+            this.log('INFO', `Connected to server: ${user}`));
+        this.registerHeartbeatHandler((u_milliseconds) => this.log('INFO', `Heartbeat received ${u_milliseconds}ms`));
+        this.registerLogoffHandler(() => this.log('INFO', 'Logoff received'));
+        this.registerTopicIntroductionHandler((topicId, name) =>
+            this.log('DEBUG', `New server topic: ${name} (Server ID: ${topicId})`));
+        this.registerKeyIntroductionHandler((keyId, name, classList, deletedClass) =>
+            this.log('DEBUG', `Key: ${name} : ${keyId} (Classes: ${JSON.stringify(classList)}/-${deletedClass})`));
+        this.registerDeleteKeyHandler((keyId, keyName) =>
+            this.log('DEBUG', `Delete key: ${keyName || 'unknown'} (Server ID: ${keyId})`));
+        this.registerSubscriptionStatusHandler(this._defaultSubscriptionStatusHandler.bind(this));
+        this.registerDeleteRecordHandler((keyId, topicId) =>
+            this.log('DEBUG', `Delete record: ${this.serverKeyIdToName.get(keyId) || 'unknown'} - ${this.serverTopicIdToName.get(topicId) || 'unknown'}`));
+        this.registerRecordUpdateHandler((keyId, topicId, value) =>
+            this.log('DEBUG', `Record update: ${this.serverKeyIdToName.get(keyId) || 'unknown'} - ${this.serverTopicIdToName.get(topicId) || 'unknown'} = ${JSON.stringify(value)}`));
+    }
+
+    /**
+     * Default handler for subscription status messages.
+     * @param {string} name - Subscription name
+     * @param {string} status - Subscription status
+     */
+    _defaultSubscriptionStatusHandler(name, status) {
+        this.log('INFO', `Subscription ${name} status: ${status}`);
+        if (status === 'NeedsContinue') {
+            this.log('INFO', `Snapshot size limit reached, sending SubscribeContinue for ${name}`);
+            this.sendSubscribeContinue(name);
+        }
+    }
+
+    /**
+     * Start the client and send introduction message.
+     */
+    start() {
+        this.running = true;
+        const introMsg = {
+            message_type: 'Introduction',
+            value: {
+                version: this.version,
+                heartbeat_timeout_interval: Math.floor(this.scaledHeartbeatTimeoutInterval),
+                unique_key_and_record_updates: this.unique_key_and_record_updates,
+                uuid: this.uuid,
+                user: this.user,
+                working_namespace: this.working_namespace
+            }
+        };
+        this.sendMessage(introMsg);
+        this.heartbeatIntervalId = setInterval(() => this._heartbeatLoop(), this.scaledHeartbeatTimeoutInterval / 2);
+        this.connect();
+    }
+
+    /**
+     * Wait until in-memory queue is empty and WebSocket bufferedAmount is zero.
+     */
+    async _waitForDrain(pollMs = 50) {
+        while (
+            this.messageQueue.length > 0 ||
+            (this.websocket && this.websocket.bufferedAmount > 0)
+            ) {
+            await new Promise(r => setTimeout(r, pollMs));
+        }
+    }
+
+    /**
+     * Stop the client and terminate all operations.
+     */
+    async stop() {
+        if (!this.running)
+            return;
+
+        this.running = false;
+        if (this.heartbeatIntervalId) {
+            clearInterval(this.heartbeatIntervalId);
+            this.heartbeatIntervalId = null;
+        }
+
+        // if it's a regular stop, wait for send-queue + socket to drain
+        if (this.connected && this.websocket) {
+            await this._waitForDrain();
+        }
+        else {
+            this.messageQueue = [];
+        }
+
+        if (this.websocket && this.websocket.readyState === 1) {
+            this.websocket.close();
+        }
+        this.messageQueue = [];
+        if (this.stoppedCallback) {
+            this.stoppedCallback();
+        }
+        this.log('INFO', 'GAR client stopped');
+    }
+
+    _isSocketOpen() {
+        // Both browser and 'ws' use readyState 1 for OPEN
+        return !!(this.websocket && this.websocket.readyState === 1);
+    }
+
+    async _ensureWebSocketCtor() {
+        // Return a WebSocket constructor for current environment.
+        // Prefer any existing globalThis.WebSocket (browser or pre-set in Node).
+        if (typeof globalThis !== 'undefined' && globalThis.WebSocket) {
+            return globalThis.WebSocket;
+        }
+        // Node.js: resolve 'ws' at runtime without using dynamic import (avoids rollup code-splitting)
+        const isNode = typeof process !== 'undefined' && process.versions && process.versions.node;
+        if (isNode) {
+            try {
+                const req = (typeof module !== 'undefined' && module.require)
+                    ? module.require.bind(module)
+                    : (typeof require !== 'undefined' ? require : Function('return require')());
+                const mod = req('ws');
+                const WS = mod.default || mod.WebSocket || mod;
+                globalThis.WebSocket = WS;
+                return WS;
+            } catch {
+                throw new Error("'ws' module is required in Node.js environment. Please install it: npm install ws");
+            }
+        }
+        throw new Error('WebSocket constructor not found in this environment');
+    }
+
+    /**
+     * Stop the client without sending pending messages.
+     */
+    halt() {
+        this.connected = false;
+        this.stop();
+    }
+
+    /**
+     * Send a logoff message to the server and stop the client.
+     */
+    logoff() {
+        this.sendMessage({ message_type: 'Logoff' });
+        this.stop();
+    }
+
+    /**
+     * Send a JSON message through the WebSocket.
+     * @param {Object} message - Message to send
+     */
+    sendMessage(message) {
+        this.messageQueue.push(message);
+    }
+
+    /**
+     * Send a SubscribeContinue message for a subscription name.
+     * @param {string} name - Subscription name
+     */
+    sendSubscribeContinue(name) {
+        const msg = {
+            message_type: 'SubscribeContinue',
+            value: { name }
+        };
+        this.sendMessage(msg);
+    }
+
+    /**
+     * Send an EchoRequest message.
+     * @param {number} msgRef - Message reference ID
+     */
+    sendEchoRequest(msgRef) {
+        this.sendMessage({
+            message_type: 'EchoRequest',
+            value: { msg_ref: msgRef }
+        });
+    }
+
+    /**
+     * Send periodic heartbeat messages.
+     */
+    _heartbeatLoop() {
+        if (this.running) {
+            this.sendMessage({ message_type: 'Heartbeat', value: { u_milliseconds: Date.now() } });
+            this.checkHeartbeat();
+        }
+    }
+
+    /**
+     * Check if the heartbeat has timed out.
+     */
+    checkHeartbeat() {
+        const now = Date.now() / 1000;
+        const cutoff = this._initialGracePeriod ? this._initialGraceDeadline : this.lastHeartbeatTime + (this.scaledHeartbeatTimeoutInterval / 1000.0);
+        if (now > cutoff) {
+            this.log('WARNING', `Heartbeat failed; previous heartbeat: ${this.lastHeartbeatTime.toFixed(3)}s`);
+            this.exitCode = 1;
+            this.halt();
+            if (this.heartbeatTimeoutCallback) {
+                this.heartbeatTimeoutCallback();
+            }
+        }
+    }
+
+    /**
+     * Reset the internal first-heartbeat latch and create a fresh Promise.
+     * Called on construction, clearConnectionState, and Introduction.
+     * @private
+     */
+    _resetFirstHeartbeatLatch() {
+        let resolved = false;
+        this._firstHeartbeatPromise = new Promise((resolve) => {
+            this._firstHeartbeatResolve = (value) => {
+                if (!resolved) {
+                    resolved = true;
+                    resolve(value);
+                }
+            };
+        });
+    }
+
+    /**
+     * Wait for the first heartbeat after the most recent Introduction.
+     * @param {number} [timeoutMs=10000] - Timeout in milliseconds
+     * @returns {Promise<void>} Resolves on first heartbeat; rejects on timeout
+     */
+    awaitFirstHeartbeat(timeoutMs = 10000) {
+        const to = Math.max(0, Math.floor(timeoutMs));
+        return new Promise((resolve, reject) => {
+            let timer = null;
+            if (to > 0) {
+                timer = setTimeout(() => {
+                    reject(new Error('Timed out waiting for first heartbeat'));
+                }, to);
+            }
+            this._firstHeartbeatPromise
+                .then(() => {
+                    if (timer) clearTimeout(timer);
+                    resolve();
+                })
+                .catch((e) => {
+                    if (timer) clearTimeout(timer);
+                    reject(e);
+                });
+        });
+    }
+
+    /**
+     * Process incoming messages by calling registered handlers.
+     * @param {Object} message - Incoming message
+     */
+    _processMessage(message) {
+        const msgType = message.message_type;
+        let subscriptionGroup = 0;
+        if (msgType === 'TopicIntroduction') {
+            this.serverTopicIdToName.set(message.value.topic_id, message.value.name);
+            this.serverTopicNameToId.set(message.value.name, message.value.topic_id);
+        } else if (msgType === 'KeyIntroduction') {
+            subscriptionGroup = this.activeSubscriptionGroup;
+            this.serverKeyIdToName.set(message.value.key_id, message.value.name);
+            this.serverKeyNameToId.set(message.value.name, message.value.key_id);
+        } else if (msgType === 'DeleteKey') {
+            subscriptionGroup = this.activeSubscriptionGroup;
+            const keyId = message.value.key_id;
+            const keyName = this.serverKeyIdToName.get(keyId) || null;
+            message.value.name = keyName;
+            if (keyName) {
+                this.serverKeyNameToId.delete(keyName);
+            } else {
+                // Ensure 'name' field exists even if unknown
+                if (!('name' in message.value)) message.value.name = null;
+            }
+            this.serverKeyIdToName.delete(keyId);
+        } else if (msgType === 'Heartbeat') {
+            this.lastHeartbeatTime = Date.now() / 1000;
+            if (this._initialGracePeriod) {
+                // Resolve first-heartbeat waiters and end the initial grace window
+                if (this._firstHeartbeatResolve) {
+                    try { this._firstHeartbeatResolve(); } catch { /* noop */ }
+                }
+                this._initialGracePeriod = false;
+            }
+        } else if (msgType === 'Introduction') {
+            const value = message.value;
+            this.serverTopicIdToName.clear();
+            this.serverTopicNameToId.clear();
+            this.serverKeyIdToName.clear();
+            this.serverKeyNameToId.clear();
+            this.recordMap.clear();
+            let newInterval = value.heartbeat_timeout_interval;
+            if (this.timeoutScale !== 1.0) {
+                newInterval *= this.timeoutScale;
+            }
+            this.scaledHeartbeatTimeoutInterval = Math.max(this.scaledHeartbeatTimeoutInterval, newInterval);
+            this.lastHeartbeatTime = Date.now() / 1000;
+            this._initialGracePeriod = true;
+            this._initialGraceDeadline = this.lastHeartbeatTime + (this.scaledHeartbeatTimeoutInterval / 1000.0) * 10;
+            // New Introduction: do not reset the first-heartbeat promise to avoid racing
+            // with consumers already awaiting it. The existing promise will resolve on
+            // the first Heartbeat observed during the grace period above.
+        } else if (msgType === 'JSONCompareExchangeResult') {
+            subscriptionGroup = this.activeSubscriptionGroup;
+        } else if (msgType === 'JSONRecordUpdate') {
+            subscriptionGroup = this.activeSubscriptionGroup;
+            const recordId = message.value.record_id;
+            const keyId = recordId.key_id;
+            const topicId = recordId.topic_id;
+            this.recordMap.set(`${keyId}:${topicId}`, message.value.value);
+        } else if (msgType === 'SubscriptionStatus') {
+            // Route status notifications to the currently active subscription group
+            subscriptionGroup = this.activeSubscriptionGroup;
+        } else if (msgType === 'DeleteRecord') {
+            subscriptionGroup = this.activeSubscriptionGroup;
+            const {key_id: keyId, topic_id: topicId} = message.value;
+            this.recordMap.delete(`${keyId}:${topicId}`);
+        } else if (msgType === 'BatchUpdate') {
+            subscriptionGroup = this.activeSubscriptionGroup;
+            const value = message.value;
+            const defaultClass = value.default_class;
+
+            // Check if there's a specific batch update handler
+            const batchHandlerKey = subscriptionGroup ? `BatchUpdate ${subscriptionGroup}` : 'BatchUpdate';
+            const hasBatchHandler = this.messageHandlers.has(batchHandlerKey);
+
+            // Pre-check for individual handlers if no batch handler
+            let keyHandler = null;
+            let recordHandler = null;
+            if (!hasBatchHandler) {
+                const keyHandlerKey = subscriptionGroup ? `KeyIntroduction ${subscriptionGroup}` : 'KeyIntroduction';
+                keyHandler = this.messageHandlers.get(keyHandlerKey);
+
+                const recordHandlerKey = subscriptionGroup ? `JSONRecordUpdate ${subscriptionGroup}` : 'JSONRecordUpdate';
+                recordHandler = this.messageHandlers.get(recordHandlerKey);
+            }
+
+            for (const keyUpdate of value.keys || []) {
+                const keyId = keyUpdate.key_id;
+                const keyName = keyUpdate.name;
+
+                // Handle key introduction if name is provided and key is new
+                if (keyName && !this.serverKeyIdToName.has(keyId)) {
+                    this.serverKeyIdToName.set(keyId, keyName);
+                    this.serverKeyNameToId.set(keyName, keyId);
+
+                    // If no batch handler but key handler exists, call KeyIntroduction handler
+                    if (!hasBatchHandler && keyHandler) {
+                        // Determine class_list: use key's classes, or default_class, or null
+                        let keyClasses = keyUpdate.classes;
+                        if (!keyClasses && keyUpdate.class) {
+                            keyClasses = [keyUpdate.class];
+                        } else if (!keyClasses && defaultClass) {
+                            keyClasses = [defaultClass];
+                        }
+
+                        const keyIntroMsg = {
+                            message_type: 'KeyIntroduction',
+                            value: {
+                                key_id: keyId,
+                                name: keyName,
+                                ...(keyClasses ? { class_list: keyClasses } : {}),
+                                deleted_class: null
+                            }
+                        };
+                        keyHandler(keyIntroMsg);
+                    }
+                }
+
+                // Process topics for this key - topic IDs are object keys
+                const topicsDict = keyUpdate.topics || {};
+                for (const [topicIdStr, recordValue] of Object.entries(topicsDict)) {
+                    const topicId = parseInt(topicIdStr, 10);
+                    this.recordMap.set(`${keyId}:${topicId}`, recordValue);
+
+                    // If no batch handler but record handler exists, call JSONRecordUpdate handler
+                    if (!hasBatchHandler && recordHandler) {
+                        const recordUpdateMsg = {
+                            message_type: 'JSONRecordUpdate',
+                            value: {
+                                record_id: { key_id: keyId, topic_id: topicId },
+                                value: recordValue
+                            }
+                        };
+                        recordHandler(recordUpdateMsg);
+                    }
+                }
+            }
+
+            // If there is a batch handler, call it
+            if (hasBatchHandler) {
+                const batchHandler = this.messageHandlers.get(batchHandlerKey);
+                if (batchHandler) {
+                    batchHandler(message);
+                }
+            }
+        } else if (msgType === "ActiveSubscription") {
+            this.activeSubscriptionGroup = message["value"]["subscription_group"]
+        } else if (msgType === 'Logoff') {
+            this.log('INFO', 'Received Logoff from server');
+            this.stop();
+        } else if (msgType === 'Error') {
+            this.log('ERROR', `GAR ${message.value.message}`);
+            this.exitCode = 1;
+            this.stop();
+        }
+
+        this.checkHeartbeat();
+
+        const handler = this.messageHandlers.get(subscriptionGroup ? `${msgType} ${subscriptionGroup}` : msgType);
+        if (handler) {
+            handler(message);
+        }
+    }
+
+    /**
+     * Send an already-formatted subscription message
+     * @param {object} subscriptionMessageValue - json representation of the gar `subscribe` struct
+     */
+    subscribeFormatted(subscriptionMessageValue) {
+        const subMsg = {
+            message_type: 'Subscribe',
+            value: subscriptionMessageValue,
+        };
+        this.sendMessage(subMsg);
+    }
+
+    /**
+     * Send a subscription request
+     * @param {string} name - Subscription name
+     * @param {string} [subscriptionMode='Streaming'] - Subscription mode
+     * @param {string|Array<string>|null} [keyName=null] - Key name(s)
+     * @param {string|Array<string>|null} [topicName=null] - Topic name(s)
+     * @param {string|Array<string>|null} [className=null] - Class name(s)
+     * @param {string|null} [keyFilter=null] - Key filter regex (cannot use with keyName)
+     * @param {string|null} [topicFilter=null] - Topic filter regex (cannot use with topicName)
+     * @param {string|null} [excludeKeyFilter=null] - Exclude key filter regex (cannot use with keyName)
+     * @param {string|null} [excludeTopicFilter=null] - Exclude topic filter regex (cannot use with topicName)
+     * @param {string|null} [maxHistory] - Maximum history to include
+     * @param {boolean} [includeDerived=false] - Include derived topics
+     * @param {boolean} [trimDefaultValues=false] - Trim records containing default values from the snapshot
+     * @param {string|null} [workingNamespace] - Namespace for matching relative paths
+     * @param {string|null} [restrictNamespace=false] - Restricts topics and keys to children of restrict_namespace. Defaults to the working namespace. Use "::" for root / no restriction.
+     * @param {string|null} [density] - For performance tuning
+     * @param {number} [subscriptionGroup=0] - Subscription group ID for isolating callbacks
+     * @param {string|null} [subscriptionSet] - Subscription set identifier
+     * @param {number} [snapshotSizeLimit=0] - Limit snapshot size
+     * @param {number} [nagleInterval=0] - Nagle interval in milliseconds
+     * @param {number} [limit=0] - Limits records in initial snapshot (0 = all)
+     * @param {string|Array<string>|null} [referencingClassList=null] - Referencing class name(s); if provided, include referencing keys and records per proto.gar subscribe.referencing_class_list
+     */
+    subscribe(
+        name,
+        subscriptionMode = 'Streaming',
+        keyName = null,
+        topicName = null,
+        className = null,
+        keyFilter = null,
+        topicFilter = null,
+        excludeKeyFilter = null,
+        excludeTopicFilter = null,
+        maxHistory = null,
+        includeDerived = false,
+        trimDefaultValues = false,
+        workingNamespace = null,
+        restrictNamespace = null,
+        density = null,
+        subscriptionGroup = 0,
+        subscriptionSet = null,
+        snapshotSizeLimit = 0,
+        nagleInterval = 0,
+        limit = 0,
+        referencingClassList = null
+    ) {
+        // Validate mutually exclusive parameters
+        if (keyName && (keyFilter || excludeKeyFilter)) {
+            throw new Error('keyName cannot be used with keyFilter or excludeKeyFilter');
+        }
+        
+        if (topicName && (topicFilter || excludeTopicFilter)) {
+            throw new Error('topicName cannot be used with topicFilter or excludeTopicFilter');
+        }
+
+        // Validate limit parameter usage
+        if (limit > 0 && subscriptionMode === 'Streaming') {
+            throw new Error('limit cannot be used with streaming subscriptions');
+        }
+
+        // Convert className to array
+        let classList = null;
+        if (typeof className === 'string') {
+            classList = className.split(/\s+/).filter(Boolean);
+        } else if (Array.isArray(className)) {
+            classList = className;
+        }
+
+        // Normalize referencingClassList to an array
+        let referencingClasses = null;
+        if (typeof referencingClassList === 'string') {
+            referencingClasses = referencingClassList.split(/\s+/).filter(Boolean);
+        } else if (Array.isArray(referencingClassList)) {
+            referencingClasses = referencingClassList;
+        }
+
+        let singleClass = Array.isArray(classList) && classList.length === 1 ? classList[0] : null;
+
+        // Convert keyName to array
+        let keyNames = [];
+        if (typeof keyName === 'string') {
+            keyNames = [keyName];
+        } else if (Array.isArray(keyName)) {
+            keyNames = keyName;
+        }
+        const keyIdList = keyNames.map(x => this.getAndPossiblyIntroduceKeyId(x, singleClass));
+
+        // Convert topicName to array
+        let topicNames = [];
+        if (typeof topicName === 'string') {
+            topicNames = topicName.split(/\s+/).filter(Boolean);
+        } else if (Array.isArray(topicName)) {
+            topicNames = topicName;
+        }
+        const topicIdList = topicNames.map(x => this.getAndPossiblyIntroduceTopicId(x));
+
+        // Build subscription message, filtering out null/undefined values
+        const valueDict = {
+            subscription_mode: subscriptionMode,
+            name,
+        };
+        
+        // Add optional fields only if they have values
+        if (subscriptionSet) {
+            valueDict.subscription_set = subscriptionSet;
+        }
+        if (maxHistory) {
+            valueDict.max_history = maxHistory;
+        }
+        if (snapshotSizeLimit > 0) {
+            valueDict.snapshot_size_limit = snapshotSizeLimit;
+        }
+        if (nagleInterval > 0) {
+            valueDict.nagle_interval = nagleInterval;
+        }
+        if (subscriptionGroup > 0) {
+            valueDict.subscription_group = subscriptionGroup;
+        }
+        if (density) {
+            valueDict.density = density;
+        }
+        if (includeDerived) {
+            valueDict.include_derived = includeDerived;
+        }
+        if (restrictNamespace) {
+            valueDict.restrict_namespace = restrictNamespace;
+        }
+        if (trimDefaultValues) {
+            valueDict.trim_default_values = trimDefaultValues;
+        }
+        if (limit > 0) {
+            valueDict.limit = limit;
+        }
+        if (keyIdList.length > 0) {
+            valueDict.key_id_list = keyIdList;
+        }
+        if (topicIdList.length > 0) {
+            valueDict.topic_id_list = topicIdList;
+        }
+        if (classList) {
+            valueDict.class_list = classList;
+        }
+        if (referencingClasses && referencingClasses.length > 0) {
+            valueDict.referencing_class_list = referencingClasses;
+        }
+        if (keyFilter) {
+            valueDict.key_filter = keyFilter;
+        }
+        if (excludeKeyFilter) {
+            valueDict.exclude_key_filter = excludeKeyFilter;
+        }
+        if (topicFilter) {
+            valueDict.topic_filter = topicFilter;
+        }
+        if (excludeTopicFilter) {
+            valueDict.exclude_topic_filter = excludeTopicFilter;
+        }
+        if (workingNamespace) {
+            valueDict.working_namespace = workingNamespace;
+        }
+
+        this.subscribeFormatted(valueDict);
+    }
+
+    /**
+     * Wrapper to `subscribe` with a smaller set of arguments.
+     * @param {string} name - Subscription name
+     * @param {string} [subscriptionMode='Streaming'] - Subscription mode
+     * @param {number} [subscriptionGroup=0] - Subscription group ID for isolating callbacks
+     * @param {number} [snapshotSizeLimit=0] - Limit snapshot size
+     * @param {string|Array<string>|null} [keyName=null] - Key name(s)
+     * @param {string|Array<string>|null} [topicName=null] - Topic name(s)
+     * @param {string|Array<string>|null} [className=null] - Class name(s)
+     * @param {string|null} [keyFilter=null] - Key filter regex (cannot use with keyName)
+     * @param {string|null} [topicFilter=null] - Topic filter regex (cannot use with topicName)
+     * @param {string|null} [excludeKeyFilter=null] - Exclude key filter regex (cannot use with keyName)
+     * @param {string|null} [excludeTopicFilter=null] - Exclude topic filter regex (cannot use with topicName)
+     */
+    subscribeCommon(
+        name,
+        subscriptionMode = 'Streaming',
+        subscriptionGroup = 0,
+        snapshotSizeLimit = 0,
+        keyName = null,
+        topicName = null,
+        className = null,
+        keyFilter = null,
+        topicFilter = null,
+        excludeKeyFilter = null,
+        excludeTopicFilter = null,
+    ) {
+        this.subscribe(
+            name,
+            subscriptionMode,
+            keyName,
+            topicName,
+            className,
+            keyFilter,
+            topicFilter,
+            excludeKeyFilter,
+            excludeTopicFilter,
+            null,
+            false,
+            false,
+            null,
+            null,
+            null,
+            subscriptionGroup,
+            null,
+            snapshotSizeLimit
+        );
+    }
+
+    /**
+     * Introduce a new key if not already known and return local key ID.
+     * @param {string} name - Key name
+     * @param {string|Array<string>|null} [className=null] - Class name(s)
+     * @returns {number} Local key ID
+     */
+    getAndPossiblyIntroduceKeyId(name, className = null) {
+        if (!this.localKeyMap.has(name)) {
+            const keyId = this.localKeyCounter++;
+            this.localKeyMap.set(name, keyId);
+            let classList = null;
+            if (className) {
+                if (typeof className === 'string') {
+                    classList = className.split(/\s+/).filter(Boolean);
+                } else if (Array.isArray(className)) {
+                    classList = className;
+                }
+            }
+            const msg = {
+                message_type: 'KeyIntroduction',
+                value: {
+                    key_id: keyId,
+                    name
+                }
+            };
+            if (classList) {
+                msg.value.class_list = classList;
+            }
+            this.sendMessage(msg);
+        }
+        return this.localKeyMap.get(name);
+    }
+
+    /**
+     * Introduce a new topic if not already known and return local topic ID.
+     * @param {string} name - Topic name
+     * @returns {number} Local topic ID
+     */
+    getAndPossiblyIntroduceTopicId(name) {
+        if (!this.localTopicMap.has(name)) {
+            const topicId = this.localTopicCounter++;
+            this.localTopicMap.set(name, topicId);
+            const msg = {
+                message_type: 'TopicIntroduction',
+                value: {
+                    topic_id: topicId,
+                    name
+                }
+            };
+            this.sendMessage(msg);
+        }
+        return this.localTopicMap.get(name);
+    }
+
+    /**
+     * Publish a DeleteKey message using a local key ID.
+     * @param {number} keyId - Key ID
+     */
+    publishDeleteKey(keyId) {
+        const msg = {
+            message_type: 'DeleteKey',
+            value: { key_id: keyId }
+        };
+        this.sendMessage(msg);
+    }
+
+    /**
+     * Delete a key by name if it exists in the localKeyMap. Safe to call multiple times.
+     * @param {string} keyName - Key name
+     */
+    deleteKey(keyName) {
+        const keyId = this.localKeyMap.get(keyName);
+        if (keyId) {
+            this.publishDeleteKey(keyId);
+        }
+    }
+
+    /**
+     * Publish a DeleteRecord message using local key and topic IDs.
+     * @param {number} keyId - Key ID
+     * @param {number} topicId - Topic ID
+     */
+    publishDeleteRecord(keyId, topicId) {
+        const msg = {
+            message_type: 'DeleteRecord',
+            value: { key_id: keyId, topic_id: topicId }
+        };
+        this.sendMessage(msg);
+    }
+
+    /**
+     * Publish an Unsubscribe message for a subscription name.
+     * @param {string} name - Subscription name
+     */
+    publishUnsubscribe(name) {
+        const msg = {
+            message_type: 'Unsubscribe',
+            value: { name }
+        };
+        this.sendMessage(msg);
+    }
+
+    /**
+     * Publish a Shutdown message.
+     */
+    publishShutdown() {
+        const msg = { message_type: 'Shutdown' };
+        this.sendMessage(msg);
+    }
+
+    /**
+     * Publish a record update using explicit key and topic IDs.
+     * @param {number} keyId - Key ID
+     * @param {number} topicId - Topic ID
+     * @param {any} value - JSON-serializable value
+     */
+    publishRecordWithIds(keyId, topicId, value) {
+        const updateMsg = {
+            message_type: 'JSONRecordUpdate',
+            value: {
+                record_id: { key_id: keyId, topic_id: topicId },
+                value
+            }
+        };
+        this.sendMessage(updateMsg);
+    }
+
+    /**
+     * Publish a record update using names, converting to local IDs.
+     * @param {string} keyName - Key name
+     * @param {string} topicName - Topic name
+     * @param {any} value - JSON-serializable value
+     * @param {string|null} [className=null] - Class name
+     */
+    publishRecord(keyName, topicName, value, className = null) {
+        const keyId = this.getAndPossiblyIntroduceKeyId(keyName, className);
+        const topicId = this.getAndPossiblyIntroduceTopicId(topicName);
+        this.publishRecordWithIds(keyId, topicId, value);
+    }
+
+    /**
+     * Send a compare-exchange using explicit key and topic IDs.
+     * @param {number} keyId - Key ID
+     * @param {number} topicId - Topic ID
+     * @param {any} test - Expected current value (null = expect missing/empty)
+     * @param {any} value - New value to set on match
+     */
+    compareExchangeRecordWithIds(keyId, topicId, test, value) {
+        this.sendMessage({
+            message_type: 'JSONCompareExchange',
+            value: { record_id: { key_id: keyId, topic_id: topicId }, test, value }
+        });
+    }
+
+    /**
+     * Send a compare-exchange using names, converting to local IDs.
+     * @param {string} keyName - Key name
+     * @param {string} topicName - Topic name
+     * @param {any} test - Expected current value (null = expect missing/empty)
+     * @param {any} value - New value to set on match
+     * @param {string|null} [className=null] - Class name
+     */
+    compareExchangeRecord(keyName, topicName, test, value, className = null) {
+        const keyId = this.getAndPossiblyIntroduceKeyId(keyName, className);
+        const topicId = this.getAndPossiblyIntroduceTopicId(topicName);
+        this.compareExchangeRecordWithIds(keyId, topicId, test, value);
+    }
+
+    /**
+     * Query GAR deployment routing to find servers with matching publications.
+     * Mirrors the Python client's route_query implementation.
+     *
+     * @param {Array<string>|null} [keyList]
+     * @param {Array<string>|null} [topicList]
+     * @param {Array<string>|null} [classList]
+     * @param {string|null} [keyFilter]
+     * @param {string|null} [excludeKeyFilter]
+     * @param {string|null} [topicFilter]
+     * @param {string|null} [excludeTopicFilter]
+     * @param {Array<string>|null} [historyTypes]
+     * @param {string|null} [workingNamespace]
+     * @param {string|null} [restrictNamespace]
+     * @param {string|null} [excludeNamespace]
+     * @param {boolean} [includeDerived=false]
+     * @param {number} [timeout=10.0] seconds
+     * @param {number} [subscriptionGroupServerKeys=650704]
+     * @param {number} [subscriptionGroupServerRecords=650705]
+     * @returns {Promise<Object|null>} Resolves to a map of server -> topic -> value, or null on timeout
+     */
+    route_query(
+        keyList = null,
+        topicList = null,
+        classList = null,
+        keyFilter = null,
+        excludeKeyFilter = null,
+        topicFilter = null,
+        excludeTopicFilter = null,
+        historyTypes = null,
+        workingNamespace = null,
+        restrictNamespace = null,
+        excludeNamespace = null,
+        includeDerived = false,
+        timeout = 10.0,
+        subscriptionGroupServerKeys = 650704,
+        subscriptionGroupServerRecords = 650705,
+    ) {
+        // Generate a unique key for this query
+        const queryKey = (typeof crypto !== 'undefined' && crypto.randomUUID)
+            ? crypto.randomUUID()
+            : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+
+        // Build record_filter value and remove null/undefined
+        const recordFilter = {};
+        if (Array.isArray(keyList)) recordFilter.key_list = keyList;
+        if (Array.isArray(topicList)) recordFilter.topic_list = topicList;
+        if (Array.isArray(classList)) recordFilter.class_list = classList;
+        if (workingNamespace != null) recordFilter.working_namespace = workingNamespace;
+        if (restrictNamespace != null) recordFilter.restrict_namespace = restrictNamespace;
+        if (excludeNamespace != null) recordFilter.exclude_namespace = excludeNamespace;
+        if (keyFilter != null) recordFilter.key_filter_regex = keyFilter;
+        if (excludeKeyFilter != null) recordFilter.exclude_key_filter_regex = excludeKeyFilter;
+        if (topicFilter != null) recordFilter.topic_filter_regex = topicFilter;
+        if (excludeTopicFilter != null) recordFilter.exclude_topic_filter_regex = excludeTopicFilter;
+        if (includeDerived) recordFilter.include_derived = includeDerived;
+        if (Array.isArray(historyTypes)) recordFilter.history_types = historyTypes;
+
+        const resultContainer = { };
+
+        const cleanup = () => {
+            this.deleteKey(queryKey);
+        };
+
+        return new Promise((resolve) => {
+            let resolved = false;
+            const finish = (result) => {
+                if (!resolved) {
+                    resolved = true;
+                    resolve(result);
+                }
+            };
+
+            const handleServers = (serversValue) => {
+                if (!serversValue || serversValue.length === 0) {
+                    resultContainer.servers = {};
+                    finish({});
+                    cleanup();
+                    return;
+                }
+
+                // Subscribe to Server records for the returned server keys
+                const subName = `route_query_servers_${queryKey}`;
+
+                const processServerRecords = (keyId, topicId, value) => {
+                    const keyName = this.serverKeyIdToName.get(keyId);
+                    const topicName = this.serverTopicIdToName.get(topicId);
+                    if (!resultContainer.servers) resultContainer.servers = {};
+                    if (!resultContainer.servers[keyName]) resultContainer.servers[keyName] = {};
+                    resultContainer.servers[keyName][topicName] = value;
+                };
+
+                const onServerStatus = (_name, status) => {
+                    if (status === 'Finished' || status === 'Streaming') {
+                        finish(resultContainer.servers || {});
+                        cleanup();
+                    }
+                };
+
+                this.registerRecordUpdateHandler(processServerRecords, subscriptionGroupServerRecords);
+                this.registerSubscriptionStatusHandler(onServerStatus, subscriptionGroupServerRecords);
+
+                this.subscribe(
+                    subName,
+                    'Snapshot',
+                    serversValue,
+                    null,
+                    'g::deployment::Server',
+                    null,
+                    null,
+                    null,
+                    null,
+                    null,
+                    true,
+                    false,
+                    'g::deployment::Server',
+                    null,
+                    null,
+                    subscriptionGroupServerRecords,
+                );
+            };
+
+            const processRecordFilter = (_keyId, _topicId, value) => {
+                resultContainer.servers = {};
+                handleServers(value);
+            };
+
+            const onRecordFilterStatus = (_name, status) => {
+                if (status === 'Finished' || status === 'Streaming') {
+                    if (!('servers' in resultContainer)) {
+                        finish({});
+                        cleanup();
+                    }
+                }
+            };
+
+            // Set up handlers for RecordFilter result
+            this.registerRecordUpdateHandler(processRecordFilter, subscriptionGroupServerKeys);
+            this.registerSubscriptionStatusHandler(onRecordFilterStatus, subscriptionGroupServerKeys);
+
+            // Publish the RecordFilter record
+            this.publishRecord(
+                queryKey,
+                'g::deployment::RecordFilter::record_filter',
+                recordFilter,
+                'g::deployment::RecordFilter',
+            );
+
+            // Subscribe to get the servers result
+            const subName = `route_query_${queryKey}`;
+            this.subscribe(
+                subName,
+                'Snapshot',
+                queryKey,
+                'g::deployment::RecordFilter::servers',
+                'g::deployment::RecordFilter',
+                null,
+                null,
+                null,
+                null,
+                null,
+                true,
+                false,
+                'g::deployment::RecordFilter',
+                null,
+                null,
+                subscriptionGroupServerKeys,
+            );
+
+            // Timeout handling
+            setTimeout(() => {
+                if (!resolved) {
+                    this.log('ERROR', 'route_query timed out');
+                    cleanup();
+                    finish(null);
+                }
+            }, Math.max(0, Math.floor(timeout * 1000)));
+        });
+    }
+
+    static _generateUUID() {
+        const bytes = new Uint8Array(16);
+        if (typeof globalThis.crypto !== 'undefined' && globalThis.crypto.getRandomValues)
+            globalThis.crypto.getRandomValues(bytes);
+        else
+            require('crypto').randomFillSync(bytes);
+        bytes[6] = (bytes[6] & 0x0f) | 0x40; // version 4
+        bytes[8] = (bytes[8] & 0x3f) | 0x80; // variant RFC 4122
+        const view = new DataView(bytes.buffer);
+        return { low: Number(view.getBigUint64(0, true)), high: Number(view.getBigUint64(8, true)) };
+    }
+}
+
+export default GARClient;