WebSocket connection and subscription manager.

Manages multiple WebSocket connections, routes subscriptions to appropriate connections, and provides a registry of active subscriptions.

Connection Strategy

All subscriptions share as few connections as possible within Hyperliquid's limits:

• Shared socket ("shared") — all :shared and :dedicated subscriptions land here. The :dedicated type is legacy; modules may still declare it but the manager treats it identically to :shared.

• First user socket — when the first :user_grouped subscription is created, it is placed on the shared socket. No extra connection is opened.

• Per-user sockets ("user:<address>") — each additional unique user gets its own connection so that message routing remains unambiguous (the connection itself is the routing tag; user addresses are not guaranteed in WS responses).

Because the shared socket carries mixed subscription types, the manager filters incoming messages by channel before dispatching to each subscription's callback.

Usage

# Subscribe to allMids (shared socket)
{:ok, sub_id} = Manager.subscribe(Hyperliquid.Api.Subscription.AllMids, %{})

# Subscribe to l2Book — also lands on the shared socket
{:ok, sub_id} = Manager.subscribe(Hyperliquid.Api.Subscription.L2Book, %{
  coin: "BTC", nSigFigs: 5
})

# First user subscription — shares the existing shared socket
{:ok, sub_id} = Manager.subscribe(Hyperliquid.Api.Subscription.UserFills, %{
  user: "0x1234..."
})

# Second user — gets its own socket
{:ok, sub_id} = Manager.subscribe(Hyperliquid.Api.Subscription.UserFills, %{
  user: "0xabcd..."
})

# Unsubscribe
:ok = Manager.unsubscribe(sub_id)

# List active subscriptions
Manager.list_subscriptions()

Architecture

The Manager uses a DynamicSupervisor to manage WebSocket connections. Each connection is a GenServer that handles the actual WebSocket communication. The Manager maintains:

1. A registry of active subscriptions (ETS table)
2. A mapping of connection keys to connection PIDs
3. Connection metadata and per-subscription metrics