feat: add structured status messages for WebSocket Client integration

Author: rjmunro

packages/timeline-state-resolver-types/src/__tests__/__snapshots__/index.spec.ts.snap

@@ -126,6 +126,8 @@ exports[`index imports 1`] = `
   "VizMSEStatusCode",
   "VizMSEStatusMessages",
   "VmixActions",
+  "WebSocketClientStatusCode",
+  "WebSocketClientStatusMessages",
   "WebsocketClientActions",
   "fillStateFromDatastore",
   "interpolateTemplateString",

packages/timeline-state-resolver-types/src/integrations/websocketClient.ts

@@ -1,4 +1,5 @@
 import { DeviceType } from '../generated/index.js'
+import type { DeviceStatusDetail } from '../deviceStatusDetail.js'
 
 export enum TimelineContentTypeWebSocketClient {
 	WEBSOCKET_MESSAGE = 'websocketMessage',
@@ -16,3 +17,29 @@ export interface TimelineContentWebSocketMessage extends TimelineContentWebSocke
 }
 
 export type TimelineContentWebSocketClientAny = TimelineContentWebSocketMessage
+
+export const WebSocketClientStatusCode = {
+	NOT_CONNECTED: 'DEVICE_WEBSOCKET_CLIENT_NOT_CONNECTED',
+	CONNECTION_FAILED: 'DEVICE_WEBSOCKET_CLIENT_CONNECTION_FAILED',
+} as const
+export type WebSocketClientStatusCode = (typeof WebSocketClientStatusCode)[keyof typeof WebSocketClientStatusCode]
+
+export interface WebSocketClientStatusContextMap {
+	[WebSocketClientStatusCode.NOT_CONNECTED]: {
+		uri?: string
+		reason?: string
+	}
+	[WebSocketClientStatusCode.CONNECTION_FAILED]: {
+		uri?: string
+		error?: string
+		statusCode?: number
+	}
+}
+
+export type WebSocketClientStatusDetail<T extends WebSocketClientStatusCode = WebSocketClientStatusCode> =
+	DeviceStatusDetail<T, WebSocketClientStatusContextMap[T]>
+
+export const WebSocketClientStatusMessages: Record<WebSocketClientStatusCode, string> = {
+	[WebSocketClientStatusCode.NOT_CONNECTED]: 'WS Disconnected: {{uri}} ({{reason}})',
+	[WebSocketClientStatusCode.CONNECTION_FAILED]: 'WS Connection failed to {{uri}}: {{error}}',
+}

packages/timeline-state-resolver/src/__tests__/__snapshots__/index.spec.ts.snap

@@ -145,6 +145,8 @@ exports[`index imports 1`] = `
   "VizMSEStatusCode",
   "VizMSEStatusMessages",
   "VmixActions",
+  "WebSocketClientStatusCode",
+  "WebSocketClientStatusMessages",
   "WebsocketClientActions",
   "fillStateFromDatastore",
   "interpolateTemplateString",

packages/timeline-state-resolver/src/integrations/websocketClient/__tests__/websocketClient.spec.ts

@@ -104,7 +104,7 @@ describe('WebSocketClientDevice', () => {
 			MockWebSocketConnection.prototype.connected.mockReturnValue(true)
 			expect(device.getStatus()).toEqual({
 				statusCode: StatusCode.BAD,
-				messages: ['No Connection'],
+				statusDetails: [],
 			})
 
 			//@ts-expect-error - is set to private

packages/timeline-state-resolver/src/integrations/websocketClient/connection.ts

@@ -1,10 +1,19 @@
 import WebSocket from 'ws'
-import { DeviceStatus, StatusCode, WebsocketClientOptions } from 'timeline-state-resolver-types'
+import {
+	DeviceStatusInput,
+	StatusCode,
+	WebsocketClientOptions,
+	WebSocketClientStatusDetail,
+	WebSocketClientStatusCode,
+} from 'timeline-state-resolver-types'
+import { createWebSocketClientStatusDetail } from './messages.js'
 
 export class WebSocketConnection {
 	private ws?: WebSocket
 	private isWsConnected = false
 	private readonly options: WebsocketClientOptions
+	private lastError?: { error: string; uri?: string }
+	private disconnectReason?: string
 
 	constructor(options: WebsocketClientOptions) {
 		this.options = options
@@ -26,21 +35,38 @@ export class WebSocketConnection {
 					this.ws.on('open', () => {
 						clearTimeout(timeout)
 						this.isWsConnected = true
+						this.lastError = undefined
+						this.disconnectReason = undefined
 						resolve()
 					})
 
 					this.ws.on('error', (error) => {
 						clearTimeout(timeout)
+						this.lastError = {
+							error: error.message || error.toString(),
+							uri: this.options.webSocket?.uri,
+						}
 						reject(error)
 					})
 				})
 
-				this.ws.on('close', () => {
+				this.ws.on('close', (code, reason) => {
 					this.isWsConnected = false
+					if (reason) {
+						this.disconnectReason = reason.toString()
+					} else if (code) {
+						this.disconnectReason = `Code ${code}`
+					} else {
+						this.disconnectReason = undefined
+					}
 				})
 			}
 		} catch (error) {
 			this.isWsConnected = false
+			this.lastError = {
+				error: error instanceof Error ? error.message : String(error),
+				uri: this.options.webSocket?.uri,
+			}
 			throw error
 		}
 	}
@@ -49,13 +75,30 @@ export class WebSocketConnection {
 		return this.isWsConnected ? true : false
 	}
 
-	connectionStatus(): Omit<DeviceStatus, 'active'> {
-		const messages: string[] = []
-		// Prepare for more detailed status messages:
-		messages.push(this.isWsConnected ? 'WS Connected' : 'WS Disconnected')
+	connectionStatus(): DeviceStatusInput {
+		const statusDetails: WebSocketClientStatusDetail[] = []
+
+		if (!this.isWsConnected) {
+			if (this.lastError) {
+				statusDetails.push(
+					createWebSocketClientStatusDetail(WebSocketClientStatusCode.CONNECTION_FAILED, {
+						uri: this.lastError.uri,
+						error: this.lastError.error,
+					})
+				)
+			} else {
+				statusDetails.push(
+					createWebSocketClientStatusDetail(WebSocketClientStatusCode.NOT_CONNECTED, {
+						uri: this.options.webSocket?.uri,
+						reason: this.disconnectReason,
+					})
+				)
+			}
+		}
+
 		return {
 			statusCode: this.isWsConnected ? StatusCode.GOOD : StatusCode.BAD,
-			messages,
+			statusDetails,
 		}
 	}
 

packages/timeline-state-resolver/src/integrations/websocketClient/index.ts

@@ -7,7 +7,7 @@ import type {
 } from 'timeline-state-resolver-api'
 import {
 	ActionExecutionResultCode,
-	DeviceStatus,
+	DeviceStatusInput,
 	DeviceType,
 	StatusCode,
 	TimelineContentTypeWebSocketClient,
@@ -74,8 +74,8 @@ export class WebSocketClientDevice implements Device<
 		return this.connection?.connected() ?? false
 	}
 
-	public getStatus(): Omit<DeviceStatus, 'active'> {
-		return this.connection?.connectionStatus() ?? { statusCode: StatusCode.BAD, messages: ['No Connection'] }
+	public getStatus(): DeviceStatusInput {
+		return this.connection?.connectionStatus() ?? { statusCode: StatusCode.BAD, statusDetails: [] }
 	}
 
 	public convertTimelineStateToDeviceState(state: DeviceTimelineState<TSRTimelineContent>): WebSocketClientDeviceState {

packages/timeline-state-resolver/src/integrations/websocketClient/messages.ts

@@ -0,0 +1,17 @@
+import {
+	WebSocketClientStatusDetail,
+	WebSocketClientStatusCode,
+	WebSocketClientStatusContextMap,
+	WebSocketClientStatusMessages,
+	interpolateTemplateString,
+} from 'timeline-state-resolver-types'
+
+/**
+ * Type-safe helper for creating WebSocketClient device status details
+ */
+export function createWebSocketClientStatusDetail<T extends WebSocketClientStatusCode>(
+	code: T,
+	context: WebSocketClientStatusContextMap[T]
+): WebSocketClientStatusDetail<T> {
+	return { code, context, message: interpolateTemplateString(WebSocketClientStatusMessages[code] ?? code, context) }
+}