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

Event state compositor for PUBLISH (RFC 3903). Equivalent to NkSIP's
`nksip_event_compositor`.

```
defmodule MyCompositor do
  use Malla.Service,
    plugins: [Caracola.EventCompositor],
    sip: [listen: "sip:all:5060", events: "presence"],
    event_compositor: [default_expires: 60]
end
```

It answers PUBLISH requests (`sip_publish/2`, see `request/1`) for the
events of the service (`:events` of the sip config), and adds `PUBLISH`
to the Allow header. Each publication is stored for the AOR of the
Request-URI with a new entity tag, returned in the SIP-ETag header (and
the `:sip_etag` meta of `Caracola.UAC.publish/3`). PUBLISH requests with
`{:sip_if_match, etag}` refresh (without body), modify (with body) or
remove (with `expires: 0`) it; unknown tags get a 412.

Publications are found with `find/3`, and all the current ones of an AOR
and event with `list/3` (as `Caracola.Presence` does to compose the
presence state).

## Configuration

Under the `:event_compositor` key:

  * `:default_expires` - expiration without Expires (secs, default 60).

## Storage

Publications are stored in memory. Services can use their own storage
implementing `sip_event_compositor_store(op, service)`, where `op` is
`{:get, aor, tag}` (returns a `Caracola.EventCompositor.Publication` or
`:not_found`), `{:list, aor}` (returns `[{tag, publication}]`, without
the expired ones), `{:put, aor, tag, publication, ttl}`, `{:del, aor, tag}`
or `:del_all` (these return `:ok`).

# `aor`

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

An address of record: scheme, user and domain.

# `clear`

```elixir
@spec clear(module()) :: :ok
```

Removes all the publications of a service.

# `find`

```elixir
@spec find(module(), aor(), String.t()) ::
  {:ok, Caracola.EventCompositor.Publication.t()} | :not_found
```

Finds a publication by its AOR and entity tag.

# `list`

```elixir
@spec list(module(), aor(), String.t()) :: [
  {String.t(), Caracola.EventCompositor.Publication.t()}
]
```

The current publications of an AOR for an event (as `"presence"`), as
`{tag, publication}`, the oldest first.

# `request`

```elixir
@spec request(Caracola.Message.t()) :: Caracola.Reply.sipreply()
```

Processes a PUBLISH request, returning the reply. Called by the default
`sip_publish/2`.

---

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