@xh/hoist 72.3.0 → 72.5.0

package/svc/TrackService.ts

@@ -5,11 +5,10 @@
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
 import {HoistService, PlainObject, TrackOptions, XH} from '@xh/hoist/core';
-import {Timer} from '@xh/hoist/utils/async';
-import {MINUTES, SECONDS} from '@xh/hoist/utils/datetime';
+import {SECONDS} from '@xh/hoist/utils/datetime';
 import {isOmitted} from '@xh/hoist/utils/impl';
-import {debounced, getClientDeviceInfo, stripTags, withDefault} from '@xh/hoist/utils/js';
-import {isEmpty, isNil, isString, round} from 'lodash';
+import {debounced, stripTags, withDefault} from '@xh/hoist/utils/js';
+import {isEmpty, isNil, isString} from 'lodash';
 
 /**
  * Primary service for tracking any activity that an application's admins want to track.
@@ -19,21 +18,10 @@ import {isEmpty, isNil, isString, round} from 'lodash';
 export class TrackService extends HoistService {
     static instance: TrackService;
 
-    private clientHealthReportSources: Map<string, () => any> = new Map();
     private oncePerSessionSent = new Map();
     private pending: PlainObject[] = [];
 
     override async initAsync() {
-        const {clientHealthReport} = this.conf;
-        if (clientHealthReport?.intervalMins > 0) {
-            Timer.create({
-                runFn: () => this.sendClientHealthReport(),
-                interval: clientHealthReport.intervalMins,
-                intervalUnits: MINUTES,
-                delay: true
-            });
-        }
-
         window.addEventListener('beforeunload', () => this.pushPendingAsync());
     }
 
@@ -103,25 +91,10 @@ export class TrackService extends HoistService {
     }
 
     /**
-     * Register a new source for client health report data. No-op if background health report is
-     * not generally enabled via `xhActivityTrackingConfig.clientHealthReport.intervalMins`.
-     *
-     * @param key - key under which to report the data - can be used to remove this source later.
-     * @param callback - function returning serializable to include with each report.
+     * Flush the queue of pending activity tracking messages to the server.
+     * @internal - apps should generally allow this service to manage w/its internal debounce.
      */
-    addClientHealthReportSource(key: string, callback: () => any) {
-        this.clientHealthReportSources.set(key, callback);
-    }
-
-    /** Unregister a previously-enabled source for client health report data. */
-    removeClientHealthReportSource(key: string) {
-        this.clientHealthReportSources.delete(key);
-    }
-
-    //------------------
-    // Implementation
-    //------------------
-    private async pushPendingAsync() {
+    async pushPendingAsync() {
         const {pending} = this;
         if (isEmpty(pending)) return;
 
@@ -133,6 +106,9 @@ export class TrackService extends HoistService {
         });
     }
 
+    //------------------
+    // Implementation
+    //------------------
     @debounced(10 * SECONDS)
     private pushPendingBuffered() {
         this.pushPendingAsync();
@@ -176,42 +152,6 @@ export class TrackService extends HoistService {
 
         this.logInfo(...consoleMsgs);
     }
-
-    private sendClientHealthReport() {
-        const {
-                intervalMins,
-                severity: defaultSeverity,
-                ...rest
-            } = this.conf.clientHealthReport ?? {},
-            {loadStarted} = XH.appContainerModel.appStateModel;
-
-        const data = {
-            session: {
-                started: loadStarted,
-                durationMins: round((Date.now() - loadStarted) / 60_000, 1)
-            },
-            ...getClientDeviceInfo()
-        };
-
-        let severity = defaultSeverity ?? 'INFO';
-        this.clientHealthReportSources.forEach((cb, k) => {
-            try {
-                data[k] = cb();
-                if (data[k]?.severity === 'WARN') severity = 'WARN';
-            } catch (e) {
-                data[k] = `Error: ${e.message}`;
-                this.logWarn(`Error running client health report callback for [${k}]`, e);
-            }
-        });
-
-        this.track({
-            category: 'App',
-            message: 'Submitted health report',
-            severity,
-            ...rest,
-            data
-        });
-    }
 }
 
 interface ActivityTrackingConfig {

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';
@@ -41,14 +41,17 @@ export class WebSocketService extends HoistService {
     readonly HEARTBEAT_TOPIC = 'xhHeartbeat';
     readonly REG_SUCCESS_TOPIC = 'xhRegistrationSuccess';
     readonly FORCE_APP_SUSPEND_TOPIC = 'xhForceAppSuspend';
+    readonly REQ_CLIENT_HEALTH_RPT_TOPIC = 'xhRequestClientHealthReport';
+    readonly METADATA_FOR_HANDSHAKE = ['appVersion', 'appBuild', 'loadId', 'tabId'];
+
+    /** 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 {
@@ -58,11 +61,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();
@@ -71,6 +74,7 @@ export class WebSocketService extends HoistService {
 
     override async initAsync() {
         if (!this.enabled) return;
+
         const {environmentService} = XH;
         if (environmentService.get('webSocketsEnabled') === false) {
             this.logError(
@@ -79,6 +83,7 @@ export class WebSocketService extends HoistService {
             this.enabled = false;
             return;
         }
+        this.telemetry = {channelKey: null, subscriptionCount: 0, events: {}};
 
         this.connect();
 
@@ -111,6 +116,7 @@ export class WebSocketService extends HoistService {
 
         const newSub = new WebSocketSubscription(topic, fn);
         subs.push(newSub);
+        this.telemetry.subscriptionCount++;
         return newSub;
     }
 
@@ -122,6 +128,7 @@ export class WebSocketService extends HoistService {
     unsubscribe(subscription: WebSocketSubscription) {
         const subs = this.getSubsForTopic(subscription.topic);
         pull(subs, subscription);
+        this.telemetry.subscriptionCount--;
     }
 
     /**
@@ -132,13 +139,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());
@@ -162,7 +180,7 @@ export class WebSocketService extends HoistService {
         this.updateConnectedStatus();
     }
 
-    disconnect() {
+    private disconnect() {
         if (this._socket) {
             this._socket.close();
             this._socket = null;
@@ -170,12 +188,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();
         }
@@ -183,34 +202,33 @@ 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();
     }
 
-    onMessage(rawMsg) {
+    onMessage(rawMsg: MessageEvent) {
         try {
             const msg = JSON.parse(rawMsg.data),
                 {topic, data} = msg;
@@ -218,6 +236,7 @@ export class WebSocketService extends HoistService {
             // Record arrival
             this.updateLastMessageTime();
             this.maybeLogMessage('Received message', rawMsg);
+            this.noteTelemetryEvent('msgReceived');
 
             // Hoist and app handling
             switch (topic) {
@@ -228,6 +247,9 @@ export class WebSocketService extends HoistService {
                     XH.suspendApp({reason: 'SERVER_FORCE', message: data});
                     XH.track({category: 'App', message: 'App suspended via WebSocket'});
                     break;
+                case this.REQ_CLIENT_HEALTH_RPT_TOPIC:
+                    XH.clientHealthService.sendReportAsync();
+                    break;
             }
 
             this.notifySubscribers(msg);
@@ -240,7 +262,7 @@ export class WebSocketService extends HoistService {
     //------------------------
     // Subscription impl
     //------------------------
-    notifySubscribers(message) {
+    private notifySubscribers(message) {
         const subs = this.getSubsForTopic(message.topic);
 
         subs.forEach(sub => {
@@ -252,7 +274,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] = [];
@@ -263,7 +285,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);
@@ -271,33 +293,32 @@ 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;
+            endpoint = `xhWebSocket?${this.METADATA_FOR_HANDSHAKE.map(key => `${key}=${XH[key]}`).join('&')}`;
         return XH.isDevelopmentMode
             ? `${protocol}//${XH.baseUrl.split('//')[1]}${endpoint}`
             : `${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();
     }
 }
 
@@ -323,3 +344,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;
+}

package/svc/index.ts

@@ -19,5 +19,6 @@ export * from './JsonBlobService';
 export * from './PrefService';
 export * from './TrackService';
 export * from './WebSocketService';
+export * from './ClientHealthService';
 export * from './storage/LocalStorageService';
 export * from './storage/SessionStorageService';