# Caracola v0.1.0-rc.1 - API Reference

## Modules

- [Caracola.DNS.Inet](Caracola.DNS.Inet.md): `Caracola.DNS.Resolver` using the system resolver.

- Core
  - [Caracola](Caracola.md): `Malla.Plugin` providing a SIP stack to a `Malla.Service`.
  - [Caracola.Call](Caracola.Call.md): Call process: every request, response and transaction with the same
Call-ID is handled by a single process, which serializes all the work for
that call. Equivalent to NkSIP's `nksip_call_srv` and `nksip_router`.
  - [Caracola.Config](Caracola.Config.md): Configuration schema for SIP services, placed under the `:sip` key.
  - [Caracola.Reply](Caracola.Reply.md): Generation of responses from "sip replies". Port of NkSIP's `nksip_reply`
and `nksip_call_uas_make`.
  - [Caracola.UAC](Caracola.UAC.md): Sending requests. Equivalent to NkSIP's `nksip_uac`.

- Dialogs and events
  - [Caracola.Dialog](Caracola.Dialog.md): SIP dialogs (RFC 3261 §12). Equivalent to NkSIP's `nksip_dialog`.
  - [Caracola.Dialog.Invite](Caracola.Dialog.Invite.md): The INVITE usage of a dialog: the last INVITE transaction and the state
of the session. Equivalent to NkSIP's `#invite{}`.
  - [Caracola.Subscription](Caracola.Subscription.md): Event subscriptions (RFC 6665). Equivalent to NkSIP's `nksip_subscription`.

- Messages
  - [Caracola.Date](Caracola.Date.md): `Date` header values (RFC 3261 §20.17), in the RFC 1123 form that SIP
requires, always in GMT
  - [Caracola.Digest](Caracola.Digest.md): Digest authentication (RFC 2617, and RFC 7616 and RFC 8760 for the SHA-2
algorithms), with `qop=auth`. Port of the stateless part of NkSIP's
`nksip_auth`: parsing of `WWW-Authenticate`, `Proxy-Authenticate`,
`Authorization` and `Proxy-Authorization` values, generation of challenges
and credentials, and verification.
  - [Caracola.Headers](Caracola.Headers.md): Header name handling: compact forms and canonical capitalization.
  - [Caracola.Message](Caracola.Message.md): A parsed SIP request or response. Equivalent to NkSIP's `#sipmsg{}`.
  - [Caracola.ParseError](Caracola.ParseError.md): Error returned by `Caracola.Parser.parse/2`.
  - [Caracola.Parser](Caracola.Parser.md): SIP message parser. Port of NkSIP's `nksip_parse_sipmsg` and `nksip_parse`.
  - [Caracola.SDP](Caracola.SDP.md): RFC 4566 SDP parser and generator. Port of NkSIP's `nksip_sdp`.
  - [Caracola.SDP.Media](Caracola.SDP.Media.md): An SDP media description (`m=` section).

  - [Caracola.SDP.WebRTC](Caracola.SDP.WebRTC.md): SDP utilities for WebRTC endpoints. Successor of NkSIP's `nksip_sdp_util`.
  - [Caracola.Serializer](Caracola.Serializer.md): SIP message serializer. Port of NkSIP's `nksip_unparse`.
  - [Caracola.Tokens](Caracola.Tokens.md): Parser for comma-separated token lists with parameters, as used in headers
like `Content-Type`, `Accept`, `Supported` or `Event`. Port of NkLIB's
`nklib_parse_tokens`.
  - [Caracola.URI](Caracola.URI.md): SIP URI, optionally in name-addr form (`"Display" <sip:...>;params`).
  - [Caracola.Via](Caracola.Via.md): Via header entry. Port of NkSIP's `nksip_parse_via`.

- Transport
  - [Caracola.DNS](Caracola.DNS.md): Locates SIP servers following RFC 3263. Port of NkPACKET's `nkpacket_dns`,
specialized for `sip` and `sips` URIs.
  - [Caracola.DNS.Resolver](Caracola.DNS.Resolver.md): Behaviour for the DNS lookups used by `Caracola.DNS`. The default
implementation, `Caracola.DNS.Inet`, uses `:inet_res` and `:inet`; tests
can provide their own.

  - [Caracola.Transport](Caracola.Transport.md): SIP transport layer: listeners, connections and sending. Replaces the
parts of NkPACKET used by NkSIP.
  - [Caracola.Transport.Handler](Caracola.Transport.Handler.md): Receives the SIP messages arriving at a listener or connection.
  - [Caracola.Transport.Port](Caracola.Transport.Port.md): A listener or connection. Equivalent to NkPACKET's `#nkport{}`.

- Plugins: registration and NAT
  - [Caracola.Gruu](Caracola.Gruu.md): Globally Routable User Agent URIs (RFC 5627). Equivalent to NkSIP's
`nksip_gruu`.
  - [Caracola.Outbound](Caracola.Outbound.md): Client-initiated connections (RFC 5626, SIP outbound). Equivalent to
NkSIP's `nksip_outbound`.
  - [Caracola.Push](Caracola.Push.md): Push notifications for mobile clients (RFC 8599), on top of
`Caracola.Registrar`: devices that cannot keep a connection open are
woken up with a push notification (APNs, FCM...) when they have a
request, and get it after they register again.
  - [Caracola.Registrar](Caracola.Registrar.md): Registrar plugin (RFC 3261 §10, RFC 3327 Path). Equivalent to NkSIP's
`nksip_registrar`.
  - [Caracola.Registrar.Cluster](Caracola.Registrar.Cluster.md): A registrar shared by the nodes of a Malla cluster: every node running
the service has all the registrations, so any of them can find the
contacts of a user.
  - [Caracola.Registrar.Contact](Caracola.Registrar.Contact.md): A registered contact. Equivalent to NkSIP's `#reg_contact{}`.
  - [Caracola.UACAutoOutbound](Caracola.UACAutoOutbound.md): Automatic registrations with outbound (RFC 5626). Equivalent to NkSIP's
`nksip_uac_auto_outbound`.
  - [Caracola.UACAutoRegister](Caracola.UACAutoRegister.md): Automatic registrations and pings. Equivalent to NkSIP's
`nksip_uac_auto_register`.

- Plugins: call control
  - [Caracola.B2BUA](Caracola.B2BUA.md): Back-to-back user agent: bridges an incoming INVITE (the *A leg*) with a
new outgoing one (the *B leg*), relaying the responses, the in-dialog
requests and the hangups between both dialogs.
  - [Caracola.InfoPackages](Caracola.InfoPackages.md): INFO packages (RFC 6086): the INFO requests of a dialog carry the
package they belong to (`Info-Package`), and each side says in the
`Recv-Info` header of its INVITEs and their responses which packages it
accepts.
  - [Caracola.Join](Caracola.Join.md): The Join header (RFC 3911): a new INVITE joins an existing dialog, as in
barge-in, call monitoring or ad hoc conferences.
  - [Caracola.Refer](Caracola.Refer.md): REFER (RFC 3515, call transfer). Equivalent to NkSIP's `nksip_refer`.
  - [Caracola.Rel100](Caracola.Rel100.md): Reliable provisional responses (RFC 3262, `100rel` and PRACK). Equivalent
to NkSIP's `nksip_100rel`.
  - [Caracola.Replaces](Caracola.Replaces.md): The Replaces header (RFC 3891): a new INVITE replaces an existing dialog,
as in attended transfers and call pickup.
  - [Caracola.SessionTimers](Caracola.SessionTimers.md): Session timers (RFC 4028). Equivalent to NkSIP's `nksip_timers`.
  - [Caracola.Siprec](Caracola.Siprec.md): Session recording (SIPREC, RFC 7866): a session recording client (SRC)
records a call by starting a *recording session* with a session
recording server (SRS): an INVITE whose body has the SDP of the media
streams sent to the SRS and the recording metadata (RFC 7865,
`application/rs-metadata+xml`), that says who the participants are and
which stream each one sends.

- Plugins: events and presence
  - [Caracola.Conference](Caracola.Conference.md): Conference state (RFC 4575): the `conference` event package, with
`application/conference-info+xml` documents, with the description and
the participants of a conference.
  - [Caracola.DialogInfo](Caracola.DialogInfo.md): Dialog state (RFC 4235): the `dialog` event package, with
`application/dialog-info+xml` documents, used by the busy lamp fields of
phones and by call pickup.
  - [Caracola.EventCompositor](Caracola.EventCompositor.md): Event state compositor for PUBLISH (RFC 3903). Equivalent to NkSIP's
`nksip_event_compositor`.
  - [Caracola.EventCompositor.Publication](Caracola.EventCompositor.Publication.md): A publication stored by `Caracola.EventCompositor`. Equivalent to NkSIP's
`#reg_publish{}`: the published `data` (the body of the PUBLISH), its
`content_type`, the `event` type (lowercase), its `expires` time
(seconds) and when it was `updated` (monotonic time).

  - [Caracola.MessageWaiting](Caracola.MessageWaiting.md): Message waiting indication (RFC 3842): the `message-summary` event
package, with `application/simple-message-summary` bodies, that turns on
the message lamp of phones.
  - [Caracola.Notifier](Caracola.Notifier.md): 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.
  - [Caracola.Presence](Caracola.Presence.md): Presence (RFC 3856) with PIDF documents (RFC 3863): a presence server
that composes the state published by the user agents of each presentity
and notifies it to its watchers.
  - [Caracola.WatcherInfo](Caracola.WatcherInfo.md): Watcher information (RFC 3857, RFC 3858): the `.winfo` template event
packages, with `application/watcherinfo+xml` bodies, that tell a
presentity who is subscribed to its state, so it can authorize the
pending watchers.

- Plugins: security and load
  - [Caracola.AssertedIdentity](Caracola.AssertedIdentity.md): Asserted identity within a trust domain (RFC 3325) and privacy (RFC
3323): the `P-Asserted-Identity`, `P-Preferred-Identity` and `Privacy`
headers.
  - [Caracola.OverloadControl](Caracola.OverloadControl.md): SIP overload control (RFC 7339) with the loss-based algorithm: an
overloaded server tells its clients, in the Via of its responses, the
percentage of requests they should stop sending it, and the clients do.
  - [Caracola.RateLimit](Caracola.RateLimit.md): Rate limiting and banning of abusive clients: request rate limits per
address and per user, and bans of SIP scanners and of addresses with too
many failed authentications (brute-force attacks).
  - [Caracola.StirShaken](Caracola.StirShaken.md): Caller identity signing and verification with STIR/SHAKEN: the
`Identity` header (RFC 8224) with a PASSporT (RFC 8225) and the SHAKEN
extension (RFC 8588), signed with ES256.
  - [Caracola.StirShaken.Passport](Caracola.StirShaken.Passport.md): Personal Assertion Tokens (PASSporT, RFC 8225) with the SHAKEN extension
(RFC 8588), signed with ES256.

- Plugins: routing
  - [Caracola.Dispatcher](Caracola.Dispatcher.md): Groups of destinations (gateways, media servers, other proxies) for a
proxy, with load balancing, health checks and failover.
  - [Caracola.History](Caracola.History.md): Call history: the `History-Info` (RFC 7044) and `Diversion` (RFC 5806)
headers, that tell the final destination of a request (a voicemail, a
forwarded phone...) the targets it went through, and why it was
retargeted.

- Observability
  - [Caracola.HEP](Caracola.HEP.md): HEP capture: sends every SIP message received or sent by the service to
a capture server (Homer, heplify-server...) with HEPv3 over UDP, from the
`[:caracola, :message, :received]` and `[:caracola, :message, :sent]`
telemetry events (see `Caracola.Telemetry`).
  - [Caracola.Telemetry](Caracola.Telemetry.md): `:telemetry` events emitted by Caracola. They replace NkSIP's trace,
stats and debug facilities: attach handlers with `:telemetry.attach/4` to
log messages, collect metrics (for example with `Telemetry.Metrics`) or
trace calls.

- Tutorial
  - [Caracola.Tutorial](Caracola.Tutorial.md): Code of the [tutorial](03-tutorial.md). `launch/0` runs all its steps.

  - [Caracola.Tutorial.Client](Caracola.Tutorial.Client.md): Callbacks of the clients of the [tutorial](03-tutorial.md), used by
`Caracola.Tutorial.Client1` and `Caracola.Tutorial.Client2`.

  - [Caracola.Tutorial.Client1](Caracola.Tutorial.Client1.md): First client of the [tutorial](03-tutorial.md): listens on `127.0.0.1`,
port 5070 for UDP and TCP and 5071 for TLS.

  - [Caracola.Tutorial.Client2](Caracola.Tutorial.Client2.md): Second client of the [tutorial](03-tutorial.md): listens on all
interfaces, random ports, and uses a `sips` From.

  - [Caracola.Tutorial.Office](Caracola.Tutorial.Office.md): Code of the [small PBX tutorial](15-small-pbx.md). `launch/0` runs all
its steps.

  - [Caracola.Tutorial.Office.Alice](Caracola.Tutorial.Office.Alice.md): A phone of the [small PBX tutorial](15-small-pbx.md), for the
`alice@example.com` extension. It listens on `127.0.0.1`, random
ports.

  - [Caracola.Tutorial.Office.Bob](Caracola.Tutorial.Office.Bob.md): A phone of the [small PBX tutorial](15-small-pbx.md), for the
`bob@example.com` extension. It listens on `127.0.0.1`, random
ports.

  - [Caracola.Tutorial.Office.PBX](Caracola.Tutorial.Office.PBX.md): The PBX of the [small PBX tutorial](15-small-pbx.md): a registrar, a B2BUA
and a dialog state server for the `example.com` domain. It listens on
`127.0.0.1`, port 5080.

  - [Caracola.Tutorial.Office.Phone](Caracola.Tutorial.Office.Phone.md): Callbacks of the phones of the [small PBX tutorial](15-small-pbx.md): they
answer calls and tell the process that started the services about the
calls and NOTIFYs they receive.

  - [Caracola.Tutorial.Office.Voicemail](Caracola.Tutorial.Office.Voicemail.md): A phone of the [small PBX tutorial](15-small-pbx.md), for the
`voicemail@example.com` extension. It listens on `127.0.0.1`, random
ports.

  - [Caracola.Tutorial.Server](Caracola.Tutorial.Server.md): Server of the [tutorial](03-tutorial.md): a registrar and a stateful proxy
for the `example.com` domain, that requires digest authentication.

