[mohamede1945]

Problem

triggerSync(immediately = true) doesn't wait. An app that wants a pull-to-refresh or "Sync now" spinner can't tell when the sync it asked for is over. Watching syncStatus doesn't settle it either: a sync already running finishes first and a follow-up run comes after it, and offline the status keeps alternating between retrying and syncing. quran-ios needs this for pull-to-refresh on Bookmarks and Notes.

Change

• New @NativeCoroutines suspend fun QuranDataService.syncNow(): SyncNowResult. It starts the same manual run as triggerSync(immediately = true): it pushes even while pushes back off, replaces a run waiting to retry, and fetches the profile now. It returns once the caller can stop waiting:
  • Ended(run): the run succeeded, failed with no retries left, or was cancelled. It never only pulls, because the manual run always pushes. run is the same entry syncHistory records.
  • Retrying(failedAt, error, nextAttemptAt): the attempt failed and the run will retry on its own (offline, say), so the caller isn't held through the backoff.
  • SignedOut: no one is signed in, the signed-in account id is unknown, or the session ended before the run reached the server.
  • Unavailable: a logout or reset is running or began during the run, or clear() ran before it started. A clear() during the run returns Ended with a CANCELLED run instead.
• If launch recovery failed, syncNow() logs the failure and rethrows it, like the other callers of awaitInitialization.
• If a sync is already running, the call waits for the run that follows it. Calls made before that run starts all share it. Cancelling the caller stops only the wait, not the sync.
• SyncScheduler gives each call a waiter, which it hands to the next run's first attempt. Cancel, close and logout complete every pending waiter with Unavailable. Only the scheduler's single command loop touches the waiters.
• Behaviour change: an immediate trigger now replaces an automatic run that is due but hasn't fired (periodic, foreground, local change). Before, it kept that timer. The waited run is therefore the manual one. It only joins a run that is itself immediate, such as a sign-in's.
• The scheduler now recovers from an attempt that throws or ends with a stray cancellation: every attempt sends Finished from its finally. Before, such an attempt left the scheduler "running" for good. Periodic sync stopped, and a later syncNow() would wait for a follow-up run that never started. A cancelled attempt's Finished carries the old generation, so it's ignored.
• KDoc, README and the scheduler notes in AGENTS.md describe the new API.

SyncClient.kt is now 533 lines, over the ~500-line guideline. I didn't split it.

Tests

• SyncClientSyncNowTest (new, 9 tests, virtual time, real engine on an in-memory database, mock HTTP):
  • idle → Ended, and an attempt that will retry → Retrying;
  • a final failure, and a call while a retry waits replaces the retry;
  • signed out → SignedOut;
  • a logout during the request or during the run → Unavailable;
  • a close during the run → Ended(CANCELLED);
  • cancelling the caller doesn't stop the run.
• SyncSchedulerTest, 9 new:
  • while a run is in flight, the call waits for the follow-up run, including when the current attempt fails and would retry;
  • calls before the run starts share it;
  • a due local-change run is replaced by an immediate one, while a due sign-in run is shared;
  • cancel or close before the run → Unavailable;
  • an attempt that throws, or ends with a stray cancellation, leaves the scheduler working. These two fail without the finally fallback.
• QuranDataServiceLifecycleTest:
  • a reset → Unavailable;
  • a failed launch recovery rethrows;
  • cancelling the caller during recovery cancels the call;
  • clear() before the run → Unavailable.
• Integration scenario OBS-05: a sync now returns the succeeded run, matching the history and the server.
• ./gradlew :sync-pipelines:allTests :umbrella:assembleSharedDebugXCFramework passes: 453 JVM, 150 Android host and 150 iOS simulator tests.

Two independent Opus reviews ran: one on the first version, one on the follow-up fixes. Neither left a must-fix or should-fix. A third review checked the final trim of comments and tests.

Consumers

• mobile-sync-spm: feat: wrap syncNow for a pull-to-refresh that waits for the sync mobile-sync-spm#53 wraps this as MobileSyncDataService.syncNow() async throws -> MobileSyncNowResult. It needs the release that includes this change.
• quran-ios: feat(sync): add pull-to-refresh to Bookmarks and Notes quran-ios#1279 uses it for pull-to-refresh on Bookmarks and Notes. I checked it end to end on a simulator signed in to prelive, against an XCFramework built from this branch.
• quran_android: nothing changes unless it adopts syncNow. The only behaviour change is the timer replacement above, which affects triggerSync(immediately = true) only when an automatic run is already due.

🤖 Generated with Claude Code