# `ZenWebsocket`
[🔗](https://github.com/ZenHive/zen_websocket/blob/v0.4.2/lib/zen_websocket.ex#L1)

A robust WebSocket client library for Elixir, built on Gun transport.

Designed for financial APIs (cryptocurrency exchanges like Deribit) but
works with any WebSocket endpoint. Provides automatic reconnection,
heartbeat management, rate limiting, and request/response correlation.

## Quick Start

    # Connect to a WebSocket endpoint
    {:ok, client} = ZenWebsocket.Client.connect("wss://test.deribit.com/ws/api/v2")

    # Send a message
    :ok = ZenWebsocket.Client.send_message(client, Jason.encode!(%{method: "public/test"}))

    # Subscribe to channels
    :ok = ZenWebsocket.Client.subscribe(client, ["trades.BTC-PERPETUAL.raw"])

    # Check connection state
    :connected = ZenWebsocket.Client.get_state(client)

    # Close when done
    :ok = ZenWebsocket.Client.close(client)

## Supervised Connections

For production use, `ZenWebsocket.ClientSupervisor` manages connection pools
with health-based load balancing:

    # Start the supervisor (add to your application supervision tree)
    ZenWebsocket.ClientSupervisor.start_link([])

    # Start managed connections
    {:ok, client} = ZenWebsocket.ClientSupervisor.start_client("wss://example.com/ws")

    # Route to healthiest connection
    :ok = ZenWebsocket.ClientSupervisor.send_balanced(message)

## Key Modules

### Client API
* `ZenWebsocket.Client` — 5-function public API: `connect/2`, `send_message/2`,
  `close/1`, `subscribe/2`, `get_state/1`
* `ZenWebsocket.ClientSupervisor` — supervised connection pool with `send_balanced/2`
* `ZenWebsocket.Config` — connection configuration and validation

### Infrastructure
* `ZenWebsocket.Reconnection` — exponential backoff retry logic
* `ZenWebsocket.HeartbeatManager` — keepalive lifecycle management
* `ZenWebsocket.SubscriptionManager` — subscription tracking and restoration
* `ZenWebsocket.RequestCorrelator` — JSON-RPC request/response correlation
* `ZenWebsocket.RateLimiter` — token bucket rate limiting
* `ZenWebsocket.PoolRouter` — health-based connection routing

### Observability
* `ZenWebsocket.ErrorHandler` — error categorization with `explain/1`
* `ZenWebsocket.LatencyStats` — connection latency tracking (p50/p99)
* `ZenWebsocket.Recorder` — session recording for debugging (JSONL format)
* `ZenWebsocket.Testing` — test utilities with `MockWebSockServer` helpers

### Protocol
* `ZenWebsocket.Frame` — WebSocket frame encoding/decoding
* `ZenWebsocket.JsonRpc` — JSON-RPC 2.0 message formatting
* `ZenWebsocket.MessageHandler` — message parsing and routing

## Platform Examples

See `ZenWebsocket.Examples.DeribitAdapter` for a production-ready adapter
demonstrating authentication, subscription management, and heartbeat handling.

## Self-Describing API

All public modules are annotated with `descripex` for progressive discovery:

    ZenWebsocket.describe()                        # Library overview
    ZenWebsocket.describe(:client)                 # Client functions
    ZenWebsocket.describe(:client, :connect)       # Full connect details

# `__descripex_modules__`

```elixir
@spec __descripex_modules__() :: [module()]
```

Return the list of modules registered with this library.

# `describe`

```elixir
@spec describe() :: [map()]
```

Return a Level 1 overview of all modules in this library.

# `describe`

```elixir
@spec describe(module() | atom()) :: [map()]
```

Return Level 2 function list for a module (by full atom or short name).

# `describe`

```elixir
@spec describe(module() | atom(), atom()) :: map() | nil
```

Return Level 3 function detail (or `nil` if not found).

---

*Consult [api-reference.md](api-reference.md) for complete listing*