Listens to the Incus event stream (/1.0/events websocket) and fans events out to subscriber processes - the push-based alternative to polling for dashboards and monitors.

Nothing is started automatically: add one listener per Incus server to your application's supervision tree if (and only if) you want events:

children = [
  {ExIncus.EventListener,
   name: MyApp.IncusEvents,
   connect: [socket_path: "/var/lib/incus/unix.socket"],
   types: [:lifecycle, :operation],
   all_projects: true}
]

Any process can then subscribe and will receive plain messages:

{:ok, status} = ExIncus.EventListener.subscribe(MyApp.IncusEvents, types: [:lifecycle])

# arriving in handle_info/2:
{:ex_incus_event, %ExIncus.Event{action: "instance-started", name: "web1"}}
{:ex_incus_connected, listener_pid}
{:ex_incus_disconnected, listener_pid, reason}

Subscribers are monitored and removed automatically when they exit.

Reconnection and the snapshot pattern

The listener reconnects with exponential backoff when the connection drops, but Incus does not replay missed events. {:ex_incus_connected, pid} is therefore sent on every (re)connect: treat it as "my picture of the world may be stale" and re-fetch state, e.g. with ExIncus.Instances.list/2. A live dashboard should:

1. subscribe/2 (the return tells you whether the stream is currently up)
2. fetch a snapshot (ExIncus.Instances.list(client, recursion: 2))
3. apply incoming lifecycle events to it
4. on {:ex_incus_connected, _}, go back to step 2

Bridging to Phoenix.PubSub (or anything else)

Instead of (or in addition to) subscribers, pass a :handler function; it is invoked with the same tuples subscribers receive:

{ExIncus.EventListener,
 connect: [socket_path: "/var/lib/incus/unix.socket"],
 types: [:lifecycle],
 handler: fn message -> Phoenix.PubSub.broadcast(MyApp.PubSub, "incus", message) end}

A crashing handler is logged, not fatal.

Options

• :connect - ExIncus.Client.new/1-style connection options (socket_path: or base_url: + certfile:/keyfile:/...)
• :types - event types to request from the server ([:lifecycle, :operation, :logging]); nil (default) means all
• :project - project to watch (defaults to connect[:project])
• :all_projects - watch every project
• :handler - function invoked with each message (see above)
• :name - GenServer name
• :backoff_min / :backoff_max - reconnect backoff bounds in ms (defaults 1_000 / 30_000)
• :upgrade_timeout - websocket handshake timeout in ms (default 15_000)