wse-client 1.2.0 → 1.2.2

package/README.md

@@ -25,7 +25,9 @@ The engine is Rust-accelerated via PyO3. Up to **2M msg/s** sustained throughput
 
 ## Quick Start
 
-### Server (Python)
+### Server (Python) -- Router Mode
+
+Embed WSE into your existing FastAPI app on the same port:
 
 ```python
 from fastapi import FastAPI
@@ -43,6 +45,31 @@ app.include_router(wse, prefix="/wse")
 await wse.publish("notifications", {"text": "Order shipped!", "order_id": 42})
 ```
 
+### Server (Python) -- Standalone Mode
+
+Run the Rust WebSocket server on a dedicated port for maximum throughput:
+
+```python
+from wse_server._wse_accel import RustWSEServer
+
+server = RustWSEServer(
+    "0.0.0.0", 5006,
+    max_connections=10000,
+    jwt_secret=b"your-secret-key",     # Rust JWT validation in handshake
+    jwt_issuer="your-app",
+    jwt_audience="your-api",
+)
+server.start()
+
+# Drain inbound events in a background thread
+while True:
+    events = server.drain_inbound(256, 50)  # batch size, timeout ms
+    for event in events:
+        handle(event)
+```
+
+Standalone mode gives you a dedicated Rust tokio runtime on its own port -- no FastAPI overhead, no GIL on the hot path. This is how WSE achieves 2M msg/s.
+
 ### Client (React)
 
 ```tsx
@@ -124,7 +151,7 @@ Compression, sequencing, filtering, rate limiting, and the WebSocket server itse
 | **Compression** | Flate2 zlib with configurable levels (1-9). Adaptive threshold -- only compress when payload exceeds size limit. Binary mode via msgpack (rmp-serde) for 30% smaller payloads. |
 | **Rate Limiter** | Atomic token-bucket rate limiter in Rust. Per-connection rate enforcement. 100K tokens capacity, 10K tokens/sec refill. |
 | **Message Deduplication** | AHashSet-backed dedup with bounded queue. Prevents duplicate delivery across reconnections and Redis fan-out. |
-| **Wire Envelope** | Protocol v2: `{t, id, ts, seq, p, v}`. Generic payload extraction with automatic type conversion (UUID, datetime, Enum, bytes to JSON-safe primitives). Latency tracking (`latency_ms` field). |
+| **Wire Envelope** | Protocol v1: `{t, id, ts, seq, p, v}`. Generic payload extraction with automatic type conversion (UUID, datetime, Enum, bytes to JSON-safe primitives). Latency tracking (`latency_ms` field). |
 | **Snapshot Provider** | Protocol for initial state delivery. Implement `get_snapshot(user_id, topics)` and clients receive current state immediately on subscribe -- no waiting for the next publish cycle. |
 | **Circuit Breaker** | Three-state machine (CLOSED / OPEN / HALF_OPEN). Sliding-window failure tracking. Automatic recovery probes. Prevents cascade failures when downstream services are unhealthy. |
 | **Message Categories** | `S` (snapshot), `U` (update), `WSE` (system). Category prefixing for client-side routing and filtering. |
@@ -217,9 +244,11 @@ Client (React + TypeScript)              Server (Python + Rust)
 ========================                 ========================
 
 useWSE hook                              FastAPI Router (/wse)
-    |                                        |
-    v                                        v
-ConnectionPool                           Rust Engine (PyO3)
+    |                                     -- OR --
+    v                                    RustWSEServer (standalone :5006)
+ConnectionPool                               |
+    |  (multi-endpoint,                      v
+    |   health scoring)              Rust Engine (PyO3)
     |  (multi-endpoint,                      |  (drain mode,
     |   health scoring)                      |   write coalescing)
     v                                        v

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wse-client",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "WSE (WebSocket Engine) React client. Type-safe hooks, auto-reconnect, offline queue, E2E encryption.",
   "main": "dist/index.js",
   "module": "dist/index.js",