wse-client 1.4.0 → 1.4.2

package/README.md

@@ -20,7 +20,7 @@ Building real-time features between React and Python is painful. You need WebSoc
 
 Install `wse-server` on your backend, `wse-client` on your frontend (React or Python). Everything works immediately: auto-reconnection, message encryption, sequence ordering, offline queues, health monitoring. No configuration required for the defaults. Override what you need.
 
-The engine is Rust-accelerated via PyO3. Up to **14M msg/s** JSON, **30M msg/s** compressed — benchmarked on AMD EPYC 7502P (32 cores) with the Rust stress-test client ([results](docs/BENCHMARKS_RUST_CLIENT.md)). Sub-millisecond connection latency (0.38ms median) with Rust JWT authentication.
+The engine is Rust-accelerated via PyO3. **14M msg/s** JSON, **30M msg/s** binary, **2.1M deliveries/s** fan-out, **500K concurrent connections** with zero message loss -- benchmarked on AMD EPYC 7502P. Multi-instance horizontal scaling via Redis pub/sub. Sub-millisecond latency (0.38 ms) with Rust JWT authentication.
 
 ---
 
@@ -33,17 +33,28 @@ Embed WSE into your existing FastAPI app on the same port:
 ```python
 from fastapi import FastAPI
 from wse_server import create_wse_router, WSEConfig
+import redis.asyncio as redis
 
 app = FastAPI()
 
+redis_client = redis.Redis(host="localhost", port=6379, decode_responses=False)
+
 wse = create_wse_router(WSEConfig(
-    redis_url="redis://localhost:6379",
+    redis_client=redis_client,
 ))
 
 app.include_router(wse, prefix="/wse")
+```
+
+Publish events from anywhere in your app via the PubSub bus:
 
-# Publish from anywhere in your app
-await wse.publish("notifications", {"text": "Order shipped!", "order_id": 42})
+```python
+bus = app.state.pubsub_bus
+
+await bus.publish(
+    topic="notifications",
+    event={"event_type": "order_shipped", "order_id": 42, "text": "Order shipped!"},
+)
 ```
 
 ### Server (Python) -- Standalone Mode
@@ -141,7 +152,7 @@ Connection quality scoring (excellent / good / fair / poor), latency tracking, j
 
 ### Scaling
 
-Redis pub/sub for multi-process fan-out. Run multiple server workers behind a load balancer. Clients get messages from any worker. Fire-and-forget delivery with sub-millisecond latency.
+Redis pub/sub for multi-instance fan-out. Run N server instances behind a load balancer -- publish on any instance, all subscribers receive the message regardless of which instance they're connected to. Pipelined PUBLISH (up to 64 per round-trip), circuit breaker, exponential backoff with jitter, dead letter queue for failed messages. Capacity scales linearly with instances: tested up to 1.04M deliveries/s per instance.
 
 ### Rust Performance
 
@@ -169,7 +180,8 @@ Compression, sequencing, filtering, rate limiting, and the WebSocket server itse
 | **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. |
-| **PubSub Bus** | Redis pub/sub with PSUBSCRIBE pattern matching. orjson fast-path serialization. Custom JSON encoder for UUID, datetime, Decimal. Non-blocking handler invocation. |
+| **Multi-Instance Orchestration** | Horizontal scaling via Redis pub/sub. Publish on any instance, all subscribers receive the message. Pipelined PUBLISH (64 commands/batch, 3 retries), circuit breaker (10-fail threshold, 60s reset), exponential backoff with jitter, dead letter queue (1000-entry ring buffer). 1.04M deliveries/s per instance, linear scaling with N instances. |
+| **PubSub Bus** | Redis pub/sub with PSUBSCRIBE pattern matching. Glob wildcard topic routing (`user:*:events`). orjson fast-path serialization. Non-blocking handler invocation. |
 | **Pluggable Security** | `EncryptionProvider` and `TokenProvider` protocols. Built-in: AES-GCM-256 with ECDH P-256 key exchange, HMAC-SHA256 signing, selective message signing. Rust-accelerated crypto (SHA-256, HMAC, AES-GCM, ECDH). |
 | **Rust JWT Authentication** | HS256 JWT validation in Rust during the WebSocket handshake. Zero GIL acquisition on the connection critical path. 0.01ms decode (85x faster than Python). Cookie extraction and `server_ready` sent from Rust before Python runs. |
 | **Lock-Free Server Queries** | `get_connection_count()` uses `AtomicUsize` — zero GIL, zero blocking, safe to call from async Python handlers. No channel round-trip to the tokio runtime. |
@@ -210,44 +222,137 @@ Compression, sequencing, filtering, rate limiting, and the WebSocket server itse
 
 ## Performance
 
-Rust-accelerated engine via PyO3. Benchmarked on localhost.
+Rust-accelerated engine via PyO3. AMD EPYC 7502P (32 cores, 128 GB), Ubuntu 24.04, localhost.
+
+### Highlights
+
+| Metric | Value | Details |
+|--------|-------|---------|
+| **Peak throughput** | **14.2M msg/s** | JSON, Rust client, 500 connections |
+| **Peak binary** | **30M msg/s** | MsgPack/compressed, Rust client |
+| **Fan-out broadcast** | **2.1M deliveries/s** | Single-instance, zero message loss |
+| **Max connections** | **500,000** | Zero errors, zero gaps at every tier |
+| **Connection latency** | **0.38 ms** median | Rust JWT auth in handshake |
+| **Accept rate** | **15,020 conn/s** | Sustained connection establishment |
+| **Memory per conn** | **4.4 KB** | Rust core static overhead |
+
+### Point-to-Point (Rust Native Client)
+
+| Payload | Throughput | Bandwidth |
+|---------|-----------|-----------|
+| 64 bytes | **19.4M msg/s** | 1.2 GB/s |
+| 256 bytes | **12.5M msg/s** | 3.1 GB/s |
+| 1 KB | **10.3M msg/s** | 10.0 GB/s |
+| 16 KB | **1.2M msg/s** | **19.9 GB/s** |
+| 64 KB | **284K msg/s** | **18.2 GB/s** |
+
+### Point-to-Point (Python Multi-Process, 64 Workers)
 
-### Apple M2 (8 cores)
+| Metric | JSON | MsgPack |
+|--------|------|---------|
+| **Sustained** | **2,045,000 msg/s** | **2,072,000 msg/s** |
+| **Burst** | 1,557,000 msg/s | 1,836,000 msg/s |
+| **64KB messages** | 256K msg/s (16.0 GB/s) | -- |
+| **Ping RTT** | 0.26 ms median | -- |
 
-| Metric | Single Client | 10 Workers |
-|--------|--------------|------------|
-| **Sustained throughput (JSON)** | 113,000 msg/s | **356,000 msg/s** |
-| **Sustained throughput (MsgPack)** | 116,000 msg/s | **345,000 msg/s** |
-| **Burst throughput (JSON)** | 106,000 msg/s | **488,000 msg/s** |
-| **Connection latency** | **0.53 ms** median | 2.20 ms median |
-| **Ping RTT** | **0.09 ms** median | 0.18 ms median |
-| **64KB messages** | 43K msg/s (2.7 GB/s) | **164K msg/s (10.2 GB/s)** |
+### Point-to-Point (TypeScript/Node.js, 64 Processes)
 
-### AMD EPYC 7502P (64 cores, 128 GB)
+| Format | Throughput | Scaling |
+|--------|-----------|---------|
+| JSON | **7.0M msg/s** | 97% linear |
+| MsgPack | **7.9M msg/s** | +13% over JSON |
 
-| Metric | 64 Workers | 128 Workers |
-|--------|-----------|-------------|
-| **Sustained throughput (JSON)** | **2,045,000 msg/s** | 2,013,000 msg/s |
-| **Sustained throughput (MsgPack)** | **2,072,000 msg/s** | 2,041,000 msg/s |
-| **Burst throughput (JSON)** | 1,557,000 msg/s | **1,836,000 msg/s** |
-| **Connection latency** | 2.60 ms median | 2.96 ms median |
-| **Ping RTT** | 0.26 ms median | 0.41 ms median |
-| **64KB messages** | **256K msg/s (16.0 GB/s)** | 238K msg/s (14.9 GB/s) |
+### Fan-out Broadcast (Single-Instance)
 
-See [BENCHMARKS.md](docs/BENCHMARKS.md) for full results and methodology.
+Server broadcasts to N subscribers. **Zero message loss at every tier.**
+
+| Subscribers | Deliveries/s | Bandwidth | p50 Latency |
+|-------------|-------------|-----------|-------------|
+| 10 | **2.1M** | 295 MB/s | 0.005 ms |
+| 1,000 | 1.4M | 185 MB/s | -- |
+| 10,000 | 1.2M | 163 MB/s | -- |
+| 100,000 | 1.7M | 234 MB/s | -- |
+| **500,000** | **1.4M** | 128 MB/s | -- |
+
+### Rust Acceleration vs Python
+
+| Component | Speedup | Rust | Python |
+|-----------|---------|------|--------|
+| JWT decode (HS256) | **85x** | 10 us | 850 us |
+| Msgpack parsing | **~50x** | -- | -- |
+| Rate limiter | **40x** | -- | -- |
+| HMAC-SHA256 | **22x** | -- | -- |
+| Compression (zlib) | **6.7x** | -- | -- |
+
+See benchmark docs for full results: [Overview](docs/BENCHMARKS.md) | [Rust Client](docs/BENCHMARKS_RUST_CLIENT.md) | [TypeScript Client](docs/BENCHMARKS_TS_CLIENT.md) | [Python Client](docs/BENCHMARKS_PYTHON_CLIENT.md) | [Fan-out](docs/BENCHMARKS_FANOUT.md)
 
 ---
 
 ## Use Cases
 
-WSE works for any real-time communication between frontend and backend:
+### Live Dashboards
+
+Push price updates, sensor data, or analytics to the browser in real time.
+
+```python
+# Server: push price updates
+await bus.publish(
+    topic="prices",
+    event={"event_type": "price_update", "symbol": "AAPL", "price": 187.42},
+)
+```
+
+```tsx
+// React: consume them
+window.addEventListener('price_update', (e: CustomEvent) => {
+  updateChart(e.detail.symbol, e.detail.price);
+});
+```
+
+### Notifications
+
+Push order updates, alerts, or system events to specific users.
+
+```python
+# Server: notify a specific user
+await bus.publish(
+    topic=f"user:{user_id}:events",
+    event={"event_type": "order_shipped", "order_id": 42, "text": "Your order shipped!"},
+)
+```
+
+```tsx
+// React: show a toast
+window.addEventListener('order_shipped', (e: CustomEvent) => {
+  showToast(e.detail.text);
+});
+```
+
+### Chat and Messaging
+
+Group chats, DMs, typing indicators, read receipts. Enable encryption for privacy.
+
+```python
+# Server: broadcast a chat message
+await bus.publish(
+    topic=f"chat:{channel_id}",
+    event={"event_type": "message_sent", "text": body.text, "author": user.name},
+)
+```
+
+```python
+# Python client: listen for messages
+async with connect("ws://localhost:5006/wse", token=jwt) as client:
+    await client.subscribe([f"chat:{channel_id}"])
+    async for event in client:
+        print(f"{event.payload['author']}: {event.payload['text']}")
+```
+
+### Other Use Cases
 
-- **Live dashboards** -- stock prices, sensor data, analytics, monitoring panels
-- **Notifications** -- order updates, alerts, system events pushed to the browser
-- **Collaborative apps** -- shared cursors, document editing, whiteboarding
-- **Chat and messaging** -- group chats, DMs, typing indicators, read receipts
-- **IoT and telemetry** -- device status, real-time metrics, command and control
-- **Gaming** -- game state sync, leaderboards, matchmaking updates
+- **Collaborative editing** -- shared cursors, document changes, conflict detection via sequence numbers
+- **IoT and telemetry** -- device status, sensor metrics, command and control. Use LOW priority for telemetry, HIGH for alerts
+- **Gaming** -- game state sync, leaderboards, matchmaking. Use msgpack binary protocol for lower latency
 
 ---
 

package/dist/constants.d.ts

@@ -1,5 +1,5 @@
 export declare const WS_PROTOCOL_VERSION = 1;
-export declare const WS_CLIENT_VERSION = "1.3.9";
+export declare const WS_CLIENT_VERSION = "1.4.2";
 export declare const HEARTBEAT_INTERVAL = 15000;
 export declare const IDLE_TIMEOUT = 40000;
 export declare const CONNECTION_TIMEOUT = 10000;

package/dist/constants.js

@@ -5,7 +5,7 @@
 // Protocol Constants
 // ---------------------------------------------------------------------------
 export const WS_PROTOCOL_VERSION = 1;
-export const WS_CLIENT_VERSION = '1.3.9';
+export const WS_CLIENT_VERSION = '1.4.2';
 // ---------------------------------------------------------------------------
 // Connection Constants
 // ---------------------------------------------------------------------------

package/dist/index.d.ts

@@ -21,5 +21,5 @@ export type { OfflineQueueConfig } from './services/OfflineQueue';
 export { EventHandlers } from './handlers/EventHandlers';
 export { registerAllHandlers } from './handlers/index';
 export * from './constants';
-export declare const WSE_VERSION = "1.3.9";
+export declare const WSE_VERSION = "1.4.2";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -44,5 +44,5 @@ export * from './constants';
 // ---------------------------------------------------------------------------
 // Version Info
 // ---------------------------------------------------------------------------
-export const WSE_VERSION = '1.3.9';
+export const WSE_VERSION = '1.4.2';
 //# sourceMappingURL=index.js.map

package/package.json

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