API Reference Caracola v#0.1.0-rc.1

Copy Markdown View Source

Modules

Malla.Plugin providing a SIP stack to a Malla.Service.

Asserted identity within a trust domain (RFC 3325) and privacy (RFC 3323): the P-Asserted-Identity, P-Preferred-Identity and Privacy headers.

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.

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.

Conference state (RFC 4575): the conference event package, with application/conference-info+xml documents, with the description and the participants of a conference.

Configuration schema for SIP services, placed under the :sip key.

Locates SIP servers following RFC 3263. Port of NkPACKET's nkpacket_dns, specialized for sip and sips URIs.

Caracola.DNS.Resolver using the system resolver.

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.

Date header values (RFC 3261 §20.17), in the RFC 1123 form that SIP requires, always in GMT

SIP dialogs (RFC 3261 §12). Equivalent to NkSIP's nksip_dialog.

The INVITE usage of a dialog: the last INVITE transaction and the state of the session. Equivalent to NkSIP's #invite{}.

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.

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.

Groups of destinations (gateways, media servers, other proxies) for a proxy, with load balancing, health checks and failover.

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

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).

Globally Routable User Agent URIs (RFC 5627). Equivalent to NkSIP's nksip_gruu.

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).

Header name handling: compact forms and canonical capitalization.

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.

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.

The Join header (RFC 3911): a new INVITE joins an existing dialog, as in barge-in, call monitoring or ad hoc conferences.

A parsed SIP request or response. Equivalent to NkSIP's #sipmsg{}.

Message waiting indication (RFC 3842): the message-summary event package, with application/simple-message-summary bodies, that turns on the message lamp of phones.

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.

Client-initiated connections (RFC 5626, SIP outbound). Equivalent to NkSIP's nksip_outbound.

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.

SIP message parser. Port of NkSIP's nksip_parse_sipmsg and nksip_parse.

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.

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.

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).

REFER (RFC 3515, call transfer). Equivalent to NkSIP's nksip_refer.

Registrar plugin (RFC 3261 §10, RFC 3327 Path). Equivalent to NkSIP's nksip_registrar.

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.

A registered contact. Equivalent to NkSIP's #reg_contact{}.

Reliable provisional responses (RFC 3262, 100rel and PRACK). Equivalent to NkSIP's nksip_100rel.

The Replaces header (RFC 3891): a new INVITE replaces an existing dialog, as in attended transfers and call pickup.

Generation of responses from "sip replies". Port of NkSIP's nksip_reply and nksip_call_uas_make.

RFC 4566 SDP parser and generator. Port of NkSIP's nksip_sdp.

An SDP media description (m= section).

SDP utilities for WebRTC endpoints. Successor of NkSIP's nksip_sdp_util.

SIP message serializer. Port of NkSIP's nksip_unparse.

Session timers (RFC 4028). Equivalent to NkSIP's nksip_timers.

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.

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.

Personal Assertion Tokens (PASSporT, RFC 8225) with the SHAKEN extension (RFC 8588), signed with ES256.

Event subscriptions (RFC 6665). Equivalent to NkSIP's nksip_subscription.

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

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.

SIP transport layer: listeners, connections and sending. Replaces the parts of NkPACKET used by NkSIP.

Receives the SIP messages arriving at a listener or connection.

A listener or connection. Equivalent to NkPACKET's #nkport{}.

Code of the tutorial. launch/0 runs all its steps.

First client of the tutorial: listens on 127.0.0.1, port 5070 for UDP and TCP and 5071 for TLS.

Second client of the tutorial: listens on all interfaces, random ports, and uses a sips From.

Code of the small PBX tutorial. launch/0 runs all its steps.

A phone of the small PBX tutorial, for the alice@example.com extension. It listens on 127.0.0.1, random ports.

A phone of the small PBX tutorial, for the bob@example.com extension. It listens on 127.0.0.1, random ports.

The PBX of the small PBX tutorial: a registrar, a B2BUA and a dialog state server for the example.com domain. It listens on 127.0.0.1, port 5080.

Callbacks of the phones of the small PBX tutorial: they answer calls and tell the process that started the services about the calls and NOTIFYs they receive.

A phone of the small PBX tutorial, for the voicemail@example.com extension. It listens on 127.0.0.1, random ports.

Server of the tutorial: a registrar and a stateful proxy for the example.com domain, that requires digest authentication.

Sending requests. Equivalent to NkSIP's nksip_uac.

Automatic registrations with outbound (RFC 5626). Equivalent to NkSIP's nksip_uac_auto_outbound.

Automatic registrations and pings. Equivalent to NkSIP's nksip_uac_auto_register.

SIP URI, optionally in name-addr form ("Display" <sip:...>;params).

Via header entry. Port of NkSIP's nksip_parse_via.

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.