Add some assertions about outliers (#10773)

I think I have finally teased apart the codepaths which handle outliers, and those that handle non-outliers. 
Let's add some assertions to demonstrate my newfound knowledge.

changelog.d/10773.misc

@@ -0,0 +1 @@
+Clean up some of the federation event authentication code for clarity.

synapse/handlers/federation_event.py

@@ -173,6 +173,9 @@ class FederationEventHandler:
             pdu: received PDU
         """
 
+        # We should never see any outliers here.
+        assert not pdu.internal_metadata.outlier
+
         room_id = pdu.room_id
         event_id = pdu.event_id
 
@@ -232,13 +235,7 @@ class FederationEventHandler:
             )
             return None
 
-        # Check that the event passes auth based on the state at the event. This is
+        # Try to fetch any missing prev events to fill in gaps in the graph
-        # done for events that are to be added to the timeline (non-outliers).
-        #
-        # Get missing pdus if necessary:
-        #  - Fetching any missing prev events to fill in gaps in the graph
-        #  - Fetching state if we have a hole in the graph
-        if not pdu.internal_metadata.is_outlier():
         prevs = set(pdu.prev_event_ids())
         seen = await self._store.have_events_in_timeline(prevs)
         missing_prevs = prevs - seen
@@ -885,8 +882,13 @@ class FederationEventHandler:
         state: Optional[Iterable[EventBase]],
         backfilled: bool = False,
     ) -> None:
-        """Called when we have a new pdu. We need to do auth checks and put it
+        """Called when we have a new non-outlier event.
-        through the StateHandler.
+
+        This is called when we have a new event to add to the room DAG - either directly
+        via a /send request, retrieved via get_missing_events after a /send request, or
+        backfilled after a client request.
+
+        We need to do auth checks and put it through the StateHandler.
 
         Args:
             origin: server sending the event
@@ -901,6 +903,7 @@ class FederationEventHandler:
                 notification to clients, and validation of device keys.)
         """
         logger.debug("Processing event: %s", event)
+        assert not event.internal_metadata.outlier
 
         try:
             context = await self._state_handler.compute_event_context(
@@ -1263,11 +1266,13 @@ class FederationEventHandler:
                 Possibly incomplete, and possibly including events that are not yet
                 persisted, or authed, or in the right room.
 
-                Only populated where we may not already have persisted these events -
+                Only populated when populating outliers.
-                for example, when populating outliers.
 
             backfilled: True if the event was backfilled.
         """
+        # claimed_auth_event_map should be given iff the event is an outlier
+        assert bool(claimed_auth_event_map) == event.internal_metadata.outlier
+
         context = await self._check_event_auth(
             origin,
             event,
@@ -1306,15 +1311,16 @@ class FederationEventHandler:
                 Possibly incomplete, and possibly including events that are not yet
                 persisted, or authed, or in the right room.
 
-                Only populated where we may not already have persisted these events -
+                Only populated when populating outliers.
-                for example, when populating outliers, or the state for a backwards
-                extremity.
 
             backfilled: True if the event was backfilled.
 
         Returns:
             The updated context object.
         """
+        # claimed_auth_event_map should be given iff the event is an outlier
+        assert bool(claimed_auth_event_map) == event.internal_metadata.outlier
+
         room_version = await self._store.get_room_version_id(event.room_id)
         room_version_obj = KNOWN_ROOM_VERSIONS[room_version]