feat(api-graphql): add WebSocket health monitoring with persistent storage

- Add getConnectionHealth() and getPersistentConnectionHealth() methods
- Add isConnected(), reconnect(), and disconnect() controls
- Implement cross-platform persistent storage (AsyncStorage/localStorage)
- Track keep-alive messages with 65-second health threshold
- Fixes #9749, #4459, #5403, #7057

Author: anivar

packages/api-graphql/src/Providers/AWSWebSocketProvider/index.ts

@@ -49,6 +49,27 @@ import {
 } from './appsyncUrl';
 import { awsRealTimeHeaderBasedAuth } from './authHeaders';
 
+// Platform-safe AsyncStorage import
+let AsyncStorage: any;
+try {
+	// Try to import AsyncStorage for React Native (optional dependency)
+	// eslint-disable-next-line import/no-extraneous-dependencies
+	AsyncStorage = require('@react-native-async-storage/async-storage').default;
+} catch (e) {
+	// Fallback for web/other platforms - use localStorage if available
+	AsyncStorage =
+		typeof localStorage !== 'undefined'
+			? {
+					setItem: (key: string, value: string) => {
+						localStorage.setItem(key, value);
+
+						return Promise.resolve();
+					},
+					getItem: (key: string) => Promise.resolve(localStorage.getItem(key)),
+				}
+			: null;
+}
+
 const dispatchApiEvent = (payload: HubPayload) => {
 	Hub.dispatch('api', payload, 'PubSub', AMPLIFY_SYMBOL);
 };
@@ -682,6 +703,18 @@ export abstract class AWSWebSocketProvider {
 		if (type === MESSAGE_TYPES.GQL_CONNECTION_KEEP_ALIVE) {
 			this.maintainKeepAlive();
 
+			// Persist keep-alive timestamp for cross-session tracking
+			if (AsyncStorage) {
+				try {
+					AsyncStorage.setItem(
+						'AWS_AMPLIFY_LAST_KEEP_ALIVE',
+						JSON.stringify(new Date()),
+					);
+				} catch (error) {
+					this.logger.warn('Failed to persist keep-alive timestamp:', error);
+				}
+			}
+
 			return;
 		}
 
@@ -1051,6 +1084,59 @@ export abstract class AWSWebSocketProvider {
 		};
 	}
 
+	/**
+	 * Get persistent WebSocket health state (survives app restarts)
+	 */
+	async getPersistentConnectionHealth(): Promise<
+		import('../../types').WebSocketHealthState
+	> {
+		let persistentKeepAliveTime: number | undefined;
+		let _timeSinceLastPersistentKeepAlive: number | undefined;
+
+		// Try to get persistent keep-alive timestamp
+		if (AsyncStorage) {
+			try {
+				const persistentKeepAlive = await AsyncStorage.getItem(
+					'AWS_AMPLIFY_LAST_KEEP_ALIVE',
+				);
+				if (persistentKeepAlive) {
+					const keepAliveDate = new Date(JSON.parse(persistentKeepAlive));
+					persistentKeepAliveTime = keepAliveDate.getTime();
+					_timeSinceLastPersistentKeepAlive =
+						Date.now() - persistentKeepAliveTime;
+				}
+			} catch (error) {
+				this.logger.warn(
+					'Failed to retrieve persistent keep-alive timestamp:',
+					error,
+				);
+			}
+		}
+
+		// Use the more recent timestamp (in-memory vs persistent)
+		const lastKeepAliveTime =
+			Math.max(this.keepAliveTimestamp || 0, persistentKeepAliveTime || 0) ||
+			undefined;
+
+		const timeSinceLastKeepAlive = lastKeepAliveTime
+			? Date.now() - lastKeepAliveTime
+			: undefined;
+
+		// Health check includes persistent data
+		const isHealthy =
+			this.connectionState === ConnectionState.Connected &&
+			lastKeepAliveTime &&
+			timeSinceLastKeepAlive !== undefined &&
+			timeSinceLastKeepAlive < 65000; // 65 second threshold
+
+		return {
+			isHealthy: Boolean(isHealthy),
+			connectionState: this.connectionState || ConnectionState.Disconnected,
+			lastKeepAliveTime,
+			timeSinceLastKeepAlive,
+		};
+	}
+
 	/**
 	 * Check if WebSocket is currently connected
 	 */

packages/api-graphql/src/types/index.ts

@@ -536,6 +536,7 @@ export interface WebSocketControl {
 	disconnect(): void;
 	isConnected(): boolean;
 	getConnectionHealth(): WebSocketHealthState;
+	getPersistentConnectionHealth(): Promise<WebSocketHealthState>;
 	onConnectionStateChange(
 		callback: (state: import('./PubSub').ConnectionState) => void,
 	): () => void;