diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/mailman/rest/docs/sub-moderation.rst | 113 | ||||
| -rw-r--r-- | src/mailman/rest/sub_moderation.py | 155 |
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']) |