@callback authorize(params :: map(), context :: any()) :: :ok | {:error, reason :: any()}

Deprecated: Use connect/2 instead.

Invoked to check whether a client is authorized to access this topic.

Return :ok to allow access, or {:error, reason} to deny.

This callback is optional. The default implementation returns :ok.

@callback connect(params :: map(), context :: any()) ::
  {:ok, params :: map()} | {:error, reason :: any()}

Invoked when a client connects to this topic.

params is a map containing the values associated with the placeholders in the route, merged with the request params (with defaults applied). context is the context established during the WebSocket connection.

Return {:ok, params} to allow access (optionally with modified params), or {:error, reason} to deny. Modified params will affect topic identity - topics with different param values are separate instances.

This is useful for incorporating context values (like user_id from auth) into topic params for per-user or per-tenant topics.

This callback is optional. The default implementation delegates to authorize/2 for backwards compatibility.

example

Example

def connect(params, context) do
  {:ok, Map.put(params, :user_id, context.user_id)}
end

@callback handle_capture(
  topic :: %Topical.Topic{state: term(), updates: term(), value: term()},
  context :: any()
) :: {:ok, %Topical.Topic{state: term(), updates: term(), value: term()}}

Invoked before state is captured (after initialisation).

This callback is optional.

@callback handle_execute(
  action :: term(),
  args :: tuple(),
  topic :: %Topical.Topic{state: term(), updates: term(), value: term()},
  context :: any()
) ::
  {:ok, term(), %Topical.Topic{state: term(), updates: term(), value: term()}}

Invoked when a client has executed an action.

This callback is optional. If one is not implemented, the topic will fail if an action is executed.

@callback handle_info(
  msg :: term(),
  topic :: %Topical.Topic{state: term(), updates: term(), value: term()}
) ::
  {:ok, %Topical.Topic{state: term(), updates: term(), value: term()}}

Invoked to handle other messages.

This callback is optional.

@callback handle_notify(
  action :: term(),
  args :: tuple(),
  topic :: %Topical.Topic{state: term(), updates: term(), value: term()},
  context :: any()
) :: {:ok, %Topical.Topic{state: term(), updates: term(), value: term()}}

Invoked when a client has sent a notification.

This callback is optional. If one is not implemented, the topic will fail if a notification is received.

@callback handle_subscribe(
  topic :: %Topical.Topic{state: term(), updates: term(), value: term()},
  context :: any()
) :: {:ok, %Topical.Topic{state: term(), updates: term(), value: term()}}

Invoked before a client subscribes (but after initialisation).

This callback can be used to update the topic, for example (in combination with handle_unsubscribe) to track connected users.

This callback is optional.

@callback handle_unsubscribe(
  topic :: %Topical.Topic{state: term(), updates: term(), value: term()},
  context :: any()
) :: {:ok, %Topical.Topic{state: term(), updates: term(), value: term()}}

Invoked after a client unsubscribes (either explicitly or because the process dies).

This callback is optional.

@callback init(params :: map()) ::
  {:ok, %Topical.Topic{state: term(), updates: term(), value: term()}}
  | {:error, reason :: any()}

Invoked when the topic is started to get the initial state.

params is a map containing the values associated with the placeholders in the route, merged with the request params (with defaults applied).

@callback terminate(
  reason :: term(),
  topic :: %Topical.Topic{state: term(), updates: term(), value: term()}
) :: term()

Invoked when a topic has been stopped.

This callback is optional.