Jido.Messaging.InstanceServer (Jido Messaging v1.0.0)

Per-instance GenServer that tracks lifecycle state and emits signals.

The InstanceServer is the authoritative source for instance status. Channel processes (Poller, Sender) communicate state changes to the InstanceServer, which then emits appropriate telemetry signals.

State Machine

:starting -> :connecting -> :connected
                        |-> :disconnected <-> :connected
                        |-> :error

Signals Emitted

[:jido_messaging, :instance, :started]
[:jido_messaging, :instance, :connecting]
[:jido_messaging, :instance, :connected]
[:jido_messaging, :instance, :disconnected]
[:jido_messaging, :instance, :stopped]
[:jido_messaging, :instance, :error]

Summary

Types

t()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

get_instance(pid)

Get the full instance struct

health_snapshot(pid)

Get a health snapshot for the instance.

notify_connected(pid, meta \\ %{})

Notify that the instance is connected

notify_connecting(pid)

Notify that the instance is connecting

notify_disconnected(pid, reason \\ :unknown)

Notify that the instance is disconnected

notify_failure(pid, reason)

Notify of a delivery or operation failure (increments failure counter)

notify_reconnect_attempt(pid, attempt, reason \\ nil)

Record reconnect attempt progress for lifecycle observability

notify_restart_marker(pid, failure_class, reason)

Record a restart marker before lifecycle workers crash/escalate

notify_success(pid)

Notify of a successful operation (resets failure counter)

schema()

Returns the Zoi schema

start_link(opts)

status(pid)

Get current instance status

stop(pid)

Gracefully stop the instance

whereis(instance_module, instance_id)

Get the instance server pid

Types

t()

@type t() :: %Jido.Messaging.InstanceServer{
  connected_at:
    nil
    | nil
    | %DateTime{
        calendar: term(),
        day: term(),
        hour: term(),
        microsecond: term(),
        minute: term(),
        month: term(),
        second: term(),
        std_offset: term(),
        time_zone: term(),
        utc_offset: term(),
        year: term(),
        zone_abbr: term()
      },
  consecutive_failures: integer(),
  instance: %Jido.Messaging.Instance{
    channel_type: term(),
    credentials: term(),
    id: term(),
    inserted_at: term(),
    name: term(),
    settings: term(),
    status: term()
  },
  instance_module: any(),
  last_error: nil | nil | any(),
  last_restart_class: nil | nil | :recoverable | :fatal,
  last_restart_reason: nil | nil | any(),
  reconnect_attempt: integer(),
  restart_count: integer(),
  started_at:
    nil
    | nil
    | %DateTime{
        calendar: term(),
        day: term(),
        hour: term(),
        microsecond: term(),
        minute: term(),
        month: term(),
        second: term(),
        std_offset: term(),
        time_zone: term(),
        utc_offset: term(),
        year: term(),
        zone_abbr: term()
      },
  status: :starting | :connecting | :connected | :disconnected | :error,
  stopped_emitted: boolean()
}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

get_instance(pid)

@spec get_instance(pid()) :: {:ok, Jido.Messaging.Instance.t()}

Get the full instance struct

health_snapshot(pid)

@spec health_snapshot(pid()) :: {:ok, map()}

Get a health snapshot for the instance.

Returns a map with:

:status - current status (:connected, :disconnected, :error, etc.)
:instance_id - the instance ID
:channel_type - the channel type atom
:name - the instance name
:uptime_ms - milliseconds since the instance started
:connected_at - DateTime when connected (or nil)
:last_error - the last error (or nil)
:consecutive_failures - number of consecutive failures
:sender_queue_depth - queue depth of sender (if available)

notify_connected(pid, meta \\ %{})

Notify that the instance is connected

notify_connecting(pid)

Notify that the instance is connecting

notify_disconnected(pid, reason \\ :unknown)

Notify that the instance is disconnected

notify_failure(pid, reason)

Notify of a delivery or operation failure (increments failure counter)

notify_reconnect_attempt(pid, attempt, reason \\ nil)

@spec notify_reconnect_attempt(pid(), non_neg_integer(), term() | nil) :: :ok

Record reconnect attempt progress for lifecycle observability

notify_restart_marker(pid, failure_class, reason)

@spec notify_restart_marker(pid(), :recoverable | :fatal, term()) :: :ok

Record a restart marker before lifecycle workers crash/escalate

notify_success(pid)

Notify of a successful operation (resets failure counter)

schema()

Returns the Zoi schema

start_link(opts)

status(pid)

@spec status(pid() | {module(), String.t()}) :: {:ok, map()} | {:error, :not_found}

Get current instance status

stop(pid)

Gracefully stop the instance

whereis(instance_module, instance_id)

Get the instance server pid