Behaviour for stateful Arizona handlers.

A stateful handler owns a piece of UI with its own bindings, lifecycle, and event handling. The framework instantiates one set of bindings per mounted instance and re-renders / diffs against that instance whenever its bindings change. The same behaviour serves both route-level pages (spawned as a live-process root, with request data supplied as bindings by the transport via arizona_middleware:extract/1 middlewares) and embedded components (instantiated from a parent template via ?stateful(Handler, Props)).

Handlers include arizona_stateful.hrl, which sets the behaviour and enables the parse transform that compiles ?html(...) calls in render/1 into optimized template maps.

Required callbacks

• mount/1 -- runs once on instance creation; returns initial bindings plus any reset values
• render/1 -- returns the template for the current bindings; called on first render and after any change

Optional callbacks

• handle_event/3 -- responds to client events
• handle_info/2 -- responds to mailbox messages
• handle_update/3 -- reacts to new props (from a parent re-render or a patch navigation), threading the effect accumulator
• handle_drain/2 -- coordinates a graceful shutdown before the live process exits (see "Graceful drain" below)
• unmount/1 -- cleanup hook on instance removal

Resets and effects

Resets is a map of binding values that should be re-applied on top of any modifications made by the handler -- typically used to clear form fields or transient flags after they've been processed.

Effects is a list of arizona_effect:cmd/0 to run client-side after the diff is applied (e.g. focus a field, dispatch a custom event).

Only the live-only callbacks carry effects. An effect is a command sent over the WebSocket, so it needs a connected client to receive it -- and mount/1 and render/1 also run on the request-free SSR path, where there is none. The split follows from that: handle_event/3, handle_info/2, handle_update/3 and handle_drain/2 never run at SSR and all return effects; mount/1 runs on both paths and returns none (mount_ret/0 is {Bindings, Resets}).

For a mount-time effect, self-cast from mount/1 and answer in handle_info/2, which is live-only and does carry effects:

mount(_Bindings0) ->
    Bindings = #{id => ~"page"},
    ?connected andalso ?send(arizona_connected),
    {Bindings, #{}}.

handle_info(arizona_connected, Bindings) ->
    {Bindings, #{}, [arizona_js:set_title(~"Ready")]}.

The ?connected guard is load-bearing. ?send is self() ! Msg: inside a live process that self-delivers and reaches handle_info/2, but at SSR self() is the request process, whose mailbox nothing ever reads -- so an unguarded send is silently dropped, with no crash to point at it.

This is also how a navigate gets a mount-time effect. A navigate remounts, and mount/1 has no effects slot, so the effect arrives as its own pushed frame rather than folded into the navigate reply.

Graceful drain

When the server adapter drains its listener (arizona_server: notify_drain/2 during a rolling deploy, which leaves the listener serving, or drain/2 for a full listener shutdown), each live handler's optional handle_drain/2 runs. If a handler doesn't export it, the framework defaults to exiting the live process with reason {shutdown, drain} so the WebSocket closes with code 1001 (going away). The JS client auto-reconnects (preserving any form state) and the new live process mounts against the new server version.

To push a client-side indicator before closing:

handle_drain(Deadline, Bindings) ->
    Remaining = Deadline - erlang:monotonic_time(millisecond),
    {stop, Bindings, [
        arizona_js:dispatch_event(~"draining",
                                  #{~"ms_remaining" => Remaining})
    ]}.

To stay alive past drain (e.g. a long-running export the user explicitly chose to finish), return {Bindings, Resets, Effects} like a normal handle_info/2. Return ok to acknowledge without state change.

One exception -- a drain that lands before the view mounted. A reconnecting client that promised its cached fingerprints (_az_fps_follow) leaves the live process deliberately unmounted until that frame arrives, and a deploy-drain broadcast is exactly what tends to land in that window. handle_drain/2 does not run there: it takes the handler's own bindings, and pre-mount those are still the raw route bindings (route config plus middleware enrichments) that mount/1 never turned into the handler's own state -- a callback head destructuring its mount keys would raise unhandled_drain and close 4500 instead of 1001. The live process takes the same default an unexported callback gets (exit {shutdown, drain}), so the client's form-state-preserving reconnect still runs. Nothing is lost: nothing has been rendered for that connection to coordinate about, and the client is mid-reconnect already.

handle_drain/2 vs unmount/1

Both run during a graceful shutdown, but they answer different questions and run at different points in the lifecycle:

They compose: a deploy-time drain runs handle_drain/2 first, then (if it returned {stop, ...} or wasn't exported) the live process exits normal and unmount/1 runs during terminate. Both are optional; implement either, both, or neither.

Sequence on a deploy drain when both are implemented:

1. The server adapter sends the live process {arizona_drain, Deadline}.
2. Live process's handle_drain/2 runs -- e.g. pushes a "reconnecting" indicator and returns {stop, B, Effects}.
3. Push frame leaves the WS session toward the client.
4. Live process exits with reason {shutdown, drain}; terminate/2 calls unmount/1 for cleanup (unsub pubsub, release ETS, etc.).
5. WS session observes the exit and sends close code 1001.
6. Client auto-reconnects to the new server version.

Why unmount/1 can't replace handle_drain/2: by the time unmount/1 fires the process is exiting; messages sent from it race the close frame. handle_drain/2 runs while the process is fully alive, so push-before-close ordering is reliable in practice on a single node (the framework sends the push from the live process before returning {stop, normal, _}, so the WS session sees the push frame before the EXIT signal).

Snapshot-template skew on post-drain reconnect

The JS client's auto-reconnect path treats the close as a transient disconnect and preserves the current snapshot for the next session (it adds _az_reconnect=1 to the upgrade URL; the server skips the fresh-mount HTML and resumes diffing). If the deploy changed the handler's render template, the new server's diff baseline won't match the client's preserved snapshot, and the first diff may misalign (visual glitches until the next full re-render).

This isn't drain-specific -- the same risk exists for any reconnect across a deploy -- but drain makes it more likely because clients reconnect deterministically on every deploy. Mitigations if the glitch is unacceptable for a given handler:

• In handle_drain/2, push arizona_js:reload() instead of dispatch_event/2 to force a full page reload on the client (loses any client-only state but guarantees template alignment).
• Or use arizona_js:navigate/1 to redirect the client to a known good route on drain.

Default behavior (no effect or a custom dispatch_event effect) takes the reconnect-with-snapshot path; choose explicitly when the handler's template churns often.