The pipeline specification.

It declares a pipeline of sequential transformations to apply to the incoming query until a response is constructed.

This module is responsible for handling the pipeline of pipes that will be executed when a DNS message is received. Handlers in this pipeline will be executed sequentially, accumulating the result of each handler and passing it to the next. This designs a pluggable framework where new behaviour can be injected as a new pipe handler in the right order.

Default pipes

The following are enabled by default, see their documentation for details:

• erldns_questions
• erldns_edns_max_payload_size
• erldns_query_throttle
• erldns_packet_cache
• erldns_resolver_recursive
• erldns_resolver
• erldns_dnssec
• erldns_sorter
• erldns_section_counter
• erldns_empty_verification

Types of pipelines

There are two kind of pipes: function pipes and module pipes.

Function pipes

A function pipe is by definition any function that receives a dns:message/0 and a set of options and returns a dns:message/0. Function pipes must have the following type signature:

-type pipe() :: fun((dns:message(), opts()) -> return()

Module pipes

The preferred mechanism, a module pipe is an extension of the function pipe.

It is a module that exports:

• a prepare/1 function which takes a set of options and initializes it, or disables the pipe.
• a call/2 function with the signature defined as in the function pipe.

The API expected by a module pipe is defined as a behaviour by this module.

Configuration

{erldns, [
    {packet_pipeline, [
        erldns_questions,
        erldns_edns_max_payload_size,
        erldns_query_throttle,
        erldns_packet_cache,
        erldns_resolver_recursive,
        erldns_resolver,
        erldns_dnssec,
        erldns_sorter,
        erldns_section_counter,
        erldns_packet_cache,
        erldns_empty_verification
    ]},
]}

Telemetry events

Emits the following telemetry events:

[erldns, pipeline, error]

• Measurements:

  count := non_neg_integer()

• Metadata: If it is an exception, the metadata will contain:

  kind => exit | error | throw
  reason => term()
  stacktrace => [term()]

  otherwise, it will contain:

  reason => term()

Examples

Here's an example of a function pipe that arbitrarily sets the truncated bit on a message if the query is directed to the "example.com" domain:

-module(erldns_packet_pipe_example_set_truncated).
-behaviour(erldns_pipeline).

-export([prepare/1, call/2]).

-spec prepare(erldns_pipeline:opts()) -> disabled | erldns_pipeline:opts().
prepare(Opts) ->
    case enabled() of
        false -> disabled;
        true -> Opts
    end.

-spec call(dns:message(), erldns_pipeline:opts()) -> erldns_pipeline:return().
call(#dns_message{questions = [#dns_query{name = <<"example.com">>} | _]} = Msg, _Opts) ->
    Msg#dns_message{tc = true}.
call(Msg, _Opts) ->
    Msg.