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

Locates SIP servers following RFC 3263. Port of NkPACKET's `nkpacket_dns`,
specialized for `sip` and `sips` URIs.

`resolve/2` returns, in order, the `{transport, ip, port}` targets to try:

  * If the host (or `maddr`) is an IP address, or a port is given, there is
    no NAPTR or SRV lookup.
  * If a transport is given but no port, the SRV records for that
    transport are used, falling back to A/AAAA with the default port.
  * With neither, NAPTR records select the transports; without them, the
    SRV records of each supported transport are tried (UDP, TCP and TLS
    for `sip`, TLS for `sips`), and finally A/AAAA with the default
    transport (UDP for `sip`, TLS for `sips`).

SRV records are ordered by priority and weight (RFC 2782), and the
addresses of each host are shuffled on every call. Lookups are cached for
`:dns_cache_ttl` milliseconds (application env, five minutes by default).

Options:

  * `:listen` - resolve an address to listen on: no NAPTR or SRV lookups,
    and the port is `0` if not given. `all` and `all6` hosts mean every IPv4
    or IPv6 address.
  * `:cache` - set to `false` to skip the cache.
  * `:resolver` - a `Caracola.DNS.Resolver` (`Caracola.DNS.Inet` by default).

# `error`

```elixir
@type error() ::
  {:invalid_uri, binary()}
  | {:invalid_scheme, Caracola.URI.scheme()}
  | {:invalid_transport, Caracola.Via.transport()}
```

Why a URI cannot be resolved.

# `target`

```elixir
@type target() :: {Caracola.Via.transport(), :inet.ip_address(), :inet.port_number()}
```

A resolved destination: transport, IP address and port.

# `clear_cache`

```elixir
@spec clear_cache() :: :ok
```

Removes all cached lookups.

# `default_port`

```elixir
@spec default_port(Caracola.Via.transport()) :: :inet.port_number()
```

Default port for a transport (RFC 3261 and RFC 7118).

# `resolve`

```elixir
@spec resolve(binary() | Caracola.URI.t() | [Caracola.URI.t()], keyword()) ::
  {:ok, [target()]} | {:error, error()}
```

Resolves a URI, a list of them, or a binary with one or more URIs.

    iex> Caracola.DNS.resolve("<sips:10.0.0.1>, sip:[::1]:5070;transport=tcp")
    {:ok, [{:tls, {10, 0, 0, 1}, 5061}, {:tcp, {0, 0, 0, 0, 0, 0, 0, 1}, 5070}]}

# `sort_srv`

```elixir
@spec sort_srv([{non_neg_integer(), non_neg_integer(), term()}]) :: [term()]
```

Orders SRV-like records `{priority, weight, target}` following RFC 2782:
by ascending priority and, within the same priority, randomly with a
probability proportional to the weight.

---

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