fix: retry deferred sessions while foregrounded

Author: ben-kaufman

app/src/main/java/to/bitkit/repositories/PubkyRepo.kt

@@ -148,11 +148,19 @@ class PubkyRepo @Inject constructor(
 
         /** Shortest time between two contact list updates of a background profile refresh. */
         internal val CONTACT_REFRESH_BATCH_WINDOW = 300.milliseconds
+
+        /** Maximum automatic restore attempts during one foreground recovery window. */
+        private const val DEFERRED_RESTORE_ATTEMPTS = 8
+
+        /** Delay after a deferred restore before another attempt may begin. */
+        private val DEFERRED_RESTORE_INTERVAL = 5.seconds
     }
 
     private val scope = appScope(ioDispatcher, TAG)
     private val serviceInitializeMutex = Mutex()
     private val initializeMutex = Mutex()
+    private val deferredRestoreMutex = Mutex()
+    private var deferredRestoreGeneration: Long? = null
     private val completedRestoreVersion = AtomicLong()
     private var completedRestoreSignInGeneration = -1L
     private val loadProfileMutex = Mutex()
@@ -340,6 +348,23 @@ class PubkyRepo @Inject constructor(
         restored
     }
 
+    /** Retries a temporarily unavailable saved session while the caller remains active. */
+    suspend fun retryDeferredSessionRestoration() = withContext(ioDispatcher) {
+        deferredRestoreMutex.withLock {
+            awaitInitialization()
+            repeat(DEFERRED_RESTORE_ATTEMPTS) {
+                val generation = initializeMutex.withLock {
+                    deferredRestoreGeneration?.takeIf { it == signInGeneration.get() }
+                } ?: return@withLock
+                delay(DEFERRED_RESTORE_INTERVAL)
+                if (restoreSession(expectedGeneration = generation)) {
+                    loadIdentityData()
+                    return@withLock
+                }
+            }
+        }
+    }
+
     /**
      * Waits for a usable saved identity, sharing any in-flight restore. Later calls can retry failures.
      * Restoration waits for active identity work and runs in the repository scope, so cancelling the caller does not
@@ -368,9 +393,14 @@ class PubkyRepo @Inject constructor(
         }
     }
 
-    private suspend fun restoreSession(): Boolean {
+    private suspend fun restoreSession(expectedGeneration: Long? = null): Boolean {
         val version = completedRestoreVersion.get()
         return initializeMutex.withLock {
+            if (expectedGeneration != null &&
+                (expectedGeneration != signInGeneration.get() || expectedGeneration != deferredRestoreGeneration)
+            ) {
+                return@withLock false
+            }
             if (completedRestoreVersion.get() != version &&
                 completedRestoreSignInGeneration == signInGeneration.get()
             ) {
@@ -401,6 +431,7 @@ class PubkyRepo @Inject constructor(
                 ensureServiceInitialized(savedSession.getOrNull())
             }.onFailure {
                 Logger.error("Failed to initialize paykit", it, context = TAG)
+                deferredRestoreGeneration = signInGeneration.get().takeIf { _ -> it.isPaykitTemporarilyUnavailable() }
                 if (notifyFailure && it.isPaykitIdentityError() && hasSavedSession()) {
                     _sessionRestorationFailed.update { true }
                 }
@@ -444,6 +475,7 @@ class PubkyRepo @Inject constructor(
                     if (notifyFailure) _sessionRestorationFailed.update { result == InitResult.RestorationFailed }
                 }
             }
+            deferredRestoreGeneration = signInGeneration.get().takeIf { result == InitResult.RestorationDeferred }
             initializationReady.complete(Unit)
             return result is InitResult.Restored
         } finally {

app/src/main/java/to/bitkit/viewmodels/AppViewModel.kt

@@ -423,6 +423,7 @@ class AppViewModel @Inject constructor(
             paykitPaymentRequestRepo.setPaymentSubmissionActive(value)
         }
     private var paykitPaymentRequestPollingJob: Job? = null
+    private var paykitSessionRestoreRetryJob: Job? = null
     private val paymentRequestPresentationRetryAttempts = mutableMapOf<PaykitPaymentRequestId, Int>()
     private val paymentRequestPresentationRetryJobs = mutableMapOf<PaykitPaymentRequestId, Job>()
     private val paymentRequestPresentationCompletionJobs = mutableMapOf<PaykitPaymentRequestId, Job>()
@@ -974,6 +975,7 @@ class AppViewModel @Inject constructor(
         isPaymentRequestPollingStopped = false
         if (paykitPaymentRequestPollingJob?.isActive == true) return
 
+        startPaykitSessionRestoreRetries()
         paykitPaymentRequestPollingJob = viewModelScope.launch {
             if (isOnline.value == ConnectivityState.CONNECTED) pubkyRepo.republishIdentityIfNeeded()
             refreshIncomingPaykitPaymentRequests(messagePriority = Priority.Background)
@@ -1012,6 +1014,17 @@ class AppViewModel @Inject constructor(
         }
     }
 
+    private fun startPaykitSessionRestoreRetries() {
+        if (paykitSessionRestoreRetryJob?.isActive == true) return
+        paykitSessionRestoreRetryJob = viewModelScope.launch {
+            combine(isOnline, isPaykitEnabled) { connectivity, enabled ->
+                connectivity == ConnectivityState.CONNECTED && enabled
+            }.distinctUntilChanged().collectLatest { shouldRetry ->
+                if (shouldRetry && walletRepo.walletExists()) pubkyRepo.retryDeferredSessionRestoration()
+            }
+        }
+    }
+
     private suspend fun refreshIdlePaykitContactEndpoints(expectedIdentity: String?) {
         currentCoroutineContext().ensureActive()
         if (expectedIdentity == null) return
@@ -1061,6 +1074,8 @@ class AppViewModel @Inject constructor(
 
     fun stopPaykitPaymentRequestPolling() {
         isPaymentRequestPollingStopped = true
+        paykitSessionRestoreRetryJob?.cancel()
+        paykitSessionRestoreRetryJob = null
         clearPaymentRequestPreparation()
         paykitPaymentRequestPollingJob?.cancel()
         paykitPaymentRequestPollingJob = null

app/src/test/java/to/bitkit/repositories/PubkyRepoTest.kt

@@ -94,6 +94,7 @@ import kotlin.test.assertSame
 import kotlin.test.assertTrue
 import kotlin.time.Clock
 import kotlin.time.Duration.Companion.milliseconds
+import kotlin.time.Duration.Companion.seconds
 import kotlin.time.ExperimentalTime
 import kotlin.time.Instant
 import com.synonym.paykit.PubkyProfile as SdkPubkyProfile
@@ -2474,6 +2475,139 @@ class PubkyRepoTest : BaseUnitTest() {
         verify(keychain, never()).delete(Keychain.Key.PAYKIT_SESSION.name)
     }
 
+    @Test
+    fun `deferred restoration recovers without another foreground caller`() = test {
+        val restore = stubSavedSessionRestore()
+        restore.answer = { throw PaykitException.SharedStateBusy("shared_state_busy", "Locked") }
+        sut.initialize()
+        clearInvocations(pubkyService, keychain)
+
+        val retry = launch { sut.retryDeferredSessionRestoration() }
+        restore.answer = { VALID_SELF_KEY }
+        advanceTimeBy(5.seconds)
+        runCurrent()
+        retry.join()
+
+        assertEquals(VALID_SELF_KEY, sut.publicKey.value)
+        assertFalse(sut.sessionRestorationFailed.value)
+        verify(pubkyService).importSession("saved_session")
+        verify(pubkyService).contactRecords()
+        verify(keychain, never()).delete(any())
+    }
+
+    @Test
+    fun `deferred restoration bounds repeated failures and permits a later caller`() = test {
+        val restore = stubSavedSessionRestore()
+        restore.answer = { throw PaykitException.SharedStateBusy("shared_state_busy", "Locked") }
+        sut.initialize()
+        clearInvocations(pubkyService)
+
+        sut.retryDeferredSessionRestoration()
+
+        verify(pubkyService, times(8)).importSession("saved_session")
+        assertNull(sut.publicKey.value)
+        assertFalse(sut.sessionRestorationFailed.value)
+        restore.answer = { VALID_SELF_KEY }
+        assertTrue(sut.restoreSessionIfNeeded())
+    }
+
+    @Test
+    fun `deferred restoration shares in-flight work with foreground callers`() = test {
+        val restore = stubSavedSessionRestore()
+        restore.answer = { throw PaykitException.SharedStateBusy("shared_state_busy", "Locked") }
+        sut.initialize()
+        val finishRestore = CompletableDeferred<Unit>()
+        restore.answer = {
+            finishRestore.await()
+            VALID_SELF_KEY
+        }
+        clearInvocations(pubkyService)
+
+        val retry = launch { sut.retryDeferredSessionRestoration() }
+        advanceTimeBy(5.seconds)
+        runCurrent()
+        val duplicate = launch { sut.retryDeferredSessionRestoration() }
+        val foreground = async { sut.awaitIdentityReady() }
+        assertFalse(foreground.isCompleted)
+        finishRestore.complete(Unit)
+
+        assertEquals(PubkyIdentityReadiness.Ready, foreground.await())
+        retry.join()
+        duplicate.join()
+        verify(pubkyService).importSession("saved_session")
+        verify(pubkyService).contactRecords()
+    }
+
+    @Test
+    fun `deferred restoration stops when the identity is removed or replaced`() = test {
+        listOf("wipe", "sign out", "replace").forEachCase({ it }) { action ->
+            resetForCase()
+            val restore = stubSavedSessionRestore()
+            restore.answer = { throw PaykitException.SharedStateBusy("shared_state_busy", "Locked") }
+            sut.initialize()
+            val retry = launch { sut.retryDeferredSessionRestoration() }
+
+            when (action) {
+                "wipe" -> sut.wipeLocalState()
+                "sign out" -> sut.signOut().getOrThrow()
+                "replace" -> authenticateForTesting(VALID_CONTACT_KEY_A, "other_session")
+            }
+            clearInvocations(pubkyService)
+            advanceUntilIdle()
+            retry.join()
+
+            verify(pubkyService, never()).importSession(any())
+            assertEquals(VALID_CONTACT_KEY_A.takeIf { action == "replace" }, sut.publicKey.value)
+        }
+    }
+
+    @Test
+    fun `deferred restoration stops on permanent failure and preserves credentials`() = test {
+        val restore = stubSavedSessionRestore()
+        restore.answer = { throw PaykitException.SharedStateBusy("shared_state_busy", "Locked") }
+        sut.initialize()
+        restore.answer = { throw TestAppError("Revoked") }
+        clearInvocations(pubkyService, keychain)
+
+        sut.retryDeferredSessionRestoration()
+
+        verify(pubkyService).importSession("saved_session")
+        verify(keychain, never()).delete(any())
+        assertNull(sut.publicKey.value)
+    }
+
+    @Test
+    fun `cancelling deferred restoration cancels admission but lets active SDK work finish`() = test {
+        val restore = stubSavedSessionRestore()
+        restore.answer = { throw PaykitException.SharedStateBusy("shared_state_busy", "Locked") }
+        sut.initialize()
+        val finishRestore = CompletableDeferred<Unit>()
+        var completedSdkWork = false
+        restore.answer = {
+            withContext(NonCancellable) {
+                finishRestore.await()
+                completedSdkWork = true
+            }
+            VALID_SELF_KEY
+        }
+        clearInvocations(pubkyService)
+
+        val active = launch { sut.retryDeferredSessionRestoration() }
+        advanceTimeBy(5.seconds)
+        runCurrent()
+        val queued = launch { sut.retryDeferredSessionRestoration() }
+        queued.cancelAndJoin()
+        active.cancel()
+        assertFalse(active.isCompleted)
+        finishRestore.complete(Unit)
+        active.join()
+
+        assertTrue(completedSdkWork)
+        advanceUntilIdle()
+        verify(pubkyService).importSession("saved_session")
+        verify(keychain, never()).delete(Keychain.Key.PAYKIT_SESSION.name)
+    }
+
     @Test
     fun `initialize should complete contacts load after contact fetch failure`() = test {
         val session = "saved_session"

app/src/test/java/to/bitkit/viewmodels/AppViewModelSendFlowTest.kt

@@ -914,6 +914,54 @@ class AppViewModelSendFlowTest : BaseUnitTest() {
         }
     }
 
+    @Test
+    fun `deferred session recovery runs once while foreground online and enabled`() = test {
+        enablePaykitUi()
+        connectivityState.value = ConnectivityState.DISCONNECTED
+        var activeRetries = 0
+        var attempts = 0
+        whenever(pubkyRepo.retryDeferredSessionRestoration()).doSuspendableAnswer {
+            attempts++
+            activeRetries++
+            try {
+                awaitCancellation()
+            } finally {
+                activeRetries--
+            }
+        }
+
+        sut.startPaykitPaymentRequestPolling()
+        assertEquals(0, attempts)
+        connectivityState.value = ConnectivityState.CONNECTED
+        runCurrent()
+        assertEquals(1, attempts)
+        assertEquals(1, activeRetries)
+        sut.startPaykitPaymentRequestPolling()
+        assertEquals(1, attempts)
+
+        connectivityState.value = ConnectivityState.DISCONNECTED
+        runCurrent()
+        assertEquals(0, activeRetries)
+        connectivityState.value = ConnectivityState.CONNECTED
+        runCurrent()
+        assertEquals(2, attempts)
+        isPaykitEnabled.value = false
+        runCurrent()
+        assertEquals(0, activeRetries)
+
+        isPaykitEnabled.value = true
+        runCurrent()
+        assertEquals(3, attempts)
+        sut.stopPaykitPaymentRequestPolling()
+        runCurrent()
+        assertEquals(0, activeRetries)
+        clearInvocations(pubkyRepo)
+        connectivityState.value = ConnectivityState.DISCONNECTED
+        connectivityState.value = ConnectivityState.CONNECTED
+        runCurrent()
+        verify(pubkyRepo, never()).retryDeferredSessionRestoration()
+    }
+
     @Test
     fun `foreground maintenance retries a missing session until restored`() = test {
         enablePaykitUi()

journeys/paykit-clock-changes.md

@@ -38,5 +38,8 @@ Network fault injection is not provided by the journey capability table. Use a d
 3. Re-enable connectivity while leaving Bitkit open. Verify that the same identity and contact list recover without signing out or restarting the app when the saved session or adopted Ring credential is still available. If the Ring credential is unavailable, select the same identity again from the normal identity choice flow.
 4. Repeat the failed startup and restore connectivity while Bitkit is backgrounded. Return to the foreground from a profile/contact screen and verify the same recovery. Resume must work from any screen, not only Home.
 5. Start adopting a Ring identity while recovery is pending. Verify that automatic restoration does not replace the selected identity. Explicit sign-out or wallet reset must not be undone by a pending restoration.
+6. While online, use an isolated shared-state lock holder to make a saved-session restore return temporarily unavailable. Keep Bitkit in the foreground without navigating, reconnecting, or resuming it. Release the held lock during the short retry window and verify recovery without another action. Android makes up to eight retries with a five-second delay between completed attempts; SDK work and safety waits can take additional time. After this window, the existing maintenance and foreground/network triggers remain available. Backgrounding the app or disabling Paykit must stop queued retries, without interrupting an active SDK write. Repeat with a permanent credentials failure and verify it does not enter this short retry loop.
 
 Both platforms retry automatically on connectivity restoration and app resume. A valid saved session must recover without a new authorization. Android can also recover with an available adopted Ring credential.
+
+The controlled lock-holder check needs a separate fixture and is not established by the unit tests for retry scheduling.