Zonemaster/Engine/NameserverSet.pm untested

filter: Statementstmt 0.0% 0 / 104 Branchbran 0.0% 0 / 36 Conditioncond 0.0% 0 / 15 MC/DCmcdc 0.0% 0 / 10 Subroutinesub 0.0% 0 / 15 Podpod 0.0% 0 / 10 totaltotal 0.0% 0 / 190 CC 19 SCAR 31.8
CC
19
Cov
0%
push
72.0
difference
20.0
get
12.0
CRAP 23.9
1 package Zonemaster::Engine::NameserverSet;
2  
3 use v5.26.0;
4 use warnings;
5  
6 use Scalar::Util qw(blessed);
7  
8 use Zonemaster::Engine::DNSName;
9 use Zonemaster::Engine::Nameserver;
10  
11 ####
12 #### Constructors
13 ####
14  
15 sub new {
16 my ( $proto, @initial_items ) = @_;
17 my $class = ref $proto || $proto;
18  
19 my $self = {
20 _names => {},
21 };
22  
23 bless $self, $class;
24 $self->push( @initial_items );
25  
26 return $self;
27 }
28  
29 ####
30 #### Mutators
31 ####
32  
33 sub push {
34 my ( $self, @items ) = @_;
35  
36 for my $item ( @items ) {
37 next if not defined $item;
38 next if $item eq '';
39  
40 if ( $item->isa('Zonemaster::Engine::DNSName') ) {
41 if ( not exists $self->{_names}{lc $item} ) {
42 $self->{_names}{lc $item} = $item;
43 }
44 }
45 elsif ( $item->isa('Zonemaster::Engine::Nameserver') ) {
46 my ( $name, $addr ) = ( $item->name, $item->address->short );
47  
48 my $r = \$self->{_names}{lc $name};
49 if ( not defined $$r or ref $$r ne 'HASH' ) {
50 $$r = {};
51 }
52 $$r->{$addr} = $item;
53 }
54 else {
55 my $name = Zonemaster::Engine::DNSName->new( "$item" );
56 if ( not exists $self->{_names}{lc $name} ) {
57 $self->{_names}{lc $item} = $name;
58 }
59 }
60 }
61  
62 return $self;
63 }
64  
65 ####
66 #### Access to items
67 ####
68  
69 sub get {
70 my ( $self, $name ) = @_;
71  
72 if ( not exists $self->{_names}{ lc $name } ) {
73 return ();
74 }
75  
76 my $r = $self->{_names}{ lc $name };
77 if ( ref $r eq 'HASH' ) {
78 return values %$r;
79 }
80  
81 return $r;
82 }
83  
84 sub get_ips {
85 my ( $self, $name ) = @_;
86  
87 if ( exists $self->{_names}{ lc $name } ) {
88 my $r = $self->{_names}{ lc $name };
89 if ( ref $r eq 'HASH' ) {
90 return values %$r;
91 }
92 }
93  
94 return ();
95 }
96  
97 sub items {
98 my ( $self ) = @_;
99  
100 my @items;
101  
102 for my $k ( keys %{ $self->{_names} } ) {
103 my $r = $self->{_names}{$k};
104 if ( ref $r eq 'HASH' ) {
105 CORE::push( @items, map { $r->{$_} } keys %$r );
106 }
107 else {
108 CORE::push( @items, $r );
109 }
110 }
111  
112 return @items;
113 }
114  
115 sub names {
116 my ( $self ) = @_;
117  
118 my @result;
119  
120 for my $k ( keys %{ $self->{_names} } ) {
121 my $r = $self->{_names}{$k};
122 if ( ref $r eq 'HASH' ) {
123 CORE::push( @result, ( values %$r )[0]->name() );
124 }
125 else {
126 CORE::push( @result, $r );
127 }
128 }
129  
130 return @result;
131 }
132  
133 sub sorted_items {
134 my ( $self ) = @_;
135  
136 my @items;
137  
138 for my $k ( sort keys %{ $self->{_names} } ) {
139 my $r = $self->{_names}{$k};
140 if ( ref $r eq 'HASH' ) {
141 CORE::push( @items, sort map { $r->{$_} } keys %$r );
142 }
143 else {
144 CORE::push( @items, $r );
145 }
146 }
147  
148 return @items;
149 }
150  
151 ####
152 #### Basic operations
153 ####
154  
155 sub is_empty {
156 my ( $self ) = @_;
157  
158 return ( scalar %{ $self->{_names} } == 0 );
159 }
160  
161 ####
162 #### Set theory operations
163 ####
164  
165 sub difference {
166 my ( $self, $other ) = @_;
167  
168 my $only_in_left = __PACKAGE__->new();
169 my $only_in_right = __PACKAGE__->new();
170  
171 my @left_items = $self->sorted_items();
172 my @right_items = $other->sorted_items();
173  
174 while ( @left_items and @right_items ) {
175 my $cmp = $left_items[0] cmp $right_items[0];
176 if ( $cmp < 0 ) {
177 $only_in_left->push( shift @left_items );
178 }
179 elsif ( $cmp == 0 ) {
180 shift @left_items;
181 shift @right_items;
182 }
183 elsif ( $cmp > 0 ) {
184 $only_in_right->push( shift @right_items );
185 }
186 }
187 $only_in_left->push( @left_items );
188 $only_in_right->push( @right_items );
189  
190 return ( $only_in_left, $only_in_right );
191 }
192  
193 sub equals {
194 my ( $self, $other ) = @_;
195  
196 my @left_items = $self->sorted_items();
197 my @right_items = $other->sorted_items();
198  
199 while ( @left_items and @right_items ) {
200 if ( shift @left_items ne shift @right_items ) {
201 return 0;
202 }
203 }
204  
205 return ( scalar @left_items == 0 and scalar @right_items == 0 );
206 }
207  
208 1;
209  
210 =encoding UTF-8
211  
212 =head1 NAME
213  
214 Zonemaster::Engine::NameserverSet - a set supporting DNS name/IP pairs and plain DNS names
215  
216 =head1 SYNOPSIS
217  
218 use Zonemaster::Engine::NameserverSet;
219  
220 my $set = Zonemaster::Engine::NameserverSet->new();
221  
222 my $ns1 = Zonemaster::Engine::Nameserver->new({ name => 'ns.nic.example', address => '2001:db8::8:53' });
223 my $ns2 = Zonemaster::Engine::Nameserver->new({ name => 'ns.nic.example', address => '2001:db8::9:53' });
224 $set->push( $ns1, $ns2 );
225  
226 my $name = Zonemaster::Engine::DNSName->new( 'ns2.nic.example' );
227 $set->push( $name );
228  
229 $set->get( 'ns.nic.example' ); # returns $ns1 and $ns2 in list context
230 $set->get( 'ns2.nic.example' ); # returns $name in list context
231  
232 # Retrieve items
233 my @items = $set->items; # or $set->sorted_items
234  
235 =head1 DESCRIPTION
236  
237 Zonemaster::Engine::NameserverSet implements a collection type that is
238 specialized for holding a mix of name/IP pairs (represented as
239 L<Zonemaster::Engine::Nameserver> objects) and bare domain names (represented
240 as L<Zonemaster::Engine::DNSName> objects).
241  
242 In other words, it is a collection type that stores mappings of name server
243 names to zero, one or more IP addresses.
244  
245 =head1 METHODS
246  
247 =over
248  
249 =item new()
250  
251 Constructs a new empty name server set.
252  
253 =item push( $name_or_ns )
254  
255 Adds an item to the set. Objects of type L<Zonemaster::Engine::DNSName> or
256 L<Zonemaster::Engine::Nameserver> are accepted. Other types are converted to
257 strings, then turned into L<Zonemaster::Engine::DNSName> objects before being
258 added to the set.
259  
260 This method obeys the following rules:
261  
262 =over
263  
264 =item *
265  
266 If C<$name_or_ns> is a L<Zonemaster::Engine::DNSName> (or automatically
267 converted to an object of that type), it is added to the set if and only if
268 the set contains no L<Zonemaster::Engine::DNSName> object with the same name
269 nor any L<Zonemaster::Engine::Nameserver> objects with the same name.
270  
271 =item *
272  
273 If C<$name_or_ns> is a L<Zonemaster::Engine::Nameserver>, it is added to
274 the set if and only if the set contains no other
275 L<Zonemaster::Engine::Nameserver> with the same name and address.
276  
277 =item *
278  
279 If C<$name_or_ns> is a L<Zonemaster::Engine::Nameserver> and the set already
280 contains a L<Zonemaster::Engine::DNSName> object with the same name, the
281 nameserver object replaces the plain DNS name in the set.
282  
283 =back
284  
285 =item get( $name )
286  
287 Returns a list of all items whose name is equivalent to C<$name>, or an empty
288 list if no match.
289  
290 If only a L<Zonemaster::Engine::DNSName> is stored in the set, that name
291 as a single return value (or a singleton list in list context).
292  
293 If one or more L<Zonemaster::Engine::Nameserver> objects with matching C<$name> are
294 stored in the set, returns a list comprising of those objects.
295  
296 =item get_ips( $name )
297  
298 Returns a list of all L<Zonemaster::Engine::Nameserver> objects with matching
299 C<$name> that are stored in the set.
300  
301 If only a L<Zonemaster::Engine::DNSName> of the same C<$name> is stored in the
302 set, this function returns undef.
303  
304 =item items()
305  
306 Returns the entire contents of the set as a list, in an unspecified order.
307  
308 =item names()
309  
310 Returns the unique list of names associated with the objects stored in the
311 set, both plain L<Zonemaster::Engine::DNSName> objects or the names of
312 L<Zonemaster::Engine::Nameserver> objects.
313  
314 All names are returned as L<Zonemaster::Engine::DNSName> objects.
315  
316 =item sorted_items()
317  
318 Returns the entire contents of the set as a list, in a deterministic order.
319  
320 Items are sorted lexicographically based on their names, and if multiple
321 L<Zonemaster::Engine::Nameserver> objects have the same name, these are sorted
322 on IP addresses such that IPv4 addresses are sorted before IPv6 addresses, and
323 within an address family, each address is sorted based on their integer
324 values.
325  
326 =item is_empty()
327  
328 Returns true if and only if the set contains no items.
329  
330 =item difference( $other_set )
331  
332 Computes the difference between two sets. Returns a pair of sets: the first
333 one contains the items only occurring in the left set (i.e. left minus right),
334 the second one the items only in the right set (i.e. right minus left).
335  
336 =item equals( $other_set )
337  
338 Returns true if and only if the set is equal to C<$other_set>.
339  
340 =back