aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authordakkar <dakkar@thenautilus.net>2017-02-05 13:59:43 +0000
committerdakkar <dakkar@thenautilus.net>2017-02-05 13:59:43 +0000
commit5b17dd8c6c9d149a00ee9895abe7a76150d6e55f (patch)
tree890c13d468d2efc573efcda16c76b2f1b645a8dd
parent::Subscriber 'raw_address' is now 'primary' (diff)
downloadSietima-5b17dd8c6c9d149a00ee9895abe7a76150d6e55f.tar.gz
Sietima-5b17dd8c6c9d149a00ee9895abe7a76150d6e55f.tar.bz2
Sietima-5b17dd8c6c9d149a00ee9895abe7a76150d6e55f.zip
POD for some roles
-rw-r--r--lib/Sietima/Role/AvoidDups.pm17
-rw-r--r--lib/Sietima/Role/Debounce.pm18
-rw-r--r--lib/Sietima/Role/Headers.pm42
-rw-r--r--lib/Sietima/Role/NoMail.pm22
-rw-r--r--lib/Sietima/Role/ReplyTo.pm50
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,