blib/lib/Mail/RoundTrip.pm

filter: Statementstmt 57.7% 41 / 71 Branchbran 0.0% 0 / 6 Conditioncond 0.0% 0 / 6 MC/DCmcdc 0.0% 0 / 4 Subroutinesub 73.3% 11 / 15 Podpod 100% 2 / 2 totaltotal 51.9% 54 / 104 CC 6 SCAR 17.7
CC
6
Cov
49%
send_confirmation
20.0
_build_code
6.0
get_data
6.0
CRAP 5.8
↑ Summary
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
BranchTrueFalseTotal
unless -f $self->spool_dir . '/' . $uuid 0 0 0
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
BranchTrueFalseTotal
unless $template 0 0 0
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
l!l&&r!l&&!r
000
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
ABresult
1X1
011
000
133 0 ▶ my $reply_to = $self->reply_to || $self->from;
Condition0%0/3
$self->reply_to || $self->from
l!l&&r!l&&!r
000
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
ABresult
1X1
011
000
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
BranchTrueFalseTotal
unless defined $spooldir 0 0 0
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
↑ Summary