« lib/Mail/DMARC/Report/Aggregate.pm
↑ Summary
blib/lib/Mail/DMARC/Report/Aggregate/Record/Row/Policy_Evaluated.pm »
| 1 | package Mail::DMARC::Report::URI; | ||||||||||||||||||||||||||||
| 2 | 17 | ▶ | use strict; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 3 | 17 | ▶ | use warnings; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 4 | 17 | ▶ | use feature 'signatures'; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 5 | |||||||||||||||||||||||||||||
| 6 | 17 | our $VERSION = '2.20260827'; | |||||||||||||||||||||||||||
| 7 | |||||||||||||||||||||||||||||
| 8 | 17 | ▶ | use Carp; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 9 | 17 | ▶ | use URI; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 10 | |||||||||||||||||||||||||||||
| 11 | 51 | ▶ | sub new($class) { | ||||||||||||||||||||||||||
|
Subroutine
new: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||||||||||||
| 12 | 51 | return bless {}, $class; | |||||||||||||||||||||||||||
| 13 | } | ||||||||||||||||||||||||||||
| 14 | |||||||||||||||||||||||||||||
| 15 | 87 | ▶ | sub parse( $self, $str = undef ) { | ||||||||||||||||||||||||||
|
Subroutine
parse: called CC=10 SCAR=23.6
Pod
undocumented
| |||||||||||||||||||||||||||||
| 16 | 87 | ▶ | $str or croak "URI string is required!"; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 17 | |||||||||||||||||||||||||||||
| 18 | 86 | my @valids = (); | |||||||||||||||||||||||||||
| 19 | 86 | foreach my $raw ( split /,/, $str ) { | |||||||||||||||||||||||||||
| 20 | |||||||||||||||||||||||||||||
| 21 | # warn "raw: $raw\n"; | ||||||||||||||||||||||||||||
| 22 | 91 | my ( $u, $size_f ) = split /!/, $raw; | |||||||||||||||||||||||||||
| 23 | 91 | my $bytes = $self->get_size_limit($size_f); | |||||||||||||||||||||||||||
| 24 | 91 | ▶ | my $uri = URI->new($u) or do { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 25 | 0 | carp "can't parse URI from $u"; | |||||||||||||||||||||||||||
| 26 | 0 | next; | |||||||||||||||||||||||||||
| 27 | }; | ||||||||||||||||||||||||||||
| 28 | 91 | ▶ | my $scheme = $uri->scheme or next; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 29 | 91 | ▶ | if ( $scheme eq 'mailto' && lc substr( $u, 0, 7 ) eq 'mailto:' ) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
$scheme eq "mailto" and lc substr($u, 0, 7) eq "mailto:"
MC/DC50%1/2
$scheme eq "mailto" and lc substr($u, 0, 7) eq "mailto:"
$scheme eq "mailto"
lc substr($u, 0, 7) eq "mailto:"
Truth table66%2/3
A and B
A= $scheme eq "mailto"B= lc substr($u, 0, 7) eq "mailto:"
| |||||||||||||||||||||||||||||
| 30 | 74 | push @valids, { max_bytes => $bytes, uri => $uri }; | |||||||||||||||||||||||||||
| 31 | 74 | next; | |||||||||||||||||||||||||||
| 32 | } | ||||||||||||||||||||||||||||
| 33 | 17 | ▶ | if ( $scheme =~ /^http(s)?/x && lc substr( $u, 0, 4 ) eq 'http' ) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
$scheme =~ /^http(s)?/x and lc substr($u, 0, 4) eq "http"
MC/DC50%1/2
$scheme =~ /^http(s)?/x and lc substr($u, 0, 4) eq "http"
$scheme =~ /^http(s)?/x
lc substr($u, 0, 4) eq "http"
Truth table66%2/3
A and B
A= $scheme =~ /^http(s)?/xB= lc substr($u, 0, 4) eq "http"
| |||||||||||||||||||||||||||||
| 34 | 8 | push @valids, { max_bytes => $bytes, uri => $uri }; | |||||||||||||||||||||||||||
| 35 | 8 | 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 | 86 | return \@valids; | |||||||||||||||||||||||||||
| 43 | } | ||||||||||||||||||||||||||||
| 44 | |||||||||||||||||||||||||||||
| 45 | 99 | ▶ | sub get_size_limit( $self, $size = undef ) { | ||||||||||||||||||||||||||
|
Subroutine
get_size_limit: called CC=8 SCAR=20.8
Pod
undocumented
| |||||||||||||||||||||||||||||
| 46 | 99 | ▶ | return 0 if !defined $size; # no limit | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 47 | 12 | ▶ | return $size if $size =~ /^\d+$/; # no units, raw byte count | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 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 | 11 | my $unit = lc chop $size; | |||||||||||||||||||||||||||
| 52 | 11 | ▶ | return $size * ( 2**10 ) if 'k' eq $unit; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 53 | 9 | ▶ | return $size * ( 2**20 ) if 'm' eq $unit; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 54 | 2 | ▶ | return $size * ( 2**30 ) if 'g' eq $unit; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 55 | 1 | ▶ | return $size * ( 2**40 ) if 't' eq $unit; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 56 | 1 | croak "unrecognized unit ($unit) in size ($size)"; | |||||||||||||||||||||||||||
| 57 | } | ||||||||||||||||||||||||||||
| 58 | |||||||||||||||||||||||||||||
| 59 | 17 | 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 | ||||||||||||||||||||||||||||