webrtc_mdns_resolver (webrtc v0.1.0)

View Source

Sans-IO one-shot multicast DNS resolver (RFC 6762 §5.1) for the A and AAAA records of .local host names, with a small TTL cache.

The owner (webrtc_mdns) sends the queries, feeds the responses it receives and arms one timer:

  R0 = webrtc_mdns_resolver:new(#{}),
  {R1, [{send, QueryA}, {send, QueryAAAA}]} = webrtc_mdns_resolver:resolve(<<"x.local">>, Now, R0),
  {R2, [{result, <<"x.local">>, {ok, [IP]}}]} =
      webrtc_mdns_resolver:handle_packet(unicast, Response, Now, R1).

Queries go out from an ephemeral port (one-shot querier, §5.1), one message for A and one for AAAA (Chromium's responder ignores messages with more than one question). The first query sets the QU bit (§5.4); retransmissions clear it, as §5.4 recommends, which also gets an answer from responders that ignore QU questions (Chromium answers QM questions only, by multicast). After the last attempt the query fails with {error, timeout}.

Responses are validated before use:

  • QR set, opcode 0 and rcode 0 (RFC 6762 §18.3, §18.11).
  • Unicast responses (unicast) are legacy unicast replies to our ephemeral port (§6.7): the ID must be the query ID and the question must be repeated.
  • Multicast responses (multicast) carry ID 0 which is ignored (§18.1).
  • Only class IN A or AAAA records whose name is a pending question are used, from the answer and additional sections (§6.2). Responses that answer nothing pending are unsolicited and ignored, and never fill the cache.

The cache keeps at most max_cache names for their TTL, capped at max_ttl seconds. Records with TTL 0 (goodbye, §10.1) are not used.

Summary

Functions

Cached addresses of a name, if still valid at Now.

A datagram received on the query socket (unicast) or on the multicast group (multicast).

Retransmit or fail the queries whose deadline passed.

Options: schedule (default [250, 1000, 2000]: attempts at 0, 250 ms and 1250 ms, failure at 3250 ms; the first retransmission is the first QM query, so it is kept short), max_queries (32), max_cache (64), max_ttl (seconds, 3600) and ids, a fun that returns query IDs (random by default).

Absolute time of the next retransmission or failure.

Names being resolved.

Start resolving Name, or join a query already running. A cached name gives its result at once.

Types

action/0

-type action() :: {send, binary()} | {result, binary(), result()}.

resolver/0

-opaque resolver()

result/0

-type result() :: {ok, [inet:ip_address(), ...]} | {error, timeout | bad_name | too_many_queries}.

Functions

cached(Name, Now, R)

-spec cached(binary(), integer(), resolver()) -> {ok, [inet:ip_address()]} | error.

Cached addresses of a name, if still valid at Now.

handle_packet(How, Bin, Now, R)

-spec handle_packet(unicast | multicast, binary(), integer(), resolver()) -> {resolver(), [action()]}.

A datagram received on the query socket (unicast) or on the multicast group (multicast).

handle_timeout(Now, R0)

-spec handle_timeout(integer(), resolver()) -> {resolver(), [action()]}.

Retransmit or fail the queries whose deadline passed.

new(Opts)

-spec new(map()) -> resolver().

Options: schedule (default [250, 1000, 2000]: attempts at 0, 250 ms and 1250 ms, failure at 3250 ms; the first retransmission is the first QM query, so it is kept short), max_queries (32), max_cache (64), max_ttl (seconds, 3600) and ids, a fun that returns query IDs (random by default).

next_timeout(R)

-spec next_timeout(resolver()) -> integer() | infinity.

Absolute time of the next retransmission or failure.

pending(R)

-spec pending(resolver()) -> [binary()].

Names being resolved.

resolve(Name0, Now, R0)

-spec resolve(binary(), integer(), resolver()) -> {resolver(), [action()]}.

Start resolving Name, or join a query already running. A cached name gives its result at once.