Add global search backfill worker (#7860)

* Add search backfill worker

This will run on background at most once an hour while the device has internet connectivity and the device is charging and start back-paginating through the user's rooms to make sure the search results are populated.

It'll run for the maximum time the default workers allow, 10 minutes.

* Create `RustMatrixClient.Factory` AssistedFactory to help with DI and add `SearchBackfillService`

* Start search backfill when entering the search screen, just once. This should help getting initial search results if none or few are found at first

libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/MatrixClient.kt

@@ -40,6 +40,7 @@ import io.element.android.libraries.matrix.api.roomdirectory.RoomDirectoryServic
 import io.element.android.libraries.matrix.api.roomlist.RoomListService
 import io.element.android.libraries.matrix.api.scanner.ContentScanner
 import io.element.android.libraries.matrix.api.search.MessageSearchService
+import io.element.android.libraries.matrix.api.search.SearchBackfillService
 import io.element.android.libraries.matrix.api.spaces.SpaceService
 import io.element.android.libraries.matrix.api.sync.SlidingSyncVersion
 import io.element.android.libraries.matrix.api.sync.SyncService
@@ -133,6 +134,9 @@ interface MatrixClient : ClientUrlContentFetcher {
     /** Scans media content before it is displayed, or `null` when no content scanner is configured for this session. */
     val contentScanner: ContentScanner?
 
+    /** Backfills messages from the homeserver for searching for messages in a room. */
+    val searchBackfillService: SearchBackfillService
+
     /** Whether the session is in the process of shutting down, either because it is being logged out or its cache is being cleared. */
     val isShuttingDown: Boolean
 

libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/SdkPendingTask.kt

@@ -0,0 +1,16 @@
+/*
+ * Copyright (c) 2026 Element Creations Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.matrix.api
+
+/**
+ * Represents a pending task in the SDK that can be canceled and closed.
+ */
+interface SdkPendingTask : AutoCloseable {
+    /** Checks if the task is still running. */
+    fun isRunning(): Boolean
+}

libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/search/SearchBackfillService.kt

@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) 2026 Element Creations Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.matrix.api.search
+
+import io.element.android.libraries.matrix.api.SdkPendingTask
+
+/**
+ * Service interface for managing search backfill tasks in the Matrix SDK.
+ * This service allows starting, checking the status of, and canceling search backfill tasks.
+ */
+interface SearchBackfillService {
+    /**
+     * Enqueues a periodic search backfill task based on the provided strategy.
+     * The strategy parameter determines how the backfill should be performed (e.g., in the foreground or background).
+     */
+    suspend fun schedulePeriodicSearchBackfill(strategy: SearchBackfillStrategy): Result<Unit>
+
+    /**
+     * Cancels any currently scheduled periodic search backfill tasks.
+     */
+    fun cancelPeriodicSearchBackfill()
+
+    /**
+     * Starts a background task to backfill messages for rooms that have been joined but not fully backfilled yet.
+     * The strategy parameter determines how the backfill should be performed (e.g., in the foreground or background).
+     *
+     * @param strategy the strategy to use for backfilling messages.
+     * @return a [Result] indicating the success or failure of enqueuing the backfill task.
+     */
+    fun startSearchBackfill(strategy: SearchBackfillStrategy): Result<SdkPendingTask>
+
+    /**
+     * Checks if a search backfill task is currently running.
+     *
+     * @return `true` if a search backfill task is running, `false` otherwise.
+     */
+    fun isSearchBackfillRunning(): Boolean
+
+    /**
+     * Cancels the currently running search backfill task, if any.
+     *
+     * @return a [Result] indicating the success or failure of the cancellation operation.
+     */
+    fun cancelSearchBackfill(): Result<Unit>
+}

libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/search/SearchBackfillStrategy.kt

@@ -0,0 +1,22 @@
+/*
+ * Copyright (c) 2026 Element Creations Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.matrix.api.search
+
+enum class SearchBackfillStrategy {
+    /**
+     * The app is in the foreground: pause between paginations so this doesn't
+     * compete with interactive traffic.
+     */
+    FOREGROUND,
+
+    /**
+     * A time-boxed background task (e.g. iOS `BGAppRefreshTask`) where there's
+     * no interactive traffic to protect.
+     */
+    BACKGROUND
+}