Amarula.Protocol.Socket.ConnectionSupervisor (amarula v0.1.0)

View Source

Per-connection supervision tree. One ConnectionSupervisor owns everything for a single WhatsApp connection instance:

ConnectionSupervisor (:one_for_one)
├── Registry            (per-instance; keys = {instance_id, role})
├── TableOwner          (per-connection retry-cache ETS)
├── Connection          (THE socket: ws + cipher + IQ + sends + consumer API)
└── SenderSupervisor    (DynamicSupervisor) — ConversationSender…

Connection.make_socket/2 starts this supervisor and returns the Connection child pid — the consumer's handle, so the public API (connect/send_text/... on that pid) lands on Connection directly (no relay).

Siblings find each other through the per-instance Registry by role, via name/2 / whereis/2 — no global atom names, no leaked atoms.

Summary

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

name(instance_id, role)

The :via tuple addressing a sibling role in this instance's Registry.

registry_name(instance_id)

The per-instance Registry's process name. Derived from the instance ref so it is unique per instance and dies with the supervisor.

start_instance(conn, opts \\ [])

Start a connection instance. opts may carry :parent_pid. Returns {:ok, sup_pid, connection_pid} — connection_pid is the consumer handle.

stop_instance(instance_id)

Stop a whole connection tree by its instance_id (the supervisor + all children, freeing the profile registration). Returns :ok, or {:error, :not_found} if no such tree is running.

supervisor_name(instance_id)

The supervisor's registered name, derived from the instance ref.

whereis(instance_id, role)

Resolve a sibling role to a pid, or :undefined.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

name(instance_id, role)

@spec name(reference(), atom()) :: {:via, Registry, {atom(), {reference(), atom()}}}

The :via tuple addressing a sibling role in this instance's Registry.

registry_name(instance_id)

The per-instance Registry's process name. Derived from the instance ref so it is unique per instance and dies with the supervisor.

start_instance(conn, opts \\ [])

@spec start_instance(
  Amarula.Conn.t(),
  keyword()
) :: {:ok, pid(), pid()} | {:error, term()}

Start a connection instance. opts may carry :parent_pid. Returns {:ok, sup_pid, connection_pid} — connection_pid is the consumer handle.

The tree is started under the library-owned Amarula.ConnectionsSupervisor (a DynamicSupervisor), not linked to the calling consumer. A connection crash is therefore observable by the consumer through parent_pid events but never delivers an exit signal that would take the consumer down.

stop_instance(instance_id)

@spec stop_instance(reference()) :: :ok | {:error, :not_found}

Stop a whole connection tree by its instance_id (the supervisor + all children, freeing the profile registration). Returns :ok, or {:error, :not_found} if no such tree is running.

supervisor_name(instance_id)

@spec supervisor_name(reference()) :: atom()

The supervisor's registered name, derived from the instance ref.

whereis(instance_id, role)

@spec whereis(reference(), atom()) :: pid() | :undefined

Resolve a sibling role to a pid, or :undefined.