jsgar 3.4.1 → 3.7.1

package/dist/gar.umd.js

@@ -25,12 +25,10 @@
      * protocol specifications and usage instructions.
      */
 
-    //for browser:
-    const WebSocket = window.WebSocket;
-
-    // for Node.js:
-    // import ws from 'ws';
-    // const WebSocket = ws;
+    // 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 {
         /**
@@ -90,6 +88,11 @@
             }
 
             this.registerDefaultHandlers();
+
+            // First-heartbeat latch: resolved on the first Heartbeat after an Introduction
+            this._firstHeartbeatResolve = null;
+            this._firstHeartbeatPromise = null;
+            this._resetFirstHeartbeatLatch();
         }
 
         /**
@@ -135,6 +138,9 @@
             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.
         }
 
         /**
@@ -149,20 +155,13 @@
 
             while (this.running && !this.connected) {
                 try {
-                    if (this.allowSelfSignedCertificate) {
-                        const isNode =
-                            typeof process !== "undefined" &&
-                            process.versions != null &&
-                            process.versions.node != null;
-                        console.assert(isNode, "Self-signed certificates are not supported in the browser.");
-                        this.websocket = new WebSocket(
-                            this.wsEndpoint,
-                            ['gar-protocol'],
-                            { rejectUnauthorized: false }
-                        );
-                    }
-                    else {
-                        this.websocket = new WebSocket(this.wsEndpoint, ['gar-protocol']);
+                    const WS = await this._ensureWebSocketCtor();
+                    const isNode = typeof process !== 'undefined' && process.versions && process.versions.node;
+                    if (this.allowSelfSignedCertificate && isNode) {
+                        // Node.js 'ws' supports options for TLS; browsers do not.
+                        this.websocket = new WS(this.wsEndpoint, ['gar-protocol'], { rejectUnauthorized: false });
+                    } else {
+                        this.websocket = new WS(this.wsEndpoint, ['gar-protocol']);
                     }
                     this.websocket.onopen = () => {
                         this.connected = true;
@@ -212,7 +211,7 @@
                 try {
                     const message = this.messageQueue.shift();
                     if (message === null) break;
-                    if (this.websocket && this.websocket.readyState === WebSocket.OPEN) {
+                    if (this._isSocketOpen()) {
                         this.websocket.send(JSON.stringify(message));
                         this.log('DEBUG', `Sent: ${JSON.stringify(message)}`);
                     }
@@ -340,13 +339,19 @@
         /**
          * Register handler for SubscriptionStatus message.
          * @param {Function} handler - Callback with (name, status)
+         * @param {number} [subscriptionGroup=0] - The subscription group for callback
          */
-        registerSubscriptionStatusHandler(handler) {
-            this.registerHandler('SubscriptionStatus', (msg) => handler(msg.value.name, msg.value.status));
+        registerSubscriptionStatusHandler(handler, subscriptionGroup = 0) {
+            this.registerHandler('SubscriptionStatus', (msg) => handler(msg.value.name, msg.value.status), subscriptionGroup);
         }
 
-        clearSubscriptionStatusHandler() {
-            this.messageHandlers.delete('SubscriptionStatus');
+        /**
+         * 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);
         }
 
         /**
@@ -495,7 +500,7 @@
                 this.messageQueue = [];
             }
 
-            if (this.websocket && this.websocket.readyState === WebSocket.OPEN) {
+            if (this.websocket && this.websocket.readyState === 1) {
                 this.websocket.close();
             }
             this.messageQueue = [];
@@ -505,6 +510,35 @@
             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.
          */
@@ -567,6 +601,49 @@
             }
         }
 
+        /**
+         * 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
@@ -588,6 +665,10 @@
             } 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') {
@@ -601,12 +682,18 @@
                 this.lastHeartbeatTime = Date.now() / 1000;
                 this._initialGracePeriod = true;
                 this._initialGraceDeadline = this.lastHeartbeatTime + this.heartbeatTimeout * 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 === '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;
@@ -733,8 +820,6 @@
          * @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} [includeReferencedKeys=false] - Add keys from key references in matched records
-         * @param {boolean} [includeReferencingKeys=false] - Add keys that have one or more records referencing any matched keys
          * @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
@@ -757,8 +842,6 @@
             excludeKeyFilter = null,
             excludeTopicFilter = null,
             maxHistory = null,
-            includeReferencedKeys = false,
-            includeReferencingKeys = false,
             includeDerived = false,
             trimDefaultValues = false,
             workingNamespace = null,
@@ -837,12 +920,6 @@
             if (density) {
                 valueDict.density = density;
             }
-            if (includeReferencedKeys) {
-                valueDict.include_referenced_keys = includeReferencedKeys;
-            }
-            if (includeReferencingKeys) {
-                valueDict.include_referencing_keys = includeReferencingKeys;
-            }
             if (includeDerived) {
                 valueDict.include_derived = includeDerived;
             }
@@ -923,8 +1000,6 @@
                 null,
                 false,
                 false,
-                false,
-                false,
                 null,
                 null,
                 null,
@@ -1062,6 +1137,189 @@
             const topicId = this.getAndPossiblyIntroduceTopicId(topicName);
             this.publishRecordWithIds(keyId, topicId, 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 = () => {
+                const keyId = this.localKeyMap.get(queryKey);
+                if (keyId) {
+                    this.publishDeleteKey(keyId);
+                }
+            };
+
+            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)));
+            });
+        }
     }
 
     return GARClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsgar",
-  "version": "3.4.1",
+  "version": "3.7.1",
   "description": "A Javascript client for the GAR protocol",
   "type": "module",
   "main": "dist/gar.umd.js",
@@ -19,15 +19,15 @@
   "license": "MIT",
   "dependencies": {
     "winston": "^3.17.0",
-    "ws": "^8.18.1",
+    "ws": "^8.18.3",
     "yargs": "^17.7.2"
   },
   "devDependencies": {
     "@eslint/js": "^9.25.0",
-    "@eslint/json": "^0.12.0",
+    "@eslint/json": "^0.13.2",
     "@rollup/plugin-commonjs": "^24.0.0",
     "@rollup/plugin-node-resolve": "^15.0.0",
-    "eslint": "^9.33.0",
+    "eslint": "^9.38.0",
     "globals": "^16.0.0",
     "rollup": "^3.0.0"
   }