SPF/MacroString.pm

filter: Statementstmt 78.0% 103 / 132 Branchbran 45.5% 41 / 90 Conditioncond 44.4% 8 / 18 MC/DCmcdc 27.2% 3 / 11 Subroutinesub 90.4% 19 / 21 Podpod 75.0% 3 / 4 totaltotal 64.1% 177 / 276 CC 53 SCAR 53.6
CC
53
Cov
63%
expand
328.2
_is_valid_context
5.8
new
2.0
CRAP 212.1
↑ Summary SPF/Util.pm »
1 #
2 # Mail::SPF::MacroString
3 # SPF record macro string class.
4 #
5 # (C) 2005-2012 Julian Mehnle <julian@mehnle.net>
6 # 2005 Shevek <cpan@anarres.org>
7 # $Id: MacroString.pm 57 2012-01-30 08:15:31Z julian $
8 #
9 ##############################################################################
10  
11 package Mail::SPF::MacroString;
12  
13 =head1 NAME
14  
15 Mail::SPF::MacroString - SPF record macro string class
16  
17 =head1 VERSION
18  
19 version 3.20250505
20  
21 =cut
22  
23 3 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
24 3 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
25  
26 3 ▶use utf8; # Hack to keep Perl 5.6 from whining about /[\p{}]/.
Subroutine BEGIN: called CC=1 SCAR=0.0
27  
28 3 ▶use base 'Mail::SPF::Base';
Subroutine BEGIN: called CC=1 SCAR=0.0
29  
30 use overload
31 3 '""' => 'stringify',
32 3 ▶ fallback => 1;
Subroutine BEGIN: called CC=1 SCAR=0.0
33  
34 3 ▶use Error ':try';
Subroutine BEGIN: called CC=1 SCAR=0.0
35 3 ▶use URI::Escape 1.13 ();
Subroutine BEGIN: called CC=1 SCAR=0.0
36  
37 3 ▶use Mail::SPF::Util;
Subroutine BEGIN: called CC=1 SCAR=0.0
38  
39 3 ▶use constant TRUE => (0 == 0);
Subroutine BEGIN: called CC=1 SCAR=0.0
40 3 ▶use constant FALSE => not TRUE;
Subroutine BEGIN: called CC=1 SCAR=0.0
41  
42 3 ▶use constant default_split_delimiters => '.';
Subroutine BEGIN: called CC=1 SCAR=0.0
43 3 ▶use constant default_join_delimiter => '.';
Subroutine BEGIN: called CC=1 SCAR=0.0
44  
45 3 ▶use constant uri_unreserved_chars => 'A-Za-z0-9\-._~';
Subroutine BEGIN: called CC=1 SCAR=0.0
46 # "unreserved" characters according to RFC 3986 -- not the "uric" chars!
47 # This deliberately deviates from what RFC 4408 says. This is a bug in
48 # RFC 4408.
49  
50 3 ▶use constant macos_epoch_offset => ((1970 - 1904) * 365 + 17) * 24 * 3600;
Subroutine BEGIN: called CC=1 SCAR=0.0
51 # This is a hack because the MacOS Classic epoch is relative to the local
52 # timezone. Get a real OS!
53  
54 # Interface:
55 ##############################################################################
56  
57 =head1 SYNOPSIS
58  
59 =head2 Providing the expansion context early
60  
61 use Mail::SPF::MacroString;
62  
63 my $macrostring = Mail::SPF::MacroString->new(
64 text => '%{ir}.%{v}._spf.%{d2}',
65 server => $server,
66 request => $request
67 );
68  
69 my $expanded = $macrostring->expand;
70  
71 =head2 Providing the expansion context late
72  
73 use Mail::SPF::MacroString;
74  
75 my $macrostring = Mail::SPF::MacroString->new(
76 text => '%{ir}.%{v}._spf.%{d2}'
77 );
78  
79 my $expanded1 = $macrostring->expand($server, $request1);
80  
81 $macrostring->context($server, $request2);
82 my $expanded2 = $macrostring->expand;
83  
84 =cut
85  
86 # Implementation:
87 ##############################################################################
88  
89 =head1 DESCRIPTION
90  
91 An object of class B<Mail::SPF::MacroString> represents a macro string that
92 can be expanded to a plain string in the context of an SPF request.
93  
94 =head2 Constructor
95  
96 The following constructor is provided:
97  
98 =over
99  
100 =item B<new(%options)>: returns I<Mail::SPF::MacroString>
101  
102 Creates a new SPF record macro string object.
103  
104 %options is a list of key/value pairs representing any of the following
105 options:
106  
107 =over
108  
109 =item B<text>
110  
111 I<Required>. The unexpanded text of the new macro string.
112  
113 =item B<server>
114  
115 The I<Mail::SPF::Server> object that is to be used when expanding the macro
116 string. A server object need not be attached statically to the macro string;
117 it can be specified dynamically when calling the C<expand> method.
118  
119 =item B<request>
120  
121 The I<Mail::SPF::Request> object that is to be used when expanding the macro
122 string. A request object need not be attached statically to the macro string;
123 it can be specified dynamically when calling the C<expand> method.
124  
125 =item B<is_explanation>
126  
127 A I<boolean> denoting whether the macro string is an explanation string
128 obtained via an C<exp> modifier. If B<true>, the C<c>, C<r>, and C<t> macros
129 may appear in the macro string, otherwise they may not, and if they do, a
130 I<Mail::SPF::EInvalidMacro> exception will be thrown when the macro string is
131 expanded. Defaults to B<false>.
132  
133 =back
134  
135 =cut
136  
137 sub new {
138 2 ▶ my ($self, %options) = @_;
Subroutine new: called CC=2 SCAR=7.0
Pod documented
139 2 $self = $self->SUPER::new(%options);
140 defined($self->{text})
141 2 ▶ or throw Mail::SPF::EOptionRequired("Missing required 'text' option");
Branch: 1 branch
BranchTrueFalseTotal
defined $self->{"text"} or "Mail::SPF::EOptionRequired"->throw("Missing required 'text' option") 0 2 2
142 2 return $self;
143 }
144  
145 =back
146  
147 =head2 Instance methods
148  
149 The following instance methods are provided:
150  
151 =over
152  
153 =item B<text>: returns I<string>
154  
155 Returns the unexpanded text of the macro string.
156  
157 =cut
158  
159 # Read-only accessor:
160 3 __PACKAGE__->make_accessor('text', TRUE);
161  
162 =item B<context($server, $request)>: throws I<Mail::SPF::EOptionRequired>
163  
164 Attaches the given I<Mail::SPF::Server> and I<Mail::SPF::Request> objects as
165 the context for the macro string.
166  
167 =cut
168  
169 sub context {
170 1 ▶ my ($self, $server, $request) = @_;
Subroutine context: called CC=1 SCAR=0.0
Pod documented
171 1 $self->_is_valid_context(TRUE, $server, $request);
172 1 $self->{server} = $server;
173 1 $self->{request} = $request;
174 1 $self->{expanded} = undef;
175 1 return;
176 }
177  
178 =item B<expand>: returns I<string>;
179 throws I<Mail::SPF::EMacroExpansionCtxRequired>, I<Mail::SPF::EInvalidMacroString>, I<Mail::SPF::Result::PermError>
180  
181 =item B<expand($server, $request)>: returns I<string>;
182 throws I<Mail::SPF::EMacroExpansionCtxRequired>, I<Mail::SPF::EInvalidMacroString>, I<Mail::SPF::Result::PermError>
183  
184 Expands the text of the macro string using either the context specified through
185 an earlier call to the C<context()> method, or the given context, and returns
186 the resulting string. See RFC 4408, 8, for how macros are expanded.
187  
188 =cut
189  
190 sub expand {
191 6 ▶ my ($self, @context) = @_;
Subroutine expand: called CC=47 SCAR=57.9
Pod documented
192  
193 return $self->{expanded}
194 6 ▶ if defined($self->{expanded});
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->{"expanded"} 2 4 6
195  
196 4 my $text = $self->{text};
197 return undef
198 4 ▶ if not defined($text);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $text 0 4 4
199  
200 4 ▶ return $self->{expanded} = $text
Branch: 1 branch
BranchTrueFalseTotal
unless $text =~ /%/ 0 4 4
201 if $text !~ /%/; # Short-circuit expansion if text has no '%' character.
202  
203 4 ▶ my ($server, $request) = @context ? @context : ($self->{server}, $self->{request});
Branch: 1 branch
BranchTrueFalseTotal
@context ? : 1 3 4
204 4 $self->_is_valid_context(TRUE, $server, $request);
205  
206 3 my $expanded = '';
207 3 pos($text) = 0;
208  
209 3 ▶ while ($text =~ m/ \G (.*?) %(.) /cgx) {
Branch: 1 branch
BranchTrueFalseTotal
if ($text =~ / \G (.*?) %(.) /cgx) 9 3 12
210 9 $expanded .= $1;
211 9 my $key = $2;
212 9 my $pos = pos($text) - 2;
213  
214 9 ▶ if ($key eq '{') {
Branch: 4 branches
BranchTrueFalseTotal
if ($key eq '{') { } 9 0 9
elsif ($key eq '-') { } 0 0 0
elsif ($key eq '_') { } 0 0 0
elsif ($key eq '%') { } 0 0 0
215 9 ▶ if ($text =~ m/ \G (\w|_\p{IsAlpha}+) ([0-9]+)? (r)? ([.\-+,\/_=]*)? } /cgx) {
Branch: 1 branch
BranchTrueFalseTotal
if ($text =~ m[ \G (\w|_\p{IsAlpha}+) ([0-9]+)? (r)? ([.\-+,/_=]*)? } ]cgx) { } 9 0 9
216 9 my ($char, $rh_parts, $reverse, $delimiters) = ($1, $2, $3, $4);
217  
218 # Upper-case macro chars trigger URL-escaping AKA percent-encoding
219 # (RFC 4408, 8.1/26):
220 9 my $do_percent_encode = $char =~ tr/A-Z/a-z/;
221  
222 9 my $value;
223  
224 9 ▶ if ($char eq 's') { # RFC 4408, 8.1/19
Branch: 12 branches
BranchTrueFalseTotal
if ($char eq 's') { } 0 9 9
elsif ($char eq 'l') { } 0 9 9
elsif ($char eq 'o') { } 0 9 9
elsif ($char eq 'd') { } 3 6 9
elsif ($char eq 'i') { } 3 3 6
elsif ($char eq 'p') { } 0 3 3
elsif ($char eq 'v') { } 3 0 3
elsif ($char eq 'h') { } 0 0 0
elsif ($char eq 'c') { } 0 0 0
elsif ($char eq 'r') { } 0 0 0
elsif ($char eq 't') { } 0 0 0
elsif ($char eq '_scope') { } 0 0 0
225 0 $value = $request->identity;
226 }
227 elsif ($char eq 'l') { # RFC 4408, 8.1/19
228 0 $value = $request->localpart;
229 }
230 elsif ($char eq 'o') { # RFC 4408, 8.1/19
231 0 $value = $request->domain;
232 }
233 elsif ($char eq 'd') { # RFC 4408, 8.1/6/4
234 3 $value = $request->authority_domain;
235 }
236 elsif ($char eq 'i') { # RFC 4408, 8.1/20, 8.1/21
237 3 my $ip_address = $request->ip_address;
238 3 ▶ $ip_address = Mail::SPF::Util->ipv6_address_to_ipv4($ip_address)
Branch: 1 branch
BranchTrueFalseTotal
if "Mail::SPF::Util"->ipv6_address_is_ipv4_mapped($ip_address) 0 3 3
239 if Mail::SPF::Util->ipv6_address_is_ipv4_mapped($ip_address);
240 3 my $ip_address_version = $ip_address->version;
241 3 ▶ if ($ip_address_version == 4) {
Branch: 2 branches
BranchTrueFalseTotal
if ($ip_address_version == 4) { } 3 0 3
elsif ($ip_address_version == 6) { } 0 0 0
242 3 $value = $ip_address->addr;
243 }
244 elsif ($ip_address_version == 6) {
245 0 $value = join(".", split(//, unpack("H32", $ip_address->aton)));
246 }
247 else {
248 # Unexpected IP address version.
249 0 $server->throw_result('permerror', $request,
250 "Unexpected IP address version '$ip_address_version' in request");
251 }
252 }
253 elsif ($char eq 'p') { # RFC 4408, 8.1/22
254 try {
255 0 ▶ $value = Mail::SPF::Util->valid_domain_for_ip_address(
Subroutine __ANON__: not called CC=1 SCAR=6.9
256 $server, $request, $request->ip_address, $request->authority_domain,
257 TRUE, TRUE
258 );
259 }
260 0 ▶ catch Mail::SPF::EDNSError with {};
Subroutine __ANON__: not called CC=1 SCAR=6.9
261 0 ▶ $value ||= 'unknown';
Condition0%0/2
$value ||= "unknown"
l!l
00
MC/DC0%0/1
$value ||= "unknown"
$value
Truth table0%0/2
A
A= $value
Aresult
11
00
262 }
263 elsif ($char eq 'v') { # RFC 4408, 8.1/6/7
264 3 my $ip_address_version = $request->ip_address->version;
265 3 ▶ if ($ip_address_version == 4) {
Branch: 2 branches
BranchTrueFalseTotal
if ($ip_address_version == 4) { } 3 0 3
elsif ($ip_address_version == 6) { } 0 0 0
266 3 $value = 'in-addr';
267 }
268 elsif ($ip_address_version == 6) {
269 0 $value = 'ip6';
270 }
271 else {
272 # Unexpected IP address version.
273 0 $server->throw_result('permerror', $request,
274 "Unexpected IP address version '$ip_address_version' in request");
275 }
276 }
277 elsif ($char eq 'h') { # RFC 4408, 8.1/6/8
278 0 ▶ $value = $request->helo_identity || 'unknown';
Condition0%0/2
$request->helo_identity || 'unknown'
l!l
00
MC/DC0%0/1
$request->helo_identity || 'unknown'
$request->helo_identity
Truth table0%0/2
A
A= $request->helo_identity
Aresult
11
00
279 }
280 elsif ($char eq 'c') { # RFC 4408, 8.1/20, 8.1/21
281 $self->{is_explanation}
282 0 ▶ or throw Mail::SPF::EInvalidMacro(
Branch: 1 branch
BranchTrueFalseTotal
$self->{"is_explanation"} or "Mail::SPF::EInvalidMacro"->throw("Illegal 'c' macro in non-explanation macro string '${text}'") 0 0 0
283 "Illegal 'c' macro in non-explanation macro string '$text'");
284 0 my $ip_address = $request->ip_address;
285 0 ▶ $ip_address = Mail::SPF::Util->ipv6_address_to_ipv4($ip_address)
Branch: 1 branch
BranchTrueFalseTotal
if "Mail::SPF::Util"->ipv6_address_is_ipv4_mapped($ip_address) 0 0 0
286 if Mail::SPF::Util->ipv6_address_is_ipv4_mapped($ip_address);
287 0 $value = Mail::SPF::Util->ip_address_to_string($ip_address);
288 }
289 elsif ($char eq 'r') { # RFC 4408, 8.1/23
290 $self->{is_explanation}
291 0 ▶ or throw Mail::SPF::EInvalidMacro(
Branch: 1 branch
BranchTrueFalseTotal
$self->{"is_explanation"} or "Mail::SPF::EInvalidMacro"->throw("Illegal 'r' macro in non-explanation macro string '${text}'") 0 0 0
292 "Illegal 'r' macro in non-explanation macro string '$text'");
293 0 ▶ $value = $server->hostname || 'unknown';
Condition0%0/2
$server->hostname || 'unknown'
l!l
00
MC/DC0%0/1
$server->hostname || 'unknown'
$server->hostname
Truth table0%0/2
A
A= $server->hostname
Aresult
11
00
294 }
295 elsif ($char eq 't') { # RFC 4408, 8.1/24
296 $self->{is_explanation}
297 0 ▶ or throw Mail::SPF::EInvalidMacro(
Branch: 1 branch
BranchTrueFalseTotal
$self->{"is_explanation"} or "Mail::SPF::EInvalidMacro"->throw("Illegal 't' macro in non-explanation macro string '${text}'") 0 0 0
298 "Illegal 't' macro in non-explanation macro string '$text'");
299 0 ▶ $value = $^O ne 'MacOS' ? time() : time() + $self->macos_epoch_offset;
Branch: 1 branch
BranchTrueFalseTotal
$^O ne 'MacOS' ? : 0 0 0
300 }
301 elsif ($char eq '_scope') {
302 # Scope pseudo macro for internal use only!
303 0 $value = $request->scope;
304 }
305 else {
306 # Unknown macro character.
307 0 throw Mail::SPF::EInvalidMacro(
308 "Unknown macro character '$char' at pos $pos in macro string '$text'");
309 }
310  
311 9 ▶ if (defined($rh_parts) or defined($reverse)) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $rh_parts or defined $reverse) 6 3 9
Condition100%3/3
defined $rh_parts or defined $reverse
l!l&&r!l&&!r
333
MC/DC100%2/2
defined $rh_parts or defined $reverse
defined $rh_parts defined $reverse
Truth table100%3/3
A or B
A= defined $rh_partsB= defined $reverse
ABresult
1X1
011
000
312 6 ▶ $delimiters ||= $self->default_split_delimiters;
Condition33%1/3
$delimiters ||= $self->default_split_delimiters
l!l&&r!l&&!r
060
MC/DC0%0/2
$delimiters ||= $self->default_split_delimiters
$delimiters $self->default_split_delimiters
Truth table33%1/3
A ||= B
A= $delimitersB= $self->default_split_delimiters
ABresult
1X1
011
000
313 6 my @list = split(/[\Q$delimiters\E]/, $value);
314 6 ▶ @list = reverse(@list) if defined($reverse);
Branch: 1 branch
BranchTrueFalseTotal
if defined $reverse 3 3 6
315  
316 # Extract desired parts:
317 6 ▶ if (defined($rh_parts) and $rh_parts > 0) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $rh_parts and $rh_parts > 0) 3 3 6
Condition66%2/3
defined $rh_parts and $rh_parts > 0
!ll&&!rl&&r
303
MC/DC50%1/2
defined $rh_parts and $rh_parts > 0
defined $rh_parts $rh_parts > 0
Truth table66%2/3
A and B
A= defined $rh_partsB= $rh_parts > 0
ABresult
0X0
100
111
318 3 ▶ splice(@list, 0, @list >= $rh_parts ? @list - $rh_parts : 0);
Branch: 1 branch
BranchTrueFalseTotal
@list >= $rh_parts ? : 3 0 3
319 }
320 6 ▶ if (defined($rh_parts) and $rh_parts == 0) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $rh_parts and $rh_parts == 0) 0 6 6
Condition66%2/3
defined $rh_parts and $rh_parts == 0
!ll&&!rl&&r
330
MC/DC0%0/2
defined $rh_parts and $rh_parts == 0
defined $rh_parts $rh_parts == 0
Truth table66%2/3
A and B
A= defined $rh_partsB= $rh_parts == 0
ABresult
0X0
100
111
321 0 throw Mail::SPF::EInvalidMacro(
322 "Illegal selection of 0 (zero) right-hand parts at pos $pos in macro string '$text'");
323 }
324  
325 6 $value = join($self->default_join_delimiter, @list);
326 }
327  
328 9 ▶ $value = URI::Escape::uri_escape($value, '^' . $self->uri_unreserved_chars)
Branch: 1 branch
BranchTrueFalseTotal
if $do_percent_encode 0 9 9
329 # Note the comment about the set of safe/unsafe characters at the
330 # definition of the "uri_unreserved_chars" constant above.
331 if $do_percent_encode;
332  
333 9 $expanded .= $value;
334 }
335 else {
336 # Invalid macro expression.
337 0 throw Mail::SPF::EInvalidMacro(
338 "Invalid macro expression at pos $pos in macro string '$text'");
339 }
340 }
341 elsif ($key eq '-') {
342 0 $expanded .= '%20';
343 }
344 elsif ($key eq '_') {
345 0 $expanded .= ' ';
346 }
347 elsif ($key eq '%') {
348 0 $expanded .= '%';
349 }
350 else {
351 # Invalid macro expression.
352 0 throw Mail::SPF::EInvalidMacro(
353 "Invalid macro expression at pos $pos in macro string '$text'");
354 }
355 }
356  
357 3 $expanded .= substr($text, pos($text)); # Append remaining unmatched characters.
358  
359 #print("DEBUG: Expand $text -> $expanded\n");
360 #printf("DEBUG: Caller: %s() (line %d)\n", (caller(1))[3, 2]);
361 3 ▶ return @context ? $expanded : ($self->{expanded} = $expanded);
Branch: 1 branch
BranchTrueFalseTotal
@context ? : 1 2 3
362 }
363  
364 =item B<is_explanation>: returns I<boolean>
365  
366 Returns B<true> if the macro string is an explanation string obtained via an
367 C<exp> modifier. See the description of the L</new> constructor's
368 C<is_explanation> option.
369  
370 =cut
371  
372 # Make read-only accessor:
373 3 __PACKAGE__->make_accessor('is_explanation', TRUE);
374  
375 =item B<stringify>: returns I<string>
376  
377 Returns the expanded text of the macro string if a context is attached to the
378 object. Returns the unexpanded text otherwise. You can simply use a
379 Mail::SPF::MacroString object as a string for the same effect, see
380 L<"OVERLOADING">.
381  
382 =cut
383  
384 sub stringify {
385 4 ▶ my ($self) = @_;
Subroutine stringify: called CC=2 SCAR=6.9
Pod undocumented
386 return
387 4 ▶ $self->_is_valid_context(FALSE, $self->{server}, $self->{request}) ?
Branch: 1 branch
BranchTrueFalseTotal
$self->_is_valid_context(0, $self->{'server'}, $self->{'request'}) ? : 2 2 4
388 $self->expand # Context availabe, expand.
389 : $self->text; # Context unavailable, do not expand.
390 }
391  
392 =back
393  
394 =cut
395  
396 sub _is_valid_context {
397 9 ▶ my ($self, $require, $server, $request) = @_;
Subroutine _is_valid_context: called CC=5 SCAR=17.5
398 9 ▶ if (not UNIVERSAL::isa($server, 'Mail::SPF::Server')) {
Branch: 1 branch
BranchTrueFalseTotal
unless (UNIVERSAL::isa($server, "Mail::SPF::Server")) 3 6 9
399 3 ▶ throw Mail::SPF::EMacroExpansionCtxRequired('Mail::SPF server object required') if $require;
Branch: 1 branch
BranchTrueFalseTotal
if $require 1 2 3
400 2 return FALSE;
401 }
402 6 ▶ if (not UNIVERSAL::isa($request, 'Mail::SPF::Request')) {
Branch: 1 branch
BranchTrueFalseTotal
unless (UNIVERSAL::isa($request, "Mail::SPF::Request")) 0 6 6
403 0 ▶ throw Mail::SPF::EMacroExpansionCtxRequired('Request object required') if $require;
Branch: 1 branch
BranchTrueFalseTotal
if $require 0 0 0
404 0 return FALSE;
405 }
406 6 return TRUE;
407 }
408  
409 =head1 OVERLOADING
410  
411 If a Mail::SPF::MacroString object is used as a I<string>, the C<stringify>
412 method is used to convert the object into a string.
413  
414 =head1 SEE ALSO
415  
416 L<Mail::SPF>, L<Mail::SPF::Record>, L<Mail::SPF::Server>, L<Mail::SPF::Request>
417  
418 L<http://tools.ietf.org/html/rfc4408>
419  
420 For availability, support, and license information, see the README file
421 included with Mail::SPF.
422  
423 =head1 AUTHORS
424  
425 Julian Mehnle <julian@mehnle.net>, Shevek <cpan@anarres.org>
426  
427 =cut
428  
429 3 TRUE;
↑ Summary SPF/Util.pm »