diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/mailman/app/docs/moderator.rst | 458 | ||||
| -rw-r--r-- | src/mailman/app/membership.py | 2 | ||||
| -rw-r--r-- | src/mailman/app/tests/test_moderation.py | 46 | ||||
| -rw-r--r-- | src/mailman/model/docs/requests.rst | 873 | ||||
| -rw-r--r-- | src/mailman/model/tests/test_requests.py | 21 | ||||
| -rw-r--r-- | src/mailman/rest/moderation.py | 25 | ||||
| -rw-r--r-- | src/mailman/rest/tests/test_moderation.py | 2 |
7 files changed, 603 insertions, 824 deletions
diff --git a/src/mailman/app/docs/moderator.rst b/src/mailman/app/docs/moderator.rst new file mode 100644 index 000000000..f5d9e93cf --- /dev/null +++ b/src/mailman/app/docs/moderator.rst @@ -0,0 +1,458 @@ +.. app-moderator: + +============================ +Application level moderation +============================ + +At an application level, moderation involves holding messages and membership +changes for moderator approval. This utilizes the :ref:`lower level interface +<model-request>` for list-centric moderation requests. + +Moderation is always mailing list-centric. + + >>> mlist = create_list('ant@example.com') + >>> mlist.preferred_language = 'en' + >>> mlist.display_name = 'A Test List' + +We'll use the lower level API for diagnostic purposes. + + >>> from mailman.interfaces.requests import IListRequests + >>> requests = IListRequests(mlist) + + +Message moderation +================== + +Holding messages +---------------- + +Anne posts a message to the mailing list, but she is not a member of the list, +so the message is held for moderator approval. + + >>> msg = message_from_string("""\ + ... From: anne@example.org + ... To: ant@example.com + ... Subject: Something important + ... Message-ID: <aardvark> + ... + ... Here's something important about our mailing list. + ... """) + +*Holding a message* means keeping a copy of it that a moderator must approve +before the message is posted to the mailing list. To hold the message, the +message, its metadata, and a reason for the hold must be provided. In this +case, we won't include any additional metadata. + + >>> from mailman.app.moderator import hold_message + >>> hold_message(mlist, msg, {}, 'Needs approval') + 1 + +We can also hold a message with some additional metadata. +:: + + >>> msg = message_from_string("""\ + ... From: bart@example.org + ... To: ant@example.com + ... Subject: Something important + ... Message-ID: <badger> + ... + ... Here's something important about our mailing list. + ... """) + >>> msgdata = dict(sender='anne@example.com', approved=True) + + >>> hold_message(mlist, msg, msgdata, 'Feeling ornery') + 2 + + +Disposing of messages +--------------------- + +The moderator can select one of several dispositions: + + * discard - throw the message away. + * reject - bounces the message back to the original author. + * defer - defer any action on the message (continue to hold it) + * accept - accept the message for posting. + + +The most trivial is to simply defer a decision for now. + + >>> from mailman.interfaces.action import Action + >>> from mailman.app.moderator import handle_message + >>> handle_message(mlist, 1, Action.defer) + +This leaves the message in the requests database. + + >>> key, data = requests.get_request(1) + >>> print key + <aardvark> + +The moderator can also discard the message. + + >>> handle_message(mlist, 1, Action.discard) + >>> print requests.get_request(1) + None + +The message can be rejected, which bounces the message back to the original +sender. + + >>> handle_message(mlist, 2, Action.reject, 'Off topic') + +The message is no longer available in the requests database. + + >>> print requests.get_request(2) + None + +And there is one message in the *virgin* queue - the bounce. + + >>> from mailman.testing.helpers import get_queue_messages + >>> messages = get_queue_messages('virgin') + >>> len(messages) + 1 + >>> print messages[0].msg.as_string() + MIME-Version: 1.0 + ... + Subject: Request to mailing list "A Test List" rejected + From: ant-bounces@example.com + To: bart@example.org + ... + <BLANKLINE> + Your request to the ant@example.com mailing list + <BLANKLINE> + Posting of your message titled "Something important" + <BLANKLINE> + has been rejected by the list moderator. The moderator gave the + following reason for rejecting your request: + <BLANKLINE> + "Off topic" + <BLANKLINE> + Any questions or comments should be directed to the list administrator + at: + <BLANKLINE> + ant-owner@example.com + <BLANKLINE> + +The bounce gets sent to the original sender. + + >>> for recipient in sorted(messages[0].msgdata['recipients']): + ... print recipient + bart@example.org + +Or the message can be approved. + + >>> msg = message_from_string("""\ + ... From: cate@example.org + ... To: ant@example.com + ... Subject: Something important + ... Message-ID: <caribou> + ... + ... Here's something important about our mailing list. + ... """) + >>> id = hold_message(mlist, msg, {}, 'Needs approval') + >>> handle_message(mlist, id, Action.accept) + +This places the message back into the incoming queue for further processing, +however the message metadata indicates that the message has been approved. +:: + + >>> messages = get_queue_messages('pipeline') + >>> len(messages) + 1 + >>> print messages[0].msg.as_string() + From: cate@example.org + To: ant@example.com + Subject: Something important + ... + + >>> dump_msgdata(messages[0].msgdata) + _parsemsg : False + approved : True + moderator_approved: True + version : 3 + + +Preserving and forwarding the message +------------------------------------- + +In addition to any of the above dispositions, the message can also be +preserved for further study. Ordinarily the message is removed from the +global message store after its disposition (though approved messages may be +re-added to the message store later). When handling a message, we can ask for +a copy to be preserve, which skips deleting the message from the storage. +:: + + >>> msg = message_from_string("""\ + ... From: dave@example.org + ... To: ant@example.com + ... Subject: Something important + ... Message-ID: <dolphin> + ... + ... Here's something important about our mailing list. + ... """) + >>> id = hold_message(mlist, msg, {}, 'Needs approval') + >>> handle_message(mlist, id, Action.discard, preserve=True) + + >>> from mailman.interfaces.messages import IMessageStore + >>> from zope.component import getUtility + >>> message_store = getUtility(IMessageStore) + >>> preserved_message = getUtility(IMessageStore).get_message_by_id( + ... '<dolphin>') + >>> print preserved_message['message-id'] + <dolphin> + +Orthogonal to preservation, the message can also be forwarded to another +address. This is helpful for getting the message into the inbox of one of the +moderators. +:: + + >>> msg = message_from_string("""\ + ... From: elly@example.org + ... To: ant@example.com + ... Subject: Something important + ... Message-ID: <elephant> + ... + ... Here's something important about our mailing list. + ... """) + >>> id = hold_message(mlist, msg, {}, 'Needs approval') + >>> handle_message(mlist, id, Action.discard, forward=['zack@example.com']) + +The forwarded message is in the virgin queue, destined for the moderator. +:: + + >>> messages = get_queue_messages('virgin') + >>> len(messages) + 1 + >>> print messages[0].msg.as_string() + Subject: Forward of moderated message + From: ant-bounces@example.com + To: zack@example.com + ... + + >>> for recipient in sorted(messages[0].msgdata['recipients']): + ... print recipient + zack@example.com + + +Holding subscription requests +============================= + +For closed lists, subscription requests will also be held for moderator +approval. In this case, several pieces of information related to the +subscription must be provided, including the subscriber's address and real +name, their password (possibly hashed), what kind of delivery option they are +choosing and their preferred language. + + >>> from mailman.app.moderator import hold_subscription + >>> from mailman.interfaces.member import DeliveryMode + >>> mlist.admin_immed_notify = False + >>> hold_subscription(mlist, + ... 'fred@example.org', 'Fred Person', + ... '{NONE}abcxyz', DeliveryMode.regular, 'en') + 2 + +In the above case the mailing list was not configured to send the list +moderators a notice about the hold, so no email message is in the virgin +queue. + + >>> get_queue_messages('virgin') + [] + +But if we set the list up to notify the list moderators immediately when a +message is held for approval, there will be a message placed in the virgin +queue when the message is held. +:: + + >>> mlist.admin_immed_notify = True + >>> hold_subscription(mlist, + ... 'gwen@example.org', 'Gwen Person', + ... '{NONE}zyxcba', DeliveryMode.regular, 'en') + 3 + + >>> messages = get_queue_messages('virgin') + >>> len(messages) + 1 + + >>> print messages[0].msg.as_string() + MIME-Version: 1.0 + ... + Subject: New subscription request to A Test List from gwen@example.org + ... + <BLANKLINE> + Your authorization is required for a mailing list subscription request + approval: + <BLANKLINE> + For: gwen@example.org + List: ant@example.com + ... + + +Disposing of membership change requests +--------------------------------------- + +Just as with held messages, the moderator can select one of several +dispositions for this membership change request. The most trivial is to +simply defer a decision for now. + + >>> from mailman.app.moderator import handle_subscription + >>> handle_subscription(mlist, 2, Action.defer) + >>> requests.get_request(2) is not None + True + +The held subscription can also be discarded. + + >>> handle_subscription(mlist, 2, Action.discard) + >>> print requests.get_request(2) + None + +The request can be rejected, in which case a message is sent to the +subscriber. +:: + + >>> handle_subscription(mlist, 3, Action.reject, + ... 'This is a closed list') + >>> messages = get_queue_messages('virgin') + >>> len(messages) + 1 + + >>> print messages[0].msg.as_string() + MIME-Version: 1.0 + ... + Subject: Request to mailing list "A Test List" rejected + From: ant-bounces@example.com + To: gwen@example.org + ... + Your request to the ant@example.com mailing list + <BLANKLINE> + Subscription request + <BLANKLINE> + has been rejected by the list moderator. The moderator gave the + following reason for rejecting your request: + <BLANKLINE> + "This is a closed list" + ... + +The subscription can also be accepted. This subscribes the address to the +mailing list. + + >>> mlist.send_welcome_message = False + >>> hold_subscription(mlist, + ... 'herb@example.org', 'Herb Person', + ... 'abcxyz', DeliveryMode.regular, 'en') + 2 + +A message will be sent to the moderators telling them about the held +subscription and the fact that they may need to approve it. +:: + + >>> messages = get_queue_messages('virgin') + >>> len(messages) + 1 + + >>> print messages[0].msg.as_string() + MIME-Version: 1.0 + ... + Subject: New subscription request to A Test List from herb@example.org + From: ant-owner@example.com + To: ant-owner@example.com + ... + <BLANKLINE> + Your authorization is required for a mailing list subscription request + approval: + <BLANKLINE> + For: herb@example.org + List: ant@example.com + ... + +The moderators accept the subscription request. + + >>> handle_subscription(mlist, 2, Action.accept) + +And now Herb is a member of the mailing list. + + >>> print mlist.members.get_member('herb@example.org').address + Herb Person <herb@example.org> + + +.. Clear the queue. + >>> ignore = get_queue_messages('virgin') + + +Holding unsubscription requests +=============================== + +Some lists require moderator approval for unsubscriptions. In this case, only +the unsubscribing address is required. + +Herb now wants to leave the mailing list, but his request must be approved. + + >>> mlist.admin_immed_notify = False + >>> from mailman.app.moderator import hold_unsubscription + >>> hold_unsubscription(mlist, 'herb@example.org') + 2 + +As with subscription requests, the unsubscription request can be deferred. + + >>> from mailman.app.moderator import handle_unsubscription + >>> handle_unsubscription(mlist, 2, Action.defer) + >>> print mlist.members.get_member('herb@example.org').address + Herb Person <herb@example.org> + +The held unsubscription can also be discarded, and the member will remain +subscribed. + + >>> handle_unsubscription(mlist, 2, Action.discard) + >>> print mlist.members.get_member('herb@example.org').address + Herb Person <herb@example.org> + +The request can be rejected, in which case a message is sent to the member, +and the person remains a member of the mailing list. + + >>> hold_unsubscription(mlist, 'herb@example.org') + 2 + >>> handle_unsubscription(mlist, 2, Action.reject, 'No can do') + >>> print mlist.members.get_member('herb@example.org').address + Herb Person <herb@example.org> + +Herb gets a rejection notice. +:: + + >>> messages = get_queue_messages('virgin') + >>> len(messages) + 1 + + >>> print messages[0].msg.as_string() + MIME-Version: 1.0 + ... + Subject: Request to mailing list "A Test List" rejected + From: ant-bounces@example.com + To: herb@example.org + ... + Your request to the ant@example.com mailing list + <BLANKLINE> + Unsubscription request + <BLANKLINE> + has been rejected by the list moderator. The moderator gave the + following reason for rejecting your request: + <BLANKLINE> + "No can do" + ... + +The unsubscription request can also be accepted. This removes the member from +the mailing list. + + >>> hold_unsubscription(mlist, 'herb@example.org') + 2 + >>> mlist.send_goodbye_message = False + >>> handle_unsubscription(mlist, 2, Action.accept) + >>> print mlist.members.get_member('herb@example.org') + None + + +Membership change notifications +=============================== + +TBD: + + * admin_immed_notify + * welcome messages + * goodbye messages diff --git a/src/mailman/app/membership.py b/src/mailman/app/membership.py index 3f012e5a5..dfe794610 100644 --- a/src/mailman/app/membership.py +++ b/src/mailman/app/membership.py @@ -131,7 +131,7 @@ def delete_member(mlist, email, admin_notif=None, userack=None): mailing list. """ if userack is None: - userack = mlist.send_goodbye_msg + userack = mlist.send_goodbye_message if admin_notif is None: admin_notif = mlist.admin_notify_mchanges # Delete a member, for which we know the approval has been made. diff --git a/src/mailman/app/tests/test_moderation.py b/src/mailman/app/tests/test_moderation.py index dc1217d67..8efffb48b 100644 --- a/src/mailman/app/tests/test_moderation.py +++ b/src/mailman/app/tests/test_moderation.py @@ -27,15 +27,18 @@ __all__ = [ import unittest +from zope.component import getUtility + from mailman.app.lifecycle import create_list from mailman.app.moderator import handle_message, hold_message from mailman.interfaces.action import Action +from mailman.interfaces.messages import IMessageStore from mailman.interfaces.requests import IListRequests from mailman.runners.incoming import IncomingRunner from mailman.runners.outgoing import OutgoingRunner from mailman.runners.pipeline import PipelineRunner from mailman.testing.helpers import ( - make_testable_runner, specialized_message_from_string) + get_queue_messages, make_testable_runner, specialized_message_from_string) from mailman.testing.layers import SMTPLayer from mailman.utilities.datetime import now @@ -48,6 +51,7 @@ class TestModeration(unittest.TestCase): def setUp(self): self._mlist = create_list('test@example.com') + self._request_db = IListRequests(self._mlist) self._msg = specialized_message_from_string("""\ From: anne@example.com To: test@example.com @@ -101,11 +105,10 @@ Message-ID: <alpha> request_id = hold_message(self._mlist, self._msg) handle_message(self._mlist, request_id, Action.defer) # The message is still in the pending requests. - requests_db = IListRequests(self._mlist) - key, data = requests_db.get_request(request_id) + key, data = self._request_db.get_request(request_id) self.assertEqual(key, '<alpha>') handle_message(self._mlist, request_id, Action.hold) - key, data = requests_db.get_request(request_id) + key, data = self._request_db.get_request(request_id) self.assertEqual(key, '<alpha>') def test_lp_1031391(self): @@ -115,6 +118,37 @@ Message-ID: <alpha> received_time = now() msgdata = dict(received_time=received_time) request_id = hold_message(self._mlist, self._msg, msgdata) - requests_db = IListRequests(self._mlist) - key, data = requests_db.get_request(request_id) + key, data = self._request_db.get_request(request_id) self.assertEqual(data['received_time'], received_time) + + def test_non_preserving_disposition(self): + # By default, disposed messages are not preserved. + request_id = hold_message(self._mlist, self._msg) + handle_message(self._mlist, request_id, Action.discard) + message_store = getUtility(IMessageStore) + self.assertIsNone(message_store.get_message_by_id('<alpha>')) + + def test_preserving_disposition(self): + # Preserving a message keeps it in the store. + request_id = hold_message(self._mlist, self._msg) + handle_message(self._mlist, request_id, Action.discard, preserve=True) + message_store = getUtility(IMessageStore) + preserved_message = message_store.get_message_by_id('<alpha>') + self.assertEqual(preserved_message['message-id'], '<alpha>') + + def test_preserve_and_forward(self): + # We can both preserve and forward the message. + request_id = hold_message(self._mlist, self._msg) + handle_message(self._mlist, request_id, Action.discard, + preserve=True, forward=['zack@example.com']) + # The message is preserved in the store. + message_store = getUtility(IMessageStore) + preserved_message = message_store.get_message_by_id('<alpha>') + self.assertEqual(preserved_message['message-id'], '<alpha>') + # And the forwarded message lives in the virgin queue. + messages = get_queue_messages('virgin') + self.assertEqual(len(messages), 1) + self.assertEqual(str(messages[0].msg['subject']), + 'Forward of moderated message') + self.assertEqual(messages[0].msgdata['recipients'], + ['zack@example.com']) diff --git a/src/mailman/model/docs/requests.rst b/src/mailman/model/docs/requests.rst index a51cbc099..cee43a3d8 100644 --- a/src/mailman/model/docs/requests.rst +++ b/src/mailman/model/docs/requests.rst @@ -1,3 +1,5 @@ +.. model-requests: + ================== Moderator requests ================== @@ -6,22 +8,15 @@ Various actions will be held for moderator approval, such as subscriptions to closed lists, or postings by non-members. The requests database is the low level interface to these actions requiring approval. -.. Here is a helper function for printing out held requests. - - >>> def show_holds(requests): - ... for request in requests.held_requests: - ... key, data = requests.get_request(request.id) - ... print request.id, str(request.request_type), key - ... if data is not None: - ... for key in sorted(data): - ... print ' {0}: {1}'.format(key, data[key]) +An :ref:`application level interface <app-moderator>` for holding messages and +membership changes is also available. Mailing list-centric ==================== -A set of requests are always related to a particular mailing list, so given a -mailing list you need to get its requests object. +A set of requests are always related to a particular mailing list. Adapt the +mailing list to get its requests. :: >>> from mailman.interfaces.requests import IListRequests @@ -48,60 +43,48 @@ The list's requests database starts out empty. At the lowest level, the requests database is very simple. Holding a request requires a request type (as an enum value), a key, and an optional dictionary of associated data. The request database assigns no semantics to the held -data, except for the request type. Here we hold some simple bits of data. +data, except for the request type. >>> from mailman.interfaces.requests import RequestType - >>> id_1 = requests.hold_request(RequestType.held_message, 'hold_1') - >>> id_2 = requests.hold_request(RequestType.subscription, 'hold_2') - >>> id_3 = requests.hold_request(RequestType.unsubscription, 'hold_3') - >>> id_4 = requests.hold_request(RequestType.held_message, 'hold_4') - >>> id_1, id_2, id_3, id_4 - (1, 2, 3, 4) -And of course, now we can see that there are four requests being held. +We can hold messages for moderator approval. - >>> requests.count - 4 - >>> requests.count_of(RequestType.held_message) - 2 - >>> requests.count_of(RequestType.subscription) + >>> requests.hold_request(RequestType.held_message, 'hold_1') 1 - >>> requests.count_of(RequestType.unsubscription) - 1 - >>> show_holds(requests) - 1 RequestType.held_message hold_1 - 2 RequestType.subscription hold_2 - 3 RequestType.unsubscription hold_3 - 4 RequestType.held_message hold_4 -If we try to hold a request with a bogus type, we get an exception. +We can hold subscription requests for moderator approval. - >>> requests.hold_request(5, 'foo') - Traceback (most recent call last): - ... - TypeError: 5 + >>> requests.hold_request(RequestType.subscription, 'hold_2') + 2 -We can hold requests with additional data. +We can hold unsubscription requests for moderator approval. - >>> data = dict(foo='yes', bar='no') - >>> id_5 = requests.hold_request(RequestType.held_message, 'hold_5', data) - >>> id_5 - 5 - >>> requests.count - 5 - >>> show_holds(requests) - 1 RequestType.held_message hold_1 - 2 RequestType.subscription hold_2 - 3 RequestType.unsubscription hold_3 - 4 RequestType.held_message hold_4 - 5 RequestType.held_message hold_5 - bar: no - foo: yes + >>> requests.hold_request(RequestType.unsubscription, 'hold_3') + 3 Getting requests ================ +We can see the total number of requests being held. + + >>> requests.count + 3 + +We can also see the number of requests being held by request type. + + >>> requests.count_of(RequestType.subscription) + 1 + >>> requests.count_of(RequestType.unsubscription) + 1 + +We can also see when there are multiple held requests of a particular type. + + >>> requests.hold_request(RequestType.held_message, 'hold_4') + 4 + >>> requests.count_of(RequestType.held_message) + 2 + We can ask the requests database for a specific request, by providing the id of the request data we want. This returns a 2-tuple of the key and data we originally held. @@ -110,25 +93,37 @@ originally held. >>> print key hold_2 -Because we did not store additional data with request 2, it comes back as None -now. +There was no additional data associated with request 2. >>> print data None -However, if we ask for a request that had data, we'd get it back now. +If we ask for a request that is not in the database, we get None back. + + >>> print requests.get_request(801) + None + + +Additional data +=============== + +When a request is held, additional data can be associated with it, in the form +of a dictionary with string values. + + >>> data = dict(foo='yes', bar='no') + >>> requests.hold_request(RequestType.held_message, 'hold_5', data) + 5 + +The data is returned when the request is retrieved. The dictionary will have +an additional key which holds the name of the request type. >>> key, data = requests.get_request(5) >>> print key hold_5 >>> dump_msgdata(data) - bar: no - foo: yes - -If we ask for a request that is not in the database, we get None back. - - >>> print requests.get_request(801) - None + _request_type: held_message + bar : no + foo : yes Iterating over requests @@ -140,767 +135,37 @@ over by type. >>> requests.count_of(RequestType.held_message) 3 >>> for request in requests.of_type(RequestType.held_message): - ... assert request.request_type is RequestType.held_message ... key, data = requests.get_request(request.id) - ... print request.id, key + ... print request.id, request.request_type, key ... if data is not None: ... for key in sorted(data): ... print ' {0}: {1}'.format(key, data[key]) - 1 hold_1 - 4 hold_4 - 5 hold_5 - bar: no - foo: yes + 1 RequestType.held_message hold_1 + 4 RequestType.held_message hold_4 + 5 RequestType.held_message hold_5 + _request_type: held_message + bar: no + foo: yes Deleting requests ================= -Once a specific request has been handled, it will be deleted from the requests +Once a specific request has been handled, it can be deleted from the requests database. + >>> requests.count + 5 >>> requests.delete_request(2) >>> requests.count 4 - >>> show_holds(requests) - 1 RequestType.held_message hold_1 - 3 RequestType.unsubscription hold_3 - 4 RequestType.held_message hold_4 - 5 RequestType.held_message hold_5 - bar: no - foo: yes - >>> print requests.get_request(2) - None -We get an exception if we ask to delete a request that isn't in the database. +Request 2 is no longer in the database. - >>> requests.delete_request(801) - Traceback (most recent call last): - ... - KeyError: 801 - -For the next section, we first clean up all the current requests. + >>> print requests.get_request(2) + None >>> for request in requests.held_requests: ... requests.delete_request(request.id) >>> requests.count 0 - - -Application support -=================== - -There are several higher level interfaces available in the ``mailman.app`` -package which can be used to hold messages, subscription, and unsubscriptions. -There are also interfaces for disposing of these requests in an application -specific and consistent way. - - >>> from mailman.app import moderator - - -Holding messages -================ - -For this section, we need a mailing list and at least one message. - - >>> mlist = create_list('alist@example.com') - >>> mlist.preferred_language = 'en' - >>> mlist.display_name = 'A Test List' - >>> msg = message_from_string("""\ - ... From: aperson@example.org - ... To: alist@example.com - ... Subject: Something important - ... - ... Here's something important about our mailing list. - ... """) - -Holding a message means keeping a copy of it that a moderator must approve -before the message is posted to the mailing list. To hold the message, you -must supply the message, message metadata, and a text reason for the hold. In -this case, we won't include any additional metadata. - - >>> id_1 = moderator.hold_message(mlist, msg, {}, 'Needs approval') - >>> requests.get_request(id_1) is not None - True - -We can also hold a message with some additional metadata. -:: - - # Delete the Message-ID from the previous hold so we don't try to store - # collisions in the message storage. - >>> del msg['message-id'] - >>> msgdata = dict(sender='aperson@example.com', - ... approved=True) - >>> id_2 = moderator.hold_message(mlist, msg, msgdata, 'Feeling ornery') - >>> requests.get_request(id_2) is not None - True - -Once held, the moderator can select one of several dispositions. The most -trivial is to simply defer a decision for now. - - >>> from mailman.interfaces.action import Action - >>> moderator.handle_message(mlist, id_1, Action.defer) - >>> requests.get_request(id_1) is not None - True - -The moderator can also discard the message. This is often done with spam. -Bye bye message! - - >>> moderator.handle_message(mlist, id_1, Action.discard) - >>> print requests.get_request(id_1) - None - >>> from mailman.testing.helpers import get_queue_messages - >>> get_queue_messages('virgin') - [] - -The message can be rejected, meaning it is bounced back to the sender. - - >>> moderator.handle_message(mlist, id_2, Action.reject, 'Off topic') - >>> print requests.get_request(id_2) - None - >>> messages = get_queue_messages('virgin') - >>> len(messages) - 1 - >>> print messages[0].msg.as_string() - MIME-Version: 1.0 - Content-Type: text/plain; charset="us-ascii" - Content-Transfer-Encoding: 7bit - Subject: Request to mailing list "A Test List" rejected - From: alist-bounces@example.com - To: aperson@example.org - Message-ID: ... - Date: ... - Precedence: bulk - <BLANKLINE> - Your request to the alist@example.com mailing list - <BLANKLINE> - Posting of your message titled "Something important" - <BLANKLINE> - has been rejected by the list moderator. The moderator gave the - following reason for rejecting your request: - <BLANKLINE> - "Off topic" - <BLANKLINE> - Any questions or comments should be directed to the list administrator - at: - <BLANKLINE> - alist-owner@example.com - <BLANKLINE> - >>> dump_msgdata(messages[0].msgdata) - _parsemsg : False - listname : alist@example.com - nodecorate : True - recipients : set([u'aperson@example.org']) - reduced_list_headers: True - version : 3 - -Or the message can be approved. This actually places the message back into -the incoming queue for further processing, however the message metadata -indicates that the message has been approved. - - >>> id_3 = moderator.hold_message(mlist, msg, msgdata, 'Needs approval') - >>> moderator.handle_message(mlist, id_3, Action.accept) - >>> messages = get_queue_messages('pipeline') - >>> len(messages) - 1 - >>> print messages[0].msg.as_string() - From: aperson@example.org - To: alist@example.com - Subject: Something important - Message-ID: ... - X-Message-ID-Hash: ... - X-Mailman-Approved-At: ... - <BLANKLINE> - Here's something important about our mailing list. - <BLANKLINE> - >>> dump_msgdata(messages[0].msgdata) - _parsemsg : False - approved : True - moderator_approved: True - sender : aperson@example.com - version : 3 - -In addition to any of the above dispositions, the message can also be -preserved for further study. Ordinarily the message is removed from the -global message store after its disposition (though approved messages may be -re-added to the message store). When handling a message, we can tell the -moderator interface to also preserve a copy, essentially telling it not to -delete the message from the storage. First, without the switch, the message -is deleted. -:: - - >>> msg = message_from_string("""\ - ... From: aperson@example.org - ... To: alist@example.com - ... Subject: Something important - ... Message-ID: <12345> - ... - ... Here's something important about our mailing list. - ... """) - >>> id_4 = moderator.hold_message(mlist, msg, {}, 'Needs approval') - >>> moderator.handle_message(mlist, id_4, Action.discard) - - >>> from mailman.interfaces.messages import IMessageStore - >>> from zope.component import getUtility - >>> message_store = getUtility(IMessageStore) - - >>> print message_store.get_message_by_id('<12345>') - None - -But if we ask to preserve the message when we discard it, it will be held in -the message store after disposition. - - >>> id_4 = moderator.hold_message(mlist, msg, {}, 'Needs approval') - >>> moderator.handle_message(mlist, id_4, Action.discard, preserve=True) - >>> stored_msg = message_store.get_message_by_id('<12345>') - >>> print stored_msg.as_string() - From: aperson@example.org - To: alist@example.com - Subject: Something important - Message-ID: <12345> - X-Message-ID-Hash: 4CF7EAU3SIXBPXBB5S6PEUMO62MWGQN6 - <BLANKLINE> - Here's something important about our mailing list. - <BLANKLINE> - -Orthogonal to preservation, the message can also be forwarded to another -address. This is helpful for getting the message into the inbox of one of the -moderators. -:: - - # Set a new Message-ID from the previous hold so we don't try to store - # collisions in the message storage. - >>> del msg['message-id'] - >>> msg['Message-ID'] = '<abcde>' - >>> id_4 = moderator.hold_message(mlist, msg, {}, 'Needs approval') - >>> moderator.handle_message(mlist, id_4, Action.discard, - ... forward=['zperson@example.com']) - - >>> messages = get_queue_messages('virgin') - >>> len(messages) - 1 - >>> print messages[0].msg.as_string() - Subject: Forward of moderated message - From: alist-bounces@example.com - To: zperson@example.com - MIME-Version: 1.0 - Content-Type: message/rfc822 - Message-ID: ... - Date: ... - Precedence: bulk - <BLANKLINE> - From: aperson@example.org - To: alist@example.com - Subject: Something important - Message-ID: <abcde> - X-Message-ID-Hash: EN2R5UQFMOUTCL44FLNNPLSXBIZW62ER - <BLANKLINE> - Here's something important about our mailing list. - <BLANKLINE> - - >>> dump_msgdata(messages[0].msgdata) - _parsemsg : False - listname : alist@example.com - nodecorate : True - recipients : [u'zperson@example.com'] - reduced_list_headers: True - version : 3 - - -Holding subscription requests -============================= - -For closed lists, subscription requests will also be held for moderator -approval. In this case, several pieces of information related to the -subscription must be provided, including the subscriber's address and real -name, their password (possibly hashed), what kind of delivery option they are -choosing and their preferred language. - - >>> from mailman.interfaces.member import DeliveryMode - >>> mlist.admin_immed_notify = False - >>> id_3 = moderator.hold_subscription(mlist, - ... 'bperson@example.org', 'Ben Person', - ... '{NONE}abcxyz', DeliveryMode.regular, 'en') - >>> requests.get_request(id_3) is not None - True - -In the above case the mailing list was not configured to send the list -moderators a notice about the hold, so no email message is in the virgin -queue. - - >>> get_queue_messages('virgin') - [] - -But if we set the list up to notify the list moderators immediately when a -message is held for approval, there will be a message placed in the virgin -queue when the message is held. -:: - - >>> mlist.admin_immed_notify = True - >>> # XXX This will almost certainly change once we've worked out the web - >>> # space layout for mailing lists now. - >>> id_4 = moderator.hold_subscription(mlist, - ... 'cperson@example.org', 'Claire Person', - ... '{NONE}zyxcba', DeliveryMode.regular, 'en') - >>> requests.get_request(id_4) is not None - True - >>> messages = get_queue_messages('virgin') - >>> len(messages) - 1 - - >>> print messages[0].msg.as_string() - MIME-Version: 1.0 - Content-Type: text/plain; charset="us-ascii" - Content-Transfer-Encoding: 7bit - Subject: New subscription request to A Test List from cperson@example.org - From: alist-owner@example.com - To: alist-owner@example.com - Message-ID: ... - Date: ... - Precedence: bulk - <BLANKLINE> - Your authorization is required for a mailing list subscription request - approval: - <BLANKLINE> - For: cperson@example.org - List: alist@example.com - <BLANKLINE> - At your convenience, visit: - <BLANKLINE> - http://lists.example.com/admindb/alist@example.com - <BLANKLINE> - to process the request. - <BLANKLINE> - - >>> dump_msgdata(messages[0].msgdata) - _parsemsg : False - listname : alist@example.com - nodecorate : True - recipients : set([u'alist-owner@example.com']) - reduced_list_headers: True - tomoderators : True - version : 3 - -Once held, the moderator can select one of several dispositions. The most -trivial is to simply defer a decision for now. - - >>> moderator.handle_subscription(mlist, id_3, Action.defer) - >>> requests.get_request(id_3) is not None - True - -The held subscription can also be discarded. - - >>> moderator.handle_subscription(mlist, id_3, Action.discard) - >>> print requests.get_request(id_3) - None - -The request can be rejected, in which case a message is sent to the -subscriber. -:: - - >>> moderator.handle_subscription(mlist, id_4, Action.reject, - ... 'This is a closed list') - >>> print requests.get_request(id_4) - None - >>> messages = get_queue_messages('virgin') - >>> len(messages) - 1 - - >>> print messages[0].msg.as_string() - MIME-Version: 1.0 - Content-Type: text/plain; charset="us-ascii" - Content-Transfer-Encoding: 7bit - Subject: Request to mailing list "A Test List" rejected - From: alist-bounces@example.com - To: cperson@example.org - Message-ID: ... - Date: ... - Precedence: bulk - <BLANKLINE> - Your request to the alist@example.com mailing list - <BLANKLINE> - Subscription request - <BLANKLINE> - has been rejected by the list moderator. The moderator gave the - following reason for rejecting your request: - <BLANKLINE> - "This is a closed list" - <BLANKLINE> - Any questions or comments should be directed to the list administrator - at: - <BLANKLINE> - alist-owner@example.com - <BLANKLINE> - - >>> dump_msgdata(messages[0].msgdata) - _parsemsg : False - listname : alist@example.com - nodecorate : True - recipients : set([u'cperson@example.org']) - reduced_list_headers: True - version : 3 - -The subscription can also be accepted. This subscribes the address to the -mailing list. - - >>> mlist.send_welcome_message = True - >>> mlist.welcome_message_uri = 'mailman:///welcome.txt' - >>> id_4 = moderator.hold_subscription(mlist, - ... 'fperson@example.org', 'Frank Person', - ... 'abcxyz', DeliveryMode.regular, 'en') - -A message will be sent to the moderators telling them about the held -subscription and the fact that they may need to approve it. -:: - - >>> messages = get_queue_messages('virgin') - >>> len(messages) - 1 - - >>> print messages[0].msg.as_string() - MIME-Version: 1.0 - Content-Type: text/plain; charset="us-ascii" - Content-Transfer-Encoding: 7bit - Subject: New subscription request to A Test List from fperson@example.org - From: alist-owner@example.com - To: alist-owner@example.com - Message-ID: ... - Date: ... - Precedence: bulk - <BLANKLINE> - Your authorization is required for a mailing list subscription request - approval: - <BLANKLINE> - For: fperson@example.org - List: alist@example.com - <BLANKLINE> - At your convenience, visit: - <BLANKLINE> - http://lists.example.com/admindb/alist@example.com - <BLANKLINE> - to process the request. - <BLANKLINE> - - >>> dump_msgdata(messages[0].msgdata) - _parsemsg : False - listname : alist@example.com - nodecorate : True - recipients : set([u'alist-owner@example.com']) - reduced_list_headers: True - tomoderators : True - version : 3 - -Accept the subscription request. - - >>> mlist.admin_notify_mchanges = True - >>> moderator.handle_subscription(mlist, id_4, Action.accept) - -There are now two messages in the virgin queue. One is a welcome message -being sent to the user and the other is a subscription notification that is -sent to the moderators. The only good way to tell which is which is to look -at the recipient list. - - >>> messages = get_queue_messages('virgin', sort_on='subject') - >>> len(messages) - 2 - -The welcome message is sent to the person who just subscribed. -:: - - >>> print messages[1].msg.as_string() - MIME-Version: 1.0 - Content-Type: text/plain; charset="us-ascii" - Content-Transfer-Encoding: 7bit - Subject: Welcome to the "A Test List" mailing list - From: alist-request@example.com - To: Frank Person <fperson@example.org> - X-No-Archive: yes - Message-ID: ... - Date: ... - Precedence: bulk - <BLANKLINE> - Welcome to the "A Test List" mailing list! - <BLANKLINE> - To post to this list, send your email to: - <BLANKLINE> - alist@example.com - <BLANKLINE> - General information about the mailing list is at: - <BLANKLINE> - http://lists.example.com/listinfo/alist@example.com - <BLANKLINE> - If you ever want to unsubscribe or change your options (eg, switch to - or from digest mode, change your password, etc.), visit your - subscription page at: - <BLANKLINE> - http://example.com/fperson@example.org - <BLANKLINE> - You can also make such adjustments via email by sending a message to: - <BLANKLINE> - alist-request@example.com - <BLANKLINE> - with the word 'help' in the subject or body (don't include the - quotes), and you will get back a message with instructions. You will - need your password to change your options, but for security purposes, - this email is not included here. There is also a button on your - options page that will send your current password to you. - <BLANKLINE> - - >>> dump_msgdata(messages[1].msgdata) - _parsemsg : False - listname : alist@example.com - nodecorate : True - recipients : set([u'Frank Person <fperson@example.org>']) - reduced_list_headers: True - verp : False - version : 3 - -The admin message is sent to the moderators. -:: - - >>> print messages[0].msg.as_string() - MIME-Version: 1.0 - Content-Type: text/plain; charset="us-ascii" - Content-Transfer-Encoding: 7bit - Subject: A Test List subscription notification - From: noreply@example.com - To: alist-owner@example.com - Message-ID: ... - Date: ... - Precedence: bulk - <BLANKLINE> - Frank Person <fperson@example.org> has been successfully subscribed to - A Test List. - <BLANKLINE> - - >>> dump_msgdata(messages[0].msgdata) - _parsemsg : False - envsender : noreply@example.com - listname : alist@example.com - nodecorate : True - recipients : set([]) - reduced_list_headers: True - version : 3 - -Frank Person is now a member of the mailing list. -:: - - >>> member = mlist.members.get_member('fperson@example.org') - >>> member - <Member: Frank Person <fperson@example.org> - on alist@example.com as MemberRole.member> - >>> member.preferred_language - <Language [en] English (USA)> - >>> print member.delivery_mode - DeliveryMode.regular - >>> print member.user.display_name - Frank Person - >>> print member.user.password - {plaintext}abcxyz - - -Holding unsubscription requests -=============================== - -Some lists, though it is rare, require moderator approval for unsubscriptions. -In this case, only the unsubscribing address is required. Like subscriptions, -unsubscription holds can send the list's moderators an immediate -notification. -:: - - - >>> from mailman.interfaces.usermanager import IUserManager - >>> from zope.component import getUtility - >>> user_manager = getUtility(IUserManager) - - >>> mlist.admin_immed_notify = False - >>> from mailman.interfaces.member import MemberRole - >>> user_1 = user_manager.create_user('gperson@example.com') - >>> address_1 = list(user_1.addresses)[0] - >>> mlist.subscribe(address_1, MemberRole.member) - <Member: gperson@example.com on alist@example.com as MemberRole.member> - - >>> user_2 = user_manager.create_user('hperson@example.com') - >>> address_2 = list(user_2.addresses)[0] - >>> mlist.subscribe(address_2, MemberRole.member) - <Member: hperson@example.com on alist@example.com as MemberRole.member> - - >>> id_5 = moderator.hold_unsubscription(mlist, 'gperson@example.com') - >>> requests.get_request(id_5) is not None - True - >>> get_queue_messages('virgin') - [] - >>> mlist.admin_immed_notify = True - >>> id_6 = moderator.hold_unsubscription(mlist, 'hperson@example.com') - - >>> messages = get_queue_messages('virgin') - >>> len(messages) - 1 - >>> print messages[0].msg.as_string() - MIME-Version: 1.0 - Content-Type: text/plain; charset="us-ascii" - Content-Transfer-Encoding: 7bit - Subject: New unsubscription request from A Test List by hperson@example.com - From: alist-owner@example.com - To: alist-owner@example.com - Message-ID: ... - Date: ... - Precedence: bulk - <BLANKLINE> - Your authorization is required for a mailing list unsubscription - request approval: - <BLANKLINE> - By: hperson@example.com - From: alist@example.com - <BLANKLINE> - At your convenience, visit: - <BLANKLINE> - http://lists.example.com/admindb/alist@example.com - <BLANKLINE> - to process the request. - <BLANKLINE> - - >>> dump_msgdata(messages[0].msgdata) - _parsemsg : False - listname : alist@example.com - nodecorate : True - recipients : set([u'alist-owner@example.com']) - reduced_list_headers: True - tomoderators : True - version : 3 - -There are now two addresses with held unsubscription requests. As above, one -of the actions we can take is to defer to the decision. - - >>> moderator.handle_unsubscription(mlist, id_5, Action.defer) - >>> requests.get_request(id_5) is not None - True - -The held unsubscription can also be discarded, and the member will remain -subscribed. - - >>> moderator.handle_unsubscription(mlist, id_5, Action.discard) - >>> print requests.get_request(id_5) - None - >>> mlist.members.get_member('gperson@example.com') - <Member: gperson@example.com on alist@example.com as MemberRole.member> - -The request can be rejected, in which case a message is sent to the member, -and the person remains a member of the mailing list. -:: - - >>> moderator.handle_unsubscription(mlist, id_6, Action.reject, - ... 'This list is a prison.') - >>> print requests.get_request(id_6) - None - >>> messages = get_queue_messages('virgin') - >>> len(messages) - 1 - - >>> print messages[0].msg.as_string() - MIME-Version: 1.0 - Content-Type: text/plain; charset="us-ascii" - Content-Transfer-Encoding: 7bit - Subject: Request to mailing list "A Test List" rejected - From: alist-bounces@example.com - To: hperson@example.com - Message-ID: ... - Date: ... - Precedence: bulk - <BLANKLINE> - Your request to the alist@example.com mailing list - <BLANKLINE> - Unsubscription request - <BLANKLINE> - has been rejected by the list moderator. The moderator gave the - following reason for rejecting your request: - <BLANKLINE> - "This list is a prison." - <BLANKLINE> - Any questions or comments should be directed to the list administrator - at: - <BLANKLINE> - alist-owner@example.com - <BLANKLINE> - - >>> dump_msgdata(messages[0].msgdata) - _parsemsg : False - listname : alist@example.com - nodecorate : True - recipients : set([u'hperson@example.com']) - reduced_list_headers: True - version : 3 - - >>> mlist.members.get_member('hperson@example.com') - <Member: hperson@example.com on alist@example.com as MemberRole.member> - -The unsubscription request can also be accepted. This removes the member from -the mailing list. - - >>> mlist.send_goodbye_msg = True - >>> mlist.goodbye_msg = 'So long!' - >>> mlist.admin_immed_notify = False - >>> id_7 = moderator.hold_unsubscription(mlist, 'gperson@example.com') - >>> moderator.handle_unsubscription(mlist, id_7, Action.accept) - >>> print mlist.members.get_member('gperson@example.com') - None - -There are now two messages in the virgin queue, one to the member who was just -unsubscribed and another to the moderators informing them of this membership -change. - - >>> messages = get_queue_messages('virgin') - >>> len(messages) - 2 - -The goodbye message... -:: - - >>> print messages[0].msg.as_string() - MIME-Version: 1.0 - Content-Type: text/plain; charset="us-ascii" - Content-Transfer-Encoding: 7bit - Subject: You have been unsubscribed from the A Test List mailing list - From: alist-bounces@example.com - To: gperson@example.com - Message-ID: ... - Date: ... - Precedence: bulk - <BLANKLINE> - So long! - <BLANKLINE> - - >>> dump_msgdata(messages[0].msgdata) - _parsemsg : False - listname : alist@example.com - nodecorate : True - recipients : set([u'gperson@example.com']) - reduced_list_headers: True - verp : False - version : 3 - -...and the admin message. -:: - - >>> print messages[1].msg.as_string() - MIME-Version: 1.0 - Content-Type: text/plain; charset="us-ascii" - Content-Transfer-Encoding: 7bit - Subject: A Test List unsubscription notification - From: noreply@example.com - To: alist-owner@example.com - Message-ID: ... - Date: ... - Precedence: bulk - <BLANKLINE> - gperson@example.com has been removed from A Test List. - <BLANKLINE> - - >>> dump_msgdata(messages[1].msgdata) - _parsemsg : False - envsender : noreply@example.com - listname : alist@example.com - nodecorate : True - recipients : set([]) - reduced_list_headers: True - version : 3 diff --git a/src/mailman/model/tests/test_requests.py b/src/mailman/model/tests/test_requests.py index a85add748..5e4d614fb 100644 --- a/src/mailman/model/tests/test_requests.py +++ b/src/mailman/model/tests/test_requests.py @@ -21,6 +21,7 @@ from __future__ import absolute_import, print_function, unicode_literals __metaclass__ = type __all__ = [ + 'TestRequests', ] @@ -39,6 +40,7 @@ class TestRequests(unittest.TestCase): def setUp(self): self._mlist = create_list('ant@example.com') + self._requests_db = IListRequests(self._mlist) self._msg = mfs("""\ From: anne@example.com To: ant@example.com @@ -51,16 +53,27 @@ Something else. def test_get_request_with_type(self): # get_request() takes an optional request type. request_id = hold_message(self._mlist, self._msg) - requests_db = IListRequests(self._mlist) # Submit a request with a non-matching type. This should return None # as if there were no matches. - response = requests_db.get_request( + response = self._requests_db.get_request( request_id, RequestType.subscription) self.assertEqual(response, None) # Submit the same request with a matching type. - key, data = requests_db.get_request( + key, data = self._requests_db.get_request( request_id, RequestType.held_message) self.assertEqual(key, '<alpha>') # It should also succeed with no optional request type given. - key, data = requests_db.get_request(request_id) + key, data = self._requests_db.get_request(request_id) self.assertEqual(key, '<alpha>') + + def test_hold_with_bogus_type(self): + # Calling hold_request() with a bogus request type is an error. + with self.assertRaises(TypeError) as cm: + self._requests_db.hold_request(5, 'foo') + self.assertEqual(cm.exception.message, 5) + + def test_delete_missing_request(self): + # Trying to delete a missing request is an error. + with self.assertRaises(KeyError) as cm: + self._requests_db.delete_request(801) + self.assertEqual(cm.exception.message, 801) diff --git a/src/mailman/rest/moderation.py b/src/mailman/rest/moderation.py index 8b777429b..8fc519996 100644 --- a/src/mailman/rest/moderation.py +++ b/src/mailman/rest/moderation.py @@ -40,11 +40,16 @@ from mailman.rest.helpers import CollectionMixin, etag, no_content from mailman.rest.validator import Validator, enum_validator +HELD_MESSAGE_REQUESTS = (RequestType.held_message,) +MEMBERSHIP_CHANGE_REQUESTS = (RequestType.subscription, + RequestType.unsubscription) + + class _ModerationBase: """Common base class.""" - def _make_resource(self, request_id): + def _make_resource(self, request_id, expected_request_types): requests = IListRequests(self._mlist) results = requests.get_request(request_id) if results is None: @@ -53,8 +58,12 @@ class _ModerationBase: resource = dict(key=key, request_id=request_id) # Flatten the IRequest payload into the JSON representation. resource.update(data) - # Rename this key, and put the request_id in the resource. - resource['type'] = resource.pop('_request_type') + # 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. @@ -67,7 +76,8 @@ class _HeldMessageBase(_ModerationBase): """Held messages are a little different.""" def _make_resource(self, request_id): - resource = super(_HeldMessageBase, self)._make_resource(request_id) + resource = super(_HeldMessageBase, self)._make_resource( + request_id, HELD_MESSAGE_REQUESTS) if resource is None: return None # Grab the message and insert its text representation into the @@ -171,7 +181,7 @@ class MembershipChangeRequest(resource.Resource, _ModerationBase): request_id = int(self._request_id) except ValueError: return http.bad_request() - resource = self._make_resource(request_id) + resource = self._make_resource(request_id, MEMBERSHIP_CHANGE_REQUESTS) if resource is None: return http.not_found() # Remove unnecessary keys. @@ -217,7 +227,7 @@ class SubscriptionRequests( def _resource_as_dict(self, request): """See `CollectionMixin`.""" - resource = self._make_resource(request.id) + resource = self._make_resource(request.id, MEMBERSHIP_CHANGE_REQUESTS) # Remove unnecessary keys. del resource['key'] return resource @@ -226,8 +236,7 @@ class SubscriptionRequests( requests = IListRequests(self._mlist) self._requests = requests items = [] - for request_type in (RequestType.subscription, - RequestType.unsubscription): + for request_type in MEMBERSHIP_CHANGE_REQUESTS: for request in requests.of_type(request_type): items.append(request) return items diff --git a/src/mailman/rest/tests/test_moderation.py b/src/mailman/rest/tests/test_moderation.py index 2ee796c87..46cc86d60 100644 --- a/src/mailman/rest/tests/test_moderation.py +++ b/src/mailman/rest/tests/test_moderation.py @@ -82,7 +82,7 @@ Something else. self.assertEqual(cm.exception.code, 404) # But using the held_id returns a valid response. response, content = call_api(url.format(held_id)) - self.assertEqual(response['key'], '<alpha>') + self.assertEqual(response['message_id'], '<alpha>') def test_bad_action(self): # POSTing to a held message with a bad action. |