# `Jido.Messaging.InstanceServer`
[🔗](https://github.com/agentjido/jido_messaging/blob/v1.0.0/lib/jido_messaging/instance_server.ex#L1)

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]`

# `t`

```elixir
@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()
}
```

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `get_instance`

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

Get the full instance struct

# `health_snapshot`

```elixir
@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`

Notify that the instance is connected

# `notify_connecting`

Notify that the instance is connecting

# `notify_disconnected`

Notify that the instance is disconnected

# `notify_failure`

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

# `notify_reconnect_attempt`

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

Record reconnect attempt progress for lifecycle observability

# `notify_restart_marker`

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

Record a restart marker before lifecycle workers crash/escalate

# `notify_success`

Notify of a successful operation (resets failure counter)

# `schema`

Returns the Zoi schema

# `start_link`

# `status`

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

Get current instance status

# `stop`

Gracefully stop the instance

# `whereis`

Get the instance server pid

---

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