From 9da626dfc814929385b08e30424386045e635b5e Mon Sep 17 00:00:00 2001
From: holger krekel <holger@merlinux.eu>
Date: Sun, 31 Mar 2024 12:37:14 +0200
Subject: [PATCH] proper doc string for Notifier

---
 chatmaild/src/chatmaild/metadata.py |  1 -
 chatmaild/src/chatmaild/notifier.py | 30 ++++++++++++++++++++++++-----
 2 files changed, 25 insertions(+), 6 deletions(-)

diff --git a/chatmaild/src/chatmaild/metadata.py b/chatmaild/src/chatmaild/metadata.py
index 28e3956..97fc9bc 100644
--- a/chatmaild/src/chatmaild/metadata.py
+++ b/chatmaild/src/chatmaild/metadata.py
@@ -125,7 +125,6 @@ def main():
     socket, vmail_dir = sys.argv[1:]
 
     vmail_dir = Path(vmail_dir)
-
     if not vmail_dir.exists():
         logging.error("vmail dir does not exist: %r", vmail_dir)
         return 1
diff --git a/chatmaild/src/chatmaild/notifier.py b/chatmaild/src/chatmaild/notifier.py
index 1e99c64..3741193 100644
--- a/chatmaild/src/chatmaild/notifier.py
+++ b/chatmaild/src/chatmaild/notifier.py
@@ -1,3 +1,28 @@
+"""
+This modules provides notification machinery for transmitting device tokens to
+a central notification server which in turns contacts a phone's notification server
+to trigger Delta Chat apps to retrieve messages and provide instant notifications to users.
+
+The Notifier class arranges the queuing of tokens in separate PriorityQueues
+from which NotifyThreads take and transmit them via HTTPS
+to the `notifications.delta.chat` service
+which in turns contacts a phone's providers's notification service
+which in turn ewakes up the Delta Chat app on user devices.
+The lack of proper HTTP2-support in Python lets us
+use multiple threads and connections to the Rust-implemented `notifications.delta.chat`
+which however uses HTTP2 and thus only a single connection to phone-notification providers.
+
+If a token fails to cause a successful notification
+it is moved to a retry-number specific PriorityQueue
+which handles all tokens that failed a particular number of times
+and which are scheduled for retry using exponential back-off timing.
+If a token exceeds MAX_NUMBER_OF_TRIES it is dropped with a log warning.
+
+Note that tokens are completely opaque to the notification machinery here
+and will in the future be encrypted foreclosing all ability to distinguish
+which device token ultimately goes to which phone-provider notification service.
+"""
+
 import time
 import logging
 from threading import Thread
@@ -65,11 +90,6 @@ class NotifyThread(Thread):
             pass
 
     def retry_one(self, requests_session, sleep=time.sleep):
-        # takes the next token from the per-retry-number PriorityQueue
-        # which is ordered by "when" (as set by add_token_for_retry()).
-        # If the request to notification server fails the token is
-        # queued to the next retry-number's PriorityQueue
-        # until it finally is dropped if MAX_NUMBER_OF_TRIES is exceeded
         when, token = self.notifier.retry_queues[self.retry_num].get()
         if when is None:
             return False