M2 #23: API: WebSocket server for real-time updates

[joaquinbejar]

Summary

Implements the WebSocket server that provides real-time streaming of order book updates, trades, and user-specific order updates to connected clients.

Changes

New Module: api/src/ws/

File	Description
mod.rs	Module exports
messages.rs	ClientMessage and ServerMessage types
channels.rs	Channel parsing and ChannelManager
connection.rs	Connection state management
handler.rs	WebSocket upgrade handler
metrics.rs	WsMetrics for monitoring

Channel Subscriptions

• book:{market} — Order book deltas
• trades:{market} — Real-time trades
• orders:{owner} — User's order updates (requires auth)

Message Types

• subscribe/unsubscribe — Channel subscription requests
• snapshot — Initial state on subscription
• update — Incremental updates
• error — Error responses
• ping/pong — Keepalive

Connection Management

• Per-connection subscription tracking
• Authentication for private channels (orders)
• Backpressure via bounded mpsc channels (100 messages)
• Automatic cleanup on disconnect

WsMetrics Tracking

• Connections opened/closed/active
• Messages received/sent
• Subscriptions/unsubscriptions
• Errors and uptime
• Messages per second rate

Dependencies

• Enable axum ws feature for WebSocket support
• Add futures dependency for stream handling

Technical Decisions

• Axum WebSocket: Uses axum's built-in WebSocket support with WebSocketUpgrade
• Channel-based messaging: Uses tokio mpsc channels for outgoing messages with backpressure
• Shared state: WsState contains ChannelManager and WsMetrics shared across connections
• Authentication: Private channels (orders) require token authentication (stub implementation)
• Snapshot on subscribe: Sends initial snapshot immediately after subscription confirmation

Testing

• 50+ unit tests for messages, channels, connection, and metrics
• Message serialization/deserialization tests
• Channel parsing tests (valid/invalid formats)
• Connection subscription tests
• Authentication tests (public vs private channels)
• ChannelManager subscription management tests
• WsMetrics recording 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 #23