The authorize callback will be called on a running program when a client tries to access it.

It receives the current state, the client's socket and the clients params. And must return an updated socket, an initial session or an error with a reason.

You cloud send a bearer token and verify it here to authorize a client.

def authorize(state, socket, %{"token" => token}) do
  case MyApp.Guardian.decode_and_verify(token) do
    {:ok, claims} ->
      {:ok, socket, claims}

    {:error, reason} ->
      {:error, reason}
  end
end

handle_info/2 is similar to how GenServer.handle_info/2 works, it will receive a message and the current state, and it expects a new updated state returned. This callback can be triggered by sending Erlang messages to the program instance.

defmodule TimeProgram do
  use Program

  def init(_args) do
    Process.send_after(self(), :tick, 1_000)
    {:ok, DateTime.utc_now()}
  end

  def handle_info(:tick, state) do
    Process.send_after(self(), :tick, 1_000)
    {:ok, DateTime.utc_now()}
  end

  def view(time, session) do
    Html.p([], DateTime.to_string(time))
  end
end

Receives parameters from the route, it should return the initial state or an error.

The parameters are taken from the program route:

defmodule Router do
  use Whistle.Router, path: "/ws"

  match("chat:*room", ChatProgram, %{"other" => true})
end

defmodule ChatProgram do
  use Program

  # when joining `chat:1`
  def init(%{"room" => "1", "other" => true}) do
    {:ok, %{}}
  end
end

The terminate callback will be called when the program instance shuts down, it will receive the state.

Remember that Programs will be automatically respawned if they crash, so there is no need to try restart it yourself. This callback could be useful to serialize the state and then load it later in the init/1 callback.

The update callback is called everytime an event handler is triggered, it will receive the message, the current state and the session of the client who triggered it.

defmodule CounterProgram do
  use Program

  def init(_args) do
    {:ok, 0}
  end

  def update(:increase, state, session) do
    {:ok, state + 1, session}
  end

  def view(state, session) do
    Html.div([], [
      Html.p([], to_string(state)),
      Html.button([on: [click: :increase]], "Increase")
    ])
  end
end

The view receives the programs state and the session of the client we are rendering the view for.

It must return a Dom tree, which looks like this:

# {key, {tag, {attributes, children}}}
{0, {"div", {[class: "red"], [
{0, {"p", {[], ["some text"]}}
]}}}

You can use the Whistle.Html helpers to generate this tree:

Html.div([class: "red"], [
Html.p([], "some text")
])

Or the Whistle.Html.Parser.sigil_H/2 if you want to write plain HTML:

text = "some text"

~H"""
<div class="red">
<p>{{ text }}</p>
</div>
"""

Both the HTML helpers and the sigil will expand to a DOM tree at compile time.