Implement WebSocket endpoint for real-time price streaming

[prodbycorne]

Overview

Clients currently poll the REST price endpoints on a timer. A WebSocket endpoint lets them subscribe to push updates when prices change, reducing latency and per-client request volume.

Protocol

Subscribe

// Client → Server
{ "action": "subscribe", "assets": ["XLM", "USDC:GA5Z..."] }
// Server → Client
{ "type": "subscribed", "assets": ["XLM", "USDC:GA5Z..."] }

Price push (emitted when price changes > 0.1%)

{
  "type": "price_update",
  "asset": "XLM",
  "price_usd": 0.1145,
  "previous_price_usd": 0.112,
  "change_pct": 2.23,
  "source": "stellar_dex",
  "timestamp": "2024-01-15T10:31:00Z"
}

Heartbeat — server sends { "type": "ping" } every 30s; client replies { "action": "pong" }

Implementation

npm install ws

• Attach ws.Server to the existing HTTP server at /ws path
• PriceSubscriptionManager tracks which assets each socket watches
• After each price refresh job cycle, compare new vs previous prices; push diffs to subscribers
• Disconnect idle sockets that miss 3 consecutive pings
• Max 5 assets per client; max 100 concurrent connections

Acceptance Criteria

• WebSocket server on /ws
• Subscribe/unsubscribe actions handled
• Pushes only on price change > 0.1% threshold
• Heartbeat ping/pong implemented
• Disconnected clients removed from subscription map
• ws_connections_current Prometheus gauge updated
• Integration test: client receives push after price change