# `Jido.Messaging.Adapters.Heartbeat`
[🔗](https://github.com/agentjido/jido_messaging/blob/v1.0.0/lib/jido_messaging/adapters/heartbeat.ex#L1)

Behaviour for channel-specific health checking.

Provides a standardized callback for channels to implement custom health checks
that probe the underlying platform connection.

## Implementation

Channels can implement this behaviour to provide platform-specific health checks:

    defmodule MyApp.Channels.Telegram do
      @behaviour Jido.Messaging.Channel
      @behaviour Jido.Messaging.Adapters.Heartbeat

      @impl Jido.Messaging.Adapters.Heartbeat
      def check_health(instance) do
        case Telegex.get_me() do
          {:ok, _bot_info} -> :ok
          {:error, reason} -> {:error, {:api_error, reason}}
        end
      end

      @impl Jido.Messaging.Adapters.Heartbeat
      def probe_interval_ms, do: :timer.seconds(30)
    end

## Default Implementations

All callbacks are optional:

  * `check_health/1` - Returns `:ok` if not implemented
  * `probe_interval_ms/0` - Returns `30_000` (30 seconds) if not implemented

## Integration

The InstanceServer can use this behaviour to perform periodic health probes:

    if function_exported?(channel_module, :check_health, 1) do
      case channel_module.check_health(instance) do
        :ok -> InstanceServer.notify_connected(pid)
        {:error, reason} -> InstanceServer.notify_disconnected(pid, reason)
      end
    end

# `check_health`
*optional* 

```elixir
@callback check_health(instance :: Jido.Messaging.Instance.t()) :: :ok | {:error, term()}
```

Performs a health check on the channel instance.

Should probe the underlying platform connection and return:
  * `:ok` - Connection is healthy
  * `{:error, reason}` - Connection is unhealthy

## Parameters

  * `instance` - The Instance struct containing credentials and settings

## Examples

    def check_health(%Instance{} = instance) do
      case MyAPI.ping(instance.credentials.api_key) do
        {:ok, _} -> :ok
        {:error, :timeout} -> {:error, :timeout}
        {:error, reason} -> {:error, reason}
      end
    end

# `probe_interval_ms`
*optional* 

```elixir
@callback probe_interval_ms() :: pos_integer()
```

Returns the recommended interval between health probes in milliseconds.

This is advisory - the actual probe schedule is controlled by the caller.

# `check_health`

```elixir
@spec check_health(module(), Jido.Messaging.Instance.t()) :: :ok | {:error, term()}
```

Safely performs a health check for a module.

Returns `:ok` if the module doesn't implement the callback.

# `implements?`

```elixir
@spec implements?(module()) :: boolean()
```

Checks if a module implements the Heartbeat behaviour.

# `probe_interval_ms`

```elixir
@spec probe_interval_ms(module()) :: pos_integer()
```

Gets the probe interval for a module.

Returns the default (30 seconds) if the module doesn't implement the callback.

---

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