# `Caracola.Notifier`
[🔗](https://github.com/netkubes/caracola/blob/v0.1.0-rc.1/lib/caracola/notifier.ex#L1)

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
`c: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.

# `aor`

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

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

# `watcher`

```elixir
@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).

# `add_events`

```elixir
@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 `c:Malla.Plugin.plugin_config/2`.

# `aor`

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

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

# `approve`

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

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

# `items`

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

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

# `notify`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

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

The watchers of an event of a resource.

# `watchers`

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

The subscriptions to an event of a resource.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
