1# -*- indent-tabs-mode: nil; -*-
2# vim:ft=perl:et:sw=4
3# $Id$
4
5# Sympa - SYsteme de Multi-Postage Automatique
6#
7# Copyright (c) 1997, 1998, 1999 Institut Pasteur & Christophe Wolfhugel
8# Copyright (c) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
9# 2006, 2007, 2008, 2009, 2010, 2011 Comite Reseau des Universites
10# Copyright (c) 2011, 2012, 2013, 2014, 2015, 2016, 2017 GIP RENATER
11# Copyright 2017, 2020 The Sympa Community. See the AUTHORS.md
12# file at the top-level directory of this distribution and at
13# <https://github.com/sympa-community/sympa.git>.
14#
15# This program is free software; you can redistribute it and/or modify
16# it under the terms of the GNU General Public License as published by
17# the Free Software Foundation; either version 2 of the License, or
18# (at your option) any later version.
19#
20# This program is distributed in the hope that it will be useful,
21# but WITHOUT ANY WARRANTY; without even the implied warranty of
22# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
23# GNU General Public License for more details.
24#
25# You should have received a copy of the GNU General Public License
26# along with this program.  If not, see <http://www.gnu.org/licenses/>.
27
28package Sympa::Spool::Auth;
29
30use strict;
31use warnings;
32
33use Conf;
34use Sympa::Tools::Text;
35
36use base qw(Sympa::Spool);
37
38sub _directories {
39    return {directory => $Conf::Conf{'queuesubscribe'},};
40}
41
42sub _filter {
43    my $self     = shift;
44    my $metadata = shift;
45
46    # Decode e-mail.
47    $metadata->{email} =
48        Sympa::Tools::Text::decode_filesystem_safe($metadata->{email})
49        if $metadata and $metadata->{email};
50
51    1;
52}
53
54sub _filter_pre {
55    my $self     = shift;
56    my $metadata = shift;
57
58    # Encode e-mail.
59    $metadata->{email} =
60        Sympa::Tools::Text::encode_filesystem_safe($metadata->{email})
61        if $metadata and $metadata->{email};
62
63    1;
64}
65
66use constant _generator => 'Sympa::Request';
67
68use constant _marshal_format => '%ld,%s@%s_%s,%s,%s';
69use constant _marshal_keys =>
70    [qw(date localpart domainpart KEYAUTH email action)];
71use constant _marshal_regexp =>
72    qr{\A(\d+),(\@?[^\s\@]+)\@([-.\w]+)_([\da-f]+),([^\s,]*),(\w+)\z};
73use constant _store_key => 'keyauth';
74
751;
76__END__
77
78=encoding utf-8
79
80=head1 NAME
81
82Sympa::Spool::Auth - Spool for held requests waiting for moderation
83
84=head1 SYNOPSIS
85
86  use Sympa::Spool::Auth;
87
88  my $spool = Sympa::Spool::Auth->new;
89  my $request = Sympa::Request->new(...);
90  $spool->store($request);
91
92  my $spool = Sympa::Spool::Auth->new(
93      context => $list, action => 'add');
94  my $size = $spool->size;
95
96  my $spool = Sympa::Spool::Auth->new(
97      context => $list, keyauth => $id, action => 'add');
98  my ($request, $handle) = $spool->next;
99
100  $spool->remove($handle);
101
102=head1 DESCRIPTION
103
104L<Sympa::Spool::Auth> implements the spool for held requests waiting
105for moderation.
106
107=head2 Methods
108
109See also L<Sympa::Spool/"Public methods">.
110
111=over
112
113=item new ( [ context =E<gt> $that ], [ action =E<gt> $action ],
114[ keyauth =E<gt> $id ], [ email =E<gt> $email ])
115
116Context may be either instance of L<Sympa::List> or L<Sympa::Family>,
117or robot.
118
119=item next ( [ no_lock =E<gt> 1 ] )
120
121If the pairs describing metadatas are specified,
122contents returned by next() are filtered by them.
123
124Order of items returned by next() is controlled by time of submission.
125
126=item quarantine ( )
127
128Does nothing.
129
130=back
131
132=head2 Context and metadata
133
134See also L<Sympa::Spool/"Marshaling and unmarshaling metadata">.
135
136This class particularly gives following metadata:
137
138=over
139
140=item {action}
141
142Action requested.
143C<'add'> etc.
144
145=item {date}
146
147Unix time when the request was submitted.
148
149=item {email}
150
151E-mail of user who submitted the request, or target e-mail of the request.
152
153=item {keyauth}
154
155Authentication key generated automatically
156when the request is stored to spool.
157
158=back
159
160=head1 CONFIGURATION PARAMETERS
161
162Following site configuration parameters in sympa.conf will be referred.
163
164=over
165
166=item queuesubscribe
167
168Directory path of held request spool.
169
170Note:
171Named such by historical reason.
172
173=back
174
175=head1 SEE ALSO
176
177L<sympa_msg(8)>, L<wwsympa(8)>,
178L<Sympa::Request>, L<Sympa::Spool>.
179
180=head1 HISTORY
181
182L<Sympa::Spool::Request> appeared on Sympa 6.2.10.
183It was renamed to L<Sympa::Spool::Auth> on Sympa 6.2.13.
184
185=cut
186