live_state v0.7.0

LiveState.Channel behaviour (live_state v0.7.0)

To build a LiveState application, you'll first want to add a channel that uses this module.

  use LiveState.Channel, web_module: MyAppWeb, json_patch: true, max_version: 100
  • json_patch optional, defaults to false. If true, each time a new state is returned from a handle_XXX callback a diff will be computed and a JSON patch send to the client.
  • max_version optional, defaults to 1000. This is the maximum version number, after which it will reset to 0 and begin incrementing again. Version numbers are used to detect a patch message arriving out of order. If such a condition is detected by phx-live-state a new copy of state is requested.

Link to this section Summary

Callbacks

authorize(channel, payload, socket)

Called from join to authorize the connection. Return {:ok, socket} to authorize or {:error, reason} to deny. Default implementation returns {:ok, socket}

handle_event(event_name, payload, state)

Receives an event an payload from the client and current state. Return a :reply tuple if you need to send events to the client, otherwise return :noreply. :reply tuples can contain a single LiveState.Event or a list of events as well as the new state.

handle_event( event_name, payload, state, socket )

Receive an event name, payload, the current state, and the socket. Use this callback if you need to receive the socket as well as the state. Return a :reply tuple if you need to send events to the client, otherwise return :noreply. :reply tuples can contain a single LiveState.Event or a list of events, as well as the new state and the socket. :noreply tuples must contain the new state and and socket.

handle_message(message, state)

Receives pubsub message and current state. Returns new state

init(channel, payload, socket)

Returns the initial application state. Called just after connection

state_key()

The key on assigns to hold application state. Defaults to :state.

state_version_key()

The key on assigns to hold application state version. Defaults to :version.

Link to this section Callbacks

Link to this callback

authorize(channel, payload, socket)

@callback authorize(channel :: binary(), payload :: term(), socket :: Socket.t()) ::
  {:ok, socket :: Socket.t()} | {:error, binary()}

Called from join to authorize the connection. Return {:ok, socket} to authorize or {:error, reason} to deny. Default implementation returns {:ok, socket}

Link to this callback

handle_event(event_name, payload, state)

(optional) 
@callback handle_event(event_name :: binary(), payload :: term(), state :: term()) ::
  {:reply,
   reply ::
     %LiveState.Event{detail: term(), name: term()}
     | [%LiveState.Event{detail: term(), name: term()}], new_state :: any()}
  | {:noreply, new_state :: map()}

Receives an event an payload from the client and current state. Return a :reply tuple if you need to send events to the client, otherwise return :noreply. :reply tuples can contain a single LiveState.Event or a list of events as well as the new state.

Link to this callback

handle_event( event_name, payload, state, socket )

(optional) 
@callback handle_event(
  event_name :: binary(),
  payload :: term(),
  state :: term(),
  socket :: Socket.t()
) ::
  {:reply,
   reply ::
     %LiveState.Event{detail: term(), name: term()}
     | [%LiveState.Event{detail: term(), name: term()}], new_state :: map(),
   Socket.t()}
  | {:noreply, new_state :: map(), Socket.t()}

Receive an event name, payload, the current state, and the socket. Use this callback if you need to receive the socket as well as the state. Return a :reply tuple if you need to send events to the client, otherwise return :noreply. :reply tuples can contain a single LiveState.Event or a list of events, as well as the new state and the socket. :noreply tuples must contain the new state and and socket.

Link to this callback

handle_message(message, state)

@callback handle_message(message :: term(), state :: term()) ::
  {:reply,
   reply ::
     %LiveState.Event{detail: term(), name: term()}
     | [%LiveState.Event{detail: term(), name: term()}], new_state :: any()}
  | {:noreply, new_state :: term()}

Receives pubsub message and current state. Returns new state

Link to this callback

init(channel, payload, socket)

@callback init(channel :: binary(), payload :: term(), socket :: Socket.t()) ::
  {:ok, state :: map()}
  | {:ok, state :: map(), Socket.t()}
  | {:error, reason :: any()}

Returns the initial application state. Called just after connection

Link to this callback

state_key()

@callback state_key() :: atom()

The key on assigns to hold application state. Defaults to :state.

Link to this callback

state_version_key()

@callback state_version_key() :: atom()

The key on assigns to hold application state version. Defaults to :version.