[PATCH 1/4] Simplify & document savemessage_getnewheader

[Sebastian Spaeth]

savemessage_getnewheader was an undocmented, cryptic and overengineered
function. It generates a new unique value that can be used as a mail
header to be inserted. For this it used LOTS of randomness sources: hash
of the mail content, hash of the folder name, hash of the repository
name, the current time, a random() value, and the offlineimap version string.
All we need is something random. So reduce this to hash of content
appended by a random integer. Sufficient and somewhat faster to calculate.

Rename the function to actually describe accurately what it does or
would you have guessed that savemessage_getnewheader() did nothing more
than returning ('X-OfllineIMAP', <randomstring> )? Rename to
generate_randomheader() to make it clearer what this is all about.

Also document the function, describing what it does, and what it returns.

Signed-off-by: Sebastian Spaeth <Sebastian at SSpaeth.de>
---
 offlineimap/folder/IMAP.py |   26 ++++++++++++++++++--------
 1 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/offlineimap/folder/IMAP.py b/offlineimap/folder/IMAP.py
index be96d5f..e4e7f06 100644
--- a/offlineimap/folder/IMAP.py
+++ b/offlineimap/folder/IMAP.py
@@ -226,14 +226,24 @@ class IMAPFolder(BaseFolder):
     def getmessageflags(self, uid):
         return self.messagelist[uid]['flags']
 
-    def savemessage_getnewheader(self, content):
+    def generate_randomheader(self, content):
+        """Returns a unique X-OfflineIMAP header
+
+        Insert an X-OfflineIMAP header into the mail which contains a
+        random unique value (which is based on the mails content, the
+        repository name, and the folder name). This header allows us to
+        fetch the mail after APPENDing it to an IMAP server and to find
+        out the UID that the server assigned it.
+
+        :returns: (headername, headervalue) tuple, consisting of strings
+                  headername == 'X-OfflineIMAP' and headervalue will be a
+                  random string
+        """
         headername = 'X-OfflineIMAP'
-        headervalue = '%s-' % str(binascii.crc32(content)).replace('-', 'x')
-        headervalue += binascii.hexlify(self.repository.getname()) + '-'
-        headervalue += binascii.hexlify(self.getname())
-        headervalue += '-%d-' % long(time.time())
-        headervalue += str(self.randomgenerator.random()).replace('.', '')
-        headervalue += '-v' + versionstr
+        # compute unsigned crc32 of 'content' as unique hash
+        # NB: crc32 returns unsigned only starting with python 3.0
+        headervalue  = str( binascii.crc32(content) & 0xffffffff ) + '-'
+        headervalue += str(self.randomgenerator.randint(0,9999999999))
         return (headername, headervalue)
 
     def savemessage_addheader(self, content, headername, headervalue):
@@ -335,7 +345,7 @@ class IMAPFolder(BaseFolder):
             content = re.sub("(?<!\r)\n", "\r\n", content)
             ui.debug('imap', 'savemessage: initial content is: ' + repr(content))
 
-            (headername, headervalue) = self.savemessage_getnewheader(content)
+            (headername, headervalue) = self.generate_randomheader(content)
             ui.debug('imap', 'savemessage: new headers are: %s: %s' % \
                      (headername, headervalue))
             content = self.savemessage_addheader(content, headername,
-- 
1.7.1