Dstar.Page behaviour (dstar v0.1.4)

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.

Options

:idle_check — ms between connection liveness checks in the stream loop (default 30_000).

Summary

Callbacks

handle_connect(t, params)

Stream open: subscribe to topics, assign loop state. Optional — defining it enables POST /path streaming.

handle_disconnect(t)

Stream close: release what handle_connect/2 acquired — unsubscribe, untrack presence, drop caches. Optional.

handle_event(t, event, signals)

Handles a Datastar event POST. SSE is already started. Optional.

handle_info(msg, t)

Handles one message from the library-owned receive loop. Optional.

mount(t, params)

GET: load data and assign what render/1 needs. Optional.

render(assigns)

The full-page HEEx template. Required.

stream_key(t)

If defined, the stream opens via Dstar.start_stream/2 keyed on the result. Optional.

Callbacks

handle_connect(t, params)

(optional)

@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.

handle_disconnect(t)

(optional)

@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.

handle_event(t, event, signals)

(optional)

@callback handle_event(Plug.Conn.t(), event :: String.t(), signals :: map()) ::
  Plug.Conn.t()

Handles a Datastar event POST. SSE is already started. Optional.

handle_info(msg, t)

(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.

mount(t, params)

(optional)

@callback mount(Plug.Conn.t(), params :: map()) :: Plug.Conn.t()

GET: load data and assign what render/1 needs. Optional.

render(assigns)

@callback render(assigns :: map()) :: Phoenix.LiveView.Rendered.t()

The full-page HEEx template. Required.

stream_key(t)

(optional)

@callback stream_key(Plug.Conn.t()) :: term()

If defined, the stream opens via Dstar.start_stream/2 keyed on the result. Optional.