2 files changed, 268 insertions, 0 deletions

diff --git a/src/mailman/rest/docs/sub-moderation.rst b/src/mailman/rest/docs/sub-moderation.rst
new file mode 100644
index 000000000..6d3d4993c
--- /dev/null
+++ b/src/mailman/rest/docs/sub-moderation.rst
@@ -0,0 +1,113 @@
+=========================
+ Subscription moderation
+=========================
+
+Subscription (and sometimes unsubscription) requests can similarly be
+accepted, discarded, rejected, or deferred by the list moderators.
+
+
+Viewing subscription requests
+=============================
+
+A mailing list starts with no pending subscription or unsubscription requests.
+
+    >>> ant = create_list('ant@example.com')
+    >>> ant.admin_immed_notify = False
+    >>> from mailman.interfaces.mailinglist import SubscriptionPolicy
+    >>> ant.subscription_policy = SubscriptionPolicy.moderate
+    >>> transaction.commit()
+    >>> dump_json('http://localhost:9001/3.0/lists/ant@example.com/requests')
+    http_etag: "..."
+    start: 0
+    total_size: 0
+
+When Anne tries to subscribe to the Ant list, her subscription is held for
+moderator approval.
+
+    >>> from mailman.interfaces.registrar import IRegistrar
+    >>> from mailman.interfaces.usermanager import IUserManager
+    >>> from zope.component import getUtility
+    >>> registrar = IRegistrar(ant)
+    >>> manager = getUtility(IUserManager)
+    >>> anne = manager.create_address('anne@example.com', 'Anne Person')
+    >>> token, token_owner, member = registrar.register(
+    ...     anne, pre_verified=True, pre_confirmed=True)
+    >>> print(member)
+    None
+
+The message is being held for moderator approval.
+
+    >>> token_owner.name
+    TokenOwner.moderator
+
+The subscription request can be viewed in the REST API.
+
+    >>> dump_json('http://localhost:9001/3.0/lists/ant@example.com/requests')
+    entry 0:
+        delivery_mode: regular
+        display_name: Anne Person
+        email: anne@example.com
+        http_etag: "..."
+        language: en
+        request_id: ...
+        type: subscription
+        when: 2005-08-01T07:49:23
+    http_etag: "..."
+    start: 0
+    total_size: 1
+
+
+Viewing individual requests
+===========================
+
+You can view an individual membership change request by providing the token
+(a.k.a. request id).  Anne's subscription request looks like this.
+
+    >>> dump_json('http://localhost:9001/3.0/lists/ant@example.com/'
+    ...           'requests/{}'.format(token))
+    delivery_mode: regular
+    display_name: Anne Person
+    email: anne@example.com
+    http_etag: "..."
+    language: en
+    request_id: ...
+    type: subscription
+    when: 2005-08-01T07:49:23
+
+
+Disposing of subscription requests
+==================================
+
+Moderators can dispose of held subscription requests by POSTing back to the
+request's resource.  The POST data requires an action of one of the following:
+
+ * discard - throw the request away.
+ * reject - the request is denied and a notification is sent to the email
+            address requesting the membership change.
+ * defer - defer any action on this membership change (continue to hold it).
+ * accept - accept the membership change.
+
+Anne's subscription request is accepted.
+
+    >>> dump_json('http://localhost:9001/3.0/lists/'
+    ...           'ant@example.com/requests/{}'.format(token),
+    ...           {'action': 'accept'})
+    content-length: 0
+    date: ...
+    server: ...
+    status: 204
+
+Anne is now a member of the mailing list.
+
+    >>> transaction.abort()
+    >>> ant.members.get_member('anne@example.com')
+    <Member: Anne Person <anne@example.com> on ant@example.com
+             as MemberRole.member>
+    >>> transaction.abort()
+
+There are no more membership change requests.
+
+    >>> dump_json('http://localhost:9001/3.0/lists/ant@example.com/requests')
+    http_etag: "..."
+    start: 0
+    total_size: 0
diff --git a/src/mailman/rest/sub_moderation.py b/src/mailman/rest/sub_moderation.py
new file mode 100644
index 000000000..4f8cf2e8e
--- /dev/null
+++ b/src/mailman/rest/sub_moderation.py
@@ -0,0 +1,155 @@
+# Copyright (C) 2012-2015 by the Free Software Foundation, Inc.
+#
+# This file is part of GNU Mailman.
+#
+# GNU Mailman is free software: you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option)
+# any later version.
+#
+# GNU Mailman is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+# more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Mailman.  If not, see <http://www.gnu.org/licenses/>.
+
+"""REST API for held subscription requests."""
+
+__all__ = [
+    'SubscriptionRequests',
+    ]
+
+
+from mailman.interfaces.action import Action
+from mailman.interfaces.pending import IPendings
+from mailman.interfaces.registrar import IRegistrar
+from mailman.rest.helpers import (
+    CollectionMixin, bad_request, child, etag, no_content, not_found, okay)
+from mailman.rest.validator import Validator, enum_validator
+from zope.component import getUtility
+
+
+
+class _ModerationBase:
+    """Common base class."""
+
+    def _make_resource(self, token):
+        requests = IListRequests(self._mlist)
+        results = requests.get_request(request_id)
+        if results is None:
+            return None
+        key, data = results
+        resource = dict(key=key, request_id=request_id)
+        # Flatten the IRequest payload into the JSON representation.
+        resource.update(data)
+        # Check for a matching request type, and insert the type name into the
+        # resource.
+        request_type = RequestType[resource.pop('_request_type')]
+        if request_type not in expected_request_types:
+            return None
+        resource['type'] = request_type.name
+        # This key isn't what you think it is.  Usually, it's the Pendable
+        # record's row id, which isn't helpful at all.  If it's not there,
+        # that's fine too.
+        resource.pop('id', None)
+        return resource
+
+
+
+class IndividualRequest(_ModerationBase):
+    """Resource for moderating a membership change."""
+
+    def __init__(self, mlist, token):
+        self._mlist = mlist
+        self._registrar = IRegistrar(self._mlist)
+        self._token = token
+
+    def on_get(self, request, response):
+        try:
+            token, token_owner, member = self._registrar.confirm(self._token)
+        except LookupError:
+            not_found(response)
+            return
+        try:
+            request_id = int(self._request_id)
+        except ValueError:
+            bad_request(response)
+            return
+        resource = self._make_resource(request_id, MEMBERSHIP_CHANGE_REQUESTS)
+        if resource is None:
+            not_found(response)
+        else:
+            # Remove unnecessary keys.
+            del resource['key']
+            okay(response, etag(resource))
+
+    def on_post(self, request, response):
+        try:
+            validator = Validator(action=enum_validator(Action))
+            arguments = validator(request)
+        except ValueError as error:
+            bad_request(response, str(error))
+            return
+        requests = IListRequests(self._mlist)
+        try:
+            request_id = int(self._request_id)
+        except ValueError:
+            bad_request(response)
+            return
+        results = requests.get_request(request_id)
+        if results is None:
+            not_found(response)
+            return
+        key, data = results
+        try:
+            request_type = RequestType[data['_request_type']]
+        except ValueError:
+            bad_request(response)
+            return
+        if request_type is RequestType.subscription:
+            handle_subscription(self._mlist, request_id, **arguments)
+        elif request_type is RequestType.unsubscription:
+            handle_unsubscription(self._mlist, request_id, **arguments)
+        else:
+            bad_request(response)
+            return
+        no_content(response)
+
+
+class SubscriptionRequests(_ModerationBase, CollectionMixin):
+    """Resource for membership change requests."""
+
+    def __init__(self, mlist):
+        self._mlist = mlist
+
+    def _resource_as_dict(self, request):
+        """See `CollectionMixin`."""
+        resource = self._make_resource(request.id, MEMBERSHIP_CHANGE_REQUESTS)
+        # Remove unnecessary keys.
+        del resource['key']
+        return resource
+
+    def _get_collection(self, request):
+        # There's currently no better way to query the pendings database for
+        # all the entries that are associated with subscription holds on this
+        # mailing list.  Brute force for now.
+        items = []
+        for token, pendable in getUtility(IPendings):
+            token_owner = pendable.get('token_owner')
+            if token_owner is None:
+                continue
+            item = dict(token=token)
+            item.update(pendable)
+            items.append(item)
+        return items
+
+    def on_get(self, request, response):
+        """/lists/listname/requests"""
+        resource = self._make_collection(request)
+        okay(response, etag(resource))
+
+    @child(r'^(?P<token>[^/]+)')
+    def subscription(self, request, segments, **kw):
+        return IndividualRequest(self._mlist, kw['token'])