diff options
Diffstat (limited to 'src/mailman/interfaces/messages.py')
| -rw-r--r-- | src/mailman/interfaces/messages.py | 111 |
1 files changed, 111 insertions, 0 deletions
diff --git a/src/mailman/interfaces/messages.py b/src/mailman/interfaces/messages.py new file mode 100644 index 000000000..72efe960f --- /dev/null +++ b/src/mailman/interfaces/messages.py @@ -0,0 +1,111 @@ +# Copyright (C) 2007-2009 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/>. + +"""The message storage service.""" + +from __future__ import absolute_import, unicode_literals + +__metaclass__ = type +__all__ = [ + 'IMessage', + 'IMessageStore', + ] + + +from zope.interface import Interface, Attribute + + + +class IMessageStore(Interface): + """The interface of the global message storage service. + + All messages that are stored in the system live in the message storage + service. A message stored in this service must have a Message-ID header. + The store writes an X-Message-ID-Hash header which contains the Base32 + encoded SHA1 hash of the message's Message-ID header. Any existing + X-Message-ID-Hash header is overwritten. + + Either the Message-ID or the X-Message-ID-Hash header can be used to + uniquely identify this message in the storage service. While it is + possible to see duplicate Message-IDs, this is never correct and the + service is allowed to drop any subsequent colliding messages, or overwrite + earlier messages with later ones. + + The combination of the List-Archive header and either the Message-ID or + X-Message-ID-Hash header can be used to retrieve the message from the + internet facing interface for the message store. This can be considered a + globally unique URI to the message. + + For example, a message with the following headers: + + Message-ID: <87myycy5eh.fsf@uwakimon.sk.tsukuba.ac.jp> + Date: Wed, 04 Jul 2007 16:49:58 +0900 + List-Archive: http://archive.example.com/ + X-Message-ID-Hash: RXTJ357KFOTJP3NFJA6KMO65X7VQOHJI + + the globally unique URI would be: + + http://archive.example.com/RXTJ357KFOTJP3NFJA6KMO65X7VQOHJI + """ + + def add(message): + """Add the message to the store. + + :param message: An email.message.Message instance containing at least + a unique Message-ID header. The message will be given an + X-Message-ID-Hash header, overriding any existing such header. + :returns: The calculated X-Message-ID-Hash header. + :raises ValueError: if the message is missing a Message-ID header. + The storage service is also allowed to raise this exception if it + find, but disallows collisions. + """ + + def get_message_by_id(message_id): + """Return the message with a matching Message-ID. + + :param message_id: The Message-ID header contents to search for. + :returns: The message, or None if no matching message was found. + """ + + def get_message_by_hash(message_id_hash): + """Return the message with the matching X-Message-ID-Hash. + + :param message_id_hash: The X-Message-ID-Hash header contents to + search for. + :returns: The message, or None if no matching message was found. + """ + + def delete_message(message_id): + """Remove the given message from the store. + + :param message: The Message-ID of the mesage to delete from the store. + :raises LookupError: if there is no such message. + """ + + messages = Attribute( + """An iterator over all messages in this message store.""") + + + +class IMessage(Interface): + """The representation of an email message.""" + + message_id = Attribute("""The message's Message-ID header.""") + + message_id_hash = Attribute("""The unique SHA1 hash of the message.""") + + path = Attribute("""The filesystem path to the message object.""") |