Tutorial: a small PBX

Copy Markdown View Source

The first tutorial covers the basics: requests, digest authentication, registrations and a proxy. This one builds something closer to a real application, a small office PBX, with three plugins:

  • a registrar where the phones register,
  • a B2BUA that connects the calls between extensions, and
  • a dialog state server that lights the busy lamps of the phones.

It also forwards the calls of an absent user to a voicemail, telling the voicemail who the call was for with the History-Info and Diversion headers.

The code is in examples/tutorial/office.ex, compiled in the dev and test environments. Caracola.Tutorial.Office.launch/0 runs all the steps of this tutorial, and it is part of the test suite. From a checkout:

iex -S mix
iex> alias Caracola.{DialogInfo, History, UAC}
iex> alias Caracola.Tutorial.Office
iex> Office.start()
:ok

The services

There are four services, all listening on 127.0.0.1:

ServiceAddressRole
Office.PBXport 5080Registrar, B2BUA, dialog state
Office.Alicerandom portPhone of alice@example.com
Office.Bobrandom portPhone of bob@example.com
Office.Voicemailrandom portvoicemail@example.com

The phones are plain user agents. They answer any INVITE with the same SDP they received, and send the NOTIFYs they get to the process that started the services, so we can see them in the shell.

The PBX lists the three plugins:

defmodule Caracola.Tutorial.Office.PBX do
  use Malla.Service,
    plugins: [Caracola.Registrar, Caracola.B2BUA, Caracola.DialogInfo],
    sip: [listen: "sip:127.0.0.1:5080"],
    # Carol is out
    forward: %{"carol" => "voicemail"}
  ...
end

Extra keys like :forward are kept in the configuration of the service, and read with call.service.get_config(). Carol has no phone: all her calls go to the voicemail.

Registering the phones

The PBX authenticates with digest, as in the first tutorial: every user has the password 1234 in the example.com realm, and requests from the address of a registered contact need no password.

iex> pbx = "sip:127.0.0.1:5080"
iex> for phone <- [Office.Alice, Office.Bob, Office.Voicemail] do
...>   UAC.register(phone, pbx, [:contact, password: "1234"])
...> end
[{:ok, 200, []}, {:ok, 200, []}, {:ok, 200, []}]

The phones use from: "sip:alice@example.com" and so on, so each one registers the address of record of its extension. From now on, all the requests from the phones can go through the PBX with route: "<sip:127.0.0.1:5080;lr>" and no password.

A call between extensions

The PBX routes the requests for example.com in sip_route/5. Calls to a user with no forwarding are processed by the PBX itself, and arrive at sip_invite/2, where the call is bridged to the first registered contact of the extension:

defcb sip_invite(req, call) do
  case Registrar.find(call.service, req.ruri.scheme, req.ruri.user, "example.com") do
    [] -> {:reply, :temporarily_unavailable}
    [contact | _] -> B2BUA.bridge(req, contact)
  end
end

Caracola.B2BUA.bridge/3 answers nothing by itself: it starts a process that sends a new INVITE to the contact, relays the responses to the caller, and keeps both dialogs together afterwards, relaying hangups and re-INVITEs. The two legs are separate dialogs, with their own Call-ID and tags: Bob never sees the address of Alice, only the PBX (see Plugins).

Let's call Bob from Alice:

iex> route = "<sip:127.0.0.1:5080;lr>"
iex> sdp = Caracola.SDP.new("127.0.0.1", [{"audio", 1080, [{:rtpmap, 0, "PCMU/8000"}]}])
iex> {:ok, 200, [dialog: dialog]} =
...>   UAC.invite(Office.Alice, "sip:bob@example.com", [:auto_2xx_ack, route: route, body: sdp])

The :auto_2xx_ack option sends the ACK for us. Bob's phone has sent a message {:invite, Caracola.Tutorial.Office.Bob, req} to the shell:

iex> flush()
{:invite, Caracola.Tutorial.Office.Bob, %Caracola.Message{...}}

Busy lamps

A phone shows the state of the line of a colleague subscribing to its dialog event (RFC 4235). Caracola.DialogInfo answers these SUBSCRIBEs for the extensions of the PBX, and it follows the INVITE dialogs of the service whose local URI has the address of the extension. In our PBX, the A leg of a call to Bob is a dialog with bob@example.com as local URI, so the PBX notifies it with no extra code.

Let's hang up the call, and subscribe Alice to the line of Bob before calling again:

iex> UAC.bye(dialog)
{:ok, 200, []}
iex> UAC.subscribe(Office.Alice, "sip:bob@example.com", event: "dialog", route: route)
{:ok, 200, [subscription: {:subscription, Office.Alice, "...", "...", "..."}]}
iex> flush()
{:notify, "<?xml version=\"1.0\"..."}

The NOTIFY has the full state of the line. Caracola.DialogInfo.decode/1 parses it:

iex> {:ok, doc} = DialogInfo.decode(body)
iex> doc.dialogs
[]

Now Alice calls Bob again, and the lamp goes through early and confirmed states, each one in a new NOTIFY with a growing version. When the call ends, one more NOTIFY tells that the dialog is terminated:

iex> {:ok, 200, [dialog: dialog]} =
...>   UAC.invite(Office.Alice, "sip:bob@example.com", [:auto_2xx_ack, route: route, body: sdp])
iex> flush()
{:notify, "..."}   # state "early", then "confirmed"
iex> UAC.bye(dialog)
iex> flush()
{:notify, "..."}   # state "terminated"

Forwarding to the voicemail

Carol is out. The PBX forwards her calls to the voicemail when sip_route/5 sees an INVITE for her, and tells the voicemail what happened with Caracola.History.retarget/3:

defcb sip_route(scheme, user, "example.com", req, call) do
  forward = call.service.get_config()[:forward]

  with {:req, :invite} <- req.class,
       ext when is_binary(ext) <- forward[user],
       [_ | _] = contacts <- Registrar.find(call.service, scheme, ext, "example.com") do
    History.retarget(req, contacts, [:diversion, cause: 302])
  else
    _ -> :process
  end
end

retarget/3 returns {:proxy, targets, opts}, a valid result of sip_route/5: this time the PBX is not a B2BUA but a proxy, as the voicemail does not need to be hidden from the caller. The cause: 302 says the call was forwarded unconditionally (RFC 4458), and :diversion adds a Diversion header too, for equipment that only understands that one.

Let's call Carol:

iex> {:ok, 200, [dialog: dialog]} =
...>   UAC.invite(Office.Alice, "sip:carol@example.com", [:auto_2xx_ack, route: route, body: sdp])

The voicemail has received the INVITE. Caracola.History.entries/1 and Caracola.History.diversions/1 read what the PBX added:

iex> receive do {:invite, Office.Voicemail, req} -> req end |> History.entries()
[
  %{index: "1", uri: %Caracola.URI{user: "carol", ...}, cause: nil, ...},
  %{index: "1.1", uri: %Caracola.URI{user: "voicemail", ...}, cause: 302, ...}
]

The first entry is the original target of the call, and the second the one it was retargeted to. A voicemail would use the first one to choose the mailbox:

iex> History.diversions(req)
[%{uri: %Caracola.URI{user: "carol", ...}, reason: "unconditional", counter: 1}]

Finally, let's hang up and stop everything:

iex> UAC.bye(dialog)
{:ok, 200, []}
iex> Office.stop()
:ok

What next