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