wse-client 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WSE Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,222 @@
+# WSE — WebSocket Engine
+
+**Up to 1.1M msg/s. End-to-end encrypted. Rust-accelerated.**
+
+<!-- badges: pypi, npm, ci, coverage, license -->
+
+---
+
+## Performance
+
+Rust-accelerated engine via PyO3. Benchmarked on Apple M3 Max, single process, 1KB JSON.
+
+| Mode | Throughput | Latency (p50) | Latency (p99) |
+|------|-----------|---------------|---------------|
+| **Rust (binary)** | **1,100,000 msg/s** | **0.009 ms** | **0.04 ms** |
+| **Rust (JSON)** | **285,000 msg/s** | **0.03 ms** | **0.15 ms** |
+| Pure Python | 106,000 msg/s | 0.09 ms | 0.4 ms |
+
+Compared to alternatives:
+
+| Library | Throughput | Encrypted | Priority Queue | Offline Queue |
+|---------|-----------|-----------|----------------|---------------|
+| **WSE** | **1.1M msg/s** | AES-256-GCM | Yes (5-level) | Yes (IndexedDB) |
+| ws (Node) | ~50K msg/s | No | No | No |
+| Socket.IO | ~25K msg/s | No | No | No |
+| SSE | ~10K msg/s | No | No | No |
+
+See [benchmarks/](benchmarks/) and [docs/BENCHMARKS.md](docs/BENCHMARKS.md) for methodology.
+
+---
+
+## Installation
+
+```bash
+# Server (Python) — includes prebuilt Rust engine
+pip install wse-server
+
+# Client (React/TypeScript)
+npm install wse-client
+```
+
+Prebuilt wheels for Linux (x86_64, aarch64), macOS (x86_64, arm64), and Windows (x86_64).
+Python 3.12+ (ABI3 stable — one wheel per platform).
+
+---
+
+## Features
+
+**Rust-Accelerated Engine**
+- Compression (zlib via flate2), sequencing, filtering, rate limiting — all in Rust
+- PyO3 native module — no subprocess, no FFI overhead
+- Python API unchanged — drop-in acceleration
+
+**Security**
+- End-to-end AES-256-GCM encryption per channel
+- HMAC-SHA256 message signing
+- JWT authentication with configurable claims
+- Per-connection scope enforcement
+
+**Reliability**
+- Automatic reconnection with exponential backoff + jitter
+- Sequence numbers with gap detection and out-of-order buffering
+- Circuit breaker with configurable threshold
+- Offline queue with IndexedDB persistence
+- Connection health monitoring with adaptive quality
+
+**Scaling**
+- Redis pub/sub for multi-process fan-out
+- Horizontal scaling across workers with shared state
+- Per-topic subscription — clients receive only what they need
+
+**Developer Experience**
+- 4-line server setup with FastAPI
+- React hook with full TypeScript types
+- Zustand store integration
+- Protocol versioning (v2) for backward compatibility
+
+---
+
+## Quick Start
+
+### Server (Python)
+
+```python
+from fastapi import FastAPI
+from wse_server import create_wse_router, WSEConfig
+
+app = FastAPI()
+
+wse = create_wse_router(WSEConfig(
+    redis_url="redis://localhost:6379",
+    encryption_key="your-32-byte-key-here...",
+))
+
+app.include_router(wse, prefix="/wse")
+```
+
+Publish from anywhere:
+
+```python
+await wse.publish("prices", {"symbol": "AAPL", "price": 187.42})
+```
+
+### Client (React)
+
+```typescript
+import { useWSE } from 'wse-client';
+
+function PriceDisplay() {
+  const wse = useWSE(authToken, ['prices'], {
+    endpoints: ['ws://localhost:8000/wse'],
+  });
+
+  useEffect(() => {
+    const handler = (e: CustomEvent) => {
+      console.log('Price update:', e.detail);
+    };
+    window.addEventListener('price_update', handler);
+    return () => window.removeEventListener('price_update', handler);
+  }, []);
+
+  return <div>Status: {wse.connectionHealth}</div>;
+}
+```
+
+---
+
+## Architecture
+
+```
+Client (React/TypeScript)              Server (Python + Rust)
+---------------------                  ---------------------
+
+useWSE hook                            FastAPI Router
+    |                                      |
+    v                                      v
+ConnectionManager                      Rust WSE Server
+    |                                      |
+    v                                      v
+MessageProcessor                       EventTransformer (Rust)
+    |                                      |
+    v                                      v
+Zustand Store                          PubSub Bus
+    |                                      |
+    v                                      v
+React Components                       Redis Streams (optional)
+```
+
+**Wire format (v2):**
+
+```json
+{
+  "v": 2,
+  "id": "019503a1-...",
+  "t": "price_update",
+  "ts": "2026-01-15T10:30:00Z",
+  "seq": 42,
+  "p": { "symbol": "AAPL", "price": 187.42 }
+}
+```
+
+Category prefixes on the wire: `WSE{` (system), `S{` (snapshot), `U{` (update).
+
+---
+
+## Packages
+
+| Package | Registry | Language | Install |
+|---------|----------|----------|---------|
+| `wse-server` | PyPI | Python + Rust | `pip install wse-server` |
+| `wse-client` | npm | TypeScript + React | `npm install wse-client` |
+
+Both packages are standalone — no shared dependencies between server and client.
+
+---
+
+## When NOT to Use WSE
+
+| Use case | Better tool | Why |
+|----------|-------------|-----|
+| Simple chat rooms | Socket.IO | Built-in rooms, namespaces, broadcast |
+| Service-to-service RPC | gRPC | Schema enforcement, bidirectional streaming |
+| Message queues | RabbitMQ, Kafka | Persistent queues, consumer groups |
+| Static dashboards | SSE | Simpler protocol, no WebSocket overhead |
+| File uploads | HTTP multipart | WebSocket not designed for large binaries |
+
+WSE is for: real-time UI updates, live data feeds, monitoring dashboards, collaborative state sync, and high-throughput server-to-client event delivery.
+
+---
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Protocol Spec](docs/PROTOCOL.md) | Wire format, versioning, encryption |
+| [Architecture](docs/ARCHITECTURE.md) | System design, data flow |
+| [Benchmarks](docs/BENCHMARKS.md) | Methodology, results, comparisons |
+| [Security Model](docs/SECURITY.md) | Encryption, auth, threat model |
+| [Integration Guide](docs/INTEGRATION.md) | FastAPI setup, Redis, deployment |
+
+---
+
+## Technology Stack
+
+| Component | Technology | Purpose |
+|-----------|-----------|---------|
+| Rust engine | PyO3 + maturin | Compression, sequencing, filtering, rate limiting |
+| Server framework | FastAPI + Starlette | ASGI WebSocket handling |
+| Serialization | orjson (Rust) | Zero-copy JSON |
+| Binary protocol | msgpack (rmp-serde) | 30% smaller payloads |
+| Encryption | AES-256-GCM (Rust) | Per-channel E2E encryption |
+| Authentication | PyJWT | Token verification |
+| Pub/Sub backbone | Redis Streams | Multi-process fan-out, replay |
+| Client state | Zustand | Lightweight React store |
+| Client hooks | React 18+ | useWSE hook |
+| Build system | maturin | Rust+Python hybrid wheels |
+
+---
+
+## License
+
+MIT

package/dist/constants.d.ts

@@ -0,0 +1,195 @@
+export declare const WS_PROTOCOL_VERSION = 2;
+export declare const WS_CLIENT_VERSION = "1.0.0";
+export declare const HEARTBEAT_INTERVAL = 15000;
+export declare const IDLE_TIMEOUT = 40000;
+export declare const CONNECTION_TIMEOUT = 10000;
+export declare const HEALTH_CHECK_INTERVAL = 30000;
+export declare const METRICS_INTERVAL = 60000;
+export declare const RECONNECT_BASE_DELAY = 1000;
+export declare const RECONNECT_MAX_DELAY = 30000;
+export declare const RECONNECT_MAX_ATTEMPTS = -1;
+export declare const RECONNECT_FACTOR = 1.5;
+export declare const RECONNECT_JITTER = true;
+export declare const CIRCUIT_BREAKER_THRESHOLD = 5;
+export declare const CIRCUIT_BREAKER_TIMEOUT = 60000;
+export declare const CIRCUIT_BREAKER_SUCCESS_THRESHOLD = 3;
+export declare const MESSAGE_QUEUE_MAX_SIZE = 1000;
+export declare const OFFLINE_QUEUE_MAX_SIZE = 1000;
+export declare const BATCH_SIZE = 10;
+export declare const BATCH_TIMEOUT = 100;
+export declare const COMPRESSION_THRESHOLD = 1024;
+export declare const COMPRESSION_LEVEL = 6;
+export declare const RATE_LIMIT_CAPACITY = 1000;
+export declare const RATE_LIMIT_REFILL_RATE = 100;
+export declare const RATE_LIMIT_REFILL_INTERVAL = 1;
+export declare const SEQUENCE_WINDOW_SIZE = 1000;
+export declare const MAX_OUT_OF_ORDER = 100;
+export declare const DUPLICATE_WINDOW_SIZE = 1000;
+export declare const STORAGE_KEY_PREFIX = "wse_";
+export declare const SUBSCRIPTION_STORAGE_KEY = "wse_subscriptions";
+export declare const ENDPOINTS_STORAGE_KEY = "wse_endpoints";
+export declare const METRICS_STORAGE_KEY = "wse_metrics";
+export declare const DIAGNOSTICS_STORAGE_KEY = "wse_diagnostics";
+export declare const DEFAULT_TOPICS: string[];
+export declare const MESSAGE_HEADERS: {
+    readonly COMPRESSED: "C:";
+    readonly MSGPACK: "M:";
+    readonly ENCRYPTED: "E:";
+};
+export declare const MEMORY_LIMITS: {
+    readonly MAX_MESSAGE_SIZE: 1048576;
+    readonly MAX_QUEUE_MEMORY: number;
+    readonly MAX_HISTORY_SIZE: 1000;
+    readonly MAX_ERROR_HISTORY: 50;
+};
+export declare const FEATURES: {
+    readonly COMPRESSION: true;
+    readonly ENCRYPTION: false;
+    readonly BATCHING: true;
+    readonly PRIORITY_QUEUE: true;
+    readonly CIRCUIT_BREAKER: true;
+    readonly OFFLINE_QUEUE: true;
+    readonly MESSAGE_SIGNING: false;
+    readonly RATE_LIMITING: true;
+    readonly HEALTH_CHECK: true;
+    readonly METRICS: true;
+};
+export declare const INTERNAL_TO_WS_EVENT_TYPE_MAP: Record<string, string>;
+export declare const ERROR_CODES: {
+    readonly NORMAL_CLOSURE: 1000;
+    readonly GOING_AWAY: 1001;
+    readonly PROTOCOL_ERROR: 1002;
+    readonly UNSUPPORTED_DATA: 1003;
+    readonly POLICY_VIOLATION: 1008;
+    readonly MESSAGE_TOO_BIG: 1009;
+    readonly SERVER_ERROR: 1011;
+    readonly AUTH_FAILED: 4401;
+    readonly AUTH_EXPIRED: 4403;
+    readonly RATE_LIMIT_EXCEEDED: 4429;
+    readonly SUBSCRIPTION_FAILED: 4430;
+    readonly INVALID_MESSAGE: 4400;
+    readonly SERVER_OVERLOAD: 4503;
+};
+export declare const PERFORMANCE_THRESHOLDS: {
+    readonly LATENCY: {
+        readonly EXCELLENT: 50;
+        readonly GOOD: 150;
+        readonly FAIR: 300;
+    };
+    readonly JITTER: {
+        readonly EXCELLENT: 25;
+        readonly GOOD: 50;
+        readonly FAIR: 100;
+    };
+    readonly PACKET_LOSS: {
+        readonly EXCELLENT: 0.1;
+        readonly GOOD: 1;
+        readonly FAIR: 3;
+    };
+};
+/**
+ * Get WebSocket endpoints. By default uses same-origin /wse path.
+ * Override this by providing endpoints in WSEConfig.
+ */
+export declare function getEndpoints(): string[];
+export declare function getSavedSubscriptions(): string[];
+export declare function saveSubscriptions(topics: string[]): void;
+export declare function clearWSEStorage(): void;
+export declare const isValidPriority: (priority: number) => boolean;
+export declare const isValidEventType: (type: string) => boolean;
+export declare const isCompressedMessage: (data: ArrayBuffer) => boolean;
+export declare const isMsgPackMessage: (data: ArrayBuffer) => boolean;
+export declare const isEncryptedMessage: (data: ArrayBuffer) => boolean;
+declare const _default: {
+    WS_PROTOCOL_VERSION: number;
+    WS_CLIENT_VERSION: string;
+    HEARTBEAT_INTERVAL: number;
+    IDLE_TIMEOUT: number;
+    CONNECTION_TIMEOUT: number;
+    HEALTH_CHECK_INTERVAL: number;
+    METRICS_INTERVAL: number;
+    RECONNECT_BASE_DELAY: number;
+    RECONNECT_MAX_DELAY: number;
+    RECONNECT_MAX_ATTEMPTS: number;
+    RECONNECT_FACTOR: number;
+    RECONNECT_JITTER: boolean;
+    CIRCUIT_BREAKER_THRESHOLD: number;
+    CIRCUIT_BREAKER_TIMEOUT: number;
+    CIRCUIT_BREAKER_SUCCESS_THRESHOLD: number;
+    MESSAGE_QUEUE_MAX_SIZE: number;
+    OFFLINE_QUEUE_MAX_SIZE: number;
+    BATCH_SIZE: number;
+    BATCH_TIMEOUT: number;
+    COMPRESSION_THRESHOLD: number;
+    COMPRESSION_LEVEL: number;
+    RATE_LIMIT_CAPACITY: number;
+    RATE_LIMIT_REFILL_RATE: number;
+    RATE_LIMIT_REFILL_INTERVAL: number;
+    SEQUENCE_WINDOW_SIZE: number;
+    MAX_OUT_OF_ORDER: number;
+    DUPLICATE_WINDOW_SIZE: number;
+    STORAGE_KEY_PREFIX: string;
+    SUBSCRIPTION_STORAGE_KEY: string;
+    ENDPOINTS_STORAGE_KEY: string;
+    METRICS_STORAGE_KEY: string;
+    DIAGNOSTICS_STORAGE_KEY: string;
+    DEFAULT_TOPICS: string[];
+    INTERNAL_TO_WS_EVENT_TYPE_MAP: Record<string, string>;
+    ERROR_CODES: {
+        readonly NORMAL_CLOSURE: 1000;
+        readonly GOING_AWAY: 1001;
+        readonly PROTOCOL_ERROR: 1002;
+        readonly UNSUPPORTED_DATA: 1003;
+        readonly POLICY_VIOLATION: 1008;
+        readonly MESSAGE_TOO_BIG: 1009;
+        readonly SERVER_ERROR: 1011;
+        readonly AUTH_FAILED: 4401;
+        readonly AUTH_EXPIRED: 4403;
+        readonly RATE_LIMIT_EXCEEDED: 4429;
+        readonly SUBSCRIPTION_FAILED: 4430;
+        readonly INVALID_MESSAGE: 4400;
+        readonly SERVER_OVERLOAD: 4503;
+    };
+    MESSAGE_HEADERS: {
+        readonly COMPRESSED: "C:";
+        readonly MSGPACK: "M:";
+        readonly ENCRYPTED: "E:";
+    };
+    PERFORMANCE_THRESHOLDS: {
+        readonly LATENCY: {
+            readonly EXCELLENT: 50;
+            readonly GOOD: 150;
+            readonly FAIR: 300;
+        };
+        readonly JITTER: {
+            readonly EXCELLENT: 25;
+            readonly GOOD: 50;
+            readonly FAIR: 100;
+        };
+        readonly PACKET_LOSS: {
+            readonly EXCELLENT: 0.1;
+            readonly GOOD: 1;
+            readonly FAIR: 3;
+        };
+    };
+    MEMORY_LIMITS: {
+        readonly MAX_MESSAGE_SIZE: 1048576;
+        readonly MAX_QUEUE_MEMORY: number;
+        readonly MAX_HISTORY_SIZE: 1000;
+        readonly MAX_ERROR_HISTORY: 50;
+    };
+    FEATURES: {
+        readonly COMPRESSION: true;
+        readonly ENCRYPTION: false;
+        readonly BATCHING: true;
+        readonly PRIORITY_QUEUE: true;
+        readonly CIRCUIT_BREAKER: true;
+        readonly OFFLINE_QUEUE: true;
+        readonly MESSAGE_SIGNING: false;
+        readonly RATE_LIMITING: true;
+        readonly HEALTH_CHECK: true;
+        readonly METRICS: true;
+    };
+};
+export default _default;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../client/constants.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,mBAAmB,IAAI,CAAC;AACrC,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAMzC,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AACxC,eAAO,MAAM,YAAY,QAAQ,CAAC;AAClC,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AACxC,eAAO,MAAM,qBAAqB,QAAQ,CAAC;AAC3C,eAAO,MAAM,gBAAgB,QAAQ,CAAC;AAMtC,eAAO,MAAM,oBAAoB,OAAO,CAAC;AACzC,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AACzC,eAAO,MAAM,sBAAsB,KAAK,CAAC;AACzC,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAMrC,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAC3C,eAAO,MAAM,uBAAuB,QAAQ,CAAC;AAC7C,eAAO,MAAM,iCAAiC,IAAI,CAAC;AAMnD,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAC3C,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAC3C,eAAO,MAAM,UAAU,KAAK,CAAC;AAC7B,eAAO,MAAM,aAAa,MAAM,CAAC;AAMjC,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAC1C,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAMnC,eAAO,MAAM,mBAAmB,OAAO,CAAC;AACxC,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAC1C,eAAO,MAAM,0BAA0B,IAAM,CAAC;AAM9C,eAAO,MAAM,oBAAoB,OAAO,CAAC;AACzC,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAM1C,eAAO,MAAM,kBAAkB,SAAS,CAAC;AACzC,eAAO,MAAM,wBAAwB,sBAAuC,CAAC;AAC7E,eAAO,MAAM,qBAAqB,kBAAmC,CAAC;AACtE,eAAO,MAAM,mBAAmB,gBAAiC,CAAC;AAClE,eAAO,MAAM,uBAAuB,oBAAqC,CAAC;AAO1E,eAAO,MAAM,cAAc,EAAE,MAAM,EAElC,CAAC;AAMF,eAAO,MAAM,eAAe;;;;CAIlB,CAAC;AAMX,eAAO,MAAM,aAAa;;;;;CAKhB,CAAC;AAMX,eAAO,MAAM,QAAQ;;;;;;;;;;;CAWX,CAAC;AAQX,eAAO,MAAM,6BAA6B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,CAAC;AAMxE,eAAO,MAAM,WAAW;;;;;;;;;;;;;;CAiBd,CAAC;AAMX,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;CAgBzB,CAAC;AAMX;;;GAGG;AACH,wBAAgB,YAAY,IAAI,MAAM,EAAE,CAwCvC;AAED,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAOhD;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAMxD;AAED,wBAAgB,eAAe,IAAI,IAAI,CAQtC;AAMD,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,KAAG,OAElD,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,OAG/C,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAAI,MAAM,WAAW,KAAG,OAGvD,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,MAAM,WAAW,KAAG,OAGpD,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,MAAM,WAAW,KAAG,OAGtD,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAMF,wBAwCE"}