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

Copy Markdown View Source

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).

Summary

Types

Why a URI cannot be resolved.

A resolved destination: transport, IP address and port.

Functions

Removes all cached lookups.

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

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

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.

Types

error()

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

Why a URI cannot be resolved.

target()

A resolved destination: transport, IP address and port.

Functions

clear_cache()

@spec clear_cache() :: :ok

Removes all cached lookups.

default_port(transport)

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

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

resolve(uris, opts \\ [])

@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(records)

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