diff options
author | dakkar <dakkar@thenautilus.net> | 2017-02-05 13:59:43 +0000 |
---|---|---|
committer | dakkar <dakkar@thenautilus.net> | 2017-02-05 13:59:43 +0000 |
commit | 5b17dd8c6c9d149a00ee9895abe7a76150d6e55f (patch) | |
tree | 890c13d468d2efc573efcda16c76b2f1b645a8dd | |
parent | ::Subscriber 'raw_address' is now 'primary' (diff) | |
download | Sietima-5b17dd8c6c9d149a00ee9895abe7a76150d6e55f.tar.gz Sietima-5b17dd8c6c9d149a00ee9895abe7a76150d6e55f.tar.bz2 Sietima-5b17dd8c6c9d149a00ee9895abe7a76150d6e55f.zip |
POD for some roles
-rw-r--r-- | lib/Sietima/Role/AvoidDups.pm | 17 | ||||
-rw-r--r-- | lib/Sietima/Role/Debounce.pm | 18 | ||||
-rw-r--r-- | lib/Sietima/Role/Headers.pm | 42 | ||||
-rw-r--r-- | lib/Sietima/Role/NoMail.pm | 22 | ||||
-rw-r--r-- | lib/Sietima/Role/ReplyTo.pm | 50 |
5 files changed, 149 insertions, 0 deletions
diff --git a/lib/Sietima/Role/AvoidDups.pm b/lib/Sietima/Role/AvoidDups.pm index 598d57b..964c413 100644 --- a/lib/Sietima/Role/AvoidDups.pm +++ b/lib/Sietima/Role/AvoidDups.pm @@ -4,6 +4,23 @@ use Sietima::Policy; use Email::Address; use namespace::clean; +=head1 NAME + +Sietima::Role::AvoidDups - prevent people from receiving the same message multiple times + +=head1 SYNOPSIS + + my $sietima = Sietima->with_traits('AvoidDups')->new(\%args); + +=head1 DESCRIPTION + +A L<< C<Sietima> >> list with this role applied will not send a +message to a subscriber, if that subscriber is already mentioned in +the C<To:> or C<Cc:> header fields, because they can be assumed to be +already receiving the message directly from the sender. + +=cut + around subscribers_to_send_to => sub ($orig,$self,$mail) { my @already_receiving = map { Email::Address->parse($_) diff --git a/lib/Sietima/Role/Debounce.pm b/lib/Sietima/Role/Debounce.pm index 8df53a5..882d982 100644 --- a/lib/Sietima/Role/Debounce.pm +++ b/lib/Sietima/Role/Debounce.pm @@ -3,6 +3,24 @@ use Moo::Role; use Sietima::Policy; use namespace::clean; +=head1 NAME + +Sietima::Role::Debounce - avoid mail loops + +=head1 SYNOPSIS + + my $sietima = Sietima->with_traits('Debounce')->new(\%args); + +=head1 DESCRIPTION + +A L<< C<Sietima> >> list with this role applied will mark each message +with a C<X-Been-There> header, and will not handle any messages that +have that same header. This prevents messages bounced by other +services from being looped between the mailing list and those other +services. + +=cut + my $been_there = 'X-Been-There'; around munge_mail => sub ($orig,$self,$incoming_mail) { diff --git a/lib/Sietima/Role/Headers.pm b/lib/Sietima/Role/Headers.pm index 3a91c6f..f73db93 100644 --- a/lib/Sietima/Role/Headers.pm +++ b/lib/Sietima/Role/Headers.pm @@ -5,6 +5,48 @@ use Sietima::Policy; use Types::Standard qw(Str); use namespace::clean; +=head1 NAME + +Sietima::Role::Headers - adds standard list-related headers to messages + +=head1 SYNOPSIS + + my $sietima = Sietima->with_traits('Headers')->new({ + %args, + name => $name_of_the_list, + }); + +=head1 DESCRIPTION + +A L<< C<Sietima> >> list with this role applied will add, to each +outgoing message, the set of headers defined in RFC 2919 and RFC 2369. + +This role uses the L<< C<list_addresses>|Sietima/list_addresses >> +method to determine what headers to add. + +If the C<name> attribute is set, a C<List-Id:> header will be added, +with a value built out of the name and the C<< +$self->list_addresses->{return_path} >> value (which is normally the +same as the L<< C<return_path>|Sietima/return_path >> attribute). + +Other C<List-*:> headers are built from the other values in the +C<list_addresses> hashref. Those values can either be L<< +C<Email::Address> >> objects (in which case the header will have a +C<mailto:> URI as value) or strings (which will be used literally for +the value of the header). + +=head1 ATTRIBUTES + +=head2 C<name> + +Optional string, the name of the mailing list. If this attribute is +set, a C<List-Id:> header will be added, with a value built out of the +name and the C<< $self->list_addresses->{return_path} >> value (which +is normally the same as the L<< C<return_path>|Sietima/return_path >> +attribute). + +=cut + has name => ( isa => Str, is => 'ro', diff --git a/lib/Sietima/Role/NoMail.pm b/lib/Sietima/Role/NoMail.pm index 84d7d9b..5f6dd77 100644 --- a/lib/Sietima/Role/NoMail.pm +++ b/lib/Sietima/Role/NoMail.pm @@ -3,6 +3,28 @@ use Moo::Role; use Sietima::Policy; use namespace::clean; +=head1 NAME + +Sietima::Role::NoMail - don't send mail to those who don't want it + +=head1 SYNOPSIS + + my $sietima = Sietima->with_traits('NoMail')->new({ + %args, + subscribers => [ + { primary => 'write-only@example.com', prefs => { wants_mail => 0 } }, + @other_subscribers, + ], + }); + +=head1 DESCRIPTION + +A L<< C<Sietima> >> list with this role applied will not send messages +to subscribers that have the C<wants_mail> preference set to a false +value. + +=cut + around subscribers_to_send_to => sub ($orig,$self,$mail) { return [ grep { $_->prefs->{wants_mail} // 1 } diff --git a/lib/Sietima/Role/ReplyTo.pm b/lib/Sietima/Role/ReplyTo.pm index 583b1de..5962451 100644 --- a/lib/Sietima/Role/ReplyTo.pm +++ b/lib/Sietima/Role/ReplyTo.pm @@ -6,12 +6,62 @@ use Sietima::Types qw(Address AddressFromStr); use List::AllUtils qw(part); use namespace::clean; +=head1 NAME + +Sietima::Role::ReplyTo - munge the C<Reply-To> header + +=head1 SYNOPSIS + + my $sietima = Sietima->with_traits('ReplyTo')->new({ + %args, + return_path => 'list-bounce@example.com', + munge_reply_to => 1, + post_address => 'list@example.com', + subscribers => [ + { primary => 'special@example.com', prefs => { munge_reply_to => 0 } }, + @other_subscribers, + ], + }); + +=head1 DESCRIPTION + +A L<< C<Sietima> >> list with this role applied will, on request, set +the C<Reply-To:> header to the value of the L<< /C<post_address> >> +attribute. + +This behaviour can be selected both at the list level (with the L<< +/C<munge_reply_to> >> attribute) and at the subscriber level (with the +C<munge_reply_to> preference). By default, the C<Reply-To:> header is +not touched. + +=head1 ATTRIBUTES + +=head2 C<munge_reply_to> + +Optional boolean, defaults to false. If set to a true value, all +messages will have their C<Reply-To:> header set to the value of the +L<< /C<post_address> >> attribute. This setting can be overridden by +individual subscribers with the C<munge_reply_to> preference. + +=cut + has munge_reply_to => ( is => 'ro', isa => Bool, default => 0, ); +=head2 C<post_address> + +An L<< C<Email::Address> >> object, defaults to the value of the L<< +C<return_path>|Sietima/return_path >> attribute. This is the address +that the mailing list receives messages at. + +This role extends the L<< C<list_addresses>|Sietima/list_addresses >> +method to include this address. + +=cut + has post_address => ( is => 'lazy', isa => Address, |