blib/lib/Mail/DMARC/Report/URI.pm untested

filter: Statementstmt 0.0% 0 / 42 Branchbran 0.0% 0 / 16 Conditioncond 0.0% 0 / 13 MC/DCmcdc 0.0% 0 / 8 Subroutinesub 0.0% 0 / 8 Podpod 0.0% 0 / 3 totaltotal 0.0% 0 / 90 CC 9 SCAR 33.1
CC
9
Cov
0%
get_size_limit
56.0
parse
12.0
new
2.0
CRAP 27.5
1 package Mail::DMARC::Report::URI;
2 use strict;
3 use warnings;
4 use feature 'signatures';
5  
6 our $VERSION = '2.20260827';
7  
8 use Carp;
9 use URI;
10  
11 sub new($class) {
12 return bless {}, $class;
13 }
14  
15 sub parse( $self, $str = undef ) {
16 $str or croak "URI string is required!";
17  
18 my @valids = ();
19 foreach my $raw ( split /,/, $str ) {
20  
21 # warn "raw: $raw\n";
22 my ( $u, $size_f ) = split /!/, $raw;
23 my $bytes = $self->get_size_limit($size_f);
24 my $uri = URI->new($u) or do {
25 carp "can't parse URI from $u";
26 next;
27 };
28 my $scheme = $uri->scheme or next;
29 if ( $scheme eq 'mailto' && lc substr( $u, 0, 7 ) eq 'mailto:' ) {
30 push @valids, { max_bytes => $bytes, uri => $uri };
31 next;
32 }
33 if ( $scheme =~ /^http(s)?/x && lc substr( $u, 0, 4 ) eq 'http' ) {
34 push @valids, { max_bytes => $bytes, uri => $uri };
35 next;
36 }
37  
38 # print "invalid URI scheme: $scheme in $u\n";
39 # 12.1 Discovery - URI schemes found in "rua" tag that are not implemented by
40 # a Mail Receiver MUST be ignored.
41 }
42 return \@valids;
43 }
44  
45 sub get_size_limit( $self, $size = undef ) {
46 return 0 if !defined $size; # no limit
47 return $size if $size =~ /^\d+$/; # no units, raw byte count
48  
49 # 6.3 Formal Definition
50 # units are considered to be powers of two; a kilobyte is 2^10, a megabyte is 2^20,
51 my $unit = lc chop $size;
52 return $size * ( 2**10 ) if 'k' eq $unit;
53 return $size * ( 2**20 ) if 'm' eq $unit;
54 return $size * ( 2**30 ) if 'g' eq $unit;
55 return $size * ( 2**40 ) if 't' eq $unit;
56 croak "unrecognized unit ($unit) in size ($size)";
57 }
58  
59 1;
60  
61 __END__
62  
63 =pod
64  
65 =head1 NAME
66  
67 Mail::DMARC::Report::URI - a DMARC report URI
68  
69 =head1 VERSION
70  
71 version 2.20260827
72  
73 =head1 SYNOPSIS
74  
75 use Mail::DMARC::URI;
76 my $duri = Mail::DMARC::URI->new;
77 my $uri_ref = $duri->parse('mailto:rua@example.com,mailto:rua@external.otherdomain.com');
78 foreach my $u ( @$uri_ref ) {
79 my $method = $u->{uri};
80 my $max = $u->{max_bytes};
81 ... do some URI stuff ...
82 };
83  
84 =head1 DESCRIPTION
85  
86 defines a generic syntax for identifying a resource. The DMARC
87 mechanism uses this as the format by which a Domain Owner specifies
88 the destination for the two report types that are supported.
89  
90 The place such URIs are specified (see Section 6.2) allows a list of
91 these to be provided. A report is to be sent to each listed URI.
92 Mail Receivers MAY impose a limit on the number of URIs that receive
93 reports, but MUST support at least two. The list of URIs is
94 separated by commas (ASCII 0x2C).
95  
96 Each URI can have associated with it a maximum report size that may
97 be sent to it. This is accomplished by appending an exclamation
98 point (ASCII 0x21), followed by a maximum size indication, before a
99 separating comma or terminating semi-colon.
100  
101 Thus, a DMARC URI is a URI within which any commas or exclamation
102 points are percent-encoded per [URI], followed by an OPTIONAL
103 exclamation point and a maximum size specification, and, if there are
104 additional reporting URIs in the list, a comma and the next URI.
105  
106 For example, the URI "mailto:reports@example.com!50m" would request a
107 report be sent via email to "reports@example.com" so long as the
108 report payload does not exceed 50 megabytes.
109  
110 A formal definition is provided in Section 6.3.
111  
112 =head1 ABNF
113  
114 dmarc-uri = URI [ "!" 1*DIGIT [ "k" / "m" / "g" / "t" ] ]
115 ; "URI" is imported from [URI]; commas (ASCII 0x2c)
116 ; and exclamation points (ASCII 0x21) MUST be encoded
117  
118 URI is imported from RFC 3986: https://www.ietf.org/rfc/rfc3986.txt
119  
120 Only mailto, http, and https URIs are currently supported, examples:
121  
122 https://www.ietf.org/rfc/rfc3986.txt
123 mailto:John.Doe@example.com
124  
125 With an optional size limit (see SIZE LIMIT).
126  
127 =head1 SIZE LIMIT
128  
129 A size limitation in a dmarc-uri, if provided, is interpreted as a
130 count of units followed by an OPTIONAL unit size ("k" for kilobytes,
131 "m" for megabytes, "g" for gigabytes, "t" for terabytes). Without a
132 unit, the number is presumed to be a basic byte count. Note that the
133 units are considered to be powers of two; a kilobyte is 2^10, a
134 megabyte is 2^20, etc.
135  
136 =head1 AUTHORS
137  
138 =over 4
139  
140 =item *
141  
142 Matt Simerson <msimerson@cpan.org>
143  
144 =item *
145  
146 Davide Migliavacca <shari@cpan.org>
147  
148 =item *
149  
150 Marc Bradshaw <marc@marcbradshaw.net>
151  
152 =back
153  
154 =head1 COPYRIGHT AND LICENSE
155  
156 This software is copyright (c) 2026 by Matt Simerson.
157  
158 This is free software; you can redistribute it and/or modify it under
159 the same terms as the Perl 5 programming language system itself.
160  
161 =cut