| 1 | package Mail::RoundTrip; | ||||||||||||||||||||
| 2 | |||||||||||||||||||||
| 3 | 3 | ▶ | use 5.006; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 4 | 3 | ▶ | use strict; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 5 | 3 | ▶ | use warnings; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 6 | 3 | ▶ | use Moo; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 7 | 3 | ▶ | use JSON; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 8 | 3 | ▶ | use UUID::Tiny qw(:std); | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 9 | 3 | ▶ | use Email::Sender::Simple qw(sendmail); | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 10 | 3 | ▶ | use Email::Simple; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 11 | 3 | ▶ | use Email::Simple::Creator; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 12 | 3 | ▶ | use File::Slurp; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 13 | 3 | ▶ | use Carp; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 14 | |||||||||||||||||||||
| 15 | =head1 NAME | ||||||||||||||||||||
| 16 | |||||||||||||||||||||
| 17 | Mail::RoundTrip - Management routines for round trip validation of users' emails | ||||||||||||||||||||
| 18 | |||||||||||||||||||||
| 19 | =head1 VERSION | ||||||||||||||||||||
| 20 | |||||||||||||||||||||
| 21 | Version 0.02 | ||||||||||||||||||||
| 22 | |||||||||||||||||||||
| 23 | =cut | ||||||||||||||||||||
| 24 | |||||||||||||||||||||
| 25 | 3 | our $VERSION = '0.02'; | |||||||||||||||||||
| 26 | |||||||||||||||||||||
| 27 | |||||||||||||||||||||
| 28 | =head1 SYNOPSIS | ||||||||||||||||||||
| 29 | |||||||||||||||||||||
| 30 | To send validation email: | ||||||||||||||||||||
| 31 | |||||||||||||||||||||
| 32 | my $validator = Mail::RoundTrip->new( | ||||||||||||||||||||
| 33 | spool_dir => '/var/spool/myapp/contacts', | ||||||||||||||||||||
| 34 | address => 'test@example.org', | ||||||||||||||||||||
| 35 | data => $data, | ||||||||||||||||||||
| 36 | from => 'me@example.com', | ||||||||||||||||||||
| 37 | reply_to => 'not_me@example.com', | ||||||||||||||||||||
| 38 | ); | ||||||||||||||||||||
| 39 | my $code = $validator->code; | ||||||||||||||||||||
| 40 | $validator->send_confirmation(template => $template); | ||||||||||||||||||||
| 41 | |||||||||||||||||||||
| 42 | To retrieve based on validation code: | ||||||||||||||||||||
| 43 | |||||||||||||||||||||
| 44 | my $data = Mail::RoundTrip->get_data( code => $code, spool_dir => $dir ); | ||||||||||||||||||||
| 45 | |||||||||||||||||||||
| 46 | =head1 DESCRIPTION | ||||||||||||||||||||
| 47 | |||||||||||||||||||||
| 48 | Many web applicatins rely on some sort of round-trip validation of user emails. | ||||||||||||||||||||
| 49 | This verifies that the email address, for example, is actually owned by the | ||||||||||||||||||||
| 50 | user. This module provides a minimalist set of routines for managing this | ||||||||||||||||||||
| 51 | process. | ||||||||||||||||||||
| 52 | |||||||||||||||||||||
| 53 | The module is curently minimalistic because it is assumed it will provide the | ||||||||||||||||||||
| 54 | common back-ends for a number of related verification routines. Extensions and | ||||||||||||||||||||
| 55 | feature requests are welcome. The module exposes a fully object-oriented | ||||||||||||||||||||
| 56 | interface. | ||||||||||||||||||||
| 57 | |||||||||||||||||||||
| 58 | The module basically provides a minimalist spooling service for holding data for | ||||||||||||||||||||
| 59 | later processing once the code has been provided. | ||||||||||||||||||||
| 60 | |||||||||||||||||||||
| 61 | =head1 PROPERTIES | ||||||||||||||||||||
| 62 | |||||||||||||||||||||
| 63 | =head2 address | ||||||||||||||||||||
| 64 | |||||||||||||||||||||
| 65 | The email address to be confirmed. | ||||||||||||||||||||
| 66 | |||||||||||||||||||||
| 67 | =head2 code | ||||||||||||||||||||
| 68 | |||||||||||||||||||||
| 69 | This is the random code used to authenticate the request. Currently this is | ||||||||||||||||||||
| 70 | generated as an sha2 256-bit hash of a pseudo-random value. | ||||||||||||||||||||
| 71 | |||||||||||||||||||||
| 72 | =head2 from | ||||||||||||||||||||
| 73 | |||||||||||||||||||||
| 74 | The address in the from header. | ||||||||||||||||||||
| 75 | |||||||||||||||||||||
| 76 | =head2 reply_to | ||||||||||||||||||||
| 77 | |||||||||||||||||||||
| 78 | The address in the reply to header. | ||||||||||||||||||||
| 79 | |||||||||||||||||||||
| 80 | =head2 return_path | ||||||||||||||||||||
| 81 | |||||||||||||||||||||
| 82 | The return path fo the email. | ||||||||||||||||||||
| 83 | |||||||||||||||||||||
| 84 | =head2 data | ||||||||||||||||||||
| 85 | |||||||||||||||||||||
| 86 | The data to be queued. | ||||||||||||||||||||
| 87 | |||||||||||||||||||||
| 88 | =head2 spool_dir | ||||||||||||||||||||
| 89 | |||||||||||||||||||||
| 90 | The spool directory to be used. | ||||||||||||||||||||
| 91 | |||||||||||||||||||||
| 92 | =cut | ||||||||||||||||||||
| 93 | |||||||||||||||||||||
| 94 | 3 | has address => (is =>'ro', required => 0); | |||||||||||||||||||
| 95 | |||||||||||||||||||||
| 96 | 3 | has code => (is => 'lazy'); | |||||||||||||||||||
| 97 | |||||||||||||||||||||
| 98 | 3 | has data => (is => 'ro', required => 0); | |||||||||||||||||||
| 99 | |||||||||||||||||||||
| 100 | 3 | has from => (is => 'ro', required => 0); | |||||||||||||||||||
| 101 | |||||||||||||||||||||
| 102 | 3 | has reply_to => (is => 'ro', required => 0); | |||||||||||||||||||
| 103 | |||||||||||||||||||||
| 104 | 3 | has return_path => (is => 'ro', requird => 0); | |||||||||||||||||||
| 105 | |||||||||||||||||||||
| 106 | 3 | has spool_dir => (is => 'ro', required => 1); | |||||||||||||||||||
| 107 | |||||||||||||||||||||
| 108 | 0 | ▶ | sub _build_code { | ||||||||||||||||||
|
Subroutine
_build_code: not called CC=2 SCAR=17.9
| |||||||||||||||||||||
| 109 | 0 | my ($self) = @_; | |||||||||||||||||||
| 110 | 0 | my $uuid = create_uuid_as_string(); | |||||||||||||||||||
| 111 | 0 | ▶ | return $uuid unless -f $self->spool_dir . '/' . $uuid; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 112 | 0 | return $self->to_build_code; # If file exists, try again | |||||||||||||||||||
| 113 | } | ||||||||||||||||||||
| 114 | |||||||||||||||||||||
| 115 | =head1 METHODS | ||||||||||||||||||||
| 116 | |||||||||||||||||||||
| 117 | =head2 send_confirmation(subject_prefix = $subpfx, template => $template) | ||||||||||||||||||||
| 118 | |||||||||||||||||||||
| 119 | This process the text in template $template, replacing __CODE__ with | ||||||||||||||||||||
| 120 | $self->code, setting the subject to "$subpfx $self->code" and sending out the | ||||||||||||||||||||
| 121 | email to the address provided. | ||||||||||||||||||||
| 122 | |||||||||||||||||||||
| 123 | =cut | ||||||||||||||||||||
| 124 | |||||||||||||||||||||
| 125 | 0 | ▶ | sub send_confirmation { | ||||||||||||||||||
|
Subroutine
send_confirmation: not called CC=4 SCAR=30.0
Pod
documented
| |||||||||||||||||||||
| 126 | 0 | my $self = shift @_; | |||||||||||||||||||
| 127 | 0 | my %args = @_; | |||||||||||||||||||
| 128 | 0 | my $template = $args{template}; | |||||||||||||||||||
| 129 | 0 | ▶ | croak 'No template defined for email' unless $template; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 130 | 0 | my $code = $self->code; | |||||||||||||||||||
| 131 | 0 | $template =~ s/__CODE__/$code/g; | |||||||||||||||||||
| 132 | 0 | ▶ | my $return_path = $self->return_path || $self->from; | ||||||||||||||||||
|
Condition0%0/3
$self->return_path || $self->from
MC/DC0%0/2
$self->return_path || $self->from
$self->return_path
$self->from
Truth table0%0/3
A || B
A= $self->return_pathB= $self->from
| |||||||||||||||||||||
| 133 | 0 | ▶ | my $reply_to = $self->reply_to || $self->from; | ||||||||||||||||||
|
Condition0%0/3
$self->reply_to || $self->from
MC/DC0%0/2
$self->reply_to || $self->from
$self->reply_to
$self->from
Truth table0%0/3
A || B
A= $self->reply_toB= $self->from
| |||||||||||||||||||||
| 134 | 0 | my $email = Email::Simple->create( | |||||||||||||||||||
| 135 | header => [ | ||||||||||||||||||||
| 136 | To => $self->address, | ||||||||||||||||||||
| 137 | From => $self->from, | ||||||||||||||||||||
| 138 | "Reply-To" => $reply_to, | ||||||||||||||||||||
| 139 | 'Return-path' => $return_path | ||||||||||||||||||||
| 140 | ], | ||||||||||||||||||||
| 141 | body => $template, | ||||||||||||||||||||
| 142 | ); | ||||||||||||||||||||
| 143 | 0 | _spool($self); | |||||||||||||||||||
| 144 | 0 | return sendmail($email); | |||||||||||||||||||
| 145 | } | ||||||||||||||||||||
| 146 | |||||||||||||||||||||
| 147 | 0 | ▶ | sub _spool { | ||||||||||||||||||
|
Subroutine
_spool: not called CC=1 SCAR=6.9
| |||||||||||||||||||||
| 148 | 0 | my ($self) = @_; | |||||||||||||||||||
| 149 | 0 | my $spooldir = $self->spool_dir; | |||||||||||||||||||
| 150 | 0 | $spooldir =~ s|/+$||; # Get rid of trailing slashes | |||||||||||||||||||
| 151 | 0 | my $filename = $self->code; | |||||||||||||||||||
| 152 | 0 | my $json = encode_json($self->data); | |||||||||||||||||||
| 153 | 0 | write_file("$spooldir/$filename", {no_clobber => 1}, $json); | |||||||||||||||||||
| 154 | } | ||||||||||||||||||||
| 155 | |||||||||||||||||||||
| 156 | |||||||||||||||||||||
| 157 | =head2 get_data(code => $code, spool_dir => $directory) | ||||||||||||||||||||
| 158 | |||||||||||||||||||||
| 159 | This gets the data from spool_dir/directory and unlinks the file. | ||||||||||||||||||||
| 160 | |||||||||||||||||||||
| 161 | =cut | ||||||||||||||||||||
| 162 | |||||||||||||||||||||
| 163 | 0 | ▶ | sub get_data{ | ||||||||||||||||||
|
Subroutine
get_data: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||||||||||||
| 164 | 0 | my ($self) = shift @_; | |||||||||||||||||||
| 165 | 0 | my %args = @_; | |||||||||||||||||||
| 166 | 0 | my $spooldir = $args{spool_dir}; | |||||||||||||||||||
| 167 | 0 | ▶ | croak 'No Spool Dir provided' unless defined $spooldir; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 168 | 0 | $spooldir =~ s|/+$||; # Get rid of trailing slashes | |||||||||||||||||||
| 169 | 0 | my $filename = $args{code}; | |||||||||||||||||||
| 170 | 0 | my $json = read_file("$spooldir/$filename"); | |||||||||||||||||||
| 171 | 0 | unlink("$spooldir/$filename"); | |||||||||||||||||||
| 172 | 0 | return decode_json($json); | |||||||||||||||||||
| 173 | } | ||||||||||||||||||||
| 174 | |||||||||||||||||||||
| 175 | |||||||||||||||||||||
| 176 | =head1 AUTHOR | ||||||||||||||||||||
| 177 | |||||||||||||||||||||
| 178 | Chris Travers, C<< <chris.travers at gmail.com> >> | ||||||||||||||||||||
| 179 | |||||||||||||||||||||
| 180 | =head1 BUGS | ||||||||||||||||||||
| 181 | |||||||||||||||||||||
| 182 | Please report any bugs or feature requests to C<bug-mail-roundtrip at rt.cpan.org>, or through | ||||||||||||||||||||
| 183 | the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Mail-RoundTrip>. I will be notified, and then you'll | ||||||||||||||||||||
| 184 | automatically be notified of progress on your bug as I make changes. | ||||||||||||||||||||
| 185 | |||||||||||||||||||||
| 186 | |||||||||||||||||||||
| 187 | |||||||||||||||||||||
| 188 | |||||||||||||||||||||
| 189 | =head1 SUPPORT | ||||||||||||||||||||
| 190 | |||||||||||||||||||||
| 191 | You can find documentation for this module with the perldoc command. | ||||||||||||||||||||
| 192 | |||||||||||||||||||||
| 193 | perldoc Mail::RoundTrip | ||||||||||||||||||||
| 194 | |||||||||||||||||||||
| 195 | |||||||||||||||||||||
| 196 | You can also look for information at: | ||||||||||||||||||||
| 197 | |||||||||||||||||||||
| 198 | =over 4 | ||||||||||||||||||||
| 199 | |||||||||||||||||||||
| 200 | =item * RT: CPAN's request tracker (report bugs here) | ||||||||||||||||||||
| 201 | |||||||||||||||||||||
| 202 | L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Mail-RoundTrip> | ||||||||||||||||||||
| 203 | |||||||||||||||||||||
| 204 | =item * AnnoCPAN: Annotated CPAN documentation | ||||||||||||||||||||
| 205 | |||||||||||||||||||||
| 206 | L<http://annocpan.org/dist/Mail-RoundTrip> | ||||||||||||||||||||
| 207 | |||||||||||||||||||||
| 208 | =item * CPAN Ratings | ||||||||||||||||||||
| 209 | |||||||||||||||||||||
| 210 | L<http://cpanratings.perl.org/d/Mail-RoundTrip> | ||||||||||||||||||||
| 211 | |||||||||||||||||||||
| 212 | =item * Search CPAN | ||||||||||||||||||||
| 213 | |||||||||||||||||||||
| 214 | L<http://search.cpan.org/dist/Mail-RoundTrip/> | ||||||||||||||||||||
| 215 | |||||||||||||||||||||
| 216 | =back | ||||||||||||||||||||
| 217 | |||||||||||||||||||||
| 218 | |||||||||||||||||||||
| 219 | =head1 ACKNOWLEDGEMENTS | ||||||||||||||||||||
| 220 | |||||||||||||||||||||
| 221 | |||||||||||||||||||||
| 222 | =head1 LICENSE AND COPYRIGHT | ||||||||||||||||||||
| 223 | |||||||||||||||||||||
| 224 | Copyright 2013 Chris Travers. | ||||||||||||||||||||
| 225 | |||||||||||||||||||||
| 226 | This program is released under the following license: BSD | ||||||||||||||||||||
| 227 | |||||||||||||||||||||
| 228 | |||||||||||||||||||||
| 229 | =cut | ||||||||||||||||||||
| 230 | |||||||||||||||||||||
| 231 | 3 | 1; # End of Mail::RoundTrip | |||||||||||||||||||