Jido.Messaging.Adapters.Heartbeat behaviour (Jido Messaging v1.0.0)

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

Summary

Callbacks

check_health(instance)

Performs a health check on the channel instance.

probe_interval_ms()

Returns the recommended interval between health probes in milliseconds.

Functions

check_health(module, instance)

Safely performs a health check for a module.

implements?(module)

Checks if a module implements the Heartbeat behaviour.

probe_interval_ms(module)

Gets the probe interval for a module.

Callbacks

check_health(instance)

(optional)

@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