One module per page: render, event handlers, stream callbacks, and colocated function components.
defmodule MyAppWeb.CounterPage do
use Dstar.Page
def mount(conn, _params), do: assign(conn, count: 0)
def render(assigns) do
~H"""
<div data-signals:count={@count}>
<button data-on:click={event("increment")}>+1</button>
</div>
"""
end
def handle_event(conn, "increment", signals) do
patch_signals(conn, %{count: (signals["count"] || 0) + 1})
end
endRoute it with Dstar.Router.dstar/2:
import Dstar.Router
dstar "/counter", MyAppWeb.CounterPageAll requests are driven by Dstar.Page.Plug — pages contain no
control flow, only callbacks. Conn in, conn out.
Options
:idle_check— ms between connection liveness checks in the stream loop (default30_000).
Summary
Callbacks
Stream open: subscribe to topics, assign loop state. Optional —
defining it enables POST /path streaming.
Stream close: release what handle_connect/2 acquired — unsubscribe,
untrack presence, drop caches. Optional.
Handles a Datastar event POST. SSE is already started. Optional.
Handles one message from the library-owned receive loop. Optional.
GET: load data and assign what render/1 needs. Optional.
The full-page HEEx template. Required.
If defined, the stream opens via Dstar.start_stream/2 keyed on the result. Optional.
Callbacks
@callback handle_connect(Plug.Conn.t(), params :: map()) :: Plug.Conn.t()
Stream open: subscribe to topics, assign loop state. Optional —
defining it enables POST /path streaming.
@callback handle_disconnect(Plug.Conn.t()) :: any()
Stream close: release what handle_connect/2 acquired — unsubscribe,
untrack presence, drop caches. Optional.
Runs on every exit from the receive loop: a {:halt, conn} from
handle_info/2, a dead client, or a takeover by a newer stream for the
same stream_key/1. The library already unregisters the stream from
Dstar.Utility.StreamRegistry for you; this is for app-owned state.
The client is usually gone by this point, so treat the conn as write-only-on-a-best-effort basis. A crash here is logged and swallowed — teardown continues either way. The return value is ignored.
Best-effort, not guaranteed
This runs when the loop ends, which requires the process to survive long enough to notice. A takeover that kills the process outright skips it: only Thousand Island (so Bandit HTTP/1.1) connection processes trap exits, whereas Bandit's HTTP/2 stream processes and Cowboy request processes do not, and the registry's escalation kill is untrappable by design.
Anything cleaned up by process monitors — Phoenix.PubSub
subscriptions, Phoenix.Presence, the registry entry itself — is
released regardless. Reserve this callback for state that is not
monitor-backed (external caches, rows in another system), and make it
idempotent: on a takeover it can interleave with, or run after, the
replacing stream's handle_connect/2, so cleanup keyed on the tab
rather than on this stream can otherwise clobber what the new stream
just wrote.
@callback handle_event(Plug.Conn.t(), event :: String.t(), signals :: map()) :: Plug.Conn.t()
Handles a Datastar event POST. SSE is already started. Optional.
@callback handle_info(msg :: term(), Plug.Conn.t()) :: Plug.Conn.t() | {:halt, Plug.Conn.t()}
Handles one message from the library-owned receive loop. Optional.
@callback mount(Plug.Conn.t(), params :: map()) :: Plug.Conn.t()
GET: load data and assign what render/1 needs. Optional.
@callback render(assigns :: map()) :: Phoenix.LiveView.Rendered.t()
The full-page HEEx template. Required.
@callback stream_key(Plug.Conn.t()) :: term()
If defined, the stream opens via Dstar.start_stream/2 keyed on the result. Optional.