wse-client 2.2.1 → 2.3.1

package/README.md

@@ -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
 
@@ -254,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
@@ -261,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.
@@ -321,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:
@@ -368,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

package/dist/constants.d.ts

@@ -1,5 +1,5 @@
 export declare const WS_PROTOCOL_VERSION = 1;
-export declare const WS_CLIENT_VERSION = "2.1.1";
+export declare const WS_CLIENT_VERSION = "2.3.1";
 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 = '2.1.1';
+export const WS_CLIENT_VERSION = '2.3.1';
 // ---------------------------------------------------------------------------
 // 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 = "2.1.1";
+export declare const WSE_VERSION = "2.3.1";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

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

package/package.json

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