1NAME
2
3    Net::DNS::Resolver::Programmable - programmable DNS resolver class for
4    offline emulation of DNS
5
6SYNOPSIS
7
8        use Net::DNS::Resolver::Programmable;
9        use Net::DNS::RR;
10
11        my $resolver = Net::DNS::Resolver::Programmable->new(
12            records         => {
13                'example.com'     => [
14                    Net::DNS::RR->new('example.com.     NS  ns.example.org.'),
15                    Net::DNS::RR->new('example.com.     A   192.168.0.1')
16                ],
17                'ns.example.org'  => [
18                    Net::DNS::RR->new('ns.example.org.  A   192.168.1.1')
19                ]
20            },
21
22            resolver_code   => sub {
23                my ($domain, $rr_type, $class) = @_;
24                ...
25                return ($result, $aa, @rrs);
26            }
27        );
28
29DESCRIPTION
30
31    Net::DNS::Resolver::Programmable is a Net::DNS::Resolver descendant
32    class that allows a virtual DNS to be emulated instead of querying the
33    real DNS. A set of static DNS records may be supplied, or arbitrary
34    code may be specified as a means for retrieving DNS records, or even
35    generating them on the fly.
36
37 Constructor
38
39    The following constructor is provided:
40
41    new(%options): returns Net::DNS::Resolver::Programmable
42
43      Creates a new programmed DNS resolver object.
44
45      %options is a list of key/value pairs representing any of the
46      following options:
47
48      records
49
50	A reference to a hash of arrays containing a static set of
51	Net::DNS::RR objects. The hash entries must be indexed by fully
52	qualified domain names (lower-case, without any trailing dots), and
53	the entries themselves must be arrays of the RR objects pertaining
54	to these domain names. For example:
55
56            records => {
57                'example.com'     => [
58                    Net::DNS::RR->new('example.com.     NS  ns.example.org.'),
59                    Net::DNS::RR->new('example.com.     A   192.168.0.1')
60                ],
61                'www.example.com' => [
62                    Net::DNS::RR->new('www.example.com. A   192.168.0.2')
63                ],
64                'ns.example.org'  => [
65                    Net::DNS::RR->new('ns.example.org.  A   192.168.1.1')
66                ]
67            }
68
69	If this option is specified, the resolver retrieves requested RRs
70	from this data structure.
71
72      resolver_code
73
74	A code reference used as a call-back for dynamically retrieving
75	requested RRs.
76
77	The code must take the following query parameters as arguments: the
78	domain, RR type, and class.
79
80	It must return a list composed of: the response's RCODE (by name,
81	as returned by Net::DNS::Header->rcode), the aa (authoritative
82	answer) flag (boolean, use undef if you don't care), and the
83	Net::DNS::RR answer objects. If an error string is returned instead
84	of a valid RCODE, a Net::DNS::Packet object is not constructed but
85	an error condition for the resolver is signaled instead.
86
87	For example:
88
89            resolver_code => sub {
90                my ($domain, $rr_type, $class) = @_;
91                ...
92                return ($result, $aa, @rrs);
93            }
94
95	If both this and the records option are specified, then statically
96	programmed records are used in addition to any that are returned by
97	the configured resolver code.
98
99      defnames
100
101      dnsrch
102
103      domain
104
105      searchlist
106
107      debug
108
109	These Net::DNS::Resolver options are also meaningful with
110	Net::DNS::Resolver::Programmable. See Net::DNS::Resolver for their
111	descriptions.
112
113 Instance methods
114
115    The following instance methods of Net::DNS::Resolver are also supported
116    by Net::DNS::Resolver::Programmable:
117
118    search: returns Net::DNS::Packet
119
120    query: returns Net::DNS::Packet
121
122    send: returns Net::DNS::Packet
123
124      Performs an offline DNS query, using the statically programmed DNS
125      RRs and/or the configured dynamic resolver code. See the "new"
126      constructor's records and resolver_code options. See the descriptions
127      of search, query, and send for details about the calling syntax of
128      these methods.
129
130    print
131
132    string: returns string
133
134    searchlist: returns list of string
135
136    defnames: returns boolean
137
138    dnsrch: returns boolean
139
140    debug: returns boolean
141
142    errorstring: returns string
143
144    answerfrom: returns string
145
146    answersize: returns integer
147
148      See "METHODS" in Net::DNS::Resolver.
149
150    Currently the following methods of Net::DNS::Resolver are not
151    supported: axfr, axfr_start, axfr_next, nameservers, port, srcport,
152    srcaddr, bgsend, bgread, bgisready, tsig, retrans, retry, recurse,
153    usevc, tcp_timeout, udp_timeout, persistent_tcp, persistent_udp, igntc,
154    dnssec, cdflag, udppacketsize. The effects of using these on
155    Net::DNS::Resolver::Programmable objects are undefined.
156
157SEE ALSO
158
159    Net::DNS::Resolver
160
161    For availability, support, and license information, see the README file
162    included with Net::DNS::Resolver::Programmable.
163
164AUTHORS
165
166    David Precious (BIGPRESH) <davidp@preshweb.co.uk> took on
167    maintainership in July 2017
168
169    Original author Julian Mehnle <julian@mehnle.net>
170
171