Amarula.SupervisedConnection (amarula v0.4.5)

View Source

The process behind Amarula.child_spec/1 — a thin owner that ties one Amarula connection to your supervision tree, so a fixed set of (already-paired) profiles come up at boot.

You normally don't reference this module directly; you list {Amarula, config} as a child (see Amarula.child_spec/1). This owner exists because of how a connection reconnects.

Reconnection is protocol logic the Connection owns in-process. WhatsApp requires reconnects — most notably the stream-error 515 ("restart required") the server sends right after first-time pairing, which the client must answer by tearing down the stream and re-logging-in. Connection drives that itself (schedule_reconnect/1handle_info(:reconnect, …)): it swaps its internal websocket but keeps the same pid and the same profile registration across the whole QR → pairing_success → 515 → re-login → :open sequence and every later socket drop. That's why the connection is supervised inside Amarula's own application tree — it can't be a passive process your supervisor cold-restarts, and a crash there never signals your app.

Amarula.connect/2 hands back that leaf Connection pid, which is not linked to your supervisor. Handing it straight to your supervisor would break supervision (unlinked) and, if reconnection were ever moved to a crash-restart model, spam it with restarts. So this owner is the supervised child instead. It:

  • start_links into your supervisor (proper supervision + shutdown);
  • connects on start, adopting an already-running profile as success so a restart never crash-loops on the one-per-profile guard;
  • monitors (not links) the connection. Routine reconnects (515/pairing, socket drops) are in-process and keep the pid, so they're invisible here — the monitor only fires on true process death: a Connection crash that rest_for_one replaces (→ poll the registry and re-adopt the new pid), or the whole tree dying (→ start fresh, or escalate to your supervisor);
  • stops the connection on a deliberate shutdown of this child.

Inbound events go to the :parent sink you configure, exactly as with Amarula.connect/2 — this owner does not relay them.

Summary

Functions

Returns a specification to start this module under a supervisor.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.