http-request-manager 18.15.34 → 18.16.1

package/src/docs/ARCHITECTURE.md

@@ -1,633 +0,0 @@
-# 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.