http-request-manager 18.15.32 → 18.15.34

package/src/docs/WS_MANAGER_README.md

@@ -0,0 +1,613 @@
+# WebSocket Manager Service
+
+The `WebSocketService` provides comprehensive WebSocket connection management with channel-based messaging, real-time communication, and notification support for Angular applications.
+
+## Overview
+
+This service offers a robust WebSocket implementation with:
+
+- **Channel-Based Messaging** - Subscribe to multiple channels for different use cases
+- **Automatic Reconnection** - Handles connection states and reconnection scenarios
+- **Session Management** - Automatic session ID generation and tracking
+- **Broadcast Messaging** - Send messages to all subscribers or specific users
+- **Notification Channels** - Dedicated notification system with date filtering
+- **Connection Status Tracking** - Real-time connection status observables
+- **JWT Authentication** - Secure WebSocket connections with JWT tokens
+
+## Installation
+
+This service is automatically available when you import `HttpRequestManagerModule`.
+
+```typescript
+import { HttpRequestManagerModule } from 'http-request-manager';
+
+@NgModule({
+  imports: [HttpRequestManagerModule.forRoot({})]
+})
+export class AppModule { }
+```
+
+## Usage
+
+### Basic Connection
+
+```typescript
+import { WebsocketService } from 'http-request-manager';
+import { WSOptions } from 'http-request-manager';
+
+@Component({
+  standalone: true,
+  providers: [WebsocketService]
+})
+export class MyComponent {
+  constructor(private wsService: WebsocketService) {}
+
+  connect() {
+    const options: WSOptions = {
+      wsServer: 'ws://localhost:8080',
+      id: 'my-channel',
+      user: { userId: 'user123', username: 'john' },
+      channels: ['notifications', 'updates']
+    };
+
+    const jwtToken = 'your-jwt-token';
+    this.wsService.connect(options, jwtToken);
+  }
+
+  disconnect() {
+    this.wsService.disconnect();
+  }
+}
+```
+
+### Subscribing to Messages
+
+```typescript
+ngOnInit() {
+  // Listen to all messages
+  this.wsService.messages$.subscribe(message => {
+    console.log('Received message:', message);
+  });
+
+  // Monitor connection status
+  this.wsService.connectionStatus$.subscribe(isConnected => {
+    console.log('Connected:', isConnected);
+  });
+
+  // Track subscribed channels
+  this.wsService.subscribedChannels$.subscribe(channels => {
+    console.log('Subscribed channels:', Array.from(channels));
+  });
+}
+```
+
+## API Reference
+
+### Connection Methods
+
+#### `connect(options: WSOptions, jwtToken?: string)`
+
+Establishes a WebSocket connection.
+
+**Parameters:**
+- `options` - WebSocket connection options
+  - `wsServer: string` - WebSocket server URL
+  - `id: string` - Primary channel name
+  - `user: any` - User information object
+  - `channels?: string[]` - Additional channels to subscribe to
+- `jwtToken?: string` - Optional JWT token for authentication
+
+**Example:**
+```typescript
+const options: WSOptions = {
+  wsServer: 'ws://localhost:8080',
+  id: 'main-channel',
+  user: { userId: '123', name: 'John' },
+  channels: ['notifications', 'updates']
+};
+this.wsService.connect(options, 'your-jwt-token');
+```
+
+#### `disconnect()`
+
+Closes the WebSocket connection and cleans up resources.
+
+```typescript
+this.wsService.disconnect();
+```
+
+### Channel Subscription Methods
+
+#### `subscribeToChannel(channelName: string)`
+
+Subscribe to a specific channel.
+
+```typescript
+this.wsService.subscribeToChannel('notifications');
+```
+
+#### `subscribeToChannels(channelNames: string[])`
+
+Subscribe to multiple channels at once.
+
+```typescript
+this.wsService.subscribeToChannels(['notifications', 'updates', 'alerts']);
+```
+
+#### `unsubscribeFromChannel(channel: string)`
+
+Unsubscribe from a specific channel.
+
+```typescript
+this.wsService.unsubscribeFromChannel('notifications');
+```
+
+#### `getSubscribedChannels(): Set<string>`
+
+Get the currently subscribed channels.
+
+```typescript
+const channels = this.wsService.getSubscribedChannels();
+console.log('Channels:', Array.from(channels));
+```
+
+### Messaging Methods
+
+#### `sendBroadcast(content: any)`
+
+Send a broadcast message to all subscribers.
+
+```typescript
+this.wsService.sendBroadcast({ message: 'Hello everyone!', timestamp: Date.now() });
+```
+
+#### `sendMessageInChannel(channel: string, content: any)`
+
+Send a message to a specific channel (state manager message type).
+
+```typescript
+this.wsService.sendMessageInChannel('notifications', {
+  type: 'alert',
+  message: 'System update available'
+});
+```
+
+#### `sendChannelMessage(channel: string, content: any)`
+
+Send a message to a specific channel (message type, broadcasts to all subscribers).
+
+```typescript
+this.wsService.sendChannelMessage('chat-room', {
+  sender: 'John',
+  text: 'Hello everyone!'
+});
+```
+
+#### `sendMessageToUser(user: string, content: any)`
+
+Send a private message to a specific user.
+
+```typescript
+this.wsService.sendMessageToUser('user123', {
+  message: 'Private message'
+});
+```
+
+### Channel Management Methods
+
+#### `createChannel(channel: string)`
+
+Create a new channel.
+
+```typescript
+this.wsService.createChannel('new-channel');
+```
+
+#### `deleteChannel(channel: string)`
+
+Delete a channel.
+
+```typescript
+this.wsService.deleteChannel('old-channel');
+```
+
+#### `getAllChannels()`
+
+Request a list of all available channels.
+
+```typescript
+this.wsService.getAllChannels();
+```
+
+#### `getUsersInChannel(channel: string)`
+
+Get the list of users in a specific channel.
+
+```typescript
+this.wsService.getUsersInChannel('chat-room');
+```
+
+### Notification Channel Methods
+
+Notification channels use the MES- prefix and provide advanced features like date filtering.
+
+#### `createNotificationChannel(channel: string)`
+
+Create a notification channel.
+
+```typescript
+this.wsService.createNotificationChannel('MES-updates');
+```
+
+#### `getNotificationChannels()`
+
+Get all notification channels (in-memory).
+
+```typescript
+this.wsService.getNotificationChannels();
+```
+
+#### `getTodaysNotificationChannels()`
+
+Get notification channels that have notifications posted today.
+
+```typescript
+this.wsService.getTodaysNotificationChannels();
+```
+
+#### `subscribeToNotificationChannel(channel: string, options?, user?)`
+
+Subscribe to a notification channel with optional date filters.
+
+```typescript
+this.wsService.subscribeToNotificationChannel('MES-updates', {
+  startEpoch: 1640995200000, // Jan 1, 2022
+  endEpoch: 1641081600000     // Jan 2, 2022
+}, { userId: 'user123' });
+```
+
+#### `unsubscribeFromNotificationChannel(channel: string)`
+
+Unsubscribe from a notification channel.
+
+```typescript
+this.wsService.unsubscribeFromNotificationChannel('MES-updates');
+```
+
+#### `sendNotification(channel: string, content: any)`
+
+Send a notification to a channel.
+
+```typescript
+this.wsService.sendNotification('MES-updates', {
+  title: 'New Update',
+  message: 'Version 2.0 is now available',
+  priority: 'high'
+});
+```
+
+## Observables
+
+### `messages$: Observable<any>`
+
+Observable that emits all incoming WebSocket messages.
+
+```typescript
+this.wsService.messages$.subscribe(message => {
+  console.log('New message:', message);
+});
+```
+
+### `connectionStatus$: Observable<boolean>`
+
+Observable that emits the current connection status (true = connected, false = disconnected).
+
+```typescript
+this.wsService.connectionStatus$.subscribe(connected => {
+  this.isConnected = connected;
+});
+```
+
+### `subscribedChannels$: Observable<Set<string>>`
+
+Observable that emits the set of currently subscribed channels.
+
+```typescript
+this.wsService.subscribedChannels$.subscribe(channels => {
+  this.currentChannels = Array.from(channels);
+});
+```
+
+## Session Management
+
+The service automatically manages WebSocket sessions using sessionStorage:
+
+- A unique session ID is generated and stored in `WSID` key
+- The session ID is included in the WebSocket URL as a query parameter
+- The session persists across page refreshes
+
+```typescript
+// Session ID is automatically included in the connection URL
+// Format: ws://server?token=xxx&sessionId=xxx
+```
+
+## JWT Authentication
+
+You can secure your WebSocket connection with JWT tokens:
+
+```typescript
+const options: WSOptions = {
+  wsServer: 'ws://localhost:8080',
+  id: 'main-channel',
+  user: { userId: 'user123' }
+};
+
+const jwtToken = 'your-jwt-token';
+this.wsService.connect(options, jwtToken);
+```
+
+### JWT Validation
+
+The service handles JWT validation errors:
+
+- If JWT validation fails, the connection is closed
+- An error message is emitted via `messages$` observable
+- The connection status is set to false
+
+```typescript
+this.wsService.messages$.subscribe(message => {
+  if (message?.error === 'JWT_INVALID') {
+    console.error('Authentication failed. Please login again.');
+    // Redirect to login or refresh token
+  }
+});
+```
+
+## Connection State Handling
+
+The service intelligently handles different connection states:
+
+### Already Open
+```typescript
+// If connection is already open, connect() returns without action
+this.wsService.connect(options, token); // No effect if already connected
+```
+
+### Connecting
+```typescript
+// If connection is in progress, connect() returns without action
+// The existing connection process continues
+```
+
+### Closing/Closed
+```typescript
+// If connection is closing or closed, the old socket is cleaned up
+// and a new connection is established
+```
+
+## Reconnection Behavior
+
+The service tracks the last connection options and supports reconnection scenarios:
+
+```typescript
+// Initial connection
+this.wsService.connect(options, token);
+
+// After disconnection, you can reconnect
+this.wsService.connect(options, token);
+
+// The service will:
+// 1. Clean up the old socket
+// 2. Establish a new connection
+// 3. Subscribe to previously subscribed channels
+```
+
+## Message Types
+
+The service supports several message types:
+
+| Message Type | Description |
+|--------------|-------------|
+| `subscribe` | Subscribe to a channel |
+| `unsubscribe` | Unsubscribe from a channel |
+| `broadcast` | Send message to all subscribers |
+| `stateMangerMessage` | Send message to a channel (state manager) |
+| `message` | Send message to a channel (broadcast to all) |
+| `userMessage` | Send private message to a user |
+| `getChannels` | Request list of all channels |
+| `createChannel` | Create a new channel |
+| `deleteChannel` | Delete a channel |
+| `getUsers` | Get users in a channel |
+| `createNotificationChannel` | Create a notification channel |
+| `getNotificationChannels` | Get notification channels |
+| `getTodaysNotificationChannels` | Get today's notification channels |
+| `subscribeNotifications` | Subscribe to notification channel |
+| `unsubscribeNotifications` | Unsubscribe from notification channel |
+| `notification` | Send notification |
+
+## Best Practices
+
+### 1. Clean Up Connections
+
+Always disconnect from WebSocket when the component is destroyed:
+
+```typescript
+ngOnDestroy() {
+  this.wsService.disconnect();
+}
+```
+
+### 2. Handle Connection Errors
+
+Monitor connection status and handle errors:
+
+```typescript
+this.wsService.connectionStatus$.subscribe(connected => {
+  if (!connected) {
+    console.warn('WebSocket disconnected. Attempting to reconnect...');
+    // Implement reconnection logic
+  }
+});
+```
+
+### 3. Use Channel-Based Messaging
+
+Organize your communication into logical channels:
+
+```typescript
+// Different channels for different use cases
+this.wsService.subscribeToChannel('notifications');  // System notifications
+this.wsService.subscribeToChannel('chat-room');      // Chat messages
+this.wsService.subscribeToChannel('updates');        // Real-time updates
+```
+
+### 4. Implement Error Handling
+
+Handle potential errors in message processing:
+
+```typescript
+this.wsService.messages$.pipe(
+  catchError(error => {
+    console.error('Message processing error:', error);
+    return EMPTY;
+  })
+).subscribe(message => {
+  // Process message
+});
+```
+
+### 5. Use Notification Channels for Date-Filtered Data
+
+For time-sensitive notifications, use notification channels with date filters:
+
+```typescript
+this.wsService.subscribeToNotificationChannel('MES-updates', {
+  startEpoch: Date.now() - 24 * 60 * 60 * 1000, // Last 24 hours
+  endEpoch: Date.now()
+});
+```
+
+## Integration with HTTPManagerStateService
+
+The WebSocketService is designed to work seamlessly with HTTPManagerStateService for real-time CRUD operations:
+
+```typescript
+// The HTTPManagerStateService automatically integrates with WebSocket
+// to keep local state synchronized with server changes
+
+this.httpStateService = httpManagerStateService.updater(
+  (state: any) => ({
+    ...state,
+    wsOptions: {
+      wsServer: 'ws://localhost:8080',
+      id: 'my-channel',
+      user: { userId: 'user123' }
+    }
+  })
+);
+
+// WebSocket messages automatically update the state
+// through the HTTPManagerStateService integration
+```
+
+## Troubleshooting
+
+### Connection Fails
+
+- Check if the WebSocket server URL is correct
+- Verify JWT token is valid (if using authentication)
+- Ensure server is running and accessible
+- Check browser console for detailed error messages
+
+### Messages Not Received
+
+- Verify you're subscribed to the correct channel
+- Check connection status via `connectionStatus$` observable
+- Ensure server is sending messages to the correct channel
+- Check message format matches expected structure
+
+### JWT Validation Error
+
+- Verify JWT token is not expired
+- Ensure token format is correct
+- Check server-side JWT validation logic
+
+## Example: Complete Chat Component
+
+```typescript
+import { Component, OnInit, OnDestroy } from '@angular/core';
+import { WebsocketService } from 'http-request-manager';
+
+@Component({
+  selector: 'app-chat',
+  template: `
+    <div *ngIf="!isConnected">
+      <button (click)="connect()">Connect</button>
+    </div>
+    <div *ngIf="isConnected">
+      <div class="messages">
+        <div *ngFor="let msg of messages" class="message">
+          {{ msg }}
+        </div>
+      </div>
+      <input [(ngModel)]="newMessage" placeholder="Type a message..." />
+      <button (click)="sendMessage()">Send</button>
+      <button (click)="disconnect()">Disconnect</button>
+    </div>
+  `
+})
+export class ChatComponent implements OnInit, OnDestroy {
+  messages: string[] = [];
+  newMessage: string = '';
+  isConnected = false;
+
+  private subscriptions = [];
+
+  constructor(private wsService: WebsocketService) {}
+
+  ngOnInit() {
+    this.subscriptions.push(
+      this.wsService.messages$.subscribe(message => {
+        this.messages.push(message);
+      }),
+      this.wsService.connectionStatus$.subscribe(connected => {
+        this.isConnected = connected;
+      })
+    );
+  }
+
+  connect() {
+    const options = {
+      wsServer: 'ws://localhost:8080',
+      id: 'chat-room',
+      user: { username: 'current-user' }
+    };
+    this.wsService.connect(options);
+    this.wsService.subscribeToChannel('chat-room');
+  }
+
+  sendMessage() {
+    this.wsService.sendChannelMessage('chat-room', {
+      sender: 'current-user',
+      text: this.newMessage,
+      timestamp: Date.now()
+    });
+    this.newMessage = '';
+  }
+
+  disconnect() {
+    this.wsService.disconnect();
+  }
+
+  ngOnDestroy() {
+    this.subscriptions.forEach(sub => sub.unsubscribe());
+    this.wsService.disconnect();
+  }
+}
+```
+
+## Related Services
+
+- [`HTTPManagerService`](HTTP_MANAGER_README.md) - HTTP request management
+- [`HTTPManagerStateService`](HTTP_STATE_MANAGER_README.md) - State management with WebSocket integration
+- [`RequestSignalsService`](HTTP_SINGNALS_MANAGER_README.md) - Signal-based HTTP requests