feat(chat): mark message prefetch requests as such

The client fetches a room's messages before the user asks for them, from
a push notification and after a conversation list sync, and on the wire
those requests are indistinguishable from the ones a user waiting on a
chat screen is making. A server operator looking at request volume
cannot tell what was speculative and what someone was waiting for.

Send prefetch=1 on the chat requests the catch-up makes. The server
ignores the parameter - the response is byte for byte the one it sends
without it - so this only makes the traffic legible in an access log,
where a query parameter needs no configuration to be recorded.

The flag travels the same route as markNotificationsAsRead, which
already separates these two cases, and defaults to false: the helpers
that build the request are shared with the chat the user has open, and
labelling those as prefetched would invert the very distinction this is
for.

Assisted-by: Claude Code:claude-opus-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>

Author: AndyScherzinger

app/src/main/java/com/nextcloud/talk/chat/data/network/ChatMessageSyncer.kt

@@ -132,10 +132,15 @@ class ChatMessageSyncer @Inject constructor(
         limit: Int = DEFAULT_MESSAGES_LIMIT,
         threadId: Long? = null,
         lastCommonRead: Int? = null,
-        markNotificationsAsRead: Boolean = true
+        markNotificationsAsRead: Boolean = true,
+        prefetch: Boolean = false
     ): HashMap<String, Int> {
         val fieldMap = HashMap<String, Int>()
 
+        if (prefetch) {
+            fieldMap["prefetch"] = 1
+        }
+
         fieldMap["includeLastKnown"] = if (includeLastKnown) 1 else 0
 
         if (lastKnown != null) {
@@ -350,15 +355,17 @@ class ChatMessageSyncer @Inject constructor(
                 target = target,
                 fromMessageId = newestMessageIdFromDb,
                 limit = limit,
-                markNotificationsAsRead = false
+                markNotificationsAsRead = false,
+                prefetch = true
             )
         } else {
             initialCatchUp(
                 target = target,
                 limit = limit,
                 lastReadMessage = lastReadMessage,
                 unreadMessages = unreadMessages,
-                markNotificationsAsRead = false
+                markNotificationsAsRead = false,
+                prefetch = true
             )
         }
 
@@ -399,6 +406,7 @@ class ChatMessageSyncer @Inject constructor(
         unreadMessages: Int = 0,
         lastCommonRead: Int? = null,
         markNotificationsAsRead: Boolean = true,
+        prefetch: Boolean = false,
         events: Events = NO_EVENTS
     ): SyncOutcome {
         val closableBacklogAnchor = lastReadMessage?.takeIf {
@@ -413,6 +421,7 @@ class ChatMessageSyncer @Inject constructor(
                 unreadMessages = unreadMessages,
                 lastCommonRead = lastCommonRead,
                 markNotificationsAsRead = markNotificationsAsRead,
+                prefetch = prefetch,
                 events = events
             )
         } else {
@@ -426,7 +435,8 @@ class ChatMessageSyncer @Inject constructor(
                     limit = limit,
                     threadId = target.threadId,
                     lastCommonRead = lastCommonRead,
-                    markNotificationsAsRead = markNotificationsAsRead
+                    markNotificationsAsRead = markNotificationsAsRead,
+                    prefetch = prefetch
                 ),
                 events
             )
@@ -445,6 +455,7 @@ class ChatMessageSyncer @Inject constructor(
         unreadMessages: Int,
         lastCommonRead: Int?,
         markNotificationsAsRead: Boolean,
+        prefetch: Boolean,
         events: Events
     ): SyncOutcome {
         Log.d(
@@ -462,7 +473,8 @@ class ChatMessageSyncer @Inject constructor(
                 limit = limit,
                 threadId = target.threadId,
                 lastCommonRead = lastCommonRead,
-                markNotificationsAsRead = markNotificationsAsRead
+                markNotificationsAsRead = markNotificationsAsRead,
+                prefetch = prefetch
             ),
             events
         )
@@ -478,6 +490,7 @@ class ChatMessageSyncer @Inject constructor(
             limit = limit,
             lastCommonRead = lastCommonRead,
             markNotificationsAsRead = markNotificationsAsRead,
+            prefetch = prefetch,
             events = events
         )
         return SyncOutcome(
@@ -510,6 +523,7 @@ class ChatMessageSyncer @Inject constructor(
         limit: Int = DEFAULT_MESSAGES_LIMIT,
         lastCommonRead: Int? = null,
         markNotificationsAsRead: Boolean = true,
+        prefetch: Boolean = false,
         events: Events = NO_EVENTS
     ): SyncOutcome {
         var anchor = fromMessageId
@@ -527,7 +541,8 @@ class ChatMessageSyncer @Inject constructor(
                 limit = limit,
                 threadId = target.threadId,
                 lastCommonRead = lastCommonRead,
-                markNotificationsAsRead = markNotificationsAsRead
+                markNotificationsAsRead = markNotificationsAsRead,
+                prefetch = prefetch
             )
             val roundOutcome = pullAndPersistMessages(target, fieldMap, events)
 
@@ -569,7 +584,8 @@ class ChatMessageSyncer @Inject constructor(
                 limit = limit,
                 threadId = target.threadId,
                 lastCommonRead = lastCommonRead,
-                markNotificationsAsRead = markNotificationsAsRead
+                markNotificationsAsRead = markNotificationsAsRead,
+                prefetch = prefetch
             ),
             events
         )

app/src/test/java/com/nextcloud/talk/chat/data/network/ChatMessageSyncerTest.kt

@@ -95,11 +95,57 @@ class ChatMessageSyncerTest {
         )
 
         assertFalse(fieldMap.containsKey("markNotificationsAsRead"))
+        assertFalse(fieldMap.containsKey("prefetch"))
         assertFalse(fieldMap.containsKey("lastKnownMessageId"))
         assertEquals(0, fieldMap["setReadMarker"])
         assertEquals(1, fieldMap["includeLastKnown"])
     }
 
+    @Test
+    fun `buildFieldMap marks the request as a prefetch when asked`() {
+        val fieldMap = syncer.buildFieldMap(
+            lookIntoFuture = true,
+            timeout = 0,
+            includeLastKnown = false,
+            lastKnown = 42,
+            prefetch = true
+        )
+
+        assertEquals(1, fieldMap["prefetch"])
+    }
+
+    @Test
+    fun `catchUpRoom marks its request as a prefetch`() =
+        runTest {
+            whenever(chatBlocksDao.getNewestMessageIdFromChatBlocks(INTERNAL_CONVERSATION_ID, null))
+                .thenReturn(42L)
+            whenever(chatBlocksDao.getChatBlocksContainingMessageId(INTERNAL_CONVERSATION_ID, null, 42L))
+                .thenReturn(flowOf(listOf(block(oldest = 10, newest = 42))))
+            wheneverBlocking { network.pullChatMessages(any(), any(), any()) }
+                .thenReturn(Response.success(overall(message(43))))
+
+            syncer.catchUpRoom(target())
+
+            val fieldMapCaptor = argumentCaptor<HashMap<String, Int>>()
+            verifyBlocking(network) { pullChatMessages(eq(CREDENTIALS), eq(CHAT_URL), fieldMapCaptor.capture()) }
+            assertEquals(1, fieldMapCaptor.firstValue["prefetch"])
+        }
+
+    @Test
+    fun `a fetch for a chat the user is reading is not marked as a prefetch`() =
+        runTest {
+            whenever(chatBlocksDao.getChatBlocksContainingMessageId(INTERNAL_CONVERSATION_ID, null, 42L))
+                .thenReturn(flowOf(listOf(block(oldest = 10, newest = 42))))
+            wheneverBlocking { network.pullChatMessages(any(), any(), any()) }
+                .thenReturn(Response.success(overall(message(43))))
+
+            syncer.tryCloseBacklog(target(), fromMessageId = 42L)
+
+            val fieldMapCaptor = argumentCaptor<HashMap<String, Int>>()
+            verifyBlocking(network) { pullChatMessages(eq(CREDENTIALS), eq(CHAT_URL), fieldMapCaptor.capture()) }
+            assertFalse(fieldMapCaptor.firstValue.containsKey("prefetch"))
+        }
+
     @Test
     fun `catchUpRoom skips without chat-keep-notifications capability`() =
         runTest {