plucky (3) Zonemaster::Engine::Recursor.3pm.gz

NAME

       Zonemaster::Engine::Recursor - recursive resolver for Zonemaster

SYNOPSIS

           my $packet = Zonemaster::Engine::Recursor->recurse( $name, $type, $dns_class );
           my $pname  = Zonemaster::Engine::Recursor->parent( 'example.org' );

CLASS VARIABLES

   %recurse_cache
       Will cache result of previous queries.

   %_fake_addresses_cache
       A hash of hashrefs of arrayrefs.  The keys of the top level hash are domain names.  The keys of the
       second level hashes are name server names (normalized to lower case).  The elements of the third level
       arrayrefs are IP addresses.

       The IP addresses are those of the nameservers which are used in case of fake delegations (pre-publication
       tests).

CLASS METHODS

   init_recursor()
       Initialize the recursor by loading the root hints.

   recurse($name[, $type, $class, $ns])
       Does a recursive resolution for the given name down from the root servers (or for the given name
       server(s), if any).  Only the first argument is mandatory. The rest are optional and default to,
       respectively: 'A', 'IN', and "root_servers()".

       Takes a string or a Zonemaster::Engine::DNSName object (name); and optionally a string (query type), a
       string (query class), and an arrayref of Zonemaster::Engine::Nameserver objects.

       Returns a Zonemaster::Engine::Packet object (which can be "undef").

   parent($name)
       Does a recursive resolution from the root down for the given name (using type "SOA" and class "IN"). If
       the resolution is successful, it returns the domain name of the second-to-last step. If the resolution is
       unsuccessful, it returns the domain name of the last step.

   get_ns_from($packet, $state)
       Internal method. Takes a packet and a recursion state and returns a list of ns objects. Used to follow
       redirections.

   get_addresses_for($name[, $state])
       Takes a name and returns a (possibly empty) list of IP addresses for that name (in the form of
       Net::IP::XS objects). When used internally by the recursor it's passed a recursion state as its second
       argument.

   add_fake_addresses($domain, $data)
       Class method to create fake addresses for fake delegations for a specified domain from data provided.

   has_fake_addresses($domain)
       Check if there is at least one fake nameserver specified for the given domain.

   get_fake_addresses($domain, $nsname)
       Returns a list of all cached fake addresses for the given domain and name server name.  Returns an empty
       list if no data is cached for the given arguments.

   get_fake_names($domain)
       Returns a list of all cached fake name server names for the given domain.  Returns an empty list if no
       data is cached for the given argument.

   remove_fake_addresses($domain)
       Remove fake delegation data for a specified domain.

   clear_cache()
       Class method to empty the cache of responses to recursive queries (but not the ones for fake
       delegations).

       N.B. This method does not affect fake delegation data.

   root_servers()
       Returns a list of ns objects representing the root servers.

           my @name_servers = Zonemaster::Engine::Recursor->root_servers();

       The default list of root servers is read from a file installed in the shared data directory.  This list
       can be replaced like so:

           Zonemaster::Engine::Recursor->remove_fake_addresses( '.' );
           Zonemaster::Engine::Recursor->add_fake_addresses(
               '.',
               {
                   'ns1.example' => ['192.0.2.1'],
                   'ns2.example' => ['192.0.2.2'],
               }
           );

INTERNAL METHODS

   _recurse()
           my ( $p, $state_hash ) = _recurse( $name, $type_string, $dns_class_string, $p, $state_hash );

       Performs a recursive lookup resolution for the given arguments. Used by the recursive lookup method in
       this module.

       Takes a Zonemaster::Engine::DNSName object, a string (query type), a string (DNS class), a
       Zonemaster::Engine::Packet object, and a reference to a hash.  The mandatory keys for that hash are 'ns'
       (arrayref), 'count' (integer), 'common' (integer), 'seen' (hash), 'glue' (hash) and optional keys are
       'in_progress' (hash), 'candidate' (Zonemaster::Engine::Packet object or "undef"), 'trace' (array),
       'tseen' (hash), 'tcount' (integer).

       Returns a Zonemaster::Engine::Packet (or "undef") and a hash.

   _resolve_cname()
           my ( $p, $state_hash ) = _resolve_cname( $name, $type_string, $dns_class_string, $p, $state_hash );

       Performs CNAME resolution for the given arguments. Used by the recursive lookup helper method in this
       module.  If CNAMEs are successfully resolved, a packet (which could be "undef") is returned and one of
       the following message tags is logged:

       CNAME_FOLLOWED_IN_ZONE
       CNAME_FOLLOWED_OUT_OF_ZONE

       Note that CNAME records are also validated and, in case of an error, an empty ("undef") packet is
       returned and one of the following message tags will be logged:

       CNAME_CHAIN_TOO_LONG
       CNAME_LOOP_INNER
       CNAME_LOOP_OUTER
       CNAME_NO_MATCH
       CNAME_RECORDS_CHAIN_BROKEN
       CNAME_RECORDS_MULTIPLE_FOR_NAME
       CNAME_RECORDS_TOO_MANY

       Takes a Zonemaster::Engine::DNSName object, a string (query type), a string (DNS class), a
       Zonemaster::Engine::Packet, and a reference to a hash.

       Returns a Zonemaster::Engine::Packet (or "undef") and a reference to a hash.