SPF/Record.pm

filter: Statementstmt 87.1% 108 / 124 Branchbran 54.7% 23 / 42 Conditioncond 50.0% 2 / 4 MC/DCmcdc 0.0% 0 / 2 Subroutinesub 92.0% 23 / 25 Podpod 61.5% 8 / 13 totaltotal 78.1% 164 / 210 CC 26 SCAR 15.5
CC
26
Cov
78%
parse_term
11.4
__ANON__
8.8
new
5.5
CRAP 4.7
« SPF/Server.pm ↑ Summary SPF/Mod.pm »
1 #
2 # Mail::SPF::Record
3 # Abstract base class for SPF records.
4 #
5 # (C) 2005-2012 Julian Mehnle <julian@mehnle.net>
6 # 2005 Shevek <cpan@anarres.org>
7 # $Id: Record.pm 57 2012-01-30 08:15:31Z julian $
8 #
9 ##############################################################################
10  
11 package Mail::SPF::Record;
12  
13 =head1 NAME
14  
15 Mail::SPF::Record - Abstract base class for SPF records
16  
17 =head1 VERSION
18  
19 version 3.20261105
20  
21 =cut
22  
23 7 our $VERSION = '3.20261105'; # VERSION
24  
25 7 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
26 7 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
27  
28 7 ▶use utf8; # Hack to keep Perl 5.6 from whining about /[\p{}]/.
Subroutine BEGIN: called CC=1 SCAR=0.0
29  
30 7 ▶use base 'Mail::SPF::Base';
Subroutine BEGIN: called CC=1 SCAR=0.0
31  
32 use overload
33 7 ▶ '""' => 'stringify',
Subroutine BEGIN: called CC=1 SCAR=0.0
34 7 fallback => 1;
35  
36 7 ▶use Error ':try';
Subroutine BEGIN: called CC=1 SCAR=0.0
37  
38 7 ▶use constant TRUE => (0 == 0);
Subroutine BEGIN: called CC=1 SCAR=0.0
39 7 ▶use constant FALSE => not TRUE;
Subroutine BEGIN: called CC=1 SCAR=0.0
40  
41 7 ▶use constant default_qualifier => '+';
Subroutine BEGIN: called CC=1 SCAR=0.0
42  
43 7 ▶use constant results_by_qualifier => {
Subroutine BEGIN: called CC=1 SCAR=0.0
44 '' => 'pass',
45 '+' => 'pass',
46 '-' => 'fail',
47 '~' => 'softfail',
48 '?' => 'neutral'
49 7 };
50  
51 # Interface:
52 ##############################################################################
53  
54 =head1 SYNOPSIS
55  
56 =head2 Creating a record from a string
57  
58 use Mail::SPF::v1::Record;
59  
60 my $record = Mail::SPF::v1::Record->new_from_string("v=spf1 a mx -all");
61  
62 =head2 Creating a record synthetically
63  
64 use Mail::SPF::v2::Record;
65  
66 my $record = Mail::SPF::v2::Record->new(
67 scopes => ['mfrom', 'pra'],
68 terms => [
69 Mail::SPF::Mech::A->new(),
70 Mail::SPF::Mech::MX->new(),
71 Mail::SPF::Mech::All->new(qualifier => '-')
72 ],
73 global_mods => [
74 Mail::SPF::Mod::Exp->new(domain_spec => 'spf-exp.example.com')
75 ]
76 );
77  
78 =cut
79  
80 # Implementation:
81 ##############################################################################
82  
83 =head1 DESCRIPTION
84  
85 B<Mail::SPF::Record> is an abstract base class for SPF records. It cannot be
86 instantiated directly. Create an instance of a concrete sub-class instead.
87  
88 =head2 Constructor
89  
90 The following constructors are provided:
91  
92 =over
93  
94 =item B<new(%options)>: returns I<Mail::SPF::Record>
95  
96 Creates a new SPF record object.
97  
98 %options is a list of key/value pairs representing any of the following
99 options:
100  
101 =over
102  
103 =item B<text>
104  
105 A I<string> denoting the unparsed text of the record.
106  
107 =item B<scopes>
108  
109 A reference to an I<array> of I<string>s denoting the scopes that are covered
110 by the record (see the description of the C<scope> option of
111 L<Mail::SPF::Request's C<new> constructor|Mail::SPF::Request/new>).
112  
113 =item B<terms>
114  
115 A reference to an I<array> of I<Mail::SPF::Term> (i.e. I<Mail::SPF::Mech> or
116 I<Mail::SPF::Mod>) objects that make up the record. I<Mail::SPF::GlobalMod>
117 objects must not be included here, but should be specified using the
118 C<global_mods> option instead.
119  
120 =item B<global_mods>
121  
122 A reference to an I<array> of I<Mail::SPF::GlobalMod> objects that are global
123 modifiers of the record.
124  
125 =back
126  
127 =cut
128  
129 37 ▶sub new {
Subroutine new: called CC=5 SCAR=17.0
Pod documented
130 37 my ($self, %options) = @_;
131 37 ▶ $self->class ne __PACKAGE__
Branch: 1 branch
BranchTrueFalseTotal
$self->class ne __PACKAGE__ or "Mail::SPF::EAbstractClass"->throw 37 0 37
132 or throw Mail::SPF::EAbstractClass;
133 37 $self = $self->SUPER::new(%options);
134 37 ▶ $self->{parse_text} = $self->{text} if not defined($self->{parse_text});
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->{"parse_text"} 37 0 37
135 37 ▶ $self->{terms} ||= [];
Condition50%1/2
$self->{"terms"} ||= []
l!l
037
MC/DC0%0/1
$self->{"terms"} ||= []
$self->{"terms"}
Truth table50%1/2
A
A= $self->{"terms"}
Aresult
11
00
136 37 ▶ $self->{global_mods} ||= {};
Condition50%1/2
$self->{"global_mods"} ||= {}
l!l
037
MC/DC0%0/1
$self->{"global_mods"} ||= {}
$self->{"global_mods"}
Truth table50%1/2
A
A= $self->{"global_mods"}
Aresult
11
00
137 37 return $self;
138 }
139  
140 =item B<new_from_string($text, %options)>: returns I<Mail::SPF::Record>;
141 throws I<Mail::SPF::ENothingToParse>, I<Mail::SPF::EInvalidRecordVersion>,
142 I<Mail::SPF::ESyntaxError>
143  
144 Creates a new SPF record object by parsing the string and any options given.
145  
146 =cut
147  
148 37 ▶sub new_from_string {
Subroutine new_from_string: called CC=1 SCAR=0.0
Pod documented
149 37 my ($self, $text, %options) = @_;
150 37 $self = $self->new(%options, text => $text);
151 37 $self->parse();
152 32 return $self;
153 }
154  
155 =back
156  
157 =head2 Class methods
158  
159 The following class methods are provided:
160  
161 =over
162  
163 =item B<version_tag_pattern>: returns I<Regexp>
164  
165 I<Abstract>. Returns a regular expression that matches a legal version tag.
166  
167 This method is abstract and must be implemented by sub-classes of
168 Mail::SPF::Record.
169  
170 =item B<default_qualifier>: returns I<string>
171  
172 Returns the default qualifier, i.e. B<'+'>.
173  
174 =item B<results_by_qualifier>: returns I<hash> of I<string>
175  
176 Returns a reference to a hash that maps qualifiers to result codes as follows:
177  
178 Qualifier | Result code
179 -----------+-------------
180 + | pass
181 - | fail
182 ~ | softfail
183 ? | neutral
184  
185 =back
186  
187 =head2 Instance methods
188  
189 The following instance methods are provided:
190  
191 =over
192  
193 =cut
194  
195 37 ▶sub parse {
Subroutine parse: called CC=3 SCAR=11.0
Pod undocumented
196 37 my ($self) = @_;
197 defined($self->{parse_text})
198 37 ▶ or throw Mail::SPF::ENothingToParse('Nothing to parse for record');
Branch: 1 branch
BranchTrueFalseTotal
defined $self->{"parse_text"} or "Mail::SPF::ENothingToParse"->throw("Nothing to parse for record") 37 0 37
199 37 $self->parse_version_tag();
200 33 ▶ $self->parse_term() while length($self->{parse_text});
Branch: 1 branch
BranchTrueFalseTotal
length $self->{"parse_text"} and do { $self->parse_term } 60 32 92
201 32 $self->parse_end();
202 32 return;
203 }
204  
205 33 ▶sub parse_version_tag {
Subroutine parse_version_tag: called CC=2 SCAR=6.9
Pod undocumented
206 33 my ($self) = @_;
207 33 ▶ if (not $self->{parse_text} =~ s/^${\$self->version_tag_pattern}(?:\x20+|$)//) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $self->{"parse_text"} =~ s/^${\$self->version_tag_pattern;}(?:\x20+|$)//) 3 30 33
208 3 throw Mail::SPF::EInvalidRecordVersion(
209 "Not a '" . $self->version_tag . "' record: '" . $self->text . "'");
210 }
211 }
212  
213 60 ▶sub parse_term {
Subroutine parse_term: called CC=9 SCAR=24.4
Pod undocumented
214 60 my ($self) = @_;
215  
216 60 eval {
217 60 require Mail::SPF::Mech;
218 };
219 60 ▶ if($@) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 60 60
220 0 throw Mail::SPF::ENothingToParse('Cannot load Mail::SPF::Mech class');
221 }
222 60 ▶ if (
Branch: 2 branches
BranchTrueFalseTotal
if ($self->{'parse_text'} =~ s/ ^ ( ${\'Mail::SPF::Mech'->qualifier_pattern;}? (${\'Mail::SPF::Mech'->name_pattern;}) [^\x20]* ) (?: \x20+ | $ ) //x) { } 54 6 60
elsif ($self->{'parse_text'} =~ s/ ^ ( (${\'Mail::SPF::Mod'->name_pattern;}) = [^\x20]* ) (?: \x20+ | $ ) //x) { } 6 0 6
223 $self->{parse_text} =~ s/
224 ^
225 (
226 60 ${\Mail::SPF::Mech->qualifier_pattern}?
227 60 (${\Mail::SPF::Mech->name_pattern})
228 [^\x20]*
229 )
230 (?: \x20+ | $ )
231 //x
232 ) {
233 # Looks like a mechanism:
234 54 my ($mech_text, $mech_name) = ($1, lc($2));
235 54 my $mech_class = $self->mech_classes->{$mech_name};
236 54 ▶ throw Mail::SPF::EInvalidMech("Unknown mechanism type '$mech_name' in '" . $self->version_tag . "' record")
Branch: 1 branch
BranchTrueFalseTotal
unless defined $mech_class 1 53 54
237 if not defined($mech_class);
238 53 my $mech = $mech_class->new_from_string($mech_text);
239 53 push(@{$self->{terms}}, $mech);
240 }
241 elsif (
242 $self->{parse_text} =~ s/
243 ^
244 (
245 6 (${\Mail::SPF::Mod->name_pattern}) =
246 [^\x20]*
247 )
248 (?: \x20+ | $ )
249 //x
250 ) {
251 # Looks like a modifier:
252 6 my ($mod_text, $mod_name) = ($1, lc($2));
253 6 my $mod_class = $self->mod_classes->{$mod_name};
254 6 ▶ if (defined($mod_class)) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $mod_class) { } 6 0 6
255 # Known modifier.
256 6 my $mod = $mod_class->new_from_string($mod_text);
257 6 ▶ if ($mod->isa('Mail::SPF::GlobalMod')) {
Branch: 2 branches
BranchTrueFalseTotal
if ($mod->isa('Mail::SPF::GlobalMod')) { } 6 0 6
elsif ($mod->isa('Mail::SPF::PositionalMod')) { } 0 0 0
258 # Global modifier.
259 6 ▶ not defined($self->{global_mods}->{$mod_name}) or
Branch: 1 branch
BranchTrueFalseTotal
defined $self->{"global_mods"}{$mod_name} and "Mail::SPF::EDuplicateGlobalMod"->throw("Duplicate global modifier '${mod_name}' encountered") 0 6 6
260 throw Mail::SPF::EDuplicateGlobalMod("Duplicate global modifier '$mod_name' encountered");
261 6 $self->{global_mods}->{$mod_name} = $mod;
262 }
263 elsif ($mod->isa('Mail::SPF::PositionalMod')) {
264 # Positional modifier, queue normally:
265 0 push(@{$self->{terms}}, $mod);
266 }
267 else {
268 # Huh? This should not happen.
269 }
270 }
271 else {
272 # Unknown modifier.
273 0 my $mod = Mail::SPF::UnknownMod->new_from_string($mod_text);
274 0 push(@{$self->{terms}}, $mod);
275 }
276 }
277 else {
278 0 throw Mail::SPF::EJunkInRecord("Junk encountered in record '" . $self->text . "'");
279 }
280 59 return;
281 }
282  
283 32 ▶sub parse_end {
Subroutine parse_end: called CC=2 SCAR=7.0
Pod undocumented
284 32 my ($self) = @_;
285 throw Mail::SPF::EJunkInRecord("Junk encountered in record '" . $self->text . "'")
286 32 ▶ if $self->{parse_text} ne '';
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"parse_text"} ne "" 0 32 32
287 32 delete($self->{parse_text});
288 32 return;
289 }
290  
291 =item B<text>: returns I<string>; throws I<Mail::SPF::ENoUnparsedText>
292  
293 Returns the unparsed text of the record. Throws a I<Mail::SPF::ENoUnparsedText>
294 exception if the record was created synthetically instead of being parsed, and
295 no text was provided.
296  
297 =cut
298  
299 4 ▶sub text {
Subroutine text: called CC=2 SCAR=7.1
Pod documented
300 4 my ($self) = @_;
301 defined($self->{text})
302 4 ▶ or throw Mail::SPF::ENoUnparsedText;
Branch: 1 branch
BranchTrueFalseTotal
defined $self->{"text"} or "Mail::SPF::ENoUnparsedText"->throw 4 0 4
303 4 return $self->{text};
304 }
305  
306 =item B<version_tag>: returns I<string>
307  
308 I<Abstract>. Returns the version tag of the record.
309  
310 This method is abstract and must be implemented by sub-classes of
311 Mail::SPF::Record.
312  
313 =item B<scopes>: returns I<list> of I<string>
314  
315 Returns a list of the scopes that are covered by the record. See the
316 description of the L</new> constructor's C<scopes> option.
317  
318 =cut
319  
320 3 ▶sub scopes {
Subroutine scopes: called CC=1 SCAR=0.0
Pod documented
321 3 my ($self) = @_;
322 3 return @{$self->{scopes}};
323 }
324  
325 =item B<terms>: returns I<list> of I<Mail::SPF::Term>
326  
327 Returns a list of the terms that make up the record, excluding any global
328 modifiers, which are returned by the C<global_mods> method. See the
329 description of the L</new> constructor's C<terms> option.
330  
331 =cut
332  
333 27 ▶sub terms {
Subroutine terms: called CC=1 SCAR=0.0
Pod documented
334 27 my ($self) = @_;
335 27 return @{$self->{terms}};
336 }
337  
338 =item B<global_mods>: returns I<list> of I<Mail::SPF::GlobalMod>
339  
340 Returns a list of the global modifiers of the record, ordered ascending by
341 modifier precedence. See the description of the L</new> constructor's
342 C<global_mods> option.
343  
344 =cut
345  
346 26 ▶sub global_mods {
Subroutine global_mods: called CC=1 SCAR=0.2
Pod documented
347 26 my ($self) = @_;
348 0 return sort { $a->precedence <=> $b->precedence } values(%{$self->{global_mods}});
349 }
350  
351 =item B<global_mod($mod_name)>: returns I<Mail::SPF::GlobalMod>
352  
353 Returns the global modifier of the given name if it is present in the record.
354 Returns B<undef> otherwise. Use this method if you wish to retrieve a specific
355 global modifier as opposed to getting all of them.
356  
357 =cut
358  
359 0 ▶sub global_mod {
Subroutine global_mod: not called CC=1 SCAR=6.9
Pod documented
360 0 my ($self, $mod_name) = @_;
361 0 return $self->{global_mods}->{$mod_name};
362 }
363  
364 =item B<stringify>: returns I<string>
365  
366 Returns the record's version tag and terms (including the global modifiers)
367 formatted as a string. You can simply use a Mail::SPF::Record object as a
368 string for the same effect, see L<"OVERLOADING">.
369  
370 =cut
371  
372 0 ▶sub stringify {
Subroutine stringify: not called CC=1 SCAR=6.9
Pod undocumented
373 0 my ($self) = @_;
374 0 return join(' ', $self->version_tag, $self->terms, $self->global_mods);
375 }
376  
377 =item B<eval($server, $request)>: throws I<Mail::SPF::Result>
378  
379 Evaluates the SPF record in the context of the request parameters represented
380 by the given I<Mail::SPF::Request> object. The given I<Mail::SPF::Server>
381 object is used for performing DNS look-ups. Throws a I<Mail::SPF::Result>
382 object matching the outcome of the evaluation; see L<Mail::SPF::Result>. See
383 RFC 4408, 4.6 and 4.7, for the exact algorithm used.
384  
385 =cut
386  
387 27 ▶sub eval {
Subroutine eval: called CC=3 SCAR=12.0
Pod documented
388 27 my ($self, $server, $request) = @_;
389  
390 27 ▶ defined($server)
Branch: 1 branch
BranchTrueFalseTotal
defined $server or "Mail::SPF::EOptionRequired"->throw("Mail::SPF server object required for record evaluation") 27 0 27
391 or throw Mail::SPF::EOptionRequired('Mail::SPF server object required for record evaluation');
392 27 ▶ defined($request)
Branch: 1 branch
BranchTrueFalseTotal
defined $request or "Mail::SPF::EOptionRequired"->throw("Request object required for record evaluation") 27 0 27
393 or throw Mail::SPF::EOptionRequired('Request object required for record evaluation');
394  
395 27 ▶ try {
Subroutine __ANON__: called CC=6 SCAR=21.8
396 27 foreach my $term ($self->terms) {
397 41 ▶ if ($term->isa('Mail::SPF::Mech')) {
Branch: 3 branches
BranchTrueFalseTotal
if ($term->isa('Mail::SPF::Mech')) { } 41 0 41
elsif ($term->isa('Mail::SPF::PositionalMod')) { } 0 0 0
elsif ($term->isa('Mail::SPF::UnknownMod')) { } 0 0 0
398 # Term is a mechanism.
399 41 my $mech = $term;
400 41 ▶ if ($mech->match($server, $request)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($mech->match($server, $request)) 26 14 40
401 26 my $result_name = $self->results_by_qualifier->{$mech->qualifier};
402 26 my $result_class = $server->result_class($result_name);
403 26 my $result = $result_class->new($server, $request, "Mechanism '$term' matched");
404 26 $mech->explain($server, $request, $result);
405 26 $result->throw();
406 }
407 }
408 elsif ($term->isa('Mail::SPF::PositionalMod')) {
409 # Term is a positional modifier.
410 0 my $mod = $term;
411 0 $mod->process($server, $request);
412 }
413 elsif ($term->isa('Mail::SPF::UnknownMod')) {
414 # Term is an unknown modifier. Ignore it (RFC 4408, 6/3).
415 }
416 else {
417 # Invalid term object encountered:
418 0 throw Mail::SPF::EUnexpectedTermObject(
419 "Unexpected term object '$term' encountered");
420 }
421 }
422  
423 # Default result when "falling off" the end of the record (RFC 4408, 4.7/1):
424 0 $server->throw_result('neutral-by-default', $request,
425 'Default neutral result due to no mechanism matches');
426 }
427 26 ▶ catch Mail::SPF::Result with {
Subroutine __ANON__: called CC=2 SCAR=6.9
428 26 my ($result) = @_;
429  
430 # Process global modifiers in ascending order of precedence:
431 26 foreach my $global_mod ($self->global_mods) {
432 6 $global_mod->process($server, $request, $result);
433 }
434  
435 26 $result->throw();
436 27 };
437 }
438  
439 =back
440  
441 =head1 OVERLOADING
442  
443 If a Mail::SPF::Record object is used as a I<string>, the C<stringify> method
444 is used to convert the object into a string.
445  
446 =head1 SEE ALSO
447  
448 L<Mail::SPF>, L<Mail::SPF::v1::Record>, L<Mail::SPF::v2::Record>,
449 L<Mail::SPF::Term>, L<Mail::SPF::Mech>, L<Mail::SPF::Mod>
450  
451 L<http://tools.ietf.org/html/rfc4408>
452  
453 For availability, support, and license information, see the README file
454 included with Mail::SPF.
455  
456 =head1 AUTHORS
457  
458 Julian Mehnle <julian@mehnle.net>, Shevek <cpan@anarres.org>
459  
460 =cut
461  
462 7 TRUE;
« SPF/Server.pm ↑ Summary SPF/Mod.pm »