Caracola.History (Caracola v0.1.0-rc.1)

Copy Markdown View Source

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.

Proxies retarget requests with retarget/3, a sip_route/5 result:

defcb sip_route(_scheme, "alice", "example.com", req, _call) do
  if MyApp.forwarding?("alice"),
    do: Caracola.History.retarget(req, ["sip:voicemail@example.com"], cause: 302),
    else: :proxy
end

Each destination gets a new History-Info entry, child of the one of the current Request-URI (which is added first if the request has none), and the cause (RFC 4458) is added to its URI. With :diversion, a Diversion header is added too, for the equipment that only understands it.

entries/1 and diversions/1 read the headers of a received request.

Summary

Types

A Diversion: the diverted URI, the reason and the counter.

A History-Info entry: the URI (with its cause param and the Reason header, if any), its index (as "1.1.2"), and how it was retargeted from its parent: :rc (to a registered contact), :mp (mapped to another user) or :np (not changed), with the index of the parent.

Functions

The Diversion headers of a message, the most recent first.

The History-Info entries of a message, in order.

A sip_route/5 result proxying req to targets (URIs, tried in parallel), with a History-Info entry for each of them.

Types

diversion()

@type diversion() :: %{
  uri: Caracola.URI.t(),
  reason: String.t() | nil,
  counter: pos_integer()
}

A Diversion: the diverted URI, the reason and the counter.

entry()

@type entry() :: %{
  uri: Caracola.URI.t(),
  index: String.t() | nil,
  type: {:rc | :mp | :np, String.t()} | nil,
  cause: non_neg_integer() | nil,
  reason: String.t() | nil
}

A History-Info entry: the URI (with its cause param and the Reason header, if any), its index (as "1.1.2"), and how it was retargeted from its parent: :rc (to a registered contact), :mp (mapped to another user) or :np (not changed), with the index of the parent.

Functions

diversions(msg)

@spec diversions(Caracola.Message.t()) :: [diversion()]

The Diversion headers of a message, the most recent first.

entries(msg)

@spec entries(Caracola.Message.t()) :: [entry()]

The History-Info entries of a message, in order.

retarget(req, targets, opts \\ [])

@spec retarget(Caracola.Message.t(), [String.t() | Caracola.URI.t()], list()) ::
  {:proxy, [Caracola.URI.t()], list()}

A sip_route/5 result proxying req to targets (URIs, tried in parallel), with a History-Info entry for each of them.

Options:

  • {:cause, code} - the reason of the retargeting (RFC 4458): 302 (unconditional forwarding), 486 (busy), 408 (no answer), 404 (unknown or not available), 480 or 487 (deflection) and 503 (not reachable). It is added as cause param to the targets.
  • {:type, :mp | :rc} - :mp (the default) when the target is another user, :rc for the registered contacts of the same one.

  • :diversion or {:diversion, reason} - add a Diversion header with the current Request-URI, and the reason (by default, the one of the cause).
  • {:proxy_opts, opts} - options of the proxy.
iex> {:ok, req, ""} = Caracola.Parser.parse("INVITE sip:alice@example.com SIP/2.0\r\nVia: SIP/2.0/UDP h;branch=z9hG4bKa\r\nFrom: <sip:a@h>;tag=1\r\nTo: <sip:alice@example.com>\r\nCall-ID: c\r\nCSeq: 1 INVITE\r\n\r\n")
iex> {:proxy, [target], []} = Caracola.History.retarget(req, ["sip:vm@example.com"], cause: 302)
iex> for {"History-Info", value} <- target.headers, do: URI.decode_www_form(value)
["<sip:alice@example.com>;index=1", "<sip:vm@example.com;cause=302>;index=1.1;mp=1"]