@xh/hoist 73.0.0-SNAPSHOT.1744325910318 → 73.0.0-SNAPSHOT.1744391471093

package/svc/WebSocketService.ts

@@ -4,8 +4,8 @@
  *
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
-import {HoistService, XH} from '@xh/hoist/core';
-import {Icon} from '@xh/hoist/icon';
+import {HoistService, PlainObject, XH} from '@xh/hoist/core';
+import {withFormattedTimestamps} from '@xh/hoist/format';
 import {action, makeObservable, observable} from '@xh/hoist/mobx';
 import {Timer} from '@xh/hoist/utils/async';
 import {SECONDS} from '@xh/hoist/utils/datetime';
@@ -43,13 +43,14 @@ export class WebSocketService extends HoistService {
     readonly FORCE_APP_SUSPEND_TOPIC = 'xhForceAppSuspend';
     readonly REQ_CLIENT_HEALTH_RPT_TOPIC = 'xhRequestClientHealthReport';
 
+    /** True if WebSockets generally enabled - set statically in code via {@link AppSpec}. */
+    enabled: boolean = XH.appSpec.webSocketsEnabled;
+
     /** Unique channel assigned by server upon successful connection. */
-    @observable
-    channelKey: string = null;
+    @observable channelKey: string = null;
 
     /** Last time a message was received, including heartbeat messages. */
-    @observable
-    lastMessageTime: Date = null;
+    @observable lastMessageTime: Date = null;
 
     /** Observable flag indicating service is connected and available for use. */
     get connected(): boolean {
@@ -59,11 +60,11 @@ export class WebSocketService extends HoistService {
     /** Set to true to log all sent/received messages - very chatty. */
     logMessages: boolean = false;
 
+    telemetry: WebSocketTelemetry = null;
+
     private _timer: Timer;
     private _socket: WebSocket;
-    private _subsByTopic = {};
-
-    enabled: boolean = XH.appSpec.webSocketsEnabled;
+    private _subsByTopic: Record<string, WebSocketSubscription[]> = {};
 
     constructor() {
         super();
@@ -72,6 +73,7 @@ export class WebSocketService extends HoistService {
 
     override async initAsync() {
         if (!this.enabled) return;
+
         const {environmentService} = XH;
         if (environmentService.get('webSocketsEnabled') === false) {
             this.logError(
@@ -80,6 +82,7 @@ export class WebSocketService extends HoistService {
             this.enabled = false;
             return;
         }
+        this.telemetry = {channelKey: null, subscriptionCount: 0, events: {}};
 
         this.connect();
 
@@ -112,6 +115,7 @@ export class WebSocketService extends HoistService {
 
         const newSub = new WebSocketSubscription(topic, fn);
         subs.push(newSub);
+        this.telemetry.subscriptionCount++;
         return newSub;
     }
 
@@ -123,6 +127,7 @@ export class WebSocketService extends HoistService {
     unsubscribe(subscription: WebSocketSubscription) {
         const subs = this.getSubsForTopic(subscription.topic);
         pull(subs, subscription);
+        this.telemetry.subscriptionCount--;
     }
 
     /**
@@ -133,13 +138,24 @@ export class WebSocketService extends HoistService {
         throwIf(!this.connected, 'Unable to send message via websocket - not connected.');
 
         this._socket.send(JSON.stringify(message));
+
+        this.noteTelemetryEvent('msgSent');
         this.maybeLogMessage('Sent message', message);
     }
 
+    shutdown() {
+        if (this._timer) this._timer.cancel();
+        this.disconnect();
+    }
+
+    getFormattedTelemetry(): PlainObject {
+        return withFormattedTimestamps(this.telemetry);
+    }
+
     //------------------------
     // Implementation
     //------------------------
-    connect() {
+    private connect() {
         try {
             // Create new socket and wire up events.  Be sure to ignore obsolete sockets
             const s = new WebSocket(this.buildWebSocketUrl());
@@ -163,7 +179,7 @@ export class WebSocketService extends HoistService {
         this.updateConnectedStatus();
     }
 
-    disconnect() {
+    private disconnect() {
         if (this._socket) {
             this._socket.close();
             this._socket = null;
@@ -171,12 +187,13 @@ export class WebSocketService extends HoistService {
         this.updateConnectedStatus();
     }
 
-    heartbeatOrReconnect() {
+    private heartbeatOrReconnect() {
         this.updateConnectedStatus();
         if (this.connected) {
             this.sendMessage({topic: this.HEARTBEAT_TOPIC, data: 'ping'});
         } else {
             this.logWarn('Heartbeat found websocket not connected - attempting to reconnect...');
+            this.noteTelemetryEvent('heartbeatReconnectAttempt');
             this.disconnect();
             this.connect();
         }
@@ -184,30 +201,29 @@ export class WebSocketService extends HoistService {
 
     private onServerInstanceChange() {
         this.logWarn('Server instance changed - attempting to connect to new instance.');
+        this.noteTelemetryEvent('instanceChangeReconnectAttempt');
         this.disconnect();
         this.connect();
     }
 
-    shutdown() {
-        if (this._timer) this._timer.cancel();
-        this.disconnect();
-    }
-
     //------------------------
     // Socket events impl
     //------------------------
     onOpen(ev) {
         this.logDebug('WebSocket connection opened', ev);
+        this.noteTelemetryEvent('connOpened');
         this.updateConnectedStatus();
     }
 
     onClose(ev) {
         this.logDebug('WebSocket connection closed', ev);
+        this.noteTelemetryEvent('connClosed');
         this.updateConnectedStatus();
     }
 
     onError(ev) {
         this.logError('WebSocket connection error', ev);
+        this.noteTelemetryEvent('connError');
         this.updateConnectedStatus();
     }
 
@@ -219,6 +235,7 @@ export class WebSocketService extends HoistService {
             // Record arrival
             this.updateLastMessageTime();
             this.maybeLogMessage('Received message', rawMsg);
+            this.noteTelemetryEvent('msgReceived');
 
             // Hoist and app handling
             switch (topic) {
@@ -244,7 +261,7 @@ export class WebSocketService extends HoistService {
     //------------------------
     // Subscription impl
     //------------------------
-    notifySubscribers(message) {
+    private notifySubscribers(message) {
         const subs = this.getSubsForTopic(message.topic);
 
         subs.forEach(sub => {
@@ -256,7 +273,7 @@ export class WebSocketService extends HoistService {
         });
     }
 
-    getSubsForTopic(topic): WebSocketSubscription[] {
+    private getSubsForTopic(topic: string): WebSocketSubscription[] {
         let ret = this._subsByTopic[topic];
         if (!ret) {
             ret = this._subsByTopic[topic] = [];
@@ -267,7 +284,7 @@ export class WebSocketService extends HoistService {
     //------------------------
     // Other impl
     //------------------------
-    updateConnectedStatus() {
+    private updateConnectedStatus() {
         const socketOpen = this._socket?.readyState === WebSocket.OPEN;
         if (!socketOpen && this.channelKey) {
             this.installChannelKey(null);
@@ -275,16 +292,17 @@ export class WebSocketService extends HoistService {
     }
 
     @action
-    installChannelKey(key) {
+    private installChannelKey(key: string) {
         this.channelKey = key;
+        this.telemetry.channelKey = key;
     }
 
     @action
-    updateLastMessageTime() {
+    private updateLastMessageTime() {
         this.lastMessageTime = new Date();
     }
 
-    buildWebSocketUrl() {
+    private buildWebSocketUrl() {
         const protocol = window.location.protocol == 'https:' ? 'wss:' : 'ws:',
             endpoint = 'xhWebSocket?clientAppVersion=' + XH.appVersion;
         return XH.isDevelopmentMode
@@ -292,16 +310,14 @@ export class WebSocketService extends HoistService {
             : `${protocol}//${window.location.host}${XH.baseUrl}${endpoint}`;
     }
 
-    showTestMessageAlert(message) {
-        XH.alert({
-            title: 'Test Message',
-            icon: Icon.bullhorn(),
-            message
-        });
+    private maybeLogMessage(...args) {
+        if (this.logMessages) this.logDebug(args);
     }
 
-    maybeLogMessage(...args) {
-        if (this.logMessages) this.logDebug(args);
+    private noteTelemetryEvent(eventKey: keyof WebSocketTelemetry['events']) {
+        const evtTel = (this.telemetry.events[eventKey] ??= {count: 0, lastTime: null});
+        evtTel.count++;
+        evtTel.lastTime = Date.now();
     }
 }
 
@@ -327,3 +343,23 @@ export interface WebSocketMessage {
     topic: string;
     data?: any;
 }
+
+/** Telemetry collected by this service + included in {@link ClientHealthService} reporting. */
+export interface WebSocketTelemetry {
+    channelKey: string;
+    subscriptionCount: number;
+    events: {
+        connOpened?: WebSocketEventTelemetry;
+        connClosed?: WebSocketEventTelemetry;
+        connError?: WebSocketEventTelemetry;
+        msgReceived?: WebSocketEventTelemetry;
+        msgSent?: WebSocketEventTelemetry;
+        heartbeatReconnectAttempt?: WebSocketEventTelemetry;
+        instanceChangeReconnectAttempt?: WebSocketEventTelemetry;
+    };
+}
+
+export interface WebSocketEventTelemetry {
+    count: number;
+    lastTime: number;
+}