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

Registrar plugin (RFC 3261 §10, RFC 3327 Path). Equivalent to NkSIP's
`nksip_registrar`.

```
defmodule MyRegistrar do
  use Malla.Service,
    plugins: [Caracola.Registrar],
    sip: [listen: "sip:all:5060"],
    registrar: [min_time: 60]
end
```

It answers REGISTER requests (`sip_register/2`, see `request/1`), adds
`REGISTER` to the Allow header, and adds `:register` to the authorization
list of `sip_authorize/3` for requests coming from a registered contact
(see `registered?/1`). Registered contacts are found with `find/4` and
`qfind/4`, to proxy requests to them.

## Configuration

Under the `:registrar` key:

  * `:min_time` - minimum expiration (secs, default 60); shorter ones
    are rejected with 423.
  * `:max_time` - maximum expiration (secs, default 86400).
  * `:default_time` - expiration without Expires (secs, default 3600).
  * `:service_route` - routes (a URI string, or a list of them) returned
    in the Service-Route header of the 2xx responses (RFC 3608): the
    registered UAs use them as the initial route set of the requests
    they send (see `Caracola.UACAutoRegister.service_route/2`).

## Storage

Contacts are stored in memory. Services can use their own storage
implementing `sip_registrar_store(op, service)`, where `op` is
`{:get, aor}` (returns the list of `Caracola.Registrar.Contact`),
`{:put, aor, contacts, ttl}`, `{:del, aor}` (`:ok` or `:not_found`) or
`:del_all`.

# `aor`

```elixir
@type aor() :: {:sip | :sips | :tel, String.t() | nil, String.t()}
```

An address of record: scheme, user and domain.

# `clear`

```elixir
@spec clear(module()) :: :ok
```

Deletes all the registrations of a service.

# `delete`

```elixir
@spec delete(module(), atom(), String.t() | nil, String.t()) :: :ok | :not_found
```

Deletes the registrations of an AOR.

# `find`

```elixir
@spec find(module(), aor() | Caracola.URI.t()) :: [Caracola.URI.t()]
```

Returns the registered contacts of an AOR (or of the AOR of a URI).

# `find`

```elixir
@spec find(module(), atom(), String.t() | nil, String.t()) :: [Caracola.URI.t()]
```

Returns the registered contacts of an AOR.

# `get_info`

```elixir
@spec get_info(module(), aor()) :: [Caracola.Registrar.Contact.t()]
```

Returns the registration records of an AOR.

# `qfind`

```elixir
@spec qfind(module(), atom(), String.t() | nil, String.t()) :: [[Caracola.URI.t()]]
```

Returns the registered contacts of an AOR as a URI set for proxying
(see [Proxies](07-proxy.md)): groups with the same `q`, the
highest first, tried in order; in each group, the last registered first.

# `registered?`

```elixir
@spec registered?(Caracola.Message.t()) :: boolean()
```

Returns `true` if a request comes from a registered contact of the AOR
of its From: from the same transport, IP and port as the REGISTER, or the
address of a registered Contact.

# `request`

```elixir
@spec request(Caracola.Message.t()) :: Caracola.Reply.sipreply()
```

Processes a REGISTER request, returning the reply: 200 with the current
contacts, or an error (unsupported scheme, invalid request, 423 if the
expiration is too short, 400 for old CSeqs).

A Contact with `expires=0` (or an Expires header with 0) removes it, and
`*` with Expires 0 removes all the contacts of the AOR. A contact replaces
a previous one with the same scheme, transport, user, host and port, or
with the same `pn-provider` and `pn-prid` (RFC 8599, see
`Caracola.Push`).

---

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