http-request-manager 18.15.33 → 18.15.34

package/src/docs/ARCHITECTURE.md

@@ -0,0 +1,633 @@
+# HTTP Request Manager - Architecture Overview
+
+## System Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         Angular Application                     │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌────────────────┐  ┌────────────────┐  ┌──────────────────┐   │
+│  │   Components   │  │   Components   │  │    Components    │   │
+│  │   (Signals)    │  │  (Observables) │  │  (State Store)   │   │
+│  └───────┬────────┘  └───────┬────────┘  └────────┬─────────┘   │
+│          │                   │                     │            │
+│          ▼                   ▼                     ▼            │
+│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────┐   │
+│  │HTTPManager   │    │HTTPManager   │    │HTTPManager       │   │
+│  │SignalsService│    │Service       │    │StateService      │   │
+│  └──────┬───────┘    └──────┬───────┘    └────────┬─────────┘   │
+│         │                   │                      │            │
+│         └───────────────────┴──────────────────────┘            │
+│                             │                                   │
+│                             ▼                                   │
+│                    ┌─────────────────┐                          │
+│                    │  HttpClient     │                          │
+│                    │  (Angular)      │                          │
+│                    └────────┬────────┘                          │
+│                             │                                   │
+├─────────────────────────────┼───────────────────────────────────┤
+│                             │                                   │
+│  ┌──────────────────────────┼──────────────────────┐            │
+│  │        Local Storage Layer                      │            │
+│  ├──────────────────────────┼──────────────────────┤            │
+│  │                          │                      │            │
+│  │  ┌────────────────┐      │      ┌─────────────┐ │            │
+│  │  │LocalStorage    │      │      │IndexedDB    │ │            │
+│  │  │Manager Service │      │      │(Dexie.js)   │ │            │
+│  │  └────────────────┘      │      └─────────────┘ │            │
+│  │                          │                      │            │
+│  └──────────────────────────┼──────────────────────┘            │
+│                             │                                   │
+│  ┌──────────────────────────┼─────────────────────┐             │
+│  │        WebSocket Layer                         │             │
+│  ├──────────────────────────┼─────────────────────┤             │
+│  │                          │                     │             │
+│  │  ┌─────────────────────────────────────┐       │             │
+│  │  │   WebsocketService                  │       │             │
+│  │  │   - Connection Management           │       │             │
+│  │  │   - Channel Subscriptions           │       │             │
+│  │  │   - Message Routing                 │       │             │
+│  │  │   - Authentication (JWT)            │       │             │
+│  │  └─────────────────────────────────────┘       │             │
+│  │                                                │             │
+│  └────────────────────────────────────────────────┘             │
+│                             │                                   │
+└─────────────────────────────┼───────────────────────────────────┘
+                              │
+                              ▼
+                ┌──────────────────────────────┐
+                │     Backend Server           │
+                ├──────────────────────────────┤
+                │                              │
+                │  ┌────────────────────────┐  │
+                │  │  HTTP REST API         │  │
+                │  │  (Express/Node.js)     │  │
+                │  └────────────────────────┘  │
+                │                              │
+                │  ┌────────────────────────┐  │
+                │  │  WebSocket Server      │  │
+                │  │  (ws library)          │  │
+                │  └────────────────────────┘  │
+                │                              │
+                │  ┌────────────────────────┐  │
+                │  │  SQLite Database       │  │
+                │  │  (Notifications)       │  │
+                │  └────────────────────────┘  │
+                │                              │
+                └──────────────────────────────┘
+```
+
+## Service Hierarchy
+
+```
+HTTPManagerService (Base - extends RequestService)
+├── Location: services/request-manager-services/http-manager.service.ts
+├── Features:
+│   ├── HTTP CRUD Operations (GET, POST, PUT, DELETE)
+│   ├── Loading States (isPending$, error$, data$, countdown$)
+│   ├── Retry Logic with delayedRetry operator
+│   ├── Polling with Countdown (requestPolling operator)
+│   ├── Adapters & Mappers for data transformation
+│   ├── Stream Handling (NDJSON, SSE)
+│   └── File Download with progress tracking
+│
+├── HTTPManagerSignalsService
+│   ├── Location: services/request-manager-services/http-manager-signals.service.ts
+│   └── Same as HTTPManagerService but with Angular Signals
+│       ├── data: Signal<any>
+│       ├── isPending: Signal<boolean>
+│       ├── error: Signal<any>
+│       └── countdown: Signal<number>
+│
+└── HTTPManagerStateService (extends ComponentStore)
+    ├── Location: services/request-manager-state-service/http-manager-state.store.ts
+    ├── Inherits all HTTPManagerService features
+    ├── ComponentStore Integration (NgRx)
+    ├── CRUD with Auto State Updates
+    ├── WebSocket Integration (via WebSocketManagerService singleton)
+    │   ├── SYS- channels (State sync - private)
+    │   ├── PUB- channels (Messaging - public)
+    │   └── MES- channels (Notifications - persisted)
+    ├── IndexedDB Caching (via DatabaseManagerService)
+    ├── Pagination Support
+    ├── Real-time Updates
+    └── clearDatabase() method for flushing cache
+
+StoreStateManagerService (extends ComponentStore)
+├── Location: services/store-state-manager-service/store-state-manager.service.ts
+└── Features:
+    ├── LocalStorage persistence with ComponentStore
+    ├── Automatic state synchronization
+    ├── Configurable model-based state
+    └── Reactive updates via localStorage changes
+
+LocalStorageManagerService (extends ComponentStore)
+├── Location: services/local-storage-manager-service/local-storage-manager.service.ts
+└── Features:
+    ├── LocalStorage & SessionStorage management
+    ├── AES encryption support
+    ├── Expiration management with auto-cleanup
+    ├── Reactive store$ observables
+    ├── Signal-based API (signal(), computed())
+    └── Metadata tracking (settings, expires)
+
+LocalStorageSignalsManagerService
+├── Location: services/local-storage-manager-service/local-storage-signals-manager.service.ts
+└── Same as LocalStorageManagerService but Signal-optimized
+
+DatabaseManagerService (extends DbService/Dexie.js)
+├── Location: services/database-manager-service/database.manager.service.ts
+└── Features:
+    ├── IndexedDB wrapper via Dexie.js
+    ├── Observable-based CRUD operations
+    ├── Table management (create, check, schema inspection)
+    ├── Bulk operations (bulkPut, bulkDelete)
+    ├── Query support (where, equals, filter)
+    └── clearTable() method for flushing tables
+
+WebSocketManagerService (Singleton)
+├── Location: services/ws-manager-service/websocket-service/websocket-manager.service.ts
+└── Features:
+    ├── Single connection across ALL instances (static)
+    ├── Connection lifecycle management
+    ├── Channel subscription tracking
+    ├── Message broadcasting via BehaviorSubject
+    ├── Session ID management (UUID per browser session)
+    ├── JWT authentication support
+    ├── Automatic reconnection handling
+    └── Message replay support (lastSeenId)
+
+MessageTrackerService
+├── Location: services/ws-manager-service/message-tracker.service.ts
+└── Features:
+    ├── Message history tracking
+    ├── Last-seen message ID persistence
+    ├── Automatic re-subscription on reconnect
+    ├── Notification channel management
+    └── Historical message retrieval
+```
+
+## Data Flow
+
+### HTTP Request Flow
+
+```
+Component
+    │
+    ├─> Call Service Method (e.g., fetchRecords())
+    │
+    ▼
+HTTPManagerStateService
+    │
+    ├─> Build ApiRequest
+    │   ├─> Apply Mapper (if provided)
+    │   └─> Add Headers
+    │
+    ▼
+HTTPManagerService
+    │
+    ├─> Check Polling
+    ├─> Execute HTTP Request (HttpClient)
+    │
+    ▼
+Interceptors
+    │
+    ├─> RequestHeadersInterceptor (add headers)
+    ├─> WithCredentialsInterceptor (add credentials)
+    └─> RequestErrorInterceptor (handle errors)
+    │
+    ▼
+Backend Server
+    │
+    ├─> Process Request
+    └─> Return Response
+    │
+    ▼
+HTTPManagerService
+    │
+    ├─> Apply Adapter (transform data)
+    ├─> Update isPending$ = false
+    ├─> Update data$ with new data
+    │
+    ▼
+HTTPManagerStateService
+    │
+    ├─> Update ComponentStore state
+    └─> Save to IndexedDB (if configured)
+    │
+    ▼
+Component
+    │
+    └─> Display updated data via data$ observable
+```
+
+### WebSocket Message Flow
+
+```
+Component
+    │
+    └─> Send Message (e.g., sendNotification())
+        │
+        ▼
+HTTPManagerStateService
+    │
+    └─> Add Channel Prefix (MES-, PUB-, or SYS-)
+        │
+        ▼
+WebsocketService
+    │
+    ├─> Format Message
+    │   ├─> type: 'notification'
+    │   ├─> channel: 'MES-alerts'
+    │   ├─> content: { message: '...' }
+    │   └─> sessionId: { id, name, email }
+    │
+    └─> Send via WebSocket
+        │
+        ▼
+Backend WebSocket Server
+    │
+    ├─> Validate Channel & User
+    ├─> Store in Database (for MES- channels)
+    └─> Broadcast to Subscribers
+        │
+        ▼
+All Connected Clients (Subscribers)
+    │
+    ├─> WebsocketService receives message
+    │
+    ▼
+HTTPManagerStateService
+    │
+    ├─> Update ComponentStore
+    └─> Emit via notificationMessages$
+        │
+        ▼
+Component
+    │
+    └─> Display notification in UI
+```
+
+## Channel Architecture
+
+### Channel Types and Data Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Client Application                       │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 |
+│  Component calls:                                               │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │ stateService.subscribeToChannel('general')           (PUB)│   │
+│  │ stateService.subscribeToNotificationChannel('alerts') (MES)│  │
+│  │ stateService.fetchRecords()                          (SYS)│   │
+│  └──────────────────────────────────────────────────────────┘   │
+│                            │                                     │
+│                            ▼                                     │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │         HTTPManagerStateService                          │   │
+│  │  - Adds appropriate prefix (PUB-, MES-, SYS-)           │   │
+│  │  - Routes to WebsocketService                           │   │
+│  └──────────────────────────────────────────────────────────┘   │
+│                            │                                     │
+│                            ▼                                     │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │              WebsocketService                            │   │
+│  │  - Manages connection lifecycle                          │   │
+│  │  - Sends subscription messages                           │   │
+│  │  - Receives and routes messages                          │   │
+│  └──────────────────────────────────────────────────────────┘   │
+│                            │                                     │
+└────────────────────────────┼─────────────────────────────────────┘
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      WebSocket Server                            │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                   │
+│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐        │
+│  │ PUB- Channel │   │ MES- Channel │   │ SYS- Channel │        │
+│  │              │   │              │   │              │        │
+│  │ In-Memory    │   │ DB Persisted │   │ State Sync   │        │
+│  │ Broadcasting │   │ Notifications│   │ Private      │        │
+│  └──────┬───────┘   └──────┬───────┘   └──────┬───────┘        │
+│         │                  │                  │                 │
+│         ▼                  ▼                  ▼                 │
+│  ┌────────────────────────────────────────────────┐            │
+│  │     Channel Subscribers (Set<WebSocket>)       │            │
+│  └────────────────────────────────────────────────┘            │
+│         │                  │                  │                 │
+│         └──────────────────┴──────────────────┘                 │
+│                            │                                     │
+│                            ▼                                     │
+│  ┌─────────────────────────────────────────────────┐            │
+│  │        Broadcast to All Subscribers             │            │
+│  └─────────────────────────────────────────────────┘            │
+│                                                                   │
+│  For MES- channels:                                              │
+│  ┌─────────────────────────────────────────────────┐            │
+│  │  1. Store in SQLite Database                    │            │
+│  │  2. Broadcast to current subscribers            │            │
+│  │  3. Retrieve historical data on new subscription│            │
+│  └─────────────────────────────────────────────────┘            │
+│                                                                   │
+└───────────────────────────────────────────────────────────────────┘
+```
+
+## State Management Flow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    ComponentStore                            │
+│                (HTTPManagerStateService extends this)        │
+├─────────────────────────────────────────────────────────────┤
+│                                                               │
+│  State Interface:                                            │
+│  {                                                            │
+│    records: T[],           // Array of entities             │
+│    record: T | null,       // Single selected entity        │
+│    page: number,           // Current page                  │
+│    totalPages: number,     // Total pages                   │
+│    isPending: boolean,     // Loading state                 │
+│    error: any              // Error state                   │
+│  }                                                            │
+│                                                               │
+│  Selectors (Observables):                                    │
+│  ├─> data$ (all records)                                     │
+│  ├─> record$ (single record)                                 │
+│  ├─> selectRecord$(id) (specific record)                     │
+│  ├─> page$                                                    │
+│  └─> totalPages$                                              │
+│                                                               │
+│  Updaters (State Mutations):                                 │
+│  ├─> updateRecordsState(records[])                           │
+│  ├─> addRecordState(record)                                  │
+│  ├─> updateRecordState(record)                               │
+│  ├─> deleteRecordState(id)                                   │
+│  └─> setError(error)                                          │
+│                                                               │
+│  Effects (Side Effects):                                      │
+│  ├─> fetchRecords() → HTTP GET                               │
+│  ├─> createRecord() → HTTP POST → addRecordState()           │
+│  ├─> updateRecord() → HTTP PUT → updateRecordState()         │
+│  ├─> deleteRecord() → HTTP DELETE → deleteRecordState()      │
+│  └─> WebSocket messages → auto state updates                 │
+│                                                               │
+└───────────────────────────────────────────────────────────────┘
+```
+
+## Caching Strategy
+
+```
+┌────────────────────────────────────────────────────────────┐
+│              Fetch Records Request                          │
+└──────────────────────┬─────────────────────────────────────┘
+                       │
+                       ▼
+         ┌─────────────────────────┐
+         │ DatabaseStorage Config? │
+         └────────┬────────────────┘
+                  │
+          ┌───────┴────────┐
+          │                │
+         YES              NO
+          │                │
+          ▼                ▼
+┌──────────────────┐  ┌──────────────┐
+│Check IndexedDB   │  │Fetch from    │
+│for cached data   │  │Server (HTTP) │
+└────┬─────────────┘  └──────┬───────┘
+     │                       │
+     ▼                       │
+┌──────────────┐             │
+│Cache Valid?  │             │
+└──┬───────────┘             │
+   │                         │
+┌──┴──┐                      │
+│ YES │ NO                   │
+│     │                      │
+▼     ▼                      │
+│  ┌──────────────┐          │
+│  │Fetch from    │          │
+│  │Server        │          │
+│  └──────┬───────┘          │
+│         │                  │
+│         ▼                  │
+│  ┌──────────────┐          │
+│  │Save to       │          │
+│  │IndexedDB     │          │
+│  └──────┬───────┘          │
+│         │                  │
+└─────────┴──────────────────┘
+          │
+          ▼
+┌──────────────────────────┐
+│Update ComponentStore     │
+│and emit via data$        │
+└──────────────────────────┘
+```
+
+## File Structure
+
+```
+projects/http-request-manager/
+├── src/
+│   ├── lib/
+│   │   ├── services/
+│   │   │   ├── request-manager-services/
+│   │   │   │   ├── http-manager.service.ts          # Base HTTP service (Observable)
+│   │   │   │   ├── http-manager-signals.service.ts  # HTTP service (Signals)
+│   │   │   │   ├── request.service.ts               # Base request service
+│   │   │   │   ├── request-signals.service.ts       # Base request service (Signals)
+│   │   │   │   └── rxjs-operators/                  # Custom RxJS operators
+│   │   │   │
+│   │   │   ├── request-manager-state-service/
+│   │   │   │   ├── http-manager-state.store.ts      # State management (ComponentStore)
+│   │   │   │   └── models/                          # Type definitions
+│   │   │   │
+│   │   │   ├── store-state-manager-service/
+│   │   │   │   ├── store-state-manager.service.ts   # LocalStorage + ComponentStore
+│   │   │   │   └── models/
+│   │   │   │
+│   │   │   ├── local-storage-manager-service/
+│   │   │   │   ├── local-storage-manager.service.ts # LocalStorage/SessionStorage
+│   │   │   │   ├── local-storage-signals-manager.service.ts # Signals API
+│   │   │   │   └── models/
+│   │   │   │
+│   │   │   ├── database-manager-service/
+│   │   │   │   ├── database.manager.service.ts      # IndexedDB (Dexie.js)
+│   │   │   │   ├── db.storage.service.ts            # Dexie.js wrapper
+│   │   │   │   └── models/
+│   │   │   │
+│   │   │   ├── ws-manager-service/
+│   │   │   │   ├── websocket-service/
+│   │   │   │   │   └── websocket-manager.service.ts # Singleton WS connection
+│   │   │   │   ├── services/
+│   │   │   │   │   └── websocket.service.ts         # Legacy WS service
+│   │   │   │   ├── message-tracker.service.ts       # Message history & replay
+│   │   │   │   └── models/
+│   │   │   │
+│   │   │   ├── utils/                               # Utility services
+│   │   │   │   ├── utils.service.ts
+│   │   │   │   ├── object-merger.service.ts
+│   │   │   │   ├── encryption/                      # Encryption utilities
+│   │   │   │   └── app.service.ts
+│   │   │   │
+│   │   │   └── index.ts                             # Service exports
+│   │   │
+│   │   ├── interceptors/
+│   │   │   ├── request-error.interceptor.ts         # Error handling + toasts
+│   │   │   ├── request-header.interceptor.ts        # Auto headers
+│   │   │   ├── credentials.interceptor.ts           # withCredentials
+│   │   │   ├── proxy-debugger.interceptor.ts        # Debug logging
+│   │   │   └── models/
+│   │   │
+│   │   ├── models/                                  # Shared models
+│   │   │   ├── api-request.model.ts
+│   │   │   ├── database-storage.model.ts
+│   │   │   ├── data-type.enum.ts
+│   │   │   ├── retry-options.model.ts
+│   │   │   ├── config-options.model.ts
+│   │   │   └── index.ts
+│   │   │
+│   │   ├── http-request-services-demo/              # Demo components
+│   │   │   ├── request-manager-demo/
+│   │   │   ├── request-manager-state-demo/
+│   │   │   ├── request-signals-manager-demo/
+│   │   │   ├── database-data-demo/
+│   │   │   ├── local-storage-demo/
+│   │   │   └── local-storage-signals-demo/
+│   │   │
+│   │   ├── http-request-manager.module.ts           # Module definition
+│   │   └── index.ts                                 # Public API
+│   │
+│   └── docs/                                        # Documentation
+│       ├── HTTP_MANAGER_README.md
+│       ├── HTTP_STATE_MANAGER_README.md
+│       ├── HTTP_SINGNALS_MANAGER_README.md
+│       ├── WS_MANAGER_README.md
+│       ├── DATABASE_README.md
+│       ├── LOCAL_STORAGE_README.md
+│       ├── UTILS_README.md
+│       └── INTERCEPTOR_README.md
+│
+├── ARCHITECTURE.md                                  # This file
+├── README.md                                        # Main documentation
+├── package.json
+└── ng-package.json                                  # ng-packagr config
+```
+
+### Backend Requirements
+
+For full functionality, the backend server must:
+
+1. **HTTP REST API**
+   - CRUD endpoints for entities
+   - JSON request/response format
+   - Support for standard HTTP methods (GET, POST, PUT, DELETE)
+
+2. **WebSocket Server**
+   - Accept WebSocket connections with optional JWT authentication
+   - Handle message types: `subscribe`, `unsubscribe`, `message`, `notification`, etc.
+   - Broadcast messages to channel subscribers
+   - Maintain channel subscriptions per connection
+
+3. **Database (for MES- channels)**
+   - Store notifications with: id, channel, user_name, created (epoch), message (JSON)
+   - Support queries by channel and date range
+   - Provide endpoints for:
+     - GET today's notification channels
+     - GET previous day's notification channels
+     - GET notifications by channel with date filters
+
+### Example Backend Structure
+
+See `gtlc-websockets` server implementation for reference:
+- `ws-server.js` - Main server with HTTP and WebSocket setup
+- `middleware/websocket-service.js` - WebSocket message handlers
+- `middleware/notification-db.js` - SQLite database operations
+
+---
+
+## Security Considerations
+
+1. **JWT Authentication**: WebSocket connections can require JWT tokens
+2. **Encrypted Storage**: LocalStorage can use AES encryption with APP_ID
+3. **Channel Access Control**: Backend validates user permissions for channels
+4. **HTTPS/WSS**: Production deployments should use secure protocols
+5. **Data Validation**: All inputs are validated on server side
+
+---
+
+## Performance Optimizations
+
+1. **IndexedDB Caching**: Reduces server load and improves offline capability
+2. **Polling with Countdown**: Visual feedback prevents duplicate requests
+3. **Connection Pooling**: WebSocket reuses single connection for all channels
+4. **Debounced Updates**: State updates batched when possible
+5. **Lazy Loading**: Services loaded only when needed
+
+---
+
+## Migration Guide
+
+### From HTTPClient to HTTPManagerService
+
+```typescript
+// Before (HttpClient)
+http.get('api/users').subscribe(users => {
+  this.users = users;
+  this.loading = false;
+});
+
+// After (HTTPManagerService)
+httpManager.getRequest(
+  ApiRequest.adapt({ path: ['users'] })
+).subscribe();
+
+data$ = this.httpManager.data$;
+isLoading$ = this.httpManager.isPending$;
+```
+
+### From Manual State to HTTPManagerStateService
+
+```typescript
+// Before (Manual State)
+users: User[] = [];
+loading = false;
+
+loadUsers() {
+  this.loading = true;
+  this.http.get('api/users').subscribe(users => {
+    this.users = users;
+    this.loading = false;
+  });
+}
+
+addUser(user: User) {
+  this.http.post('api/users', user).subscribe(newUser => {
+    this.users = [...this.users, newUser];
+  });
+}
+
+// After (HTTPManagerStateService)
+@Injectable()
+export class UsersStore extends HTTPManagerStateService<User> {
+  constructor() {
+    super(ApiRequest.adapt({ path: ['users'] }), DataType.ARRAY);
+  }
+  
+  loadUsers() { this.fetchRecords(); }
+  addUser(user: User) { this.createRecord(user); }
+}
+
+// Component
+data$ = this.usersStore.data$;
+isLoading$ = this.usersStore.isPending$;
+```
+
+---
+
+This architecture provides a scalable, maintainable foundation for Angular applications with comprehensive data management capabilities.