LiveState.Channel behaviour (live_state v0.9.0)

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

  use LiveState.Channel, web_module: MyAppWeb, max_version: 100
  • message_builder optional, defaults to {LiveState.MessageBuilder, ignore_keys: [:__meta__]}. If set, should be a tuple whose first element is a module that defines update_state_message/4 and new_state_message/3 and and second element contains any options. Options are passed as final arg to both functions when invoked. See LiveState.MessageBuilder for details
  • 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.

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

handle_message(message, state, socket)

Receives pubsub message and current state. Use this callback if you need to receive the socket as well as the 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.

Callbacks

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}

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.

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.

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

handle_message(message, state, socket)

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

Receives pubsub message and current state. Use this callback if you need to receive the socket as well as the state. Returns new state.

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

state_key()

@callback state_key() :: atom()

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

state_version_key()

@callback state_version_key() :: atom()

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