From 795d0584f611bc6a67ed0f7f041141c062cbc642 Mon Sep 17 00:00:00 2001
From: Andrew Morgan <andrew@amorgan.xyz>
Date: Wed, 20 Oct 2021 17:11:37 +0100
Subject: [PATCH 01/16] Add docstring to on_new_event

---
 synapse/notifier.py | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/synapse/notifier.py b/synapse/notifier.py
index 1a9f84ba4533..37513f2b35d9 100644
--- a/synapse/notifier.py
+++ b/synapse/notifier.py
@@ -402,10 +402,17 @@ def on_new_event(
         new_token: Union[int, RoomStreamToken],
         users: Optional[Collection[Union[str, UserID]]] = None,
         rooms: Optional[Collection[str]] = None,
-    ):
+    ) -> None:
         """Used to inform listeners that something has happened event wise.
 
         Will wake up all listeners for the given users and rooms.
+
+        Args:
+            stream_key: The stream the event came from.
+            new_token: The value of the new stream token.
+            users: The users that should be informed of the new event.
+            rooms: A collection of room IDs for which each joined member will be
+                informed of the new event.
         """
         users = users or []
         rooms = rooms or []

From 1e5a0f2fea1a8e30da0f79f25b88a2011588ab41 Mon Sep 17 00:00:00 2001
From: Andrew Morgan <andrew@amorgan.xyz>
Date: Wed, 20 Oct 2021 17:10:45 +0100
Subject: [PATCH 02/16] Add docstring to _notify_app_services_ephemeral

---
 synapse/notifier.py | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/synapse/notifier.py b/synapse/notifier.py
index 37513f2b35d9..1acd899fab79 100644
--- a/synapse/notifier.py
+++ b/synapse/notifier.py
@@ -379,7 +379,14 @@ def _notify_app_services_ephemeral(
         stream_key: str,
         new_token: Union[int, RoomStreamToken],
         users: Optional[Collection[Union[str, UserID]]] = None,
-    ):
+    ) -> None:
+        """Notify application services of ephemeral event activity.
+
+        Args:
+            stream_key: The stream the event came from.
+            new_token: The value of the new stream token.
+            users: The users that should be informed of the new event, if any.
+        """
         try:
             stream_token = None
             if isinstance(new_token, int):

From 2fd99fefedda118433f633423b3d8c471840421b Mon Sep 17 00:00:00 2001
From: Andrew Morgan <andrew@amorgan.xyz>
Date: Wed, 20 Oct 2021 17:15:10 +0100
Subject: [PATCH 03/16] Add comments to notify_interested_services_ephemeral

---
 synapse/handlers/appservice.py | 39 +++++++++++++++++++++++++---------
 1 file changed, 29 insertions(+), 10 deletions(-)

diff --git a/synapse/handlers/appservice.py b/synapse/handlers/appservice.py
index 163278708c9e..c8be6f16e9de 100644
--- a/synapse/handlers/appservice.py
+++ b/synapse/handlers/appservice.py
@@ -185,19 +185,25 @@ def notify_interested_services_ephemeral(
         new_token: Optional[int],
         users: Optional[Collection[Union[str, UserID]]] = None,
     ) -> None:
-        """This is called by the notifier in the background
-        when a ephemeral event handled by the homeserver.
-
-        This will determine which appservices
-        are interested in the event, and submit them.
+        """
+        This is called by the notifier in the background when
+        an ephemeral event is handled by the homeserver.
 
-        Events will only be pushed to appservices
-        that have opted into ephemeral events
+        This will determine which appservices are
+        interested in the event, and submit them.
 
         Args:
             stream_key: The stream the event came from.
-            new_token: The latest stream token
-            users: The user(s) involved with the event.
+
+                When `stream_key` is "typing_key", "receipt_key" or "presence_key", events
+                will only be pushed to appservices that have opted into ephemeral events.
+                Appservices will only receive ephemeral events that fall within their
+                registered user and room namespaces.
+
+                Any other value for `stream_key` will cause this function to return early.
+
+            new_token: The latest stream token.
+            users: The users that should be informed of the new event, if any.
         """
         if not self.notify_appservices:
             return
@@ -232,21 +238,34 @@ async def _notify_interested_services_ephemeral(
             for service in services:
                 # Only handle typing if we have the latest token
                 if stream_key == "typing_key" and new_token is not None:
+                    # Note that we don't persist the token (via set_type_stream_id_for_appservice)
+                    # for typing_key due to performance reasons and due to their highly
+                    # ephemeral nature.
+                    #
+                    # Instead we simply grab the latest typing update in _handle_typing
+                    # and, if it applies to this application service, send it off.
                     events = await self._handle_typing(service, new_token)
                     if events:
                         self.scheduler.submit_ephemeral_events_for_as(service, events)
-                    # We don't persist the token for typing_key for performance reasons
+
                 elif stream_key == "receipt_key":
                     events = await self._handle_receipts(service)
                     if events:
                         self.scheduler.submit_ephemeral_events_for_as(service, events)
+
+                    # Persist the latest handled stream token for this appservice
+                    # TODO: We seem to update the stream token for each appservice,
+                    #  even if sending the ephemeral events to the appservice failed.
                     await self.store.set_type_stream_id_for_appservice(
                         service, "read_receipt", new_token
                     )
+
                 elif stream_key == "presence_key":
                     events = await self._handle_presence(service, users)
                     if events:
                         self.scheduler.submit_ephemeral_events_for_as(service, events)
+
+                    # Persist the latest handled stream token for this appservice
                     await self.store.set_type_stream_id_for_appservice(
                         service, "presence", new_token
                     )

From 0ce33e58fce24073334dd97d09576fcd59edce55 Mon Sep 17 00:00:00 2001
From: Andrew Morgan <andrew@amorgan.xyz>
Date: Wed, 20 Oct 2021 17:42:00 +0100
Subject: [PATCH 04/16] Add comments to _handle* methods and those methods they
 call

---
 synapse/handlers/appservice.py | 46 +++++++++++++++++++++++++++++++++-
 synapse/handlers/device.py     |  4 +++
 synapse/handlers/receipts.py   |  8 +++++-
 synapse/handlers/typing.py     |  7 +++++-
 4 files changed, 62 insertions(+), 3 deletions(-)

diff --git a/synapse/handlers/appservice.py b/synapse/handlers/appservice.py
index c8be6f16e9de..827884cbb04d 100644
--- a/synapse/handlers/appservice.py
+++ b/synapse/handlers/appservice.py
@@ -273,18 +273,49 @@ async def _notify_interested_services_ephemeral(
     async def _handle_typing(
         self, service: ApplicationService, new_token: int
     ) -> List[JsonDict]:
+        """
+        Given an application service, determine which events it should receive
+        from the given typing event stream token and now.
+
+        Args:
+            service: The application service to check for which events it should receive.
+            new_token: The latest typing event stream token.
+
+        Returns:
+            A list of JSON dictionaries containing data derived from the typing events that
+            should be sent to the given application service.
+        """
         typing_source = self.event_sources.sources.typing
         # Get the typing events from just before current
         typing, _ = await typing_source.get_new_events_as(
             service=service,
             # For performance reasons, we don't persist the previous
-            # token in the DB and instead fetch the latest typing information
+            # token in the DB and instead fetch the latest typing event
             # for appservices.
+            # TODO: It'd probably be more efficient to simply fetch the
+            #  typing event with the given 'new_token' stream token and
+            #  checking if the given service was interested, rather than
+            #  iterating over all typing events and only grabbing the
+            #  latest one.
             from_key=new_token - 1,
         )
         return typing
 
     async def _handle_receipts(self, service: ApplicationService) -> List[JsonDict]:
+        """
+        Given an application service, determine which events it should receive
+        from those between the last-recorded typing event stream token for this
+        appservice and the latest one.
+
+        Args:
+            service: The application service to check for which events it should receive.
+            new_token: A typing event stream token. Typing events between this token and
+                the current event stream token will be checked.
+
+        Returns:
+            A list of JSON dictionaries containing data derived from the typing events that
+            should be sent to the given application service.
+        """
         from_key = await self.store.get_type_stream_id_for_appservice(
             service, "read_receipt"
         )
@@ -297,6 +328,19 @@ async def _handle_receipts(self, service: ApplicationService) -> List[JsonDict]:
     async def _handle_presence(
         self, service: ApplicationService, users: Collection[Union[str, UserID]]
     ) -> List[JsonDict]:
+        """
+        Given an application service and a list of users who should be receiving
+        presence updates, return a list of presence updates destined for the
+        application service.
+
+        Args:
+            service: The application service that ephemeral events are being sent to.
+            users: The users that should receive the presence update.
+
+        Returns:
+            A list of json dictionaries containing data derived from the presence events
+            that should be sent to the given application service.
+        """
         events: List[JsonDict] = []
         presence_source = self.event_sources.sources.presence
         from_key = await self.store.get_type_stream_id_for_appservice(
diff --git a/synapse/handlers/device.py b/synapse/handlers/device.py
index 6eafbea25d02..68b446eb66c8 100644
--- a/synapse/handlers/device.py
+++ b/synapse/handlers/device.py
@@ -454,6 +454,10 @@ async def notify_device_update(
     ) -> None:
         """Notify that a user's device(s) has changed. Pokes the notifier, and
         remote servers if the user is local.
+
+        Args:
+            user_id: The Matrix ID of the user who's device list has been updated.
+            device_ids: The device IDs that have changed.
         """
         if not device_ids:
             # No changes to notify about, so this is a no-op.
diff --git a/synapse/handlers/receipts.py b/synapse/handlers/receipts.py
index 374e961e3bf8..4911a1153519 100644
--- a/synapse/handlers/receipts.py
+++ b/synapse/handlers/receipts.py
@@ -241,12 +241,18 @@ async def get_new_events(
     async def get_new_events_as(
         self, from_key: int, service: ApplicationService
     ) -> Tuple[List[JsonDict], int]:
-        """Returns a set of new receipt events that an appservice
+        """Returns a set of new read receipt events that an appservice
         may be interested in.
 
         Args:
             from_key: the stream position at which events should be fetched from
             service: The appservice which may be interested
+
+        Returns:
+            A two-tuple containing the following:
+                * A list of json dictionaries derived from read receipts that the
+                  appservice may be interested in.
+                * The current read receipt stream token.
         """
         from_key = int(from_key)
         to_key = self.get_current_key()
diff --git a/synapse/handlers/typing.py b/synapse/handlers/typing.py
index d10e9b8ec441..662ea59d420c 100644
--- a/synapse/handlers/typing.py
+++ b/synapse/handlers/typing.py
@@ -467,9 +467,14 @@ async def get_new_events_as(
         Args:
             from_key: the stream position at which events should be fetched from
             service: The appservice which may be interested
+
+        Returns:
+            A two-tuple containing the following:
+                * A list of json dictionaries derived from typing events that the
+                  appservice may be interested in.
+                * The latest known room serial.
         """
         with Measure(self.clock, "typing.get_new_events_as"):
-            from_key = int(from_key)
             handler = self.get_typing_handler()
 
             events = []

From e423a94b28263a3971147c210729769734fe66c5 Mon Sep 17 00:00:00 2001
From: Andrew Morgan <andrew@amorgan.xyz>
Date: Wed, 20 Oct 2021 17:47:04 +0100
Subject: [PATCH 05/16] Improve docstring for format_user_presence_state

---
 synapse/handlers/presence.py | 33 ++++++++++++++++++++++++++++++---
 1 file changed, 30 insertions(+), 3 deletions(-)

diff --git a/synapse/handlers/presence.py b/synapse/handlers/presence.py
index b5968e047bf1..06c30472cf8b 100644
--- a/synapse/handlers/presence.py
+++ b/synapse/handlers/presence.py
@@ -1483,11 +1483,38 @@ def should_notify(old_state: UserPresenceState, new_state: UserPresenceState) ->
 def format_user_presence_state(
     state: UserPresenceState, now: int, include_user_id: bool = True
 ) -> JsonDict:
-    """Convert UserPresenceState to a format that can be sent down to clients
+    """Convert UserPresenceState to a JSON format that can be sent down to clients
     and to other servers.
 
-    The "user_id" is optional so that this function can be used to format presence
-    updates for client /sync responses and for federation /send requests.
+    Args:
+        state: The user presence state to format.
+        now: The current timestamp since the epoch in ms.
+        include_user_id: Whether to include `user_id` in the returned dictionary.
+            As this function can be used both to format presence updates for client /sync
+            responses and for federation /send requests, only the latter needs the include
+            the `user_id` field.
+
+    Returns:
+        A JSON dictionary with the following keys:
+            * presence: The presence state as a str.
+            * user_id: Optional. Included if `include_user_id` is truthy. The canonical
+                Matrix ID of the user.
+            * last_active_ago: Optional. Included if `last_active_ts` is set on `state`.
+                The timestamp that the user was last active.
+            * status_msg: Optional. Included if `status_msg` is set on `state`. The user's
+                status.
+            * currently_active: Optional. Included only if `state.state` is "online". Set to
+                the value of `state.currently_active`.
+
+        Example:
+
+        {
+            "presence": "online",
+            "user_id": "@alice:example.com",
+            "last_active_ago": 16783813918,
+            "status_msg": "Hello world!",
+            "currently_active": True
+        }
     """
     content: JsonDict = {"presence": state.state}
     if include_user_id:

From 1df714c21c449c71f39f18c389ec1904e4f1d395 Mon Sep 17 00:00:00 2001
From: Andrew Morgan <andrew@amorgan.xyz>
Date: Wed, 20 Oct 2021 18:04:44 +0100
Subject: [PATCH 06/16] newsfile

---
 changelog.d/11138.misc | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 changelog.d/11138.misc

diff --git a/changelog.d/11138.misc b/changelog.d/11138.misc
new file mode 100644
index 000000000000..79b777697593
--- /dev/null
+++ b/changelog.d/11138.misc
@@ -0,0 +1 @@
+Add docstrings and comments to the application service ephemeral event sending code.
\ No newline at end of file

From 95a49727a6807e716a2386c6d0b167f29f5f8c9a Mon Sep 17 00:00:00 2001
From: Andrew Morgan <andrew@amorgan.xyz>
Date: Wed, 20 Oct 2021 18:13:51 +0100
Subject: [PATCH 07/16] Note that AS interest via room ID or alias isn't
 respected

Typing and read receipt events (those that are associated with a room)
should be sent to an AS that has registered interest in that room,
according to MSC2409:

https://github.com/Sorunome/matrix-doc/blob/231084da132af6518ecefa2a42c37937dfe373d2/proposals/2409-appservice-edus.md#expectations-of-when-an-edu-should-be-pushed-to-an-appservice
---
 synapse/handlers/receipts.py | 4 ++++
 synapse/handlers/typing.py   | 5 +++++
 2 files changed, 9 insertions(+)

diff --git a/synapse/handlers/receipts.py b/synapse/handlers/receipts.py
index 4911a1153519..9fe980e72a94 100644
--- a/synapse/handlers/receipts.py
+++ b/synapse/handlers/receipts.py
@@ -267,6 +267,10 @@ async def get_new_events_as(
         )
 
         # Then filter down to rooms that the AS can read
+        # TODO: This doesn't seem to honour an appservice's registration of room or
+        #   namespace aliases. For instance, if an appservice registered a room namespace
+        #   that matched this room, but it didn't have any members in the room, then that
+        #   appservice wouldn't receive the read receipt.
         events = []
         for room_id, event in rooms_to_events.items():
             if not await service.matches_user_in_member_list(room_id, self.store):
diff --git a/synapse/handlers/typing.py b/synapse/handlers/typing.py
index 662ea59d420c..7290eecfa1e2 100644
--- a/synapse/handlers/typing.py
+++ b/synapse/handlers/typing.py
@@ -481,6 +481,11 @@ async def get_new_events_as(
             for room_id in handler._room_serials.keys():
                 if handler._room_serials[room_id] <= from_key:
                     continue
+
+                # TODO: This doesn't seem to honour an appservice's registration of room or
+                #   namespace aliases. For instance, if an appservice registered a room namespace
+                #   that matched this room, but it didn't have any members in the room, then that
+                #   appservice wouldn't receive the typing event.
                 if not await service.matches_user_in_member_list(
                     room_id, handler.store
                 ):

From 97b9d24b6d19a8caeafc8db119e57e609ffcb9b5 Mon Sep 17 00:00:00 2001
From: Andrew Morgan <andrew@amorgan.xyz>
Date: Wed, 20 Oct 2021 19:19:43 +0100
Subject: [PATCH 08/16] Clean up some comments, add a new TODO...

---
 synapse/handlers/appservice.py | 61 ++++++++++++++++++++--------------
 synapse/handlers/typing.py     |  4 +--
 2 files changed, 38 insertions(+), 27 deletions(-)

diff --git a/synapse/handlers/appservice.py b/synapse/handlers/appservice.py
index 827884cbb04d..56958c49a585 100644
--- a/synapse/handlers/appservice.py
+++ b/synapse/handlers/appservice.py
@@ -186,22 +186,23 @@ def notify_interested_services_ephemeral(
         users: Optional[Collection[Union[str, UserID]]] = None,
     ) -> None:
         """
-        This is called by the notifier in the background when
-        an ephemeral event is handled by the homeserver.
+        This is called by the notifier in the background when an ephemeral event is handled
+        by the homeserver.
 
-        This will determine which appservices are
-        interested in the event, and submit them.
+        This will determine which appservices are interested in the event, and submit them.
 
         Args:
             stream_key: The stream the event came from.
 
-                When `stream_key` is "typing_key", "receipt_key" or "presence_key", events
-                will only be pushed to appservices that have opted into ephemeral events.
+                `stream_key` can "typing_key", "receipt_key" or "presence_key". Any other
+                value for `stream_key` will cause this function to return early.
+
+                Ephemeral events will only be pushed to appservices that have opted into
+                them.
+
                 Appservices will only receive ephemeral events that fall within their
                 registered user and room namespaces.
 
-                Any other value for `stream_key` will cause this function to return early.
-
             new_token: The latest stream token.
             users: The users that should be informed of the new event, if any.
         """
@@ -242,8 +243,8 @@ async def _notify_interested_services_ephemeral(
                     # for typing_key due to performance reasons and due to their highly
                     # ephemeral nature.
                     #
-                    # Instead we simply grab the latest typing update in _handle_typing
-                    # and, if it applies to this application service, send it off.
+                    # Instead we simply grab the latest typing updates in _handle_typing
+                    # and, if they apply to this application service, send it off.
                     events = await self._handle_typing(service, new_token)
                     if events:
                         self.scheduler.submit_ephemeral_events_for_as(service, events)
@@ -274,12 +275,16 @@ async def _handle_typing(
         self, service: ApplicationService, new_token: int
     ) -> List[JsonDict]:
         """
-        Given an application service, determine which events it should receive
-        from the given typing event stream token and now.
+        Return the typing events since the given stream token that the given application
+        service should receive.
+
+        First fetch all typing events between the given typing stream token (non-inclusive)
+        and the latest typing event stream token (inclusive). Then return only those typing
+        events that the given application service may be interested in.
 
         Args:
             service: The application service to check for which events it should receive.
-            new_token: The latest typing event stream token.
+            new_token: A typing event stream token.
 
         Returns:
             A list of JSON dictionaries containing data derived from the typing events that
@@ -292,28 +297,29 @@ async def _handle_typing(
             # For performance reasons, we don't persist the previous
             # token in the DB and instead fetch the latest typing event
             # for appservices.
-            # TODO: It'd probably be more efficient to simply fetch the
+            # TODO: It'd likely be more efficient to simply fetch the
             #  typing event with the given 'new_token' stream token and
-            #  checking if the given service was interested, rather than
+            #  check if the given service was interested, rather than
             #  iterating over all typing events and only grabbing the
-            #  latest one.
+            #  latest few.
             from_key=new_token - 1,
         )
         return typing
 
     async def _handle_receipts(self, service: ApplicationService) -> List[JsonDict]:
         """
-        Given an application service, determine which events it should receive
-        from those between the last-recorded typing event stream token for this
-        appservice and the latest one.
+        Return the latest read receipts that the given application service should receive.
+
+        First fetch all read receipts between the last receipt stream token that this
+        application service should have previously received (non-inclusive) and the
+        latest read receipt stream token (inclusive). Then from that set, return only
+        those read receipts that the given application service may be interested in.
 
         Args:
             service: The application service to check for which events it should receive.
-            new_token: A typing event stream token. Typing events between this token and
-                the current event stream token will be checked.
 
         Returns:
-            A list of JSON dictionaries containing data derived from the typing events that
+            A list of JSON dictionaries containing data derived from the read receipts that
             should be sent to the given application service.
         """
         from_key = await self.store.get_type_stream_id_for_appservice(
@@ -329,9 +335,12 @@ async def _handle_presence(
         self, service: ApplicationService, users: Collection[Union[str, UserID]]
     ) -> List[JsonDict]:
         """
-        Given an application service and a list of users who should be receiving
-        presence updates, return a list of presence updates destined for the
-        application service.
+        Return the latest presence updates that the given application service should receive.
+
+        First, filter the given users list to those that the application service is
+        interested in. Then retrieve the latest presence updates since the
+        the last-known previously received presence stream token for the given
+        application service. Return those presence updates.
 
         Args:
             service: The application service that ephemeral events are being sent to.
@@ -353,6 +362,8 @@ async def _handle_presence(
             interested = await service.is_interested_in_presence(user, self.store)
             if not interested:
                 continue
+
+            # TODO: Make presence_events a Set. These presence events should be de-duplicated.
             presence_events, _ = await presence_source.get_new_events(
                 user=user,
                 service=service,
diff --git a/synapse/handlers/typing.py b/synapse/handlers/typing.py
index 7290eecfa1e2..d41ae5195d26 100644
--- a/synapse/handlers/typing.py
+++ b/synapse/handlers/typing.py
@@ -465,8 +465,8 @@ async def get_new_events_as(
         may be interested in.
 
         Args:
-            from_key: the stream position at which events should be fetched from
-            service: The appservice which may be interested
+            from_key: the stream position at which events should be fetched from.
+            service: The appservice which may be interested.
 
         Returns:
             A two-tuple containing the following:

From 4c1f9d2663747f860093a895e27aca2b21c93a1d Mon Sep 17 00:00:00 2001
From: Andrew Morgan <andrew@amorgan.xyz>
Date: Wed, 20 Oct 2021 19:21:54 +0100
Subject: [PATCH 09/16] Remove unused 'service' argument from
 PresenceSource.get_new_events

---
 synapse/handlers/appservice.py | 4 +---
 synapse/handlers/presence.py   | 2 --
 2 files changed, 1 insertion(+), 5 deletions(-)

diff --git a/synapse/handlers/appservice.py b/synapse/handlers/appservice.py
index 56958c49a585..91011dd3ff3e 100644
--- a/synapse/handlers/appservice.py
+++ b/synapse/handlers/appservice.py
@@ -365,9 +365,7 @@ async def _handle_presence(
 
             # TODO: Make presence_events a Set. These presence events should be de-duplicated.
             presence_events, _ = await presence_source.get_new_events(
-                user=user,
-                service=service,
-                from_key=from_key,
+                user=user, from_key=from_key,
             )
             time_now = self.clock.time_msec()
             events.extend(
diff --git a/synapse/handlers/presence.py b/synapse/handlers/presence.py
index 06c30472cf8b..727aea1b53d2 100644
--- a/synapse/handlers/presence.py
+++ b/synapse/handlers/presence.py
@@ -52,7 +52,6 @@
 from synapse.api.constants import EventTypes, Membership, PresenceState
 from synapse.api.errors import SynapseError
 from synapse.api.presence import UserPresenceState
-from synapse.appservice import ApplicationService
 from synapse.events.presence_router import PresenceRouter
 from synapse.logging.context import run_in_background
 from synapse.logging.utils import log_function
@@ -1553,7 +1552,6 @@ async def get_new_events(
         is_guest: bool = False,
         explicit_room_id: Optional[str] = None,
         include_offline: bool = True,
-        service: Optional[ApplicationService] = None,
     ) -> Tuple[List[UserPresenceState], int]:
         # The process for getting presence events are:
         #  1. Get the rooms the user is in.

From b7988c564c365a1e93ff9d2e69246372d0ee3338 Mon Sep 17 00:00:00 2001
From: Andrew Morgan <andrew@amorgan.xyz>
Date: Wed, 20 Oct 2021 19:25:22 +0100
Subject: [PATCH 10/16] +1 confidence

---
 synapse/handlers/appservice.py | 6 ++++--
 synapse/handlers/receipts.py   | 6 +++---
 synapse/handlers/typing.py     | 6 +++---
 3 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/synapse/handlers/appservice.py b/synapse/handlers/appservice.py
index 91011dd3ff3e..dff33de60951 100644
--- a/synapse/handlers/appservice.py
+++ b/synapse/handlers/appservice.py
@@ -255,8 +255,8 @@ async def _notify_interested_services_ephemeral(
                         self.scheduler.submit_ephemeral_events_for_as(service, events)
 
                     # Persist the latest handled stream token for this appservice
-                    # TODO: We seem to update the stream token for each appservice,
-                    #  even if sending the ephemeral events to the appservice failed.
+                    # TODO: We update the stream token for each appservice, even
+                    #  if sending the ephemeral events to the appservice failed.
                     await self.store.set_type_stream_id_for_appservice(
                         service, "read_receipt", new_token
                     )
@@ -267,6 +267,8 @@ async def _notify_interested_services_ephemeral(
                         self.scheduler.submit_ephemeral_events_for_as(service, events)
 
                     # Persist the latest handled stream token for this appservice
+                    # TODO: We update the stream token for each appservice, even
+                    #  if sending the ephemeral events to the appservice failed.
                     await self.store.set_type_stream_id_for_appservice(
                         service, "presence", new_token
                     )
diff --git a/synapse/handlers/receipts.py b/synapse/handlers/receipts.py
index 9fe980e72a94..008b0586e9cd 100644
--- a/synapse/handlers/receipts.py
+++ b/synapse/handlers/receipts.py
@@ -267,9 +267,9 @@ async def get_new_events_as(
         )
 
         # Then filter down to rooms that the AS can read
-        # TODO: This doesn't seem to honour an appservice's registration of room or
-        #   namespace aliases. For instance, if an appservice registered a room namespace
-        #   that matched this room, but it didn't have any members in the room, then that
+        # TODO: This doesn't honour an appservice's registration of room or namespace
+        #   aliases. For instance, if an appservice registered a room namespace that
+        #   matched this room, but it didn't have any members in the room, then that
         #   appservice wouldn't receive the read receipt.
         events = []
         for room_id, event in rooms_to_events.items():
diff --git a/synapse/handlers/typing.py b/synapse/handlers/typing.py
index d41ae5195d26..7ca63a9e612f 100644
--- a/synapse/handlers/typing.py
+++ b/synapse/handlers/typing.py
@@ -482,9 +482,9 @@ async def get_new_events_as(
                 if handler._room_serials[room_id] <= from_key:
                     continue
 
-                # TODO: This doesn't seem to honour an appservice's registration of room or
-                #   namespace aliases. For instance, if an appservice registered a room namespace
-                #   that matched this room, but it didn't have any members in the room, then that
+                # TODO: This doesn't to honour an appservice's registration of room or namespace
+                #   aliases. For instance, if an appservice registered a room namespace that
+                #   matched this room, but it didn't have any members in the room, then that
                 #   appservice wouldn't receive the typing event.
                 if not await service.matches_user_in_member_list(
                     room_id, handler.store

From cd8ac02375450d7d37cd692527d003dccae5d91a Mon Sep 17 00:00:00 2001
From: Andrew Morgan <andrew@amorgan.xyz>
Date: Wed, 20 Oct 2021 19:29:28 +0100
Subject: [PATCH 11/16] Remove tail end of currently_active description

---
 synapse/handlers/presence.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/synapse/handlers/presence.py b/synapse/handlers/presence.py
index 727aea1b53d2..fdab50da373c 100644
--- a/synapse/handlers/presence.py
+++ b/synapse/handlers/presence.py
@@ -1502,8 +1502,7 @@ def format_user_presence_state(
                 The timestamp that the user was last active.
             * status_msg: Optional. Included if `status_msg` is set on `state`. The user's
                 status.
-            * currently_active: Optional. Included only if `state.state` is "online". Set to
-                the value of `state.currently_active`.
+            * currently_active: Optional. Included only if `state.state` is "online".
 
         Example:
 

From d22faf8778578db6f01a02f1144c7af478968a39 Mon Sep 17 00:00:00 2001
From: Andrew Morgan <andrew@amorgan.xyz>
Date: Wed, 20 Oct 2021 19:39:22 +0100
Subject: [PATCH 12/16] lint

---
 synapse/handlers/appservice.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/synapse/handlers/appservice.py b/synapse/handlers/appservice.py
index dff33de60951..aed8d4c040f7 100644
--- a/synapse/handlers/appservice.py
+++ b/synapse/handlers/appservice.py
@@ -367,7 +367,8 @@ async def _handle_presence(
 
             # TODO: Make presence_events a Set. These presence events should be de-duplicated.
             presence_events, _ = await presence_source.get_new_events(
-                user=user, from_key=from_key,
+                user=user,
+                from_key=from_key,
             )
             time_now = self.clock.time_msec()
             events.extend(

From 4c206d452660bf8e0ae4fc9a89eb6be1111da0c4 Mon Sep 17 00:00:00 2001
From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>
Date: Thu, 21 Oct 2021 14:49:08 +0100
Subject: [PATCH 13/16] Update synapse/handlers/appservice.py

Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com>
---
 synapse/handlers/appservice.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/synapse/handlers/appservice.py b/synapse/handlers/appservice.py
index aed8d4c040f7..d4ca6f6c5cb7 100644
--- a/synapse/handlers/appservice.py
+++ b/synapse/handlers/appservice.py
@@ -194,7 +194,7 @@ def notify_interested_services_ephemeral(
         Args:
             stream_key: The stream the event came from.
 
-                `stream_key` can "typing_key", "receipt_key" or "presence_key". Any other
+                `stream_key` can be "typing_key", "receipt_key" or "presence_key". Any other
                 value for `stream_key` will cause this function to return early.
 
                 Ephemeral events will only be pushed to appservices that have opted into

From d337164ba57e473ab6b2478d363f9fa710e6c93a Mon Sep 17 00:00:00 2001
From: Andrew Morgan <andrew@amorgan.xyz>
Date: Thu, 21 Oct 2021 16:50:59 +0100
Subject: [PATCH 14/16] Move TODO to issue #11150

---
 synapse/handlers/appservice.py | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/synapse/handlers/appservice.py b/synapse/handlers/appservice.py
index d4ca6f6c5cb7..d4039b5f1bb6 100644
--- a/synapse/handlers/appservice.py
+++ b/synapse/handlers/appservice.py
@@ -255,8 +255,6 @@ async def _notify_interested_services_ephemeral(
                         self.scheduler.submit_ephemeral_events_for_as(service, events)
 
                     # Persist the latest handled stream token for this appservice
-                    # TODO: We update the stream token for each appservice, even
-                    #  if sending the ephemeral events to the appservice failed.
                     await self.store.set_type_stream_id_for_appservice(
                         service, "read_receipt", new_token
                     )
@@ -267,8 +265,6 @@ async def _notify_interested_services_ephemeral(
                         self.scheduler.submit_ephemeral_events_for_as(service, events)
 
                     # Persist the latest handled stream token for this appservice
-                    # TODO: We update the stream token for each appservice, even
-                    #  if sending the ephemeral events to the appservice failed.
                     await self.store.set_type_stream_id_for_appservice(
                         service, "presence", new_token
                     )

From 4623514101a38ce17202dc8385d8afa95cbdfbc2 Mon Sep 17 00:00:00 2001
From: Andrew Morgan <andrew@amorgan.xyz>
Date: Thu, 21 Oct 2021 16:54:30 +0100
Subject: [PATCH 15/16] Replace TODO with solution in PR #11140

---
 synapse/handlers/appservice.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/synapse/handlers/appservice.py b/synapse/handlers/appservice.py
index d4039b5f1bb6..36c206dae6a0 100644
--- a/synapse/handlers/appservice.py
+++ b/synapse/handlers/appservice.py
@@ -361,7 +361,6 @@ async def _handle_presence(
             if not interested:
                 continue
 
-            # TODO: Make presence_events a Set. These presence events should be de-duplicated.
             presence_events, _ = await presence_source.get_new_events(
                 user=user,
                 from_key=from_key,

From 768382e080ef103cf8c9c0bca0304334d09bd6a3 Mon Sep 17 00:00:00 2001
From: Andrew Morgan <andrew@amorgan.xyz>
Date: Thu, 21 Oct 2021 17:14:59 +0100
Subject: [PATCH 16/16] Replace TODO with issue #11152

---
 synapse/handlers/receipts.py | 4 ----
 synapse/handlers/typing.py   | 4 ----
 2 files changed, 8 deletions(-)

diff --git a/synapse/handlers/receipts.py b/synapse/handlers/receipts.py
index 008b0586e9cd..4911a1153519 100644
--- a/synapse/handlers/receipts.py
+++ b/synapse/handlers/receipts.py
@@ -267,10 +267,6 @@ async def get_new_events_as(
         )
 
         # Then filter down to rooms that the AS can read
-        # TODO: This doesn't honour an appservice's registration of room or namespace
-        #   aliases. For instance, if an appservice registered a room namespace that
-        #   matched this room, but it didn't have any members in the room, then that
-        #   appservice wouldn't receive the read receipt.
         events = []
         for room_id, event in rooms_to_events.items():
             if not await service.matches_user_in_member_list(room_id, self.store):
diff --git a/synapse/handlers/typing.py b/synapse/handlers/typing.py
index 7ca63a9e612f..c411d6992421 100644
--- a/synapse/handlers/typing.py
+++ b/synapse/handlers/typing.py
@@ -482,10 +482,6 @@ async def get_new_events_as(
                 if handler._room_serials[room_id] <= from_key:
                     continue
 
-                # TODO: This doesn't to honour an appservice's registration of room or namespace
-                #   aliases. For instance, if an appservice registered a room namespace that
-                #   matched this room, but it didn't have any members in the room, then that
-                #   appservice wouldn't receive the typing event.
                 if not await service.matches_user_in_member_list(
                     room_id, handler.store
                 ):