http-request-manager 22.0.4 → 22.0.13

package/README.md

@@ -25,15 +25,51 @@ This README is the main documentation hub for the library. Detailed service guid
 | **🗄️ Database Queries** | MySQL-syntax SQL queries on IndexedDB — the recommended way to query data | [`DexieSqlService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/SQL_DIXIE_README.md) | Uses the same service |
 | **⚡ Utility Functions** | JSON handling, encryption, headers, validation, logging | [`UtilsService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/UTILS_README.md), [`Encryption`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/ENCRYPTION_README.md), [`Logger`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/LOGGER_README.md) | Uses the same utility layer |
 | **🔧 Utility Services** | Headers, path/query, merging, base request classes | [`Utility Services`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/UTILS_SERVICES_README.md) | Internal and helper services |
+| **🖥️ Node.js WS Server** | Companion [`ws-request-manager`](https://www.npmjs.com/package/ws-request-manager) Node.js package — pluggable auth, IP rate limiting, channels, heartbeat, message replay | [`WebSocket Server Guide`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/WS_SERVER_README.md) | Same protocol on both sides |
 
 ### Key Benefits
 
 - ✅ **Type-Safe** - Full TypeScript support with generics
 - ✅ **Offline-First** - Built-in IndexedDB caching
-- ✅ **Real-Time Ready** - Seamless WebSocket integration
+- ✅ **Real-Time Ready** - Seamless WebSocket integration with companion Node.js server
 - ✅ **Secure** - AES & RSA encryption support for sensitive data
 - ✅ **Scalable** - ComponentStore-based architecture
 - ✅ **Flexible** - Works with Observables or Signals
+- ✅ **Pluggable Auth on Server** - You control auth (API key, JWT, cookie, BFF session) and rate limits on the Node.js side
+
+### 🖥️ Server-Side Companion — `ws-request-manager`
+
+The frontend `http-request-manager` speaks the full WebSocket protocol implemented by the Node.js package [`ws-request-manager`](https://www.npmjs.com/package/ws-request-manager). The server package is **deliberately thin** — it does **not** implement any auth strategy. Instead, you provide a `WsAuthFn` (an async function) and the library calls it on every WebSocket upgrade.
+
+**Quick start:**
+
+```javascript
+// server.js
+const express = require('express');
+const http = require('http');
+const { register, registerServer, destroy, noAuth } = require('ws-request-manager');
+
+const app = express();
+app.use(express.json());
+
+async function start() {
+  await register(app, noAuth);              // mounts /ws/channels, /ws/connections, /ws/broadcast
+  const server = http.createServer(app);
+  await registerServer(server, noAuth);      // attaches WS upgrade handler at /ws
+  server.listen(3000);
+  process.on('SIGTERM', async () => { await destroy(); server.close(); });
+}
+start();
+```
+
+Swap `noAuth` for a custom `WsAuthFn` to gate access. Common patterns:
+
+- `createApiKeyAuth(process.env.STATIC_API_KEY)` — static API key
+- `createJwtAuth(process.env.JWT_SECRET_KEY)` — JWT (re-use your HTTP API's secret)
+- `createCookieAuth(validateSession)` — BFF session cookie
+- `createRateLimitedAuth(authFn, { maxFailures: 10, blockDurationMs: 300_000 })` — IP-based rate limiting wrapper
+
+👉 **Full guide:** [`WS_SERVER_README.md`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/WS_SERVER_README.md) — covers configuration (env vars), auth patterns, rate limiting, full message protocol reference, HTTP REST routes, and the end-to-end BFF setup.
 
 Note on clearing persisted data:
 
@@ -72,6 +108,7 @@ See the full SQL syntax reference: [`DexieSqlService Guide`](https://github.com/
 | **🏷️ Channel Architecture** | SYS-, PUB-, MES- channel prefixes | [`WebSocket Guide`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/ADVANCED_WEBSOCKET.md#channels) |
 | **🔌 Singleton WebSocket** | Single connection across ALL instances | [`WebSocket Guide`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/ADVANCED_WEBSOCKET.md#singleton) |
 | **✨ Unified Message Service** | Type-safe WebSocket messaging with auto prefixes | [`WebSocket Message Service`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/WEBSOCKET_MESSAGE_SERVICE.md) |
+| **🖥️ Node.js WS Server** | Companion `ws-request-manager` package for Node.js — pluggable auth, rate limiting, channels, heartbeat | [`WebSocket Server Guide`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/WS_SERVER_README.md) ([npm](https://www.npmjs.com/package/ws-request-manager)) |
 | **🚀 Batch Requests** | Execute multiple HTTP requests with sequential/parallel modes | [`Batch Request Guide`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/BATCH_REQUEST_README.md) |
 | **📝 Message Tracking** | Guaranteed delivery with gap detection | [`Message Tracker`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/MESSAGE_TRACKER_README.md) |
 | **🔍 Debug Logging** | Context-aware logging with dev/prod modes | [`Logger Service`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/LOGGER_README.md) |