M3 #29: Rust SDK: WebSocket client for real-time streaming

[joaquinbejar]

Summary

Implements the WebSocket client that connects to the streaming API for real-time order book updates, trades, and user order notifications.

Changes

New Module: sdk/src/ws/

File	Description
mod.rs	Module exports
config.rs	WebSocket configuration
error.rs	WebSocket-specific errors
messages.rs	Message types for client/server communication
client.rs	WebSocket client implementation

WebSocket Configuration

• URL: Configurable WebSocket endpoint
• Heartbeat Interval: Ping interval (default: 30s)
• Reconnect Delay: Initial reconnect delay (default: 1s)
• Max Reconnect Delay: Maximum backoff (default: 30s)
• API Key: Optional authentication

Subscription Management

• subscribe_book(market, depth) — Order book updates
• subscribe_trades(market) — Trade stream
• subscribe_orders() — User order updates (authenticated)
• subscribe_ticker(market) — Price ticker
• unsubscribe(channel, market) — Unsubscribe from channel

Message Types

Client Messages:

• Subscribe — Subscribe to a channel
• Unsubscribe — Unsubscribe from a channel
• Ping — Heartbeat ping

Server Messages:

• Subscribed / Unsubscribed — Subscription confirmations
• BookSnapshot — Full order book snapshot
• BookUpdate — Incremental book updates (deltas)
• Trade — Trade events
• Ticker — Price ticker updates
• OrderUpdate — User order updates
• Pong — Heartbeat response
• Error — Error messages

Connection Lifecycle

• Automatic heartbeat/ping-pong handling
• Event stream via next_event()
• Subscription tracking
• Graceful shutdown via close()

Dependencies

• Add tokio-tungstenite v0.26 with rustls-tls
• Add futures-util v0.3

Technical Decisions

• tokio-tungstenite: Industry-standard async WebSocket library
• Async stream API: Events delivered via next_event() method
• Thread-safe subscriptions: Using RwLock<HashSet<Subscription>>
• Automatic heartbeat: Spawns background task for ping/pong
• Message parsing: Deserializes into SDK types

Testing

• 28 unit tests for WebSocket client
• Configuration validation tests
• Message serialization/deserialization tests
• Subscription tracking tests

Checklist

• Code follows .internalDoc/09-rust-guidelines.md
• Documentation added for all public items
• No warnings from cargo clippy
• cargo fmt passes
• All tests pass

Closes #29