fix: [SDK-4792] guard push subscriptions against transient token-fetch errors

A tokenless, transient FCM/HMS token-fetch error (e.g. -9, -11) could overwrite an
already-SUBSCRIBED push subscription and flip it to unsubscribed on the backend. The
prior guard lived in PushTokenManager using in-memory state that reset on process
restart, so a cold start during an FCM/HMS outage could still persist the error.

- Add SubscriptionStatus.isRetryableTokenError covering the transient FCM/HMS codes
  (-8, -9, -11, -12, -25, -27, -29).
- Add a durable guard in SubscriptionManager.addOrUpdatePushSubscriptionToken that
  ignores a tokenless retryable error when the persisted subscription is already
  SUBSCRIBED with a valid token. Real opt-outs / permission changes are not retryable
  and still downgrade as before.
- Add tests for the guard and the new flag; correct an existing test that paired a
  non-null token with an error status (an impossible production combination).

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: nan-li

OneSignalSDK/onesignal/core/src/main/java/com/onesignal/user/internal/subscriptions/SubscriptionModel.kt

@@ -74,7 +74,33 @@ enum class SubscriptionStatus(val value: Int) {
     ERROR(9999),
     ;
 
+    /**
+     * `true` when this status represents a *transient, retryable* failure to fetch a push token
+     * from FCM/HMS (e.g. a temporary IOException, service-unavailable, or init error)
+     *
+     * A retryable token error means "we momentarily couldn't reach FCM/HMS", not "this device can
+     * no longer receive push". It must therefore never downgrade a subscription that is already
+     * [SUBSCRIBED] with a valid token — the next successful registration recovers the token.
+     */
+    val isRetryableTokenError: Boolean
+        get() = this in RETRYABLE_TOKEN_ERRORS
+
     companion object {
+        /**
+         * Transient, retryable token-fetch failures. These are the statuses that should not
+         * overwrite a healthy push subscription.
+         */
+        private val RETRYABLE_TOKEN_ERRORS =
+            setOf(
+                FIREBASE_FCM_INIT_ERROR, // -8
+                FIREBASE_FCM_ERROR_IOEXCEPTION_SERVICE_NOT_AVAILABLE, // -9
+                FIREBASE_FCM_ERROR_IOEXCEPTION_OTHER, // -11
+                FIREBASE_FCM_ERROR_MISC_EXCEPTION, // -12
+                HMS_TOKEN_TIMEOUT, // -25
+                HMS_API_EXCEPTION_OTHER, // -27
+                FIREBASE_FCM_ERROR_IOEXCEPTION_AUTHENTICATION_FAILED, // -29
+            )
+
         fun fromInt(value: Int): SubscriptionStatus? {
             return SubscriptionStatus.values().firstOrNull { it.value == value }
         }

OneSignalSDK/onesignal/core/src/main/java/com/onesignal/user/internal/subscriptions/impl/SubscriptionManager.kt

@@ -89,6 +89,19 @@ internal class SubscriptionManager(
                 pushSubModel.address = pushToken
             }
 
+            // A temporary token-fetch failure (no token) shouldn't unsubscribe a device that is
+            // already subscribed with a valid token. Keep the current status.
+            val isTransientTokenlessError = pushToken == null && pushTokenStatus.isRetryableTokenError
+            val isAlreadyHealthy =
+                pushSubModel.status == SubscriptionStatus.SUBSCRIBED && pushSubModel.address.isNotEmpty()
+            if (isTransientTokenlessError && isAlreadyHealthy) {
+                Logging.warn(
+                    "SubscriptionManager: ignoring transient push token status $pushTokenStatus " +
+                        "(${pushTokenStatus.value}).",
+                )
+                return
+            }
+
             pushSubModel.status = pushTokenStatus
         }
     }

OneSignalSDK/onesignal/core/src/test/java/com/onesignal/user/internal/subscriptions/SubscriptionManagerTests.kt

@@ -5,6 +5,8 @@ import com.onesignal.common.PIIHasher
 import com.onesignal.common.modeling.ModelChangeTags
 import com.onesignal.common.modeling.ModelChangedArgs
 import com.onesignal.core.internal.application.IApplicationService
+import com.onesignal.debug.LogLevel
+import com.onesignal.debug.internal.logging.Logging
 import com.onesignal.session.internal.session.ISessionService
 import com.onesignal.user.internal.Subscription
 import com.onesignal.user.internal.subscriptions.impl.SubscriptionManager
@@ -24,6 +26,10 @@ import io.mockk.verify
 
 class SubscriptionManagerTests : FunSpec({
 
+    beforeAny {
+        Logging.logLevel = LogLevel.NONE
+    }
+
     test("initializes subscriptions from model store") {
         // Given
         val mockSubscriptionModelStore = mockk<SubscriptionModelStore>()
@@ -182,12 +188,13 @@ class SubscriptionManagerTests : FunSpec({
 
         val subscriptionManager = SubscriptionManager(mockApplicationService, mockSessionService, mockSubscriptionModelStore)
 
-        // When
-        subscriptionManager.addOrUpdatePushSubscriptionToken("pushToken2", SubscriptionStatus.FIREBASE_FCM_ERROR_IOEXCEPTION_OTHER)
+        // When a new token arrives (a successful registration always reports SUBSCRIBED with a
+        // token; an error always reports a null token, never a token paired with an error status)
+        subscriptionManager.addOrUpdatePushSubscriptionToken("pushToken2", SubscriptionStatus.SUBSCRIBED)
 
         // Then
         pushSubscription.address shouldBe "pushToken2"
-        pushSubscription.status shouldBe SubscriptionStatus.FIREBASE_FCM_ERROR_IOEXCEPTION_OTHER
+        pushSubscription.status shouldBe SubscriptionStatus.SUBSCRIBED
     }
 
     test("remove email subscription removes from model store") {
@@ -617,4 +624,172 @@ class SubscriptionManagerTests : FunSpec({
         result shouldNotBe null
         result!!.id shouldBe "subscription1"
     }
+
+    // A transient, tokenless FCM/HMS token-fetch failure (e.g. -9 SERVICE_NOT_AVAILABLE) must not
+    // downgrade a push subscription that is already SUBSCRIBED with a valid cached token. A failed
+    // registration reports a null token alongside the error status, so the cached address is left
+    // intact and persisting the error would spuriously unsubscribe the device on the backend.
+    test("transient tokenless token-fetch error does not downgrade a healthy SUBSCRIBED push subscription") {
+        val retryableErrors =
+            listOf(
+                SubscriptionStatus.FIREBASE_FCM_INIT_ERROR,
+                SubscriptionStatus.FIREBASE_FCM_ERROR_IOEXCEPTION_SERVICE_NOT_AVAILABLE,
+                SubscriptionStatus.FIREBASE_FCM_ERROR_IOEXCEPTION_OTHER,
+                SubscriptionStatus.FIREBASE_FCM_ERROR_MISC_EXCEPTION,
+                SubscriptionStatus.HMS_TOKEN_TIMEOUT,
+                SubscriptionStatus.HMS_API_EXCEPTION_OTHER,
+                SubscriptionStatus.FIREBASE_FCM_ERROR_IOEXCEPTION_AUTHENTICATION_FAILED,
+            )
+
+        for (status in retryableErrors) {
+            // Given a healthy push subscription
+            val pushSubscription = SubscriptionModel()
+            pushSubscription.id = "subscription1"
+            pushSubscription.type = SubscriptionType.PUSH
+            pushSubscription.status = SubscriptionStatus.SUBSCRIBED
+            pushSubscription.optedIn = true
+            pushSubscription.address = "validToken"
+
+            val mockSubscriptionModelStore = mockk<SubscriptionModelStore>()
+            val mockApplicationService = mockk<IApplicationService>()
+            val mockSessionService = mockk<ISessionService>(relaxed = true)
+            every { mockSubscriptionModelStore.subscribe(any()) } just runs
+            every { mockSubscriptionModelStore.list() } returns listOf(pushSubscription)
+
+            val subscriptionManager =
+                SubscriptionManager(mockApplicationService, mockSessionService, mockSubscriptionModelStore)
+
+            // When a failed registration reports a null token alongside the transient error
+            subscriptionManager.addOrUpdatePushSubscriptionToken(null, status)
+
+            // Then the healthy SUBSCRIBED state and cached token are preserved
+            pushSubscription.status shouldBe SubscriptionStatus.SUBSCRIBED
+            pushSubscription.address shouldBe "validToken"
+        }
+    }
+
+    // The guard must be narrow: real opt-outs / permission changes are also tokenless, but they are
+    // not retryable token errors and must continue to downgrade the subscription as before.
+    test("non-retryable tokenless statuses still downgrade a SUBSCRIBED push subscription") {
+        val nonRetryableStatuses =
+            listOf(
+                SubscriptionStatus.NO_PERMISSION,
+                SubscriptionStatus.UNSUBSCRIBE,
+                SubscriptionStatus.DISABLED_FROM_REST_API_DEFAULT_REASON,
+            )
+
+        for (status in nonRetryableStatuses) {
+            // Given a healthy push subscription
+            val pushSubscription = SubscriptionModel()
+            pushSubscription.id = "subscription1"
+            pushSubscription.type = SubscriptionType.PUSH
+            pushSubscription.status = SubscriptionStatus.SUBSCRIBED
+            pushSubscription.optedIn = true
+            pushSubscription.address = "validToken"
+
+            val mockSubscriptionModelStore = mockk<SubscriptionModelStore>()
+            val mockApplicationService = mockk<IApplicationService>()
+            val mockSessionService = mockk<ISessionService>(relaxed = true)
+            every { mockSubscriptionModelStore.subscribe(any()) } just runs
+            every { mockSubscriptionModelStore.list() } returns listOf(pushSubscription)
+
+            val subscriptionManager =
+                SubscriptionManager(mockApplicationService, mockSessionService, mockSubscriptionModelStore)
+
+            // When
+            subscriptionManager.addOrUpdatePushSubscriptionToken(null, status)
+
+            // Then the downgrade is applied
+            pushSubscription.status shouldBe status
+        }
+    }
+
+    test("transient tokenless token-fetch error is persisted when there is no cached token to protect") {
+        // Given a SUBSCRIBED push subscription with no cached token (nothing to protect)
+        val pushSubscription = SubscriptionModel()
+        pushSubscription.id = "subscription1"
+        pushSubscription.type = SubscriptionType.PUSH
+        pushSubscription.status = SubscriptionStatus.SUBSCRIBED
+        pushSubscription.optedIn = true
+        pushSubscription.address = ""
+
+        val mockSubscriptionModelStore = mockk<SubscriptionModelStore>()
+        val mockApplicationService = mockk<IApplicationService>()
+        val mockSessionService = mockk<ISessionService>(relaxed = true)
+        every { mockSubscriptionModelStore.subscribe(any()) } just runs
+        every { mockSubscriptionModelStore.list() } returns listOf(pushSubscription)
+
+        val subscriptionManager =
+            SubscriptionManager(mockApplicationService, mockSessionService, mockSubscriptionModelStore)
+
+        // When
+        subscriptionManager.addOrUpdatePushSubscriptionToken(
+            null,
+            SubscriptionStatus.FIREBASE_FCM_ERROR_IOEXCEPTION_SERVICE_NOT_AVAILABLE,
+        )
+
+        // Then the error is persisted (the guard only protects an already-healthy, tokened subscription)
+        pushSubscription.status shouldBe SubscriptionStatus.FIREBASE_FCM_ERROR_IOEXCEPTION_SERVICE_NOT_AVAILABLE
+    }
+
+    test("transient tokenless token-fetch error is persisted when the subscription is not already SUBSCRIBED") {
+        // Given a push subscription that is already in a non-subscribed state
+        val pushSubscription = SubscriptionModel()
+        pushSubscription.id = "subscription1"
+        pushSubscription.type = SubscriptionType.PUSH
+        pushSubscription.status = SubscriptionStatus.NO_PERMISSION
+        pushSubscription.optedIn = true
+        pushSubscription.address = "validToken"
+
+        val mockSubscriptionModelStore = mockk<SubscriptionModelStore>()
+        val mockApplicationService = mockk<IApplicationService>()
+        val mockSessionService = mockk<ISessionService>(relaxed = true)
+        every { mockSubscriptionModelStore.subscribe(any()) } just runs
+        every { mockSubscriptionModelStore.list() } returns listOf(pushSubscription)
+
+        val subscriptionManager =
+            SubscriptionManager(mockApplicationService, mockSessionService, mockSubscriptionModelStore)
+
+        // When
+        subscriptionManager.addOrUpdatePushSubscriptionToken(
+            null,
+            SubscriptionStatus.FIREBASE_FCM_ERROR_IOEXCEPTION_SERVICE_NOT_AVAILABLE,
+        )
+
+        // Then the status is updated (there is no healthy SUBSCRIBED state to protect)
+        pushSubscription.status shouldBe SubscriptionStatus.FIREBASE_FCM_ERROR_IOEXCEPTION_SERVICE_NOT_AVAILABLE
+    }
+
+    test("SubscriptionStatus.isRetryableTokenError flags exactly the transient token-fetch errors") {
+        // Given the full enum
+        // When filtering by the new flag
+        val retryable = SubscriptionStatus.values().filter { it.isRetryableTokenError }.toSet()
+
+        // Then it is exactly the transient FCM/HMS token-fetch errors and nothing else
+        retryable shouldBe
+            setOf(
+                SubscriptionStatus.FIREBASE_FCM_INIT_ERROR,
+                SubscriptionStatus.FIREBASE_FCM_ERROR_IOEXCEPTION_SERVICE_NOT_AVAILABLE,
+                SubscriptionStatus.FIREBASE_FCM_ERROR_IOEXCEPTION_OTHER,
+                SubscriptionStatus.FIREBASE_FCM_ERROR_MISC_EXCEPTION,
+                SubscriptionStatus.HMS_TOKEN_TIMEOUT,
+                SubscriptionStatus.HMS_API_EXCEPTION_OTHER,
+                SubscriptionStatus.FIREBASE_FCM_ERROR_IOEXCEPTION_AUTHENTICATION_FAILED,
+            )
+    }
+
+    test("SubscriptionStatus.isRetryableTokenError is false for healthy and user-driven statuses") {
+        // SUBSCRIBED, permission/opt-out, and permanent configuration errors must never be treated
+        // as transient, otherwise the guard would mask real subscription state changes.
+        listOf(
+            SubscriptionStatus.SUBSCRIBED,
+            SubscriptionStatus.NO_PERMISSION,
+            SubscriptionStatus.UNSUBSCRIBE,
+            SubscriptionStatus.INVALID_FCM_SENDER_ID,
+            SubscriptionStatus.OUTDATED_GOOGLE_PLAY_SERVICES_APP,
+            SubscriptionStatus.HMS_ARGUMENTS_INVALID,
+            SubscriptionStatus.DISABLED_FROM_REST_API_DEFAULT_REASON,
+            SubscriptionStatus.ERROR,
+        ).forEach { it.isRetryableTokenError shouldBe false }
+    }
 })