feat(reminders): fire immediately if notification is late

Review Reminders

We currently schedule all stored review reminders for their next upcoming alarm time when the application process starts up, such as when the app initially launches (we also have a BOOT_COMPLETED receiver). However, a notification "firing" is not just a single moment in time; since we don't have permissions to use proper alarm-clock-style alarms, the best we can do is a 10 minute `setWindow`, which means "firing" a notification is a non-deterministic event that happens some time in the ten minutes after a review reminder's scheduled notification time. Consider the following set of actions:

1. The user creates a review reminder for 1:00 pm, its first notification is scheduled for 1:00 pm on Monday
2. At 1:00, we enter the `setWindow` period
3. At 1:03, the notification still has not fired; curious as to why, the user opens up their app
4. This causes `scheduleAllNotifications` to trigger, which reschedules the review reminder notification for the next upcoming time, which is 1:00 pm on Tuesday
5. ... We've skipped a notification!

To solution for this is to copy most notification systems: we record when the latest notification time was ourselves (it's impossible to read AlarmManager's currently-scheduled alarms programmatically) and check whenever scheduling a notification if the review reminder's notification has fired since its most recent scheduled time. If not, we immediately fire a notification. This also helps with missed notifications in general: if, for example, the user has had their device off for 6 hours and then turns it on, all alarms that fired during that interval should immediately show.

This commit also creates unit tests surrounding this feature and enhances the readability of NotificationServiceTest. The ReviewReminderSchema is migrated from v2 to v3.

Author: ericli3690

AnkiDroid/src/main/java/com/ichi2/anki/reviewreminders/ReviewReminder.kt

@@ -22,6 +22,7 @@ import android.text.format.DateFormat
 import com.ichi2.anki.CollectionManager.withCol
 import com.ichi2.anki.common.time.TimeManager
 import com.ichi2.anki.libanki.DeckId
+import com.ichi2.anki.libanki.EpochMilliseconds
 import com.ichi2.anki.settings.Prefs
 import kotlinx.parcelize.IgnoredOnParcel
 import kotlinx.parcelize.Parcelize
@@ -185,6 +186,9 @@ sealed class ReviewReminderScope : Parcelable {
  * @param enabled Whether the review reminder's notifications are active or disabled.
  * @param profileID ID representing the profile which created this review reminder, as review reminders for
  * multiple profiles might be active simultaneously.
+ * @param latestNotifTime The time at which this review reminder last attempted to fire a routine daily (non-snooze)
+ * notification, in epoch milliseconds, or the time at which it was created if no notification has ever been fired.
+ * See [shouldImmediatelyFire].
  * @param onlyNotifyIfNoReviews If true, only notify the user if this scope has not been reviewed today yet.
  */
 @Serializable
@@ -196,6 +200,7 @@ data class ReviewReminder private constructor(
     val cardTriggerThreshold: ReviewReminderCardTriggerThreshold,
     val scope: ReviewReminderScope,
     var enabled: Boolean,
+    var latestNotifTime: EpochMilliseconds,
     val profileID: String,
     val onlyNotifyIfNoReviews: Boolean,
 ) : Parcelable,
@@ -219,11 +224,42 @@ data class ReviewReminder private constructor(
             cardTriggerThreshold,
             scope,
             enabled,
+            latestNotifTime = TimeManager.time.calendar().timeInMillis,
             profileID,
             onlyNotifyIfNoReviews,
         )
     }
 
+    /**
+     * Updates [latestNotifTime] to the current time.
+     * This should be called whenever this review reminder attempts to fire a routine daily (non-snooze) notification.
+     */
+    fun updateLatestNotifTime() {
+        latestNotifTime = TimeManager.time.calendar().timeInMillis
+    }
+
+    /**
+     * Checks if this review reminder has tried to fire a routine daily (non-snooze) notification in the time between
+     * its latest scheduled firing time and now. If not, this method returns true, indicating that a notification
+     * should be immediately fired for this review reminder.
+     */
+    fun shouldImmediatelyFire(): Boolean {
+        val (hour, minute) = this.time
+
+        val currentTimestamp = TimeManager.time.calendar()
+        val latestScheduledTimestamp = currentTimestamp.clone() as Calendar
+        latestScheduledTimestamp.apply {
+            set(Calendar.HOUR_OF_DAY, hour)
+            set(Calendar.MINUTE, minute)
+            set(Calendar.SECOND, 0)
+            if (after(currentTimestamp)) {
+                add(Calendar.DAY_OF_YEAR, -1)
+            }
+        }
+
+        return latestNotifTime < latestScheduledTimestamp.timeInMillis
+    }
+
     /**
      * This is the up-to-date schema, we cannot migrate to a newer version.
      */

AnkiDroid/src/main/java/com/ichi2/anki/reviewreminders/ReviewReminderSchema.kt

@@ -75,6 +75,31 @@ data class ReviewReminderSchemaV1(
     var enabled: Boolean,
     val profileID: String,
     val onlyNotifyIfNoReviews: Boolean = false,
+) : ReviewReminderSchema {
+    override fun migrate(): ReviewReminderSchema =
+        ReviewReminderSchemaV2(
+            id = id,
+            time = time,
+            cardTriggerThreshold = cardTriggerThreshold,
+            scope = scope,
+            enabled = enabled,
+            profileID = profileID,
+            onlyNotifyIfNoReviews = onlyNotifyIfNoReviews,
+        )
+}
+
+/**
+ * Version 2 of [ReviewReminderSchema]. Updated to Version 3 by adding [ReviewReminder.latestNotifTime].
+ */
+@Serializable
+data class ReviewReminderSchemaV2(
+    override val id: ReviewReminderId,
+    val time: ReviewReminderTime,
+    val cardTriggerThreshold: ReviewReminderCardTriggerThreshold,
+    val scope: ReviewReminderScope,
+    var enabled: Boolean,
+    val profileID: String,
+    val onlyNotifyIfNoReviews: Boolean,
 ) : ReviewReminderSchema {
     override fun migrate(): ReviewReminderSchema =
         ReviewReminder.createReviewReminder(

AnkiDroid/src/main/java/com/ichi2/anki/reviewreminders/ReviewRemindersDatabase.kt

@@ -107,12 +107,13 @@ object ReviewRemindersDatabase {
      *
      * Version 1: 3 August 2025 - Initial version
      * Version 2: 25 January 2026 - Added [ReviewReminder.onlyNotifyIfNoReviews]
+     * Version 3: 8 February 2026 - Added [ReviewReminder.latestNotifTime]
      *
      * @see [oldReviewReminderSchemasForMigration]
      * @see [ReviewReminder]
      */
     @VisibleForTesting
-    var schemaVersion = ReviewReminderSchemaVersion(2)
+    var schemaVersion = ReviewReminderSchemaVersion(3)
 
     /**
      * A map of all old [ReviewReminderSchema]s that [ReviewRemindersDatabase.performSchemaMigration] will attempt to migrate old
@@ -130,7 +131,8 @@ object ReviewRemindersDatabase {
     var oldReviewReminderSchemasForMigration: Map<ReviewReminderSchemaVersion, KClass<out ReviewReminderSchema>> =
         mapOf(
             ReviewReminderSchemaVersion(1) to ReviewReminderSchemaV1::class,
-            ReviewReminderSchemaVersion(2) to ReviewReminder::class, // Most up to date version
+            ReviewReminderSchemaVersion(2) to ReviewReminderSchemaV2::class,
+            ReviewReminderSchemaVersion(3) to ReviewReminder::class, // Most up to date version
         )
 
     /**

AnkiDroid/src/main/java/com/ichi2/anki/services/AlarmManagerService.kt

@@ -22,13 +22,16 @@ import android.app.PendingIntent
 import android.content.BroadcastReceiver
 import android.content.Context
 import android.content.Intent
+import androidx.annotation.VisibleForTesting
 import androidx.core.app.PendingIntentCompat
 import androidx.core.content.getSystemService
 import androidx.core.os.BundleCompat
 import com.ichi2.anki.R
 import com.ichi2.anki.common.time.TimeManager
 import com.ichi2.anki.reviewreminders.ReviewReminder
+import com.ichi2.anki.reviewreminders.ReviewReminderScope
 import com.ichi2.anki.reviewreminders.ReviewRemindersDatabase
+import com.ichi2.anki.reviewreminders.upsertReminder
 import com.ichi2.anki.showThemedToast
 import timber.log.Timber
 import java.util.Calendar
@@ -65,7 +68,8 @@ class AlarmManagerService : BroadcastReceiver() {
          * by at much this amount of time. We set it to 10 minutes, which is the minimum allowable duration
          * according to [the docs](https://developer.android.com/reference/android/app/AlarmManager).
          */
-        private val WINDOW_LENGTH_MS: Long = 10.minutes.inWholeMilliseconds
+        @VisibleForTesting
+        val WINDOW_LENGTH_MS: Long = 10.minutes.inWholeMilliseconds
 
         /**
          * Shows error messages if an error occurs when scheduling review reminders via AlarmManager.
@@ -132,6 +136,11 @@ class AlarmManagerService : BroadcastReceiver() {
          * Queues a review reminder to have its notification fired at its specified time. Does not check
          * if the review reminder is enabled or not, the caller must handle this.
          *
+         * If the review reminder has failed to fire a notification at its most recent specified time for some
+         * reason (ex. if the device was off, or if the OS delayed the notification for some reason),
+         * a notification will be fired immediately and no alarm will be immediately scheduled, as the
+         * notification should automatically trigger the scheduling of the next alarm.
+         *
          * Note that this only schedules the next upcoming notification, using [AlarmManager.setWindow]
          * rather than [AlarmManager.setRepeating]. This is because [AlarmManager.setRepeating] sometimes
          * postpones alarm firings for long periods of time, with intervals as long as one hour observed
@@ -164,6 +173,13 @@ class AlarmManagerService : BroadcastReceiver() {
                 ) ?: return
             Timber.v("Pending intent for ${reviewReminder.id} is $pendingIntent")
 
+            if (reviewReminder.shouldImmediatelyFire()) {
+                immediatelyFireNotification(context, reviewReminder)
+                // Once the notification has fired, it will automatically trigger the setting of the next alarm
+                // so we can return immediately
+                return
+            }
+
             val currentTimestamp = TimeManager.time.calendar()
             val alarmTimestamp = currentTimestamp.clone() as Calendar
             alarmTimestamp.apply {
@@ -186,6 +202,37 @@ class AlarmManagerService : BroadcastReceiver() {
             }
         }
 
+        /**
+         * Immediately fires a review reminder notification for a review reminder, which in turn then schedules the next notification.
+         * Used when a review reminder's notification has been delayed and failed to fire for some reason.
+         */
+        private fun immediatelyFireNotification(
+            context: Context,
+            reviewReminder: ReviewReminder,
+        ) {
+            Timber.d("Review reminder ${reviewReminder.id} should have fired already, sending notification immediately")
+
+            // Immediately (redundantly) record this latest routine notification-firing attempt's timestamp
+            // to prevent this from being triggered multiple times in rapid succession
+            reviewReminder.updateLatestNotifTime()
+            when (val scope = reviewReminder.scope) {
+                is ReviewReminderScope.DeckSpecific ->
+                    ReviewRemindersDatabase.editRemindersForDeck(
+                        scope.did,
+                        upsertReminder(reviewReminder),
+                    )
+                is ReviewReminderScope.Global -> ReviewRemindersDatabase.editAllAppWideReminders(upsertReminder(reviewReminder))
+            }
+
+            val immediateNotificationIntent =
+                NotificationService.getIntent(
+                    context,
+                    reviewReminder,
+                    NotificationService.NotificationServiceAction.ScheduleRecurringNotifications,
+                )
+            context.sendBroadcast(immediateNotificationIntent)
+        }
+
         /**
          * Deletes any scheduled notifications for this review reminder. Does not actually delete the
          * review reminder itself from anywhere, only deletes any queued alarms for the review reminder.

AnkiDroid/src/main/java/com/ichi2/anki/services/NotificationService.kt

@@ -20,6 +20,7 @@ import android.content.BroadcastReceiver
 import android.content.Context
 import android.content.Intent
 import android.graphics.Color
+import androidx.annotation.VisibleForTesting
 import androidx.core.app.NotificationCompat
 import androidx.core.app.PendingIntentCompat
 import androidx.core.content.getSystemService
@@ -37,6 +38,8 @@ import com.ichi2.anki.preferences.PENDING_NOTIFICATIONS_ONLY
 import com.ichi2.anki.preferences.sharedPrefs
 import com.ichi2.anki.reviewreminders.ReviewReminder
 import com.ichi2.anki.reviewreminders.ReviewReminderScope
+import com.ichi2.anki.reviewreminders.ReviewRemindersDatabase
+import com.ichi2.anki.reviewreminders.upsertReminder
 import com.ichi2.anki.runGloballyWithTimeout
 import com.ichi2.anki.settings.Prefs
 import com.ichi2.anki.utils.ext.allDecksCounts
@@ -71,7 +74,8 @@ class NotificationService : BroadcastReceiver() {
         /**
          * Extra key for sending a review reminder as an extra to this broadcast receiver.
          */
-        private const val EXTRA_REVIEW_REMINDER = "notification_service_review_reminder"
+        @VisibleForTesting
+        const val EXTRA_REVIEW_REMINDER = "notification_service_review_reminder"
 
         /**
          * Timeout for the process of sending a review reminder notification.
@@ -417,8 +421,20 @@ class NotificationService : BroadcastReceiver() {
                 ) ?: return
             Timber.d("onReceive: ${reviewReminder.id}")
 
-            // Schedule the next instance of this review reminder notification if this is a recurring notification
+            // If this is a recurring notification...
             if (action == NotificationServiceAction.ScheduleRecurringNotifications.actionString) {
+                // Record this latest routine notification-firing attempt's timestamp
+                reviewReminder.updateLatestNotifTime()
+                when (val scope = reviewReminder.scope) {
+                    is ReviewReminderScope.DeckSpecific ->
+                        ReviewRemindersDatabase.editRemindersForDeck(
+                            scope.did,
+                            upsertReminder(reviewReminder),
+                        )
+                    is ReviewReminderScope.Global -> ReviewRemindersDatabase.editAllAppWideReminders(upsertReminder(reviewReminder))
+                }
+
+                // Schedule the next routine notification-firing
                 Timber.d("Scheduling next review reminder notification")
                 AlarmManagerService.scheduleReviewReminderNotification(context, reviewReminder)
             }