wse-client 2.2.0 → 2.3.0

package/README.md

@@ -14,7 +14,7 @@ High-performance WebSocket server built in Rust with native clustering, E2E encr
 | Feature | Details |
 |---------|---------|
 | **Rust core** | tokio async runtime, tungstenite WebSocket transport, dedicated thread pool, zero GIL on the data path |
-| **JWT authentication** | Rust-native HS256 validation during handshake (0.01ms), cookie + Authorization header extraction |
+| **JWT authentication** | HS256, RS256, ES256 algorithms via jsonwebtoken crate. Validated during handshake (0.01ms), cookie + Authorization header extraction, key rotation, kid validation |
 | **Protocol negotiation** | `client_hello`/`server_hello` handshake with feature discovery, capability advertisement, version agreement |
 | **Topic subscriptions** | Per-connection topic subscriptions with automatic cleanup on disconnect |
 | **Pre-framed broadcast** | WebSocket frame built once, shared via Arc across all connections, single allocation per broadcast |
@@ -29,6 +29,9 @@ High-performance WebSocket server built in Rust with native clustering, E2E encr
 | **Compression** | zlib for client-facing messages above threshold (default 1024 bytes) |
 | **MessagePack** | Opt-in binary transport via `?format=msgpack`, roughly 2x faster serialization, 30% smaller |
 | **Message signing** | Selective HMAC-SHA256 signing for critical operations, nonce-based replay prevention |
+| **Queue groups** | Round-robin dispatch within named groups for load-balanced worker pools |
+| **Topic ACL** | Per-connection allow/deny glob patterns for topic access control |
+| **Graceful drain** | `drain()` sends Close frame to all clients, rejects new connections, notifies cluster peers |
 
 ### End-to-End Encryption
 
@@ -55,6 +58,7 @@ High-performance WebSocket server built in Rust with native clustering, E2E encr
 | **Circuit breaker** | 10 failures to open, 60s reset, 3 half-open probe calls |
 | **Dead letter queue** | 1000-entry ring buffer for failed cluster sends |
 | **Presence sync** | PresenceUpdate/PresenceFull frames, CRDT last-write-wins conflict resolution |
+| **Topology API** | `cluster_info()` returns connected peer list with address, instance_id, status |
 
 ### Presence Tracking
 
@@ -99,7 +103,7 @@ High-performance WebSocket server built in Rust with native clustering, E2E encr
 
 | Feature | Details |
 |---------|---------|
-| **Origin validation** | `ALLOWED_ORIGINS` env var, rejects unlisted origins with close code 4403 |
+| **Origin validation** | Configure in reverse proxy (nginx/Caddy) to prevent CSWSH |
 | **Cookie auth** | `access_token` HTTP-only cookie with `Secure + SameSite=Lax` (OWASP recommended for browsers) |
 | **Frame protection** | 1 MB max frame size, serde_json parsing (no eval), escaped user IDs in server_ready |
 | **Cluster frame protection** | zstd decompression output capped at 1 MB (MAX_FRAME_SIZE), protocol version validation |
@@ -163,9 +167,14 @@ token = rust_jwt_encode(
 | `host` | required | Bind address |
 | `port` | required | Bind port |
 | `max_connections` | 1000 | Maximum concurrent WebSocket connections |
-| `jwt_secret` | None | HS256 secret for JWT validation (bytes, min 32 bytes). `None` disables authentication |
+| `jwt_secret` | None | JWT key for validation. HS256: shared secret (bytes, min 32). RS256/ES256: PEM public key. `None` disables auth |
 | `jwt_issuer` | None | Expected `iss` claim. Skipped if `None` |
 | `jwt_audience` | None | Expected `aud` claim. Skipped if `None` |
+| `jwt_cookie_name` | "access_token" | Cookie name for JWT token extraction |
+| `jwt_previous_secret` | None | Previous key for zero-downtime rotation. HS256: previous secret. RS256/ES256: previous public key PEM |
+| `jwt_key_id` | None | Expected `kid` header claim. Rejects tokens with mismatched key ID |
+| `jwt_algorithm` | None | JWT algorithm: `"HS256"` (default), `"RS256"`, or `"ES256"` |
+| `jwt_private_key` | None | PEM private key for RS256/ES256 token encoding. Not needed for HS256 |
 | `max_inbound_queue_size` | 131072 | Drain mode bounded queue capacity |
 | `recovery_enabled` | False | Enable per-topic message recovery buffers |
 | `recovery_buffer_size` | 128 | Ring buffer slots per topic (rounded to power-of-2) |
@@ -176,7 +185,6 @@ token = rust_jwt_encode(
 | `presence_max_data_size` | 4096 | Max bytes for a user's presence metadata |
 | `presence_max_members` | 0 | Max tracked members per topic (0 = unlimited) |
 | `max_outbound_queue_bytes` | 16777216 | Per-connection outbound buffer limit (bytes, default 16 MB). Messages dropped when exceeded |
-| `jwt_cookie_name` | "access_token" | Cookie name for JWT token extraction |
 | `rate_limit_capacity` | 100000.0 | Token bucket capacity per connection |
 | `rate_limit_refill` | 10000.0 | Token bucket refill rate per second |
 | `max_message_size` | 1048576 | Maximum WebSocket frame size in bytes (default 1 MB) |
@@ -250,6 +258,7 @@ server.broadcast(topic, text)                    # Fan-out to topic subscribers
 ```python
 server.subscribe_connection(conn_id, ["prices", "news"])              # Subscribe to topics
 server.subscribe_connection(conn_id, ["chat"], {"status": "online"})  # Subscribe with presence data
+server.subscribe_connection(conn_id, ["tasks"], queue_group="workers") # Subscribe with queue group (round-robin)
 server.unsubscribe_connection(conn_id, ["news"])                      # Unsubscribe from specific topics
 server.unsubscribe_connection(conn_id, None)                          # Unsubscribe from all topics
 server.get_topic_subscriber_count("prices")                           # Subscriber count for a topic
@@ -257,6 +266,26 @@ server.get_topic_subscriber_count("prices")                           # Subscrib
 
 Subscriptions are cleaned up automatically on disconnect. In cluster mode, interest changes are propagated to peers via SUB/UNSUB frames.
 
+**Queue groups**: connections in the same `queue_group` receive messages round-robin instead of fanout. Normal subscribers (no queue group) still receive all messages. Useful for distributing work across a pool of consumers.
+
+### Topic ACL
+
+Per-connection topic access control with glob pattern matching.
+
+```python
+# Allow only "user:*" topics, deny everything else
+server.set_topic_acl(conn_id, allow=["user:*"])
+
+# Allow "data:*" but deny "data:internal:*"
+server.set_topic_acl(conn_id, allow=["data:*"], deny=["data:internal:*"])
+
+# Must be called before subscribe_connection
+server.subscribe_connection(conn_id, ["data:prices"])   # allowed
+server.subscribe_connection(conn_id, ["data:internal:audit"])  # denied
+```
+
+Deny patterns take precedence over allow patterns. Supports `*` (any characters) and `?` (single character) wildcards. Applied at subscribe time.
+
 ### Presence Tracking
 
 Requires `presence_enabled=True` in the constructor.
@@ -317,6 +346,7 @@ server.connect_cluster(
 
 server.cluster_connected()       # True if connected to at least one peer
 server.cluster_peers_count()     # Number of active peer connections
+server.cluster_info()            # List of connected peers (address, instance_id, connected)
 ```
 
 Nodes form a full TCP mesh automatically. The cluster protocol uses a custom binary frame format with an 8-byte header, 12 message types, and capability negotiation during handshake. Features:
@@ -364,11 +394,14 @@ health = server.health_snapshot()
 server.get_connection_count()        # Lock-free AtomicUsize read
 server.get_connections()             # List all connection IDs (snapshot)
 server.disconnect(conn_id)           # Force-disconnect a connection
+server.drain(close_code=4300, close_reason="shutting down", timeout=10)  # Graceful drain
 server.inbound_queue_depth()         # Events waiting to be drained
 server.inbound_dropped_count()       # Events dropped due to full queue
 server.get_cluster_dlq_entries()     # Retrieve failed cluster messages from dead letter queue
 ```
 
+`drain()` sends a WebSocket Close frame to all connected clients and rejects new connections. The drain wait runs as a separate task, so the command processor stays responsive. Use for zero-downtime deployments and rolling restarts.
+
 ---
 
 ## Security
@@ -382,7 +415,7 @@ Token delivery:
 - **Backend clients**: `Authorization: Bearer <token>` header and/or `access_token` cookie
 - **API clients**: `Authorization: Bearer <token>` header
 
-Required claims: `sub` (user ID), `exp` (expiration), `iat` (issued at). Optional: `iss`, `aud` (validated if configured).
+Required claims: `sub` (user ID), `exp` (expiration). Recommended: `iat` (issued at). Optional: `iss`, `aud` (validated if configured).
 
 ### End-to-End Encryption
 

package/package.json

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