From 5b17dd8c6c9d149a00ee9895abe7a76150d6e55f Mon Sep 17 00:00:00 2001 From: dakkar Date: Sun, 5 Feb 2017 13:59:43 +0000 Subject: POD for some roles --- lib/Sietima/Role/AvoidDups.pm | 17 +++++++++++++++ lib/Sietima/Role/Debounce.pm | 18 ++++++++++++++++ lib/Sietima/Role/Headers.pm | 42 ++++++++++++++++++++++++++++++++++++ lib/Sietima/Role/NoMail.pm | 22 +++++++++++++++++++ lib/Sietima/Role/ReplyTo.pm | 50 +++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 149 insertions(+) (limited to 'lib') 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 >> list with this role applied will not send a +message to a subscriber, if that subscriber is already mentioned in +the C or C 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 >> list with this role applied will mark each message +with a C 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 >> 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|Sietima/list_addresses >> +method to determine what headers to add. + +If the C attribute is set, a C 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|Sietima/return_path >> attribute). + +Other C headers are built from the other values in the +C hashref. Those values can either be L<< +C >> objects (in which case the header will have a +C URI as value) or strings (which will be used literally for +the value of the header). + +=head1 ATTRIBUTES + +=head2 C + +Optional string, the name of the mailing list. If this attribute is +set, a C 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|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 >> list with this role applied will not send messages +to subscribers that have the C 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 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 >> list with this role applied will, on request, set +the C header to the value of the L<< /C >> +attribute. + +This behaviour can be selected both at the list level (with the L<< +/C >> attribute) and at the subscriber level (with the +C preference). By default, the C header is +not touched. + +=head1 ATTRIBUTES + +=head2 C + +Optional boolean, defaults to false. If set to a true value, all +messages will have their C header set to the value of the +L<< /C >> attribute. This setting can be overridden by +individual subscribers with the C preference. + +=cut + has munge_reply_to => ( is => 'ro', isa => Bool, default => 0, ); +=head2 C + +An L<< C >> object, defaults to the value of the L<< +C|Sietima/return_path >> attribute. This is the address +that the mailing list receives messages at. + +This role extends the L<< C|Sietima/list_addresses >> +method to include this address. + +=cut + has post_address => ( is => 'lazy', isa => Address, -- cgit v1.2.3