http-request-manager 18.15.32 → 18.15.34

package/src/docs/WEBSOCKET_SINGLETON_REFACTORING.md

@@ -0,0 +1,201 @@
+# WebSocket Singleton Refactoring Summary
+
+## Overview
+
+Refactored WebSocket connection management to use a **true singleton pattern** via `WebSocketManagerService`, ensuring only ONE WebSocket connection exists across ALL instances of `HTTPManagerStateService`.
+
+## Problem Solved
+
+**Before:**
+- Multiple instances of `HTTPManagerStateService` each attempted to manage their own WebSocket connection
+- `WebsocketService` was `providedIn: 'root'` but inherited through `HTTPManagerService → RequestService → WebsocketService`
+- Static properties (`wsConnection`, `wsCommunicationQueue`) were used as a band-aid solution
+- Risk of duplicate connections, race conditions, and inconsistent state
+
+**After:**
+- Single `WebSocketManagerService` manages the ONE and ONLY WebSocket connection
+- All instances inject and share the same connection via static properties in the service
+- Connection is initialized once - subsequent instances detect existing connection and skip reconnection
+- Clean architecture with proper separation of concerns
+
+## Files Created
+
+### 1. `WebSocketManagerService` (Singleton)
+**Location:** `projects/http-request-manager/src/lib/services/ws-manager-service/websocket-service/websocket-manager.service.ts`
+
+**Key Features:**
+- Static properties for connection state (shared across ALL instances):
+  - `private static socket: WebSocket | null`
+  - `private static isConnecting: boolean`
+  - `private static connectionInitialized: boolean`
+  - `private static lastOptions: WSOptions | null`
+
+- Static BehaviorSubjects for observables (shared across ALL instances):
+  - `connectionStatus$: Observable<boolean>`
+  - `messages$: Observable<any>`
+  - `subscribedChannels$: Observable<Set<string>>`
+
+- Static helper methods:
+  - `isConnected(): boolean` - Check if WebSocket is currently open
+  - `isInitialized(): boolean` - Check if connection was ever initialized
+
+- Connection management:
+  - `connect(options, jwtToken)` - Only first call establishes connection
+  - `disconnect()` - Closes connection and resets state
+  - Prevents duplicate connection attempts via `isConnecting` flag
+
+- All WebSocket operations:
+  - Channel subscriptions (subscribe/unsubscribe)
+  - Message sending (broadcast, channel messages, user messages)
+  - Channel management (create, delete, list)
+  - Notification channels (MES- prefix)
+
+## Files Modified
+
+### 1. `HTTPManagerService`
+**Location:** `projects/http-request-manager/src/lib/services/request-manager-services/http-manager.service.ts`
+
+**Changes:**
+- Injects `WebSocketManagerService`
+- Delegates ALL WebSocket methods to `WebSocketManagerService`
+- Exposes observables from singleton service with `override` modifier
+- No longer extends `WebsocketService` for WebSocket functionality (still extends `RequestService` for HTTP)
+
+**Example:**
+```typescript
+wsManager = inject(WebSocketManagerService)
+
+override connectionStatus$ = this.wsManager.connectionStatus$
+override messages$ = this.wsManager.messages$
+override subscribedChannels$ = this.wsManager.subscribedChannels$
+
+override connect(options: any, jwtToken: string): void {
+  this.wsManager.connect(options, jwtToken);
+}
+```
+
+### 2. `HTTPManagerStateService`
+**Location:** `projects/http-request-manager/src/lib/services/request-manager-state-service/http-manager-state.store.ts`
+
+**Changes:**
+- Removed `private static wsConnection = false` (replaced with `WebSocketManagerService.isConnected()`)
+- Kept `private static wsCommunicationQueue` for message queuing
+- Updated all connection checks from `HTTPManagerStateService.wsConnection` to `WebSocketManagerService.isConnected()`
+- Updated `initWS` effect to remove static connection state assignment
+- Imports `WebSocketManagerService`
+
+**Example:**
+```typescript
+// Before
+if (HTTPManagerStateService.wsConnection) {
+  this.httpManagerService.subscribeToChannel(channel);
+}
+
+// After
+if (WebSocketManagerService.isConnected()) {
+  this.httpManagerService.subscribeToChannel(channel);
+}
+```
+
+### 3. Module Exports
+**Location:** `projects/http-request-manager/src/lib/services/ws-manager-service/index.ts`
+
+**Added:**
+```typescript
+export * from "./websocket-service/index";
+```
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│           WebSocketManagerService (Singleton)               │
+│                                                             │
+│  ┌───────────────────────────────────────────────────────┐ │
+│  │  Static Properties (Shared Across ALL Instances)      │ │
+│  │  • socket: WebSocket                                  │ │
+│  │  • connectionStatus$: BehaviorSubject<boolean>       │ │
+│  │  • messages$: BehaviorSubject<any>                   │ │
+│  │  • subscribedChannels$: BehaviorSubject<Set<string>> │ │
+│  │  • isConnected(): boolean                             │ │
+│  └───────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+           ▲                    ▲                    ▲
+           │                    │                    │
+    ┌──────┴──────┐      ┌─────┴──────┐      ┌─────┴──────┐
+    │  Instance 1 │      │  Instance 2 │      │  Instance N │
+    │  HTTPManager│      │  HTTPManager│      │  HTTPManager│
+    │  Service    │      │  Service    │      │  Service    │
+    └──────┬──────┘      └─────┬──────┘      └─────┬──────┘
+           │                    │                    │
+           └────────────────────┼────────────────────┘
+                                │
+                    All delegate to SINGLETON
+                    ✓ Single connection
+                    ✓ Coordinated subscriptions
+                    ✓ No race conditions
+                    ✓ Consistent state
+```
+
+## Usage Example
+
+```typescript
+// First instance initializes connection
+const stateService1 = new HTTPManagerStateService(...);
+// → WebSocketManagerService.connect() called
+// → WebSocket connection established
+
+// Second instance detects existing connection
+const stateService2 = new HTTPManagerStateService(...);
+// → WebSocketManagerService.connect() called
+// → Detects socket.readyState === WebSocket.OPEN
+// → Returns immediately, no duplicate connection
+
+// Both instances share the same observables
+stateService1.connectionStatus$.subscribe(status => { ... })
+stateService2.connectionStatus$.subscribe(status => { ... })
+// → Both receive updates from SAME WebSocketManagerService.connectionStatus$
+```
+
+## Benefits
+
+✅ **Single WebSocket Connection** - Only one connection regardless of how many state services are created  
+✅ **No Race Conditions** - Connection initialization is coordinated via static state  
+✅ **Consistent State** - All instances share the same connection status and messages  
+✅ **Clean Architecture** - WebSocket logic properly separated in dedicated service  
+✅ **Backward Compatible** - Existing API unchanged, consumers don't notice  
+✅ **Testable** - Singleton pattern makes testing easier  
+✅ **Memory Efficient** - No duplicate WebSocket instances  
+
+## Migration Notes
+
+### For Consumers of HTTPManagerStateService
+**No changes required!** The public API remains the same.
+
+### For Developers Adding New WebSocket Features
+- Add methods to `WebSocketManagerService` (the singleton)
+- Delegate through `HTTPManagerService` if needed
+- Use `WebSocketManagerService.isConnected()` to check connection status
+- Never create new WebSocket instances directly
+
+### For Testing
+- Mock `WebSocketManagerService` instead of `WebsocketService`
+- Test singleton behavior (only first connect() should establish connection)
+- Verify multiple instances share the same observables
+
+## Build Status
+
+✅ **Build Successful** - `ng build http-request-manager` completes without errors
+
+## Next Steps (Optional)
+
+1. **Deprecate WebsocketService** - Consider marking the old service as deprecated
+2. **Update Documentation** - Add README examples showing singleton pattern
+3. **Add Unit Tests** - Test singleton behavior and connection sharing
+4. **Monitor Performance** - Verify single connection reduces resource usage
+
+## Related Files
+
+- `projects/http-request-manager/src/lib/services/ws-manager-service/websocket-service/`
+- `projects/http-request-manager/src/lib/services/request-manager-services/http-manager.service.ts`
+- `projects/http-request-manager/src/lib/services/request-manager-state-service/http-manager-state.store.ts`