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
end

Route it with Dstar.Router.dstar/2:

import Dstar.Router
dstar "/counter", MyAppWeb.CounterPage

All requests are driven by Dstar.Page.Plug — pages contain no control flow, only callbacks. Conn in, conn out.

Authorization

dstar/2 registers three independent routes. Session-wide authentication belongs in the surrounding router pipeline — it already covers GET, event POST, stream POST, and dstar_components/2.

mount/2 runs only on the GET. Putting a tenant or ownership check there does not protect a direct POST /path/_event/:event or POST /path. Those skip mount/2 and would otherwise start SSE (status 200, text/event-stream) before handle_event/3 or handle_connect/2 can return a normal 401/403.

Use the optional authorize/2 callback for page-local checks. It runs after signals are read and before Dstar.SSE.start/1 / start_stream/2. Halt or send a response to reject; return the conn to continue. Assigns and private data you set are visible to later callbacks.

Route and component-module allowlists select code. They do not authorize the current user to touch a particular record. Interpolating an id into the event name ("change_title:" <> id) is fine; the handler or authorize/2 must still prove the user may touch id.

Stream deduplication

Define stream_key/1 to opt a Page stream into Dstar.Utility.StreamRegistry. The coordinator atomically claims {stream_key, tabId} before SSE and handle_connect/2. A valid keyed claim failure returns a normal halted 503 and neither callback nor loop runs; missing/invalid tabId intentionally starts unkeyed.

Takeovers carry an ownership generation. The loop ignores stale generations left in a reused keep-alive process and synchronously releases the exact current generation before handle_disconnect/1, closing the stale release-versus-kill race.

Options

• :idle_check — ms between connection liveness checks in the stream loop (default 30_000).
• :max_signal_bytes — maximum raw signal JSON size for event and stream requests (default 1_000_000). Configure Plug.Parsers to the same or a smaller limit when it reads bodies before the page plug.