From 63d9ef9a12a015f80001f9f63a9bb8d5cdf754e4 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 9 May 2022 11:46:38 -0400 Subject: [PATCH 1/3] Add class-diagrams and notes for push. --- synapse/push/__init__.py | 79 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) diff --git a/synapse/push/__init__.py b/synapse/push/__init__.py index a1b771109848..aa7e3db32262 100644 --- a/synapse/push/__init__.py +++ b/synapse/push/__init__.py @@ -12,6 +12,85 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +This module implements the push rules & notifications portion of the Matrix +specification. + +There's a few related features: + +* Push notifications (i.e. email or outgoing requests to a Push Gateway). +* Calculation of unread notifications (for /sync and /notifications). + +When Synapse receives a new event (locally, via the Client-Server API, or via +federation), the following occurs: + +1. The push rules get evaluated to generate a set of per-user actions. +2. The event is persisted into the database. +3. (In the background) The notifier is notified about the new event. + +The per-user actions are initially stored in the event_push_actions_staging table, +before getting moved into the event_push_actions table when the event is persisted. +The event_push_actions table is periodically summarised into the event_push_summary +and event_push_summary_stream_ordering tables. + +Since push actions block an event from being persisted the generation of push +actions is performance sensitive. + +The general interaction of the classes are: + + +---------------------------------------------+ + | FederationEventHandler/EventCreationHandler | + +---------------------------------------------+ + | + v + +-----------------+ + | ActionGenerator | + +-----------------+ + | + v + +-----------------------+ +---------------------------+ + | BulkPushRuleEvaluator |---->| PushRuleEvaluatorForEvent | + +-----------------------+ +---------------------------+ + | + v + +-----------------------------+ + | EventPushActionsWorkerStore | + +-----------------------------+ + +The notifier notifies the pusher pool of the new event, which checks for affected +users. Each user-configured pusher of the affected users then performs the +previously calculated action. + +The general interaction of the classes are: + + +----------+ + | Notifier | + +----------+ + | + v + +------------+ +--------------+ + | PusherPool |---->| PusherConfig | + +------------+ +--------------+ + | + | +---------------+ + +<--->| PusherFactory | + | +---------------+ + v + +------------------------+ +-----------------------------------------------+ + | EmailPusher/HttpPusher |---->| EventPushActionsWorkerStore/PusherWorkerStore | + +------------------------+ +-----------------------------------------------+ + | + v + +------------------+ + | SimpleHttpClient | + +------------------+ + +The Pusher instance also calls out to various utilities for generating payloads +(or email templates), but those interactions are not detailed in this diagram +(and are specific to the type of pusher). + +""" + import abc from typing import TYPE_CHECKING, Any, Dict, Optional From 9931c5be198fc3fa61c5411f7da2ccd7d3e2f47b Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 9 May 2022 11:49:25 -0400 Subject: [PATCH 2/3] Newsfragment --- changelog.d/12676.misc | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/12676.misc diff --git a/changelog.d/12676.misc b/changelog.d/12676.misc new file mode 100644 index 000000000000..26490af00dee --- /dev/null +++ b/changelog.d/12676.misc @@ -0,0 +1 @@ +Improve documentation of the `synapse.push` module. From fb29d06983fb58afe9ef249a765dd769ca663c3e Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 9 May 2022 11:52:52 -0400 Subject: [PATCH 3/3] EmailPusher doesn't use SimpleHttpClient. --- synapse/push/__init__.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/synapse/push/__init__.py b/synapse/push/__init__.py index aa7e3db32262..d1dfb406d43a 100644 --- a/synapse/push/__init__.py +++ b/synapse/push/__init__.py @@ -81,9 +81,9 @@ +------------------------+ +-----------------------------------------------+ | v - +------------------+ - | SimpleHttpClient | - +------------------+ + +-------------------------+ + | Mailer/SimpleHttpClient | + +-------------------------+ The Pusher instance also calls out to various utilities for generating payloads (or email templates), but those interactions are not detailed in this diagram