http-request-manager 18.15.32 → 18.15.34

package/src/docs/ADVANCED_WEBSOCKET.md

@@ -0,0 +1,633 @@
+# Advanced WebSocket Guide
+
+Comprehensive guide to WebSocket features, channel architecture, and real-time communication patterns.
+
+## Table of Contents
+
+1. [Singleton Connection Pattern](#singleton-connection-pattern)
+2. [Channel Architecture](#channel-architecture)
+3. [Message Types](#message-types)
+4. [Message History & Replay](#message-history--replay)
+5. [User Presence Tracking](#user-presence-tracking)
+6. [Notifications System](#notifications-system)
+7. [Best Practices](#best-practices)
+
+---
+
+## Singleton Connection Pattern
+
+### One Connection Across ALL Instances
+
+The `WebSocketManagerService` uses **static properties** to ensure only ONE WebSocket connection exists across the entire application, regardless of how many service instances are created.
+
+```typescript
+export class WebSocketManagerService {
+  // Static properties = shared across ALL instances
+  private static socket: WebSocket | null = null;
+  private static isConnecting = false;
+  private static connectionInitialized = false;
+  
+  // Shared BehaviorSubjects
+  private static connectionStatus = new BehaviorSubject<boolean>(false);
+  private static messages = new BehaviorSubject<any>(null);
+  private static subscribedChannels = new BehaviorSubject<Set<string>>(new Set());
+}
+```
+
+### Benefits
+
+✅ **Resource Efficiency** - No duplicate connections  
+✅ **Consistent State** - All instances share connection status  
+✅ **Automatic Coordination** - No manual synchronization needed  
+✅ **Memory Optimization** - Single connection object  
+
+### Example
+
+```typescript
+// Component 1
+@Component({})
+export class ChatComponent {
+  ws1 = inject(WebSocketManagerService);
+  
+  ngOnInit() {
+    this.ws1.connect({ wsServer: 'ws://localhost:8080' }, 'token');
+  }
+}
+
+// Component 2 (different component, same connection)
+@Component({})
+export class NotificationComponent {
+  ws2 = inject(WebSocketManagerService);
+  
+  ngOnInit() {
+    // This will NOT create a new connection
+    // It will use the existing connection from ChatComponent
+    this.ws2.messages$.subscribe(msg => {
+      console.log('Received:', msg);
+    });
+  }
+}
+```
+
+---
+
+## Channel Architecture
+
+### Channel Prefix System
+
+The library uses a prefix-based channel architecture to separate different types of communication:
+
+```typescript
+export enum ChannelType {
+  STATE = 'SYS',      // Private state synchronization
+  MESSAGE = 'PUB',    // Public messaging
+  NOTIFICATION = 'MES' // Persistent notifications
+}
+
+export function createChannelName(type: ChannelType, name: string): string {
+  return `${type}-${name}`;
+}
+```
+
+### Channel Types
+
+#### 1. SYS- Channels (State Synchronization)
+
+**Private channels** for synchronizing state between specific clients.
+
+**Characteristics:**
+- 🔒 **Private** - Only subscribed users receive messages
+- 🔄 **Real-time** - Instant state updates
+- 📦 **Lightweight** - No database persistence
+- 🎯 **Targeted** - Specific user/state sync
+
+**Use Cases:**
+- User-specific state updates
+- Private data synchronization
+- Real-time form collaboration
+- Live cursor tracking
+
+**Example:**
+```typescript
+// Subscribe to private state channel
+stateService.subscribeToChannel('SYS-user-123');
+
+// Send state update
+stateService.sendChannelMessage('SYS-user-123', {
+  type: 'STATE_UPDATE',
+  data: { field: 'value' }
+});
+```
+
+#### 2. PUB- Channels (Public Messaging)
+
+**Public channels** for broadcasting messages to all subscribers.
+
+**Characteristics:**
+- 📢 **Broadcast** - All subscribers receive messages
+- 💬 **Chat-like** - Group conversations
+- 🌐 **Open** - Anyone can subscribe
+- ⚡ **Fast** - In-memory routing
+
+**Use Cases:**
+- Chat rooms
+- Public announcements
+- Team collaboration
+- Live comments
+
+**Example:**
+```typescript
+// Join public chat room
+stateService.subscribeToChannel('PUB-general-chat');
+
+// Send message to room
+stateService.sendChannelMessage('PUB-general-chat', {
+  type: 'CHAT_MESSAGE',
+  user: 'John',
+  message: 'Hello everyone!'
+});
+```
+
+#### 3. MES- Channels (Persistent Notifications)
+
+**Database-backed channels** for notifications with persistence.
+
+**Characteristics:**
+- 💾 **Persistent** - Stored in SQLite database
+- 📅 **Historical** - Can retrieve past notifications
+- 🔔 **Notifications** - User alerts and updates
+- 📊 **Trackable** - Read/unread status
+
+**Use Cases:**
+- System notifications
+- Alert messages
+- Activity feeds
+- Announcements
+
+**Example:**
+```typescript
+// Subscribe to notification channel
+stateService.subscribeToNotificationChannel('MES-alerts');
+
+// Send notification
+stateService.sendNotification('MES-alerts', {
+  title: 'New Order',
+  message: 'Order #12345 received',
+  priority: 'high'
+});
+```
+
+### Channel Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      Client Application                         │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  Component calls:                                               │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │ subscribeToChannel('general')              → PUB-general │   │
+│  │ subscribeToNotificationChannel('alerts')   → MES-alerts  │   │
+│  │ fetchRecords()                            → SYS-state    │   │
+│  └──────────────────────────────────────────────────────────┘   │
+│                            │                                     │
+│                            ▼                                     │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │         HTTPManagerStateService                          │   │
+│  │  - Adds appropriate prefix (PUB-, MES-, SYS-)           │   │
+│  │  - Routes to WebSocketManagerService                    │   │
+│  └──────────────────────────────────────────────────────────┘   │
+│                            │                                     │
+│                            ▼                                     │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │         WebSocketManagerService (Singleton)              │   │
+│  │  - Single connection across ALL instances               │   │
+│  │  - Channel subscription tracking                        │   │
+│  │  - Message routing                                      │   │
+│  └──────────────────────────────────────────────────────────┘   │
+│                            │                                     │
+└────────────────────────────┼─────────────────────────────────────┘
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      WebSocket Server                            │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐        │
+│  │ PUB- Channel │   │ MES- Channel │   │ SYS- Channel │        │
+│  │              │   │              │   │              │        │
+│  │ In-Memory    │   │ DB Persisted │   │ State Sync   │        │
+│  │ Broadcasting │   │ Notifications│   │ Private      │        │
+│  └──────┬───────┘   └──────┬───────┘   └──────┬───────┘        │
+│         │                  │                  │                 │
+│         ▼                  ▼                  ▼                 │
+│  ┌────────────────────────────────────────────────┐            │
+│  │     Channel Subscribers (Set<WebSocket>)       │            │
+│  └────────────────────────────────────────────────┘            │
+│                                                                 │
+│  For MES- channels:                                            │
+│  ┌─────────────────────────────────────────────────┐            │
+│  │  1. Store in SQLite Database                    │            │
+│  │  2. Broadcast to current subscribers            │            │
+│  │  3. Retrieve historical data on new subscription│            │
+│  └─────────────────────────────────────────────────┘            │
+│                                                                 │
+└───────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Message Types
+
+### WebSocket Communication Types
+
+```typescript
+export enum CommunicationType {
+  SUBSCRIBE = 'subscribe',
+  UNSUBSCRIBE = 'unsubscribe',
+  MESSAGE = 'message',
+  NOTIFICATION = 'notification',
+  BROADCAST = 'broadcast',
+  USER_LIST = 'user-list',
+  CHANNEL_CREATED = 'channel-created',
+  CHANNEL_DELETED = 'channel-deleted',
+  PRESENCE = 'presence',
+  HISTORY = 'history',
+  LAST_SEEN = 'last-seen'
+}
+```
+
+### Message Structure
+
+```typescript
+export interface ChannelMessage {
+  type: CommunicationType;
+  channel: string;
+  content: any;
+  sessionId: {
+    id: string;
+    name?: string;
+    email?: string;
+  };
+  timestamp?: number;
+}
+```
+
+### Example Messages
+
+#### Subscribe to Channel
+```json
+{
+  "type": "subscribe",
+  "channel": "PUB-general",
+  "sessionId": {
+    "id": "uuid-123",
+    "name": "John Doe",
+    "email": "john@example.com"
+  }
+}
+```
+
+#### Send Message
+```json
+{
+  "type": "message",
+  "channel": "PUB-general",
+  "content": {
+    "text": "Hello everyone!",
+    "timestamp": 1234567890
+  },
+  "sessionId": {
+    "id": "uuid-123",
+    "name": "John Doe"
+  }
+}
+```
+
+#### Notification
+```json
+{
+  "type": "notification",
+  "channel": "MES-alerts",
+  "content": {
+    "title": "System Update",
+    "message": "Server will restart at 2 AM",
+    "priority": "high"
+  }
+}
+```
+
+---
+
+## Message History & Replay
+
+### MessageTrackerService
+
+Tracks message history and enables replay on reconnection.
+
+**Features:**
+- 📜 **History Tracking** - Records all messages
+- 🔄 **Replay Support** - Resend messages on reconnect
+- 🏷️ **Last Seen ID** - Track position in message stream
+- 📊 **Statistics** - Message counts and metrics
+
+### Automatic Re-subscription
+
+When a WebSocket reconnects, the MessageTrackerService automatically:
+
+1. Retrieves last-seen message ID
+2. Requests historical messages from server
+3. Replays missed messages
+4. Updates subscription state
+
+**Example:**
+```typescript
+export class MessageTrackerService {
+  private messageHistory = new Map<string, any[]>();
+  private lastSeenId = new BehaviorSubject<string>('');
+  
+  // Subscribe with automatic replay
+  subscribeToChannel(channel: string, userData?: any) {
+    // Track subscription
+    this.trackedChannels.add(channel);
+    
+    // Send subscribe message
+    this.wsManager.subscribeToChannel(channel, userData);
+    
+    // Replay historical messages
+    this.replayHistory(channel);
+  }
+  
+  // Replay missed messages
+  private replayHistory(channel: string) {
+    const lastId = this.lastSeenId.getValue();
+    if (lastId) {
+      this.requestHistory(channel, lastId);
+    }
+  }
+}
+```
+
+### Usage
+
+```typescript
+@Component({})
+export class ChatComponent {
+  private messageTracker = inject(MessageTrackerService);
+  
+  ngOnInit() {
+    // Messages flow through MessageTrackerService
+    this.messageTracker.messages$.subscribe(message => {
+      console.log('Received:', message);
+      
+      // Update last seen
+      if (message.id) {
+        this.messageTracker.updateLastSeen(message.id);
+      }
+    });
+  }
+}
+```
+
+---
+
+## User Presence Tracking
+
+### Real-time User Lists
+
+Track which users are subscribed to each channel.
+
+**Features:**
+- 👥 **User Lists** - See all users in channel
+- 🟢 **Online Status** - Real-time presence
+- 📊 **Channel Stats** - User count per channel
+- 🔄 **Auto-update** - Changes broadcast automatically
+
+### Example
+
+```typescript
+@Component({
+  selector: 'app-channel-users',
+  template: `
+    <div class="user-list">
+      <h3>Users in {{ channelName }} ({{ userCount }})</h3>
+      <div *ngFor="let user of users$ | async" class="user">
+        <span class="status" [class.online]="user.online"></span>
+        {{ user.name }}
+      </div>
+    </div>
+  `
+})
+export class ChannelUsersComponent {
+  @Input() channelName = 'PUB-general';
+  
+  private stateService = inject(HTTPManagerStateService);
+  
+  users$ = this.stateService.userListByChannel$.pipe(
+    map(users => users.get(this.channelName) || [])
+  );
+  
+  userCount$ = this.users$.pipe(map(users => users.length));
+}
+```
+
+### Presence Messages
+
+```json
+{
+  "type": "presence",
+  "channel": "PUB-general",
+  "content": {
+    "action": "joined",
+    "user": {
+      "id": "user-123",
+      "name": "John Doe",
+      "email": "john@example.com"
+    }
+  }
+}
+```
+
+---
+
+## Notifications System
+
+### Persistent Notifications
+
+MES- channels store notifications in the database for persistence.
+
+**Server Requirements:**
+
+Backend must provide endpoints for:
+- GET today's notification channels
+- GET previous day's notification channels  
+- GET notifications by channel with date filters
+
+**Database Schema:**
+```sql
+CREATE TABLE notifications (
+  id INTEGER PRIMARY KEY,
+  channel TEXT NOT NULL,
+  user_name TEXT,
+  created INTEGER NOT NULL,
+  message TEXT NOT NULL
+);
+```
+
+### Subscribe to Notifications
+
+```typescript
+@Component({})
+export class NotificationBellComponent {
+  private stateService = inject(HTTPManagerStateService);
+  
+  notifications$ = this.stateService.notificationMessages$;
+  
+  ngOnInit() {
+    // Subscribe to notification channel
+    this.stateService.subscribeToNotificationChannel('MES-alerts');
+    
+    // Receive notifications
+    this.notifications$.subscribe(notification => {
+      this.showNotification(notification);
+    });
+  }
+  
+  private showNotification(notification: any) {
+    // Display notification in UI
+    console.log('New notification:', notification);
+  }
+}
+```
+
+### Send Notification
+
+```typescript
+// Send to specific user
+stateService.sendNotification('MES-alerts', {
+  title: 'New Message',
+  body: 'You have a new message from John',
+  action: '/messages/123',
+  priority: 'high'
+});
+
+// Broadcast to all
+stateService.sendBroadcast({
+  type: 'announcement',
+  message: 'System maintenance at 2 AM'
+});
+```
+
+---
+
+## Best Practices
+
+### 1. Channel Naming Convention
+
+```typescript
+// ✅ Good - Use prefixes and descriptive names
+const userChannel = createChannelName(ChannelType.STATE, `user-${userId}`);
+const chatChannel = createChannelName(ChannelType.MESSAGE, 'general-chat');
+const alertChannel = createChannelName(ChannelType.NOTIFICATION, 'system-alerts');
+
+// ❌ Avoid - No prefixes or unclear names
+const channel1 = 'channel1';
+const myChannel = 'my-channel';
+```
+
+### 2. Connection Management
+
+```typescript
+// ✅ Good - Connect once in app initialization
+@Injectable({ providedIn: 'root' })
+export class WebSocketInitService {
+  private wsManager = inject(WebSocketManagerService);
+  
+  constructor() {
+    // Single connection for entire app
+    this.wsManager.connect(options, jwtToken);
+  }
+}
+
+// ❌ Avoid - Multiple connect calls
+@Component({})
+export class ComponentA {
+  ws = inject(WebSocketManagerService);
+  ngOnInit() { this.ws.connect(...); } // Creates connection
+}
+
+@Component({})
+export class ComponentB {
+  ws = inject(WebSocketManagerService);
+  ngOnInit() { this.ws.connect(...); } // Unnecessary - already connected
+}
+```
+
+### 3. Message Handling
+
+```typescript
+// ✅ Good - Type-safe message handling
+messages$.subscribe((message: ChannelMessage) => {
+  switch (message.type) {
+    case CommunicationType.MESSAGE:
+      this.handleChatMessage(message.content);
+      break;
+    case CommunicationType.NOTIFICATION:
+      this.handleNotification(message.content);
+      break;
+    case CommunicationType.PRESENCE:
+      this.handlePresenceChange(message.content);
+      break;
+  }
+});
+
+// ❌ Avoid - Untyped messages
+messages$.subscribe(message => {
+  console.log(message); // No type safety
+});
+```
+
+### 4. Error Handling
+
+```typescript
+// ✅ Good - Handle connection errors
+connectionStatus$.subscribe(isConnected => {
+  if (!isConnected) {
+    // Show reconnection UI
+    this.showReconnectingMessage();
+    
+    // Attempt manual reconnect if needed
+    setTimeout(() => {
+      this.wsManager.connect(options, jwtToken);
+    }, 5000);
+  }
+});
+```
+
+### 5. Cleanup
+
+```typescript
+// ✅ Good - Unsubscribe on destroy
+@Component({})
+export class ChatComponent implements OnDestroy {
+  private subscription?: Subscription;
+  
+  ngOnInit() {
+    this.subscription = this.messages$.subscribe(...);
+  }
+  
+  ngOnDestroy() {
+    this.subscription?.unsubscribe();
+    this.wsManager.unsubscribeFromChannel('PUB-general');
+  }
+}
+```
+
+---
+
+## Related Documentation
+
+- [`WebSocket Manager`](WS_MANAGER_README.md) - Basic WebSocket usage
+- [`HTTP State Manager`](HTTP_STATE_MANAGER_README.md) - State sync with WebSocket
+- [`Complete API Reference`](COMPLETE_API_REFERENCE.md) - Full API documentation
+- [`Architecture`](ARCHITECTURE.md) - System architecture overview