| 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
| |||||||||||||||||||
| 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
| |||||||||||||||||||
| 135 | 37 | ▶ | $self->{terms} ||= []; | ||||||||||||||||
|
Condition50%1/2
$self->{"terms"} ||= []
MC/DC0%0/1
$self->{"terms"} ||= []
$self->{"terms"}
Truth table50%1/2
A
A= $self->{"terms"}
| |||||||||||||||||||
| 136 | 37 | ▶ | $self->{global_mods} ||= {}; | ||||||||||||||||
|
Condition50%1/2
$self->{"global_mods"} ||= {}
MC/DC0%0/1
$self->{"global_mods"} ||= {}
$self->{"global_mods"}
Truth table50%1/2
A
A= $self->{"global_mods"}
| |||||||||||||||||||
| 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
| |||||||||||||||||||
| 199 | 37 | $self->parse_version_tag(); | |||||||||||||||||
| 200 | 33 | ▶ | $self->parse_term() while length($self->{parse_text}); | ||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||
| 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
| |||||||||||||||||||
| 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
| |||||||||||||||||||
| 220 | 0 | throw Mail::SPF::ENothingToParse('Cannot load Mail::SPF::Mech class'); | |||||||||||||||||
| 221 | } | ||||||||||||||||||
| 222 | 60 | ▶ | if ( | ||||||||||||||||
|
Branch: 2 branches
| |||||||||||||||||||
| 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
| |||||||||||||||||||
| 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
| |||||||||||||||||||
| 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
| |||||||||||||||||||
| 258 | # Global modifier. | ||||||||||||||||||
| 259 | 6 | ▶ | not defined($self->{global_mods}->{$mod_name}) or | ||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||
| 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
| |||||||||||||||||||
| 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
| |||||||||||||||||||
| 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
| |||||||||||||||||||
| 391 | or throw Mail::SPF::EOptionRequired('Mail::SPF server object required for record evaluation'); | ||||||||||||||||||
| 392 | 27 | ▶ | defined($request) | ||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||
| 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
| |||||||||||||||||||
| 398 | # Term is a mechanism. | ||||||||||||||||||
| 399 | 41 | my $mech = $term; | |||||||||||||||||
| 400 | 41 | ▶ | if ($mech->match($server, $request)) { | ||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||
| 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; | |||||||||||||||||