1# Copyright (C) 2007-2020 by the Free Software Foundation, Inc.
2#
3# This file is part of GNU Mailman.
4#
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)
8# any later version.
9#
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
13# more details.
14#
15# You should have received a copy of the GNU General Public License along with
16# GNU Mailman.  If not, see <https://www.gnu.org/licenses/>.
17
18"""The message storage service."""
19
20from public import public
21from zope.interface import Attribute, Interface
22
23
24@public
25class IMessageStore(Interface):
26    """The interface of the global message storage service.
27
28    All messages that are stored in the system live in the message
29    storage service.  A message stored in this service must have a
30    Message-ID header.  The store writes an Message-ID-Hash header which
31    contains the Base32 encoded SHA1 hash of the message's Message-ID
32    header.  Any existing Message-ID-Hash header is overwritten.
33
34    Either the Message-ID or the Message-ID-Hash header can be used to
35    uniquely identify this message in the storage service.  While it is
36    possible to see duplicate Message-IDs, this is never correct and the
37    service is allowed to drop any subsequent colliding messages, or
38    overwrite earlier messages with later ones.
39
40    The combination of the List-Archive header and either the Message-ID
41    or Message-ID-Hash header can be used to retrieve the message from
42    the internet facing interface for the message store.  This can be
43    considered a globally unique URI to the message.
44
45    For example, a message with the following headers:
46
47    Message-ID: <87myycy5eh.fsf@uwakimon.sk.tsukuba.ac.jp>
48    Date: Wed, 04 Jul 2007 16:49:58 +0900
49    List-Archive: http://archive.example.com/
50    Message-ID-Hash: RXTJ357KFOTJP3NFJA6KMO65X7VQOHJI
51
52    the globally unique URI would be:
53
54    http://archive.example.com/RXTJ357KFOTJP3NFJA6KMO65X7VQOHJI
55    """
56
57    def add(message):
58        """Add the message to the store.
59
60        :param message: An email.message.Message instance containing at least
61            a unique Message-ID header.  The message will be given an
62            Message-ID-Hash header, overriding any existing such header.  If
63            the message already exists in the store, it is not added again.
64        :returns: The calculated Message-ID-Hash header or None if the message
65            already exists in the store.
66        :rtype: str or None
67        :raises ValueError: if the message is missing a Message-ID header.
68        """
69
70    def get_message_by_id(message_id):
71        """Return the message with a matching Message-ID.
72
73        :param message_id: The Message-ID header contents to search for.
74        :returns: The message, or None if no matching message was found.
75        """
76
77    def get_message_by_hash(message_id_hash):
78        """Return the message with the matching Message-ID-Hash.
79
80        :param message_id_hash: The Message-ID-Hash header contents to
81            search for.
82        :returns: The message, or None if no matching message was found.
83        """
84
85    def delete_message(message_id):
86        """Remove the given message from the store.
87
88        If the referenced message is missing from the message store, the
89        operation is ignored.
90
91        :param message: The Message-ID of the message to delete from the store.
92        """
93
94    messages = Attribute(
95        """An iterator over all messages in this message store.""")
96
97
98@public
99class IMessage(Interface):
100    """The representation of an email message."""
101
102    message_id = Attribute("""The message's Message-ID header.""")
103
104    message_id_hash = Attribute("""The unique SHA1 hash of the message.""")
105
106    path = Attribute("""The filesystem path to the message object.""")
107