From b0b9b4ebcba601b4cca2f6b24c04597fca542be5 Mon Sep 17 00:00:00 2001
From: Eric Eastwood <erice@element.io>
Date: Thu, 28 Aug 2025 19:44:57 -0500
Subject: [PATCH] Temp: Implement `/messages?backfill=true/false`

To try out the flow:

 - **Default to fast responses with gaps**: As a default, we can always
     respond quickly and indicate gaps ([MSC3871]
     (https://github.com/matrix-org/matrix-spec-proposals/pull/3871)) for
     clients to paginate at their leisure.
 - **Fast back-pagination**: Clients back-paginate with
     `/messages?dir=b&backfill=false`, and Synapse skips backfilling
     entirely, returning only local history with gaps as necessary.
 - **Explicit gap filling**: To fill in gaps, clients use
     `/messages?dir=b&backfill=true` which works just like today to do a best
     effort backfill.

This allows the client to back-paginate the history we already have without
delay. And can fill in the gaps as they see fit.

This is basically a simplified version of [MSC4282]
(https://github.com/matrix-org/matrix-spec-proposals/pull/4282).
---
 synapse/handlers/pagination.py |  6 +++++-
 synapse/rest/client/room.py    | 14 ++++++++++++++
 2 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/synapse/handlers/pagination.py b/synapse/handlers/pagination.py
index 3107978306..6957ce74b6 100644
--- a/synapse/handlers/pagination.py
+++ b/synapse/handlers/pagination.py
@@ -414,12 +414,14 @@ class PaginationHandler:
     @trace
     async def get_messages(
         self,
+        *,
         requester: Requester,
         room_id: str,
         pagin_config: PaginationConfig,
         as_client_event: bool = True,
         event_filter: Optional[Filter] = None,
         use_admin_priviledge: bool = False,
+        backfill: bool = True,
     ) -> JsonDict:
         """Get messages in a room.
 
@@ -432,6 +434,8 @@ class PaginationHandler:
             use_admin_priviledge: if `True`, return all events, regardless
                 of whether `user` has access to them. To be used **ONLY**
                 from the admin API.
+            backfill: If false, we skip backfill altogether. When true, we backfill as a
+                best effort.
 
         Returns:
             Pagination API results
@@ -522,7 +526,7 @@ class PaginationHandler:
             event_filter=event_filter,
         )
 
-        if pagin_config.direction == Direction.BACKWARDS:
+        if backfill and pagin_config.direction == Direction.BACKWARDS:
             # We use a `Set` because there can be multiple events at a given depth
             # and we only care about looking at the unique continum of depths to
             # find gaps.
diff --git a/synapse/rest/client/room.py b/synapse/rest/client/room.py
index 64deae7650..6a25b39251 100644
--- a/synapse/rest/client/room.py
+++ b/synapse/rest/client/room.py
@@ -811,6 +811,17 @@ class RoomMessageListRestServlet(RestServlet):
     async def on_GET(
         self, request: SynapseRequest, room_id: str
     ) -> Tuple[int, JsonDict]:
+        """
+        Query paremeters:
+            dir
+            from
+            to
+            limit
+            filter
+            backfill: If false, we skip backfill altogether. When true, we backfill as a
+                best effort.
+        """
+
         processing_start_time = self.clock.time_msec()
         # Fire off and hope that we get a result by the end.
         #
@@ -840,12 +851,15 @@ class RoomMessageListRestServlet(RestServlet):
         ):
             as_client_event = False
 
+        backfill = parse_boolean(request, "backfill", default=True)
+
         msgs = await self.pagination_handler.get_messages(
             room_id=room_id,
             requester=requester,
             pagin_config=pagination_config,
             as_client_event=as_client_event,
             event_filter=event_filter,
+            backfill=backfill,
         )
 
         processing_end_time = self.clock.time_msec()