doc: add note that we can't incrementally clean old records from db

The clean operation can take a while. I considered setting a time
limit so it would clean as many records as it can within a time limit
(e.g. 2 seconds) and then return from clean.

However the callers expect that all old record are removed so that
looking for a matching session key, csrf key etc. will match ONLY
unexpired records. They don't check the __timestamp returned.

So clean MUST destroy all expired records before returning.

Author: rouilj

roundup/backends/sessions_dbm.py

@@ -201,6 +201,10 @@ def updateTimestamp(self, sessid):
 
     def clean(self):
         ''' Remove session records that haven't been used for a week. '''
+        ''' Note: deletion of old keys must be completed when this method
+            returns. Calling code must not have any expired keys present
+            after this returns or expired keys could be used to validate
+            a user. This can mean a long delay when expiring but ....'''
         now = time.time()
         week = 60*60*24*7
         a_week_ago = now - week