SIP extensions are Malla plugins.
A plugin depends on Caracola (or on other SIP plugins), can change the
configuration of the service, start processes, and implement callbacks.
defmodule MyApp.Blocklist do
@moduledoc "Rejects the requests coming from some addresses."
use Malla.Plugin, plugin_deps: [Caracola]
@impl true
def plugin_config(_srv_id, config) do
ips = get_in(config, [:blocklist, :ips]) || []
{:ok, Keyword.put(config, :blocklist, ips: ips)}
end
# Before the sip_route/5 of the service (see "Callback chain" below)
defcb caracola_callback(:sip_route, [_scheme, _user, _domain, req, call]) do
if req.port.remote_ip in call.service.get_config()[:blocklist][:ips],
do: {:done, {:reply, :forbidden}},
else: :cont
end
defcb caracola_callback(_fun, _args), do: :cont
enddefmodule MyServer do
use Malla.Service,
plugins: [MyApp.Blocklist, Caracola.Registrar],
sip: [listen: "sip:all:5060"],
blocklist: [ips: [{10, 0, 0, 66}]]
endCallback chain
Callbacks are chained at compile time: the service itself first, then its
plugins (each one before its dependencies), and Caracola last, with the
defaults. A callback returning :cont passes to the next one (or
{:cont, new_args}, with other arguments); anything else is the result.
So a plugin can implement any sip_* callback, as the defaults of
Caracola.Registrar (sip_register/2) or Caracola.Refer (sip_refer/2),
and the service can still override it.
Some callbacks exist to be extended by plugins:
sip_authorize_data(list, req, call)builds the authorization list ofsip_authorize/3: a plugin can add values with{:cont, [[value | list], req, call]}(the registrar adds:register).caracola_callback(fun, args)is called before every callback to the service (funis its name, as:sip_notify, andargsits arguments). Returning:contcalls the callback;{:done, result}usesresultinstead. Plugins use it to see or handle callbacks before the service, which comes first in the chain:Caracola.Referhandles the NOTIFYs of REFER subscriptions this way, whateversip_notify/2the service has.
Plugins can also define new callbacks, with a default implementation, for
the services to implement (as sip_refer_update/3 in Caracola.Refer).
Configuration
Malla.Plugin.plugin_config/2 gets the configuration of the service and
returns it, changed. Plugins usually validate their own key (with
NimbleOptions), and add their methods and option tags with
Caracola.Config.add_values/3:
@impl true
def plugin_config(_srv_id, config) do
config = Caracola.Config.add_values(config, :allow, ["PUBLISH"])
{:ok, config}
endPlugins listed first are configured first, so a plugin sees the
configuration before Caracola validates the :sip key.
Processes
Malla.Plugin.plugin_start/2 returns the children to start with the
service, under a supervisor of the plugin:
@impl true
def plugin_start(srv_id, _config),
do: {:ok, children: [{MyApp.Blocklist.Store, srv_id}]}They are stopped with the service, before the SIP listeners.
In the call process
Callbacks run in the process of the call (a Caracola.Call): they get its
state, but can not change it, and must not block. Use other processes for
slow work, and Caracola.reply/2 or Caracola.UAC from them.
Testing
Start the services with start_supervised!/1 in your tests, on random
ports (listen: "sip:127.0.0.1:0"), and get them with
Caracola.listeners/1. The tests of Caracola are a good source of
examples.