Caracola.Notifier (Caracola v0.1.0-rc.1)

Copy Markdown View Source

Notifier of event packages (RFC 6665 §4.2): accepts subscriptions to the state of a resource and sends NOTIFYs with it, initially and whenever it changes. It is the base of Caracola.Presence, Caracola.DialogInfo, Caracola.MessageWaiting and Caracola.Conference, and of any other event package with the state in a body.

A plugin built on it adds its events with add_events/2 in its Malla.Plugin.plugin_config/2, and implements sip_notifier_body(event, aor, version, service), returning the current state as {content_type, body} (or :none for a NOTIFY without body). For example, a message waiting package taking the summaries from a voicemail system (Caracola.MessageWaiting keeps them itself):

defmodule MyMWI do
  use Malla.Plugin, plugin_deps: [Caracola.Notifier]

  @impl true
  def plugin_config(_srv_id, config),
    do: {:ok, Caracola.Notifier.add_events(config, ["message-summary"])}

  defcb sip_notifier_body("message-summary", {_scheme, user, _domain}, _version, _service),
    do: {"application/simple-message-summary", MyVoicemail.summary(user)}

  defcb sip_notifier_body(_event, _aor, _version, _service), do: :cont
end

The resource of a SUBSCRIBE is the AOR ({scheme, user, domain}) of its Request-URI. Before accepting it, the plugin calls sip_notifier_authorize(event, aor, req, call), which returns :ok (the default), :pending or a reply to reject it (as :forbidden). Accepted subscriptions get a 200 and a NOTIFY with the current state, and another one with each refresh; when the state of a resource changes, call notify/3 to send it to all its watchers.

Pending subscriptions get NOTIFYs with Subscription-State: pending and no state, until they are authorized with approve/1 or rejected with terminate/2. watcher_info/3 returns the watchers of a resource and their status, and Caracola.WatcherInfo sends them to the subscribers of the .winfo packages (RFC 3857).

version starts at 0 and grows with each NOTIFY of a subscription (as RFC 4235 requires). The NOTIFYs of a resource are sent in order by the same process, so watchers get the states in the order they happened.

Summary

Types

A resource: the AOR of the Request-URI of the subscriptions.

A watcher of a resource: its subscription, status, the URI of the subscriber (its From) and when it subscribed (system time in seconds).

Functions

Adds event packages to the notifier, and to the :events of the sip configuration. For plugins, in their Malla.Plugin.plugin_config/2.

The resource of a request: the AOR of its Request-URI.

Authorizes a pending subscription: its watcher gets a NOTIFY with the current state.

The items of the state of a resource, as {key, value}, ordered by key.

Sends the current state of a resource to all its watchers (in the background).

Stores an item of the state of a resource (nil removes it), for plugins that keep the state in the notifier. Items are kept in memory, in the node.

Ends a subscription, with a last NOTIFY with the reason (:rejected by default, or :deactivated, :probation, :timeout, :giveup or :noresource).

The URI of a resource, as "sip:alice@example.com".

The watchers of an event of a resource.

The subscriptions to an event of a resource.

Types

aor()

@type aor() :: {Caracola.URI.scheme(), String.t() | nil, String.t()}

A resource: the AOR of the Request-URI of the subscriptions.

watcher()

@type watcher() :: %{
  handle: Caracola.Subscription.handle(),
  status: :active | :pending | {:terminated, Caracola.Subscription.reason()},
  uri: String.t(),
  since: integer()
}

A watcher of a resource: its subscription, status, the URI of the subscriber (its From) and when it subscribed (system time in seconds).

Functions

add_events(config, events)

@spec add_events(keyword(), [String.t()]) :: keyword()

Adds event packages to the notifier, and to the :events of the sip configuration. For plugins, in their Malla.Plugin.plugin_config/2.

aor(message)

@spec aor(Caracola.Message.t()) :: aor()

The resource of a request: the AOR of its Request-URI.

approve(handle)

@spec approve(Caracola.Subscription.handle()) :: :ok | {:error, :not_found}

Authorizes a pending subscription: its watcher gets a NOTIFY with the current state.

items(service, event, aor)

@spec items(module(), String.t(), aor()) :: [{term(), term()}]

The items of the state of a resource, as {key, value}, ordered by key.

notify(service, event, aor, opts \\ [])

@spec notify(module(), String.t(), aor(), keyword()) :: :ok

Sends the current state of a resource to all its watchers (in the background).

With {:then, fun}, fun (without arguments) is called once the NOTIFYs have been queued, before any later state is read: for example, to forget ended items that must appear in one notification.

put_item(service, event, aor, key, value)

@spec put_item(module(), String.t(), aor(), term(), term()) :: :ok

Stores an item of the state of a resource (nil removes it), for plugins that keep the state in the notifier. Items are kept in memory, in the node.

terminate(handle, reason \\ :rejected)

@spec terminate(Caracola.Subscription.handle(), Caracola.Subscription.reason()) ::
  :ok | {:error, :not_found}

Ends a subscription, with a last NOTIFY with the reason (:rejected by default, or :deactivated, :probation, :timeout, :giveup or :noresource).

uri(arg)

@spec uri(aor()) :: String.t()

The URI of a resource, as "sip:alice@example.com".

iex> Caracola.Notifier.uri({:sip, "alice", "example.com"})
"sip:alice@example.com"

watcher_info(service, event, aor)

@spec watcher_info(module(), String.t(), aor()) :: [watcher()]

The watchers of an event of a resource.

watchers(service, event, aor)

@spec watchers(module(), String.t(), aor()) :: [Caracola.Subscription.handle()]

The subscriptions to an event of a resource.