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

Manages heartbeat lifecycle for WebSocket connections.

Pure functional module - state ownership stays with Client GenServer.
Timer ownership stays with Client (Process.send_after needs self()).

## API Functions
| Function | Arity | Description | Param Kinds |
| --- | --- | --- | --- |
| `get_health` | 1 | Return heartbeat health metrics. | `state: value` |
| `send_heartbeat` | 1 | Send platform-specific heartbeat message. | `state: value` |
| `handle_message` | 2 | Route incoming heartbeat message to platform-specific handler. | `msg: value`, `state: value` |
| `cancel_timer` | 1 | Cancel active heartbeat timer. Call on disconnect/error. | `state: value` |
| `start_timer` | 1 | Start heartbeat timer if configured. Call on connection upgrade. | `state: value` |

# `health`

```elixir
@type health() :: %{
  active_heartbeats: [term()],
  last_heartbeat_at: integer() | nil,
  failure_count: non_neg_integer(),
  config: heartbeat_config(),
  timer_active: boolean()
}
```

Health metrics returned by get_health/1

# `heartbeat_config`

```elixir
@type heartbeat_config() :: :disabled | %{:type => atom(), optional(atom()) => term()}
```

Heartbeat configuration - disabled or platform-specific config map

# `state`

```elixir
@type state() :: %{
  :heartbeat_config => heartbeat_config(),
  :heartbeat_timer => reference() | nil,
  :heartbeat_failures => non_neg_integer(),
  :active_heartbeats => MapSet.t(),
  optional(atom()) => term()
}
```

Client state map containing heartbeat fields (subset of Client.state)

# `cancel_timer`

```elixir
@spec cancel_timer(state()) :: state()
```

Cancels active heartbeat timer. Call on disconnect/error.

Returns updated state with timer and failure count reset.

# `get_health`

```elixir
@spec get_health(state()) :: health()
```

Returns heartbeat health metrics map.

# `handle_message`

```elixir
@spec handle_message(map(), state()) :: state()
```

Routes incoming heartbeat messages to platform-specific handlers.

Returns updated state after processing heartbeat.

# `send_heartbeat`

```elixir
@spec send_heartbeat(state()) :: state()
```

Sends platform-specific heartbeat message.

Returns updated state with last_heartbeat_at timestamp for known types.
Returns unchanged state for unrecognized or disabled configs.

# `start_timer`

```elixir
@spec start_timer(state()) :: state()
```

Starts heartbeat timer if configured. Call on connection upgrade.

Returns updated state with timer reference.

---

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