# `Caracola.History`
[🔗](https://github.com/netkubes/caracola/blob/v0.1.0-rc.1/lib/caracola/history.ex#L1)

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.

# `diversion`

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

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

# `entry`

```elixir
@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.

# `diversions`

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

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

# `entries`

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

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

# `retarget`

```elixir
@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"]
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*
