http-request-manager 18.15.33 → 18.15.34

package/src/docs/MESSAGE_TRACKER_README.md

@@ -0,0 +1,518 @@
+<!-- markdownlint-disable MD031 MD060 -->
+
+# Message Tracker Service
+
+The `MessageTrackerService` provides guaranteed message delivery tracking for WebSocket communications with sequence tracking, gap detection, and automatic re-subscription.
+
+## Overview
+
+This service ensures that frontend clients never miss WebSocket messages, even during disconnections. It provides:
+
+- ✅ **Per-Channel Message Tracking** - Track message sequences per channel
+- ✅ **Gap Detection** - Automatically detect missing messages
+- ✅ **Batch Acknowledgments** - Efficient message confirmation
+- ✅ **Reconnection Sync** - Resume from last-seen message after disconnect
+- ✅ **Persistent Tracking** - Survives page refreshes via sessionStorage
+- ✅ **Notification Channel Support** - Special handling for notification channels
+
+## Installation
+
+```typescript
+import { MessageTrackerService } from 'http-request-manager';
+```
+
+The service is automatically available when you import `HttpRequestManagerModule`.
+
+## Basic Usage
+
+### Channel Subscription with Tracking
+
+```typescript
+import { Component, inject, OnDestroy } from '@angular/core';
+import { MessageTrackerService, WebSocketManagerService } from 'http-request-manager';
+import { Subscription } from 'rxjs';
+
+@Component({
+  selector: 'app-chat',
+  template: `
+    <div class="chat">
+      <h2>Chat Messages</h2>
+      <div class="messages">
+        <div *ngFor="let message of messages" class="message">
+          <strong>{{ message.user }}:</strong> {{ message.content }}
+        </div>
+      </div>
+    </div>
+  `
+})
+export class ChatComponent implements OnDestroy {
+  private tracker = inject(MessageTrackerService);
+  private wsManager = inject(WebSocketManagerService);
+  
+  messages: any[] = [];
+  private messagesSubscription: Subscription;
+
+  constructor() {
+    // Subscribe to tracked messages
+    this.messagesSubscription = this.tracker.messages$.subscribe(message => {
+      if (message) {
+        this.messages.push(message);
+      }
+    });
+
+    // Connect and subscribe to channel
+    this.wsManager.connect({
+      wsServer: 'ws://localhost:8080',
+      id: 'chat',
+      user: { id: 'user123', name: 'John' }
+    }, 'jwt-token');
+
+    // Subscribe with automatic tracking
+    this.tracker.subscribeToChannel('chat');
+  }
+
+  ngOnDestroy() {
+    this.messagesSubscription?.unsubscribe();
+  }
+}
+```
+
+## API Reference
+
+### Message Tracking
+
+#### `trackMessage(message: any): void`
+
+Manually tracks a message and updates sequence tracking.
+
+```typescript
+tracker.trackMessage({
+  id: 123,
+  channel: 'chat',
+  user: 'user123',
+  content: 'Hello!',
+  timestamp: new Date().toISOString()
+});
+```
+
+### Channel Management
+
+#### `subscribeToChannel(channel: string, userData?: any): void`
+
+Subscribe to a channel with automatic last-seen tracking for message replay.
+
+```typescript
+// Subscribe to general chat
+tracker.subscribeToChannel('general');
+
+// Subscribe with user data
+tracker.subscribeToChannel('private', { userId: 'user123' });
+```
+
+**Features:**
+- Automatically includes `lastSeenId` for message replay
+- Persists intended channels to sessionStorage
+- Re-subscribes automatically after reconnection
+
+#### `unsubscribeFromChannel(channel: string): void`
+
+Unsubscribe from a tracked channel.
+
+```typescript
+tracker.unsubscribeFromChannel('general');
+```
+
+#### `getIntendedChannels(): Set<string>`
+
+Get all channels the service intends to stay subscribed to.
+
+```typescript
+const channels = tracker.getIntendedChannels();
+console.log('Tracking channels:', Array.from(channels));
+```
+
+### Notification Channels
+
+#### `getNotificationChannels(): void`
+
+Request list of all notification channels.
+
+```typescript
+tracker.getNotificationChannels();
+```
+
+#### `getTodaysNotificationChannels(): void`
+
+Request list of today's notification channels only.
+
+```typescript
+tracker.getTodaysNotificationChannels();
+```
+
+#### `subscribeToNotificationChannel(channel: string, options?: any, user?: any): void`
+
+Subscribe to a persistent notification channel.
+
+```typescript
+tracker.subscribeToNotificationChannel('alerts', {
+  limit: 50,
+  since: new Date().toISOString()
+}, { id: 'user123' });
+```
+
+#### `unsubscribeFromNotificationChannel(channel: string): void`
+
+Unsubscribe from a notification channel.
+
+```typescript
+tracker.unsubscribeFromNotificationChannel('alerts');
+```
+
+#### `sendNotification(channel: string, content: any): void`
+
+Send a notification to a channel.
+
+```typescript
+tracker.sendNotification('alerts', {
+  title: 'New Message',
+  body: 'You have a new message',
+  priority: 'high'
+});
+```
+
+#### `createNotificationChannel(channel: string): void`
+
+Create a new notification channel.
+
+```typescript
+tracker.createNotificationChannel('system-alerts');
+```
+
+### State Accessors
+
+#### `getLastSeen(channel: string): number`
+
+Get the last seen message ID for a channel.
+
+```typescript
+const lastId = tracker.getLastSeen('chat');
+console.log('Last seen message ID:', lastId);
+```
+
+#### `getExpectedSequence(channel: string): number`
+
+Get the expected next message ID for gap detection.
+
+```typescript
+const expected = tracker.getExpectedSequence('chat');
+console.log('Expected next message ID:', expected);
+```
+
+#### `getGapCount(channel: string): number`
+
+Get the number of detected gaps in a channel.
+
+```typescript
+const gaps = tracker.getGapCount('chat');
+if (gaps > 0) {
+  console.warn(`Detected ${gaps} message gaps in channel ${channel}`);
+}
+```
+
+#### `isInReplayMode(channel: string): boolean`
+
+Check if a channel is currently in replay mode.
+
+```typescript
+if (tracker.isInReplayMode('chat')) {
+  console.log('Replaying missed messages...');
+}
+```
+
+#### `getMessages(): Observable<any>`
+
+Observable emitting all tracked messages.
+
+```typescript
+tracker.messages$.subscribe(message => {
+  console.log('Tracked message:', message);
+});
+```
+
+### Utility Methods
+
+#### `clearState(): void`
+
+Clear all tracking state (useful for debugging or manual reset).
+
+```typescript
+tracker.clearState();
+```
+
+#### `persistLastSeen(): void`
+
+Manually persist last-seen IDs to sessionStorage.
+
+```typescript
+tracker.persistLastSeen();
+```
+
+## Advanced Features
+
+### Gap Detection and Recovery
+
+The service automatically detects when messages are missing and can request replay:
+
+```typescript
+// Automatic gap detection
+// When a gap is detected (e.g., expected ID 5 but received ID 7):
+// 1. Gap count is incremented
+// 2. If gap threshold exceeded (10 messages), UI is notified
+// 3. Service attempts to recover missed messages on reconnect
+
+// Monitor gap counts
+setInterval(() => {
+  const channels = tracker.getIntendedChannels();
+  channels.forEach(channel => {
+    const gaps = tracker.getGapCount(channel);
+    if (gaps > 0) {
+      console.warn(`Channel ${channel} has ${gaps} message gaps`);
+    }
+  });
+}, 5000);
+```
+
+### Batch Acknowledgments
+
+Messages are acknowledged in batches for efficiency:
+
+```typescript
+// Automatic batch acknowledgment every 5 seconds
+// No manual intervention needed
+
+// Manual acknowledgment (if needed)
+tracker.sendBatchAck('chat');
+```
+
+### Reconnection Handling
+
+Automatic re-subscription with last-seen tracking:
+
+```typescript
+// When WebSocket reconnects:
+// 1. All intended channels are re-subscribed
+// 2. Last-seen IDs are sent to server
+// 3. Server replays missed messages
+// 4. Gap detection resumes
+
+// This happens automatically - no code needed
+```
+
+### Persistent Tracking
+
+Intended channels survive page refreshes:
+
+```typescript
+// Channels are persisted to sessionStorage automatically
+// On page load, service restores intended channels:
+
+// Example flow:
+// 1. User subscribes to 'chat' and 'alerts'
+// 2. Page is refreshed
+// 3. Service restores intended channels from sessionStorage
+// 4. When WebSocket connects, auto-subscribes to restored channels
+```
+
+## Complete Example: Chat Application
+
+```typescript
+import { Component, inject, OnDestroy } from '@angular/core';
+import { MessageTrackerService, WebSocketManagerService } from 'http-request-manager';
+import { Subscription } from 'rxjs';
+
+interface ChatMessage {
+  id: number;
+  channel: string;
+  user: string;
+  content: string;
+  timestamp: string;
+}
+
+@Component({
+  selector: 'app-chat-room',
+  template: `
+    <div class="chat-room">
+      <div class="channel-selector">
+        <button *ngFor="let channel of channels" 
+                [class.active]="currentChannel === channel"
+                (click)="switchChannel(channel)">
+          {{ channel }}
+          <span class="unread" *ngIf="getUnreadCount(channel) > 0">
+            {{ getUnreadCount(channel) }}
+          </span>
+        </button>
+      </div>
+      
+      <div class="messages">
+        <div *ngFor="let message of messages" class="message">
+          <div class="message-header">
+            <span class="user">{{ message.user }}</span>
+            <span class="time">{{ message.timestamp | date:'short' }}</span>
+          </div>
+          <div class="message-content">{{ message.content }}</div>
+        </div>
+      </div>
+      
+      <div class="input-area">
+        <input [(ngModel)]="newMessage" 
+               (keyup.enter)="sendMessage()"
+               placeholder="Type a message...">
+        <button (click)="sendMessage()">Send</button>
+      </div>
+      
+      <div class="connection-status" *ngIf="!isConnected">
+        ⚠️ Disconnected - Reconnecting...
+      </div>
+    </div>
+  `,
+  styles: [`
+    .chat-room { display: flex; flex-direction: column; height: 100%; }
+    .channel-selector { display: flex; gap: 8px; padding: 8px; }
+    .messages { flex: 1; overflow-y: auto; padding: 16px; }
+    .message { margin-bottom: 16px; }
+    .message-header { display: flex; justify-content: space-between; margin-bottom: 4px; }
+    .user { font-weight: bold; }
+    .time { color: #666; font-size: 0.8em; }
+    .input-area { display: flex; gap: 8px; padding: 16px; }
+    .input-area input { flex: 1; padding: 8px; }
+    .connection-status { background: #fff3cd; padding: 8px; text-align: center; }
+    .unread { background: #dc3545; color: white; border-radius: 50%; padding: 2px 6px; font-size: 0.7em; }
+  `]
+})
+export class ChatRoomComponent implements OnDestroy {
+  private tracker = inject(MessageTrackerService);
+  private wsManager = inject(WebSocketManagerService);
+  
+  channels = ['general', 'random', 'announcements'];
+  currentChannel = 'general';
+  messages: ChatMessage[] = [];
+  newMessage = '';
+  isConnected = true;
+  
+  private messagesSubscription: Subscription;
+  private connectionSubscription: Subscription;
+
+  constructor() {
+    // Subscribe to tracked messages
+    this.messagesSubscription = this.tracker.messages$.subscribe(message => {
+      if (message && message.channel === this.currentChannel) {
+        this.messages.push(message);
+      }
+    });
+
+    // Monitor connection status
+    this.connectionSubscription = this.wsManager.connectionStatus$.subscribe(connected => {
+      this.isConnected = connected;
+    });
+
+    // Initialize WebSocket connection
+    this.wsManager.connect({
+      wsServer: 'ws://localhost:8080',
+      id: 'chat',
+      user: { id: 'user123', name: 'John Doe' }
+    }, 'jwt-token');
+
+    // Subscribe to channels with tracking
+    this.channels.forEach(channel => {
+      this.tracker.subscribeToChannel(channel);
+    });
+  }
+
+  switchChannel(channel: string) {
+    this.currentChannel = channel;
+    // Load messages for this channel
+  }
+
+  sendMessage() {
+    if (!this.newMessage.trim()) return;
+
+    this.wsManager.sendChannelMessage(this.currentChannel, {
+      type: 'CHAT_MESSAGE',
+      content: this.newMessage,
+      timestamp: new Date().toISOString()
+    });
+
+    this.newMessage = '';
+  }
+
+  getUnreadCount(channel: string): number {
+    const lastSeen = this.tracker.getLastSeen(channel);
+    const expected = this.tracker.getExpectedSequence(channel);
+    return Math.max(0, expected - lastSeen - 1);
+  }
+
+  ngOnDestroy() {
+    this.messagesSubscription?.unsubscribe();
+    this.connectionSubscription?.unsubscribe();
+  }
+}
+```
+
+## Troubleshooting
+
+### Messages Not Tracked
+
+**Problem**: Messages not appearing in `messages$` observable
+
+**Solution**: Ensure WebSocket connection is active and you're subscribed to channels
+
+```typescript
+// Check connection
+wsManager.connectionStatus$.subscribe(connected => {
+  if (!connected) {
+    console.warn('WebSocket not connected');
+  }
+});
+
+// Ensure subscription
+tracker.subscribeToChannel('your-channel');
+```
+
+### Gaps Not Detected
+
+**Problem**: Missing messages not detected
+
+**Solution**: Ensure messages have proper ID structure
+
+```typescript
+// Messages should have numeric IDs
+{
+  id: 123,        // ✅ Required for tracking
+  channel: 'chat',
+  content: 'Hello'
+}
+```
+
+### Channels Not Restored After Refresh
+
+**Problem**: Intended channels not persisted
+
+**Solution**: Check sessionStorage permissions and browser settings
+
+```typescript
+// Check if sessionStorage is available
+try {
+  sessionStorage.setItem('test', 'test');
+  sessionStorage.removeItem('test');
+  console.log('sessionStorage available');
+} catch (e) {
+  console.error('sessionStorage not available');
+}
+```
+
+## Related Documentation
+
+- [Message Tracker Signals Service](./MESSAGE_TRACKER_SIGNALS_README.md) - Signal-based version for Angular 19+
+- [WebSocket Manager Service](./WS_MANAGER_README.md) - Underlying WebSocket connection management
+- [Advanced WebSocket Guide](./ADVANCED_WEBSOCKET.md) - Channel architecture and patterns
+- [WebSocket Message Service](./WEBSOCKET_MESSAGE_SERVICE.md) - Type-safe message sending