Skip to content

StreamVault is a TV-first free IPTV player for Android TV built with Kotlin, Jetpack Compose, Room, Hilt, and Media3.

Coalesce completed Xtream primary recovery after foreground imports

David Nashash2af03f5149e8
diff --git a/data/src/main/java/com/streamvault/data/sync/ProviderSyncPorts.kt b/data/src/main/java/com/streamvault/data/sync/ProviderSyncPorts.kt
index cf936bf1..babef5ea 100644
--- a/data/src/main/java/com/streamvault/data/sync/ProviderSyncPorts.kt
+++ b/data/src/main/java/com/streamvault/data/sync/ProviderSyncPorts.kt
@@ -12,6 +12,10 @@ import kotlinx.coroutines.flow.Flow
interface ProviderSyncCommands {
fun currentSyncState(providerId: Long): SyncState
+ /** Resume queued primary work; implementations may coalesce an already completed catalog. */
+ suspend fun resumePrimaryCatalog(providerId: Long, trackInitialLiveOnboarding: Boolean): Result<Unit> =
+ sync(providerId, force = false, trackInitialLiveOnboarding = trackInitialLiveOnboarding)
+
suspend fun sync(
providerId: Long,
force: Boolean = false,
diff --git a/data/src/main/java/com/streamvault/data/sync/ProviderSyncWorker.kt b/data/src/main/java/com/streamvault/data/sync/ProviderSyncWorker.kt
index 5c5b1b69..9a6c0764 100644
--- a/data/src/main/java/com/streamvault/data/sync/ProviderSyncWorker.kt
+++ b/data/src/main/java/com/streamvault/data/sync/ProviderSyncWorker.kt
@@ -232,9 +232,8 @@ class ProviderSyncWorker(
onboardingDao = entryPoint.xtreamLiveOnboardingDao()
)
val result = if (requestedProviderId == provider.id) {
- entryPoint.syncCommands().sync(
+ entryPoint.syncCommands().resumePrimaryCatalog(
provider.id,
- force = false,
trackInitialLiveOnboarding = trackInitialLiveOnboarding
)
} else if (provider.type == ProviderType.XTREAM_CODES) {
@@ -652,9 +651,8 @@ class ProviderSyncWorker(
): com.streamvault.domain.model.Result<Unit> {
val now = System.currentTimeMillis()
if (shouldTrackInitialLiveOnboarding(provider, entryPoint.xtreamLiveOnboardingDao())) {
- return entryPoint.syncCommands().sync(
+ return entryPoint.syncCommands().resumePrimaryCatalog(
provider.id,
- force = false,
trackInitialLiveOnboarding = true
)
}
diff --git a/data/src/main/java/com/streamvault/data/sync/SyncManager.kt b/data/src/main/java/com/streamvault/data/sync/SyncManager.kt
index ac47c739..67698e9f 100644
--- a/data/src/main/java/com/streamvault/data/sync/SyncManager.kt
+++ b/data/src/main/java/com/streamvault/data/sync/SyncManager.kt
@@ -1162,12 +1162,47 @@ class SyncManager @Inject constructor(
providerOverride: Provider?,
afterCatalogApply: (suspend () -> Unit)?,
bootstrap: Boolean
- ): com.streamvault.domain.model.Result<Unit> = withProviderLock(providerId) lock@{
+ ): com.streamvault.domain.model.Result<Unit> = syncProviderInternal(
+ providerId, force, movieFastSyncOverride, epgSyncModeOverride, onProgress,
+ trackInitialLiveOnboarding, providerOverride, afterCatalogApply, bootstrap
+ )
+
+ override suspend fun resumePrimaryCatalog(providerId: Long, trackInitialLiveOnboarding: Boolean): Result<Unit> =
+ syncProviderInternal(providerId, false, null, null, null, trackInitialLiveOnboarding, null, null, false, resumeOnly = true)
+
+ private suspend fun syncProviderInternal(
+ providerId: Long,
+ force: Boolean,
+ movieFastSyncOverride: Boolean?,
+ epgSyncModeOverride: ProviderEpgSyncMode?,
+ onProgress: ((String) -> Unit)?,
+ trackInitialLiveOnboarding: Boolean,
+ providerOverride: Provider?,
+ afterCatalogApply: (suspend () -> Unit)?,
+ bootstrap: Boolean,
+ resumeOnly: Boolean = false
+ ): Result<Unit> = withProviderLock(providerId) lock@{
var progressSession: SyncProgressSession? = null
try {
val providerEntity = providerDao.getById(providerId)
?: return@lock com.streamvault.domain.model.Result.error("Provider $providerId not found")
+ if (resumeOnly) Log.i(TAG, "Primary resume provider=$providerId active=${providerEntity.isActive} status=${providerEntity.status}")
+ if (resumeOnly && providerEntity.type == ProviderType.XTREAM_CODES &&
+ providerEntity.status in setOf(com.streamvault.domain.model.ProviderStatus.ACTIVE, com.streamvault.domain.model.ProviderStatus.PARTIAL) &&
+ xtreamLiveOnboardingDao.getIncompleteByProvider(providerId) == null
+ ) {
+ val metadata = syncMetadataRepository.getMetadata(providerId)
+ if (metadata?.lastSyncStatus == "SUCCESS" &&
+ !ContentCachePolicy.shouldRefresh(metadata.lastLiveSuccess, ContentCachePolicy.CATALOG_TTL_MILLIS, System.currentTimeMillis()) &&
+ metadata.lastLiveSync <= metadata.lastLiveSuccess &&
+ channelDao.countByProvider(providerId) == metadata.liveCount
+ ) {
+ Log.i(TAG, "Xtream primary resume coalesced provider=$providerId")
+ return@lock Result.success(Unit)
+ }
+ }
+
require(providerOverride == null || providerOverride.id == providerId) {
"Provider override must match the requested provider ID."
}
diff --git a/data/src/test/java/com/streamvault/data/sync/SyncManagerTest.kt b/data/src/test/java/com/streamvault/data/sync/SyncManagerTest.kt
index bfa05782..2fd4b17b 100644
--- a/data/src/test/java/com/streamvault/data/sync/SyncManagerTest.kt
+++ b/data/src/test/java/com/streamvault/data/sync/SyncManagerTest.kt
@@ -774,6 +774,85 @@ class SyncManagerTest {
assertThat(state!!.message).isNotEmpty()
}
+ @Test
+ fun `primary resume waiting behind foreground sync rechecks completion under the lock`() = runTest {
+ val mgr = buildManager(providerEntity = sampleProvider().copy(status = com.streamvault.domain.model.ProviderStatus.ACTIVE))
+ stubXtreamLiveCatalog()
+ stubXtreamEmptyVodAndSeriesCategories()
+ org.mockito.kotlin.whenever(channelDao.countByProvider(1)).thenReturn(1)
+ val entered = CompletableDeferred<Unit>()
+ val release = java.util.concurrent.CountDownLatch(1)
+ val foreground = async(kotlinx.coroutines.Dispatchers.Default) {
+ mgr.sync(1L, onProgress = { message ->
+ if (message == "Connecting to server...") {
+ entered.complete(Unit)
+ check(release.await(5, java.util.concurrent.TimeUnit.SECONDS))
+ }
+ })
+ }
+ try {
+ kotlinx.coroutines.withContext(kotlinx.coroutines.Dispatchers.Default) {
+ withTimeout(5000) { entered.await() }
+ }
+ val resume = async(start = kotlinx.coroutines.CoroutineStart.UNDISPATCHED) { mgr.resumePrimaryCatalog(1, false) }
+ release.countDown()
+ assertThat(foreground.await().isSuccess).isTrue()
+ assertThat(resume.await().isSuccess).isTrue()
+ assertThat(xtreamBackend.requestedActions.count { it == "get_live_streams" }).isEqualTo(1)
+ } finally {
+ release.countDown()
+ }
+ }
+
+ @Test
+ fun `resume coalesces complete primary work before transitional provider status is finalized`() = runTest {
+ val mgr = buildManager(providerEntity = sampleProvider().copy(status = com.streamvault.domain.model.ProviderStatus.PARTIAL, isActive = false))
+ val now = System.currentTimeMillis()
+ syncMetadataRepo.updateMetadata(SyncMetadata(providerId = 1, lastLiveSync = now, lastLiveSuccess = now,
+ liveCount = 1, lastSyncStatus = "SUCCESS"))
+ org.mockito.kotlin.whenever(channelDao.countByProvider(1)).thenReturn(1)
+ assertThat(mgr.resumePrimaryCatalog(1, true).isSuccess).isTrue()
+ assertThat(xtreamBackend.requestedActions).isEmpty()
+ }
+
+ @Test
+ fun `queued primary resume coalesces a fresh successful complete catalog`() = runTest {
+ val mgr = buildManager(providerEntity = sampleProvider().copy(status = com.streamvault.domain.model.ProviderStatus.ACTIVE))
+ val now = System.currentTimeMillis()
+ syncMetadataRepo.updateMetadata(SyncMetadata(providerId = 1, lastLiveSync = now, lastLiveSuccess = now,
+ liveCount = 1, lastSyncStatus = "SUCCESS"))
+ org.mockito.kotlin.whenever(channelDao.countByProvider(1)).thenReturn(1)
+ val result = mgr.resumePrimaryCatalog(1, trackInitialLiveOnboarding = true)
+ assertThat(result.isSuccess).isTrue()
+ assertThat(xtreamBackend.requestedActions).isEmpty()
+ }
+
+ @Test
+ fun `queued primary resume does not coalesce an incomplete persisted catalog`() = runTest {
+ val mgr = buildManager(providerEntity = sampleProvider().copy(status = com.streamvault.domain.model.ProviderStatus.ACTIVE))
+ val now = System.currentTimeMillis()
+ syncMetadataRepo.updateMetadata(SyncMetadata(providerId = 1, lastLiveSync = now, lastLiveSuccess = now,
+ liveCount = 2, lastSyncStatus = "SUCCESS"))
+ org.mockito.kotlin.whenever(channelDao.countByProvider(1)).thenReturn(1)
+ stubXtreamLiveCatalog()
+ stubXtreamEmptyVodAndSeriesCategories()
+ mgr.resumePrimaryCatalog(1, trackInitialLiveOnboarding = false)
+ assertThat(xtreamBackend.requestedActions).contains("get_live_streams")
+ }
+
+ @Test
+ fun `queued primary resume does not coalesce a failed previous attempt`() = runTest {
+ val mgr = buildManager(providerEntity = sampleProvider().copy(status = com.streamvault.domain.model.ProviderStatus.ACTIVE))
+ val now = System.currentTimeMillis()
+ syncMetadataRepo.updateMetadata(SyncMetadata(providerId = 1, lastLiveSync = now, lastLiveSuccess = now,
+ liveCount = 1, lastSyncStatus = "FAILED_RETRYABLE"))
+ org.mockito.kotlin.whenever(channelDao.countByProvider(1)).thenReturn(1)
+ stubXtreamLiveCatalog()
+ stubXtreamEmptyVodAndSeriesCategories()
+ mgr.resumePrimaryCatalog(1, trackInitialLiveOnboarding = false)
+ assertThat(xtreamBackend.requestedActions).contains("get_live_streams")
+ }
+
@Test
fun `sync_xtream_withFreshCache_andForceFalse_runs_index_first_shell`() = runTest {
val mgr = buildManager(providerType = ProviderType.XTREAM_CODES)
diff --git a/docs/XTREAM_SYNC_IMPROVEMENT_PLAN.md b/docs/XTREAM_SYNC_IMPROVEMENT_PLAN.md
index 7ed19862..e84feed2 100644
--- a/docs/XTREAM_SYNC_IMPROVEMENT_PLAN.md
+++ b/docs/XTREAM_SYNC_IMPROVEMENT_PLAN.md
@@ -13,6 +13,7 @@ Supporting evidence:
- [Bounded live pipeline implementation](XTREAM_SYNC_PIPELINE_IMPLEMENTATION.md)
- [Database write and search implementation](XTREAM_SYNC_DATABASE_IMPLEMENTATION.md)
- [Live category scheduling implementation](XTREAM_SYNC_CATEGORY_IMPLEMENTATION.md)
+- [Completed primary resume coalescing](XTREAM_SYNC_RESUME_IMPLEMENTATION.md)
The reference implementation provides hypotheses to investigate, not a design
authority or proof of correctness. Choose behavior for this app's measured
@@ -293,6 +294,9 @@ fingerprint costs, SQL live-index projection and trigger-maintained search are
implemented with fresh/migrated Room checks and measured backend improvements.
P5 refilled live-category workers and adaptive pacing are implemented with
cancellation, authentication and Retry-After coverage. P6–P8 remain pending.
+Targeted primary recovery now rechecks completion under the provider lock to
+coalesce already successful foreground imports; its observed duplicate-refresh
+route has regression and fixture coverage.
The new measurements identify writer cost, slow fallback and extra completed
imports during some refresh intervals as remaining priorities. Earlier runs
also showed memory-driven category fallback; the default-strategy gate has not
diff --git a/docs/XTREAM_SYNC_RESUME_IMPLEMENTATION.md b/docs/XTREAM_SYNC_RESUME_IMPLEMENTATION.md
new file mode 100644
index 00000000..8b7a32f5
--- /dev/null
+++ b/docs/XTREAM_SYNC_RESUME_IMPLEMENTATION.md
@@ -0,0 +1,69 @@
+# Coalescing completed Xtream primary recovery work
+
+Targeted recovery previously called full sync unconditionally. Periodic work
+also called full sync when its earlier read found incomplete onboarding. A job
+queued while foreground catalog work was running could acquire the provider
+lock after completion and download the same live lineup again. Measured refresh
+accounts sometimes made three complete bulk requests instead of the expected
+two for initial import plus refresh, roughly doubling refresh latency.
+
+Both recovery routes now call `resumePrimaryCatalog`. SyncManager rechecks persisted
+state after acquiring its provider lock. An Xtream provider can skip
+redundant primary work only when:
+
+- onboarding has no incomplete receipt;
+- the provider is ACTIVE or in the transitional PARTIAL state;
+- the last sync status is SUCCESS;
+- the last live success is fresh under the existing catalog TTL;
+- no newer unsuccessful live attempt is recorded;
+- the actual persisted live count matches metadata.
+
+Failed, partial, stale and incomplete catalogs still run recovery. Initial setup
+can still have an inactive PARTIAL provider row while its successful catalog is
+already committed and the repository is finalizing activation. The metadata
+and onboarding proofs distinguish that transition from an actual partial sync;
+provider activation flags alone do not determine catalog completion.
+Candidate configuration workflows retain their separate generation-aware path.
+Manual full sync and Settings Live refresh retain explicit request semantics,
+including nonforced manual full sync with fresh metadata. Other protocols retain
+their existing full recovery behavior. Successful foreground work already owns
+its durable movie/series/EPG continuations; skipping its duplicate primary import
+does not cancel those jobs.
+
+Regression tests exercise a resume queued behind foreground sync, fresh catalog
+coalescing, incomplete-count recovery, failed-attempt recovery and existing
+manual/worker/workflow behavior. The queued test confirms one live retrieval
+across both callers after the foreground transaction completes.
+The initial-activation test explicitly uses an inactive PARTIAL provider with
+successful complete catalog metadata.
+
+The 10,000-row/100-category emulator run passed all 12 requested samples and
+made exactly 12 complete bulk responses, with exactly two requests per account.
+Report: `build/xtream-sync-performance/20261010T080831597314Z/report.json`.
+Initial median was 5,525 ms and refresh median 5,067 ms. Host unit-test execution
+overlapped part of this run, so these times are not a controlled comparison with
+P4 medians. No duplicate-import refresh tail occurred in the measured accounts.
+This proves the tested path and coverage, not all possible background overlap.
+
+The larger fixture reproduced another necessary handoff: initial provider
+activation had not finalized when the periodic resume acquired the lock.
+The intermediate runs still made three bulk imports, despite fixing the targeted
+route. Their reports are `20261010T081002546566Z`, `20261010T081445540937Z` and
+`20261010T081842264251Z` under the same benchmark directory. Recognizing complete
+catalog metadata while that provider row is transitional fixes the reproduced
+handoff.
+
+Final 50,000-row/200-category report:
+`build/xtream-sync-performance/20261010T082158044977Z/report.json`.
+Exactly two complete bulk responses occurred for initial setup plus refresh;
+both retained 50,000 channels, and cleanup/count assertions passed. Initial setup
+took 25,863 ms and refresh 26,765 ms. The preceding run with the redundant import
+took 25,213/53,129 ms. These are single-sample diagnostics, not release-device
+performance medians. The fixed-format numeric/enum log evidence in
+`resume-proof.log` confirms an inactive PARTIAL provider was coalesced. Setup's
+final sync state was Success.
+
+Large-catalog writer cost remains substantial. This work removes duplicate
+primary retrieval; it does not claim to meet the complete latency target.
+
+AUTO strategy selection and the complete P6 acceptance matrix remain open.