Coordinates the lifecycle of a WhatsApp Web connection.

When started with runtime.ownership.vext_managed: true, the worker behaves as a transport engine only: it still emits raw lifecycle facts, but leaves reconnect and product-level stop policy to the external owner.

This GenServer is designed for long-running production use with:

• Automatic reconnection with exponential backoff
• Connection health monitoring
• Graceful degradation on errors
• Telemetry events for observability
• Crash recovery via supervision

What lives here, and what does not

This module owns the process: the state struct, the GenServer callbacks and the decision of what each incoming message means. The work each decision triggers lives in a module named after the concern, all of them called from this process — a module is not a process, so the transport is still linked to the session, monitors are registered against it and timers land in its mailbox.

• ExWapp.Session.Worker.Connection — opening, tearing down and retrying the transport, and the connection events it reports
• ExWapp.Session.Worker.SendRecovery — resending, repairing a rejected peer session, and asking the primary device for a placeholder resend
• ExWapp.Session.Worker.SendHealth — send counters and the error guard
• ExWapp.Session.Worker.SignalSessions — loading, persisting and pruning Signal sessions
• ExWapp.Session.Worker.PostAuth — the prekey and passive handshake that follows a successful login
• ExWapp.Session.Worker.NodeHandler — turning an inbound stanza into state plus a list of actions
• ExWapp.Session.Worker.Outbound / OutboundConfirmation / Retry — the send path and its delivery confirmations
• ExWapp.Session.Worker.Subscribers / Events — what the session reports to subscribers and to telemetry

Supervision

For production use, run Session under ExWapp.Session.Supervisor:

{:ok, sup} = ExWapp.Session.Supervisor.start_link(
  store: {ExWapp.Store.Ets, path: "/var/lib/myapp/wa.etf"}
)
session = ExWapp.Session.Supervisor.session(sup)

Telemetry Events

The session emits the following telemetry events:

• [:ex_wapp, :session, :init] - Session process initialized
• [:ex_wapp, :session, :connect] - Connection attempt
• [:ex_wapp, :session, :connected] - Successfully connected
• [:ex_wapp, :session, :disconnected] - Connection lost
• [:ex_wapp, :session, :reconnect] - Reconnection attempt
• [:ex_wapp, :session, :error] - Error occurred
• [:ex_wapp, :session, :qr] - QR lifecycle event (:code, :success, :error)
• [:ex_wapp, :session, :message_received] - Message persisted/forwarded
• [:ex_wapp, :session, :message_sent] - Message sent to transport
• [:ex_wapp, :session, :terminate] - Session terminate callback

State Machine

idle -> connecting -> handshaking -> syncing -> connected
  ^                                                  |
  |                                                  v
  +<---------------- disconnected <------------------+