Installation

Add caracola to your dependencies in mix.exs:

def deps do
  [
    {:caracola, "~> 0.1.0-rc.1"}
  ]
end

Caracola requires Elixir 1.18 or later. It brings Malla, whose concepts (services, plugins, callbacks, configuration) are worth a look; this guide only covers what a SIP application needs.

A service

A SIP application is a Malla service using the Caracola plugin, or any of the SIP plugins (they all depend on it):

defmodule MyUA do
  use Malla.Service,
    plugins: [Caracola],
    sip: [
      listen: "sip:all:5060, <sip:all:5061;transport=tls>",
      from: "\"My UA\" <sip:my_ua@example.com>",
      tls: [certfile: "priv/cert.pem", keyfile: "priv/key.pem"]
    ]

  defcb sip_invite(_req, _call), do: {:reply, :decline}
end

The SIP configuration goes under the :sip key. The main options are:

  • :listen - the listening addresses, as URIs. sip:all:5060 listens on all the IPv4 interfaces, on port 5060, for UDP and TCP (UDP listeners always listen on TCP on the same port). Use transport=tcp, tls, ws or wss for other transports, sips: for TLS, port 0 for a random port, and [::1] or all6 (any IPv6 address) for IPv6. A path is the HTTP path accepted by WS and WSS listeners: <sip:all:8080/ws;transport=ws>.
  • :from - the default From of the requests.
  • :local_host (and :local_host6) - the host in the Via, Contact and Record-Route headers, instead of the IP of the listener (or the main IP of the machine, for listeners on all interfaces).
  • :route - routes for all the requests (an outbound proxy).
  • :tls - :ssl options of the TLS and WSS listeners, and :tls_client - options of the outgoing TLS connections (the server certificate is verified against the system CAs by default).
  • :timer_t1, :timer_t2... - SIP timers.

See Caracola.Config for all of them.

Configuration given when starting the service is deep-merged with the one in the module:

MyUA.start_link(sip: [listen: "sip:127.0.0.1:5070"])

Usually you will start it in your application supervisor:

children = [
  {MyUA, sip: [listen: "sip:all:5060"]}
]

MyUA.stop() stops it. Services can be reconfigured at runtime (see Malla's documentation); a change in the :sip configuration restarts the SIP part of the service.

Sending requests

Requests are sent with the functions of Caracola.UAC, giving the service, the destination URI and a list of options:

iex> Caracola.UAC.options(MyUA, "sip:sip.example.com")
{:ok, 200, []}

iex> Caracola.UAC.options(MyUA, "<sip:127.0.0.1:5070;transport=tcp>",
...>   get_meta: [:reason_phrase, "server"])
{:ok, 200, [reason_phrase: "OK", {"server", ["MyServer 1.0"]}]}

The call waits for the final response, and returns its code and the values asked for with :get_meta. See Sending requests.

Receiving requests

Incoming requests go through the sip_* callbacks of the service. sip_route/5 decides what to do with each request (process it, proxy it or reply at once) and, for the requests to process, the callback of its method (sip_invite/2, sip_options/2, sip_register/2...) replies to it:

defcb sip_options(_req, _call), do: {:reply, {:ok, [:allow, :supported]}}

Any callback you do not implement has a default (OPTIONS are answered, INVITEs declined, REGISTERs rejected unless you use the registrar plugin...). See Receiving requests.

Plugins

SIP extensions are plugins, listed in :plugins instead of (or with) Caracola:

use Malla.Service,
  plugins: [Caracola.Registrar, Caracola.Rel100],
  sip: [listen: "sip:all:5060"],
  registrar: [min_time: 60]

See Plugins.

Tracing messages

To see the SIP messages sent and received, while developing:

Caracola.Telemetry.trace(true)

They are logged at the :info level. See Observability.