1
# Copyright (C) 2007-2012 by the Free Software Foundation, Inc.
3
# This file is part of GNU Mailman.
5
# GNU Mailman is free software: you can redistribute it and/or modify it under
6
# the terms of the GNU General Public License as published by the Free
7
# Software Foundation, either version 3 of the License, or (at your option)
10
# GNU Mailman is distributed in the hope that it will be useful, but WITHOUT
11
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
15
# You should have received a copy of the GNU General Public License along with
16
# GNU Mailman. If not, see <http://www.gnu.org/licenses/>.
18
"""The message storage service."""
20
from __future__ import absolute_import, unicode_literals
29
from zope.interface import Interface, Attribute
33
class IMessageStore(Interface):
34
"""The interface of the global message storage service.
36
All messages that are stored in the system live in the message storage
37
service. A message stored in this service must have a Message-ID header.
38
The store writes an X-Message-ID-Hash header which contains the Base32
39
encoded SHA1 hash of the message's Message-ID header. Any existing
40
X-Message-ID-Hash header is overwritten.
42
Either the Message-ID or the X-Message-ID-Hash header can be used to
43
uniquely identify this message in the storage service. While it is
44
possible to see duplicate Message-IDs, this is never correct and the
45
service is allowed to drop any subsequent colliding messages, or overwrite
46
earlier messages with later ones.
48
The combination of the List-Archive header and either the Message-ID or
49
X-Message-ID-Hash header can be used to retrieve the message from the
50
internet facing interface for the message store. This can be considered a
51
globally unique URI to the message.
53
For example, a message with the following headers:
55
Message-ID: <87myycy5eh.fsf@uwakimon.sk.tsukuba.ac.jp>
56
Date: Wed, 04 Jul 2007 16:49:58 +0900
57
List-Archive: http://archive.example.com/
58
X-Message-ID-Hash: RXTJ357KFOTJP3NFJA6KMO65X7VQOHJI
60
the globally unique URI would be:
62
http://archive.example.com/RXTJ357KFOTJP3NFJA6KMO65X7VQOHJI
66
"""Add the message to the store.
68
:param message: An email.message.Message instance containing at least
69
a unique Message-ID header. The message will be given an
70
X-Message-ID-Hash header, overriding any existing such header.
71
:returns: The calculated X-Message-ID-Hash header.
72
:raises ValueError: if the message is missing a Message-ID header.
73
The storage service is also allowed to raise this exception if it
74
find, but disallows collisions.
77
def get_message_by_id(message_id):
78
"""Return the message with a matching Message-ID.
80
:param message_id: The Message-ID header contents to search for.
81
:returns: The message, or None if no matching message was found.
84
def get_message_by_hash(message_id_hash):
85
"""Return the message with the matching X-Message-ID-Hash.
87
:param message_id_hash: The X-Message-ID-Hash header contents to
89
:returns: The message, or None if no matching message was found.
92
def delete_message(message_id):
93
"""Remove the given message from the store.
95
:param message: The Message-ID of the mesage to delete from the store.
96
:raises LookupError: if there is no such message.
100
"""An iterator over all messages in this message store.""")
104
class IMessage(Interface):
105
"""The representation of an email message."""
107
message_id = Attribute("""The message's Message-ID header.""")
109
message_id_hash = Attribute("""The unique SHA1 hash of the message.""")
111
path = Attribute("""The filesystem path to the message object.""")
added
removed
src/mailman/interfaces/messages.py
