@kesha-antonov/react-native-background-downloader 4.5.3 → 4.5.5

package/README.md

@@ -15,14 +15,14 @@
 <h1 align="center">React Native Background Downloader</h1>
 
 <p align="center">
-  Download and upload large files on iOS & Android — even when your app is in the background or terminated.
+  Download and upload large files on iOS & Android — even when your app is in the background or terminated by the OS.
 </p>
 
 ---
 
 ## ✨ Features
 
-- 📥 **Background Downloads** - Downloads continue even when app is in background or terminated
+- 📥 **Background Downloads** - Downloads continue even when app is in background or terminated by the OS
 - 📤 **Background Uploads** - Upload files reliably in the background
 - ⏸️ **Pause/Resume** - Full pause and resume support on both iOS and Android
 - 🔄 **Re-attach to Downloads** - Reconnect to ongoing downloads after app restart
@@ -37,7 +37,7 @@
 **The Problem:** Standard network requests in React Native are tied to your app's lifecycle. When the user switches to another app or the OS terminates your app to free memory, your downloads stop. For small files this is fine, but for large files (videos, podcasts, documents) this creates a frustrating user experience.
 
 **The Solution:** Both iOS and Android provide system-level APIs for background file transfers:
-- **iOS:** [`NSURLSession`](https://developer.apple.com/documentation/foundation/url_loading_system/downloading_files_in_the_background) - handles downloads in a separate process, continuing even after your app is terminated
+- **iOS:** [`NSURLSession`](https://developer.apple.com/documentation/foundation/url_loading_system/downloading_files_in_the_background) - handles downloads in a separate process, continuing even after your app is terminated by the OS. Note: if the user explicitly force-kills the app via the App Switcher, iOS cancels all background tasks — this is an iOS system limitation that cannot be overridden
 - **Android:** A combination of [`DownloadManager`](https://developer.android.com/reference/android/app/DownloadManager) for system-managed downloads, [Foreground Services](https://developer.android.com/develop/background-work/services/foreground-services) for pause/resume support, and [MMKV](https://github.com/Tencent/MMKV) for persistent state storage
 
 **The Challenge:** These APIs are powerful but complex. Downloads run in a separate process, so your app might restart from scratch while downloads are still in progress. Keeping your UI in sync with background downloads requires careful state management.
@@ -53,6 +53,7 @@
 - [📦 Installation](#-installation)
   - [Expo Projects](#expo-projects)
   - [Bare React Native Projects](#bare-react-native-projects)
+    - [MMKV version comparison](#mmkv-version-comparison)
 - [🚀 Usage](#-usage)
   - [Downloading a file](#downloading-a-file)
   - [Re-Attaching to background tasks](#re-attaching-to-background-tasks)
@@ -113,7 +114,7 @@ export default {
   expo: {
     plugins: [
       ["@kesha-antonov/react-native-background-downloader", {
-        mmkvVersion: "2.2.4",  // Customize MMKV version on Android
+        mmkvVersion: "1.3.16",  // Customize MMKV version on Android
         skipMmkvDependency: true  // Skip if you want to add MMKV manually
       }]
     ]
@@ -123,8 +124,8 @@ export default {
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `mmkvVersion` | string | `'2.2.4'` | The version of [MMKV](https://github.com/Tencent/MMKV/releases) to use on Android. |
-| `skipMmkvDependency` | boolean | `false` | Skip adding MMKV dependency. Set to `true` if you're using [react-native-mmkv](https://github.com/mrousavy/react-native-mmkv) to avoid duplicate class errors. The plugin auto-detects `react-native-mmkv` but you can use this option to explicitly skip. |
+| `mmkvVersion` | string | `'1.3.16'` | The version of [MMKV](https://github.com/Tencent/MMKV/releases) to use on Android. See [MMKV version comparison](#mmkv-version-comparison) for details. |
+| `skipMmkvDependency` | boolean | `false` | Skip adding MMKV dependency. Set to `true` if you're using [react-native-mmkv](https://github.com/mrousavy/react-native-mmkv) to avoid duplicate class errors. The plugin auto-detects `react-native-mmkv` but you can use this option to explicitly skip. See [MMKV version comparison](#mmkv-version-comparison). |
 
 </details>
 
@@ -214,11 +215,29 @@ Add MMKV to your `android/app/build.gradle`:
 
 ```gradle
 dependencies {
-    implementation 'com.tencent:mmkv-shared:2.2.4'
+    implementation 'com.tencent:mmkv-shared:1.3.16'
 }
 ```
 
-> **Note:** If you're already using [react-native-mmkv](https://github.com/mrousavy/react-native-mmkv) in your project, skip this step — it already includes MMKV.
+> **Note:** If you're already using [react-native-mmkv](https://github.com/mrousavy/react-native-mmkv) in your project, skip this step — it already includes MMKV. Note that `react-native-mmkv` v4.x uses [Margelo's fork of MMKV](https://github.com/margelo/MMKV) (`io.github.zhongwuzw:mmkv`) which re-adds armeabi-v7a (32-bit ARM) support that was dropped in the official MMKV 2.x release.
+
+> **⚠️ armeabi-v7a (32-bit ARM) users:** MMKV 2.x dropped 32-bit ABI support (since v2.0.0). If you need armeabi-v7a support and get a CMake error like `No compatible library found for //mmkv/mmkv`, use the MMKV 1.3.x LTS series instead — it supports both armeabi-v7a **and** 16KB page sizes (since v1.3.14):
+> ```gradle
+> dependencies {
+>     implementation 'com.tencent:mmkv-shared:1.3.16'
+> }
+> ```
+
+#### MMKV version comparison
+
+| Dependency | armeabi-v7a (32-bit) | arm64-v8a | 16KB page size | Recommended for |
+|---|:---:|:---:|:---:|---|
+| `com.tencent:mmkv-shared:1.3.16` (**default**) | ✅ | ✅ | ✅ (since 1.3.14) | Most apps — broadest device coverage |
+| `com.tencent:mmkv-shared:2.x` | ❌ | ✅ | ✅ | 64-bit only apps (no legacy devices) |
+| `io.github.zhongwuzw:mmkv:2.3.0` ([Margelo fork](https://github.com/margelo/MMKV)) | ✅ | ✅ | ✅ | Used automatically by `react-native-mmkv` v4.x — skip manual dependency |
+| `react-native-mmkv` (already in project) | ✅ | ✅ | ✅ | If you already use `react-native-mmkv` — skip Step 4 entirely |
+
+**TL;DR:** Use the default `1.3.16`. If you already have `react-native-mmkv` in your project, skip Step 4.
 
 ## 🚀 Usage
 
@@ -504,6 +523,39 @@ const task = createDownloadTask({
 
 </details>
 
+<details>
+<summary><strong>iOS Data Protection (downloading while the device is locked)</strong></summary>
+
+On iOS, files protected with `NSFileProtectionComplete` cannot be written while the device is locked. Since a background download can finish while the screen is locked, the library saves files with **`completeUntilFirstUserAuthentication`** by default - writable while locked after the first unlock since boot - and, if a save still can't happen because the device is locked, it stages the bytes and finishes the save (emitting `complete`) when the device is next unlocked.
+
+You usually don't need to change this. If your app has stricter security requirements you can raise the protection level globally or per task (iOS only - ignored on Android):
+
+```javascript
+import { setConfig, createDownloadTask, directories } from '@kesha-antonov/react-native-background-downloader'
+
+// Global default for all downloads
+setConfig({
+  iosDataProtection: 'completeUntilFirstUserAuthentication', // default
+})
+
+// Per-download override
+const task = createDownloadTask({
+  id: 'secret-doc',
+  url: 'https://example.com/secret.pdf',
+  destination: `${directories.documents}/secret.pdf`,
+  iosDataProtection: 'complete', // strongest; note: won't be writable while locked before first unlock
+})
+```
+
+| Value | NSFileProtection level | Notes |
+|-------|------------------------|-------|
+| `'completeUntilFirstUserAuthentication'` | `NSFileProtectionCompleteUntilFirstUserAuthentication` | **Default.** Accessible after the first unlock since boot - recommended for background downloads |
+| `'complete'` | `NSFileProtectionComplete` | Strongest. File is inaccessible whenever the device is locked |
+| `'completeUnlessOpen'` | `NSFileProtectionCompleteUnlessOpen` | Accessible while open, even if the device locks afterward |
+| `'none'` | `NSFileProtectionNone` | No protection |
+
+</details>
+
 <details>
 <summary><strong>Enabling debug logs</strong></summary>
 
@@ -836,6 +888,8 @@ This can happen with slow-responding servers. The library automatically adds kee
 <summary><strong>Duplicate class errors with react-native-mmkv (Android)</strong></summary>
 
 If you're using `react-native-mmkv`, you don't need to add the MMKV dependency manually - it's already included. The library uses `compileOnly` to avoid conflicts.
+
+`react-native-mmkv` v4.x uses [Margelo's fork of MMKV](https://github.com/margelo/MMKV) (`io.github.zhongwuzw:mmkv`) which re-adds armeabi-v7a (32-bit ARM) support, so you have full ABI coverage including 32-bit devices when using `react-native-mmkv`.
 </details>
 
 <details>
@@ -844,6 +898,18 @@ If you're using `react-native-mmkv`, you don't need to add the MMKV dependency m
 This was fixed in v4.4.0. Update to the latest version. If you're not using `react-native-mmkv`, add `pod 'MMKV', '>= 1.0.0'` to your Podfile.
 </details>
 
+<details>
+<summary><strong>Downloads "don't work" when the iOS screen is locked</strong></summary>
+
+On iOS the actual transfer is handed to the system `nsurlsessiond` daemon and **keeps running while the app is suspended and the screen is locked** - this library already configures the background session correctly (`discretionary = NO`, `sessionSendsLaunchEvents = YES`). If it looks like downloads stop when locked, check these in order:
+
+1. **Did you force-quit the app?** If the user swipes the app away in the app switcher, iOS halts *that app's* background transfers until it's relaunched. This is an OS policy and cannot be worked around by any library.
+2. **You won't get live `progress` events while locked.** Your JavaScript isn't running while the app is suspended, so `begin` / `progress` / `complete` callbacks fire when the app resumes or is relaunched - not in real time. Re-attach with `getExistingDownloadTasks()` on launch.
+3. **AppDelegate wiring.** Make sure `handleEventsForBackgroundURLSession` is implemented (see [Installation](#-installation)) and that you call `completeHandler(jobId)` from JS in your `complete`/`error` handlers, or iOS will throttle future background time.
+4. **Data Protection (the one this library handles).** On a passcoded, locked device, files protected with `NSFileProtectionComplete` can't be written, so a download that *finishes* while locked could previously fail to save. The library now writes the file with `NSFileProtectionCompleteUntilFirstUserAuthentication` by default (writable while locked after the first unlock since boot), and if the move still can't happen because the device is locked it stages the bytes and completes the save automatically when the device is next unlocked - emitting `complete` then. You can change the level with `setConfig({ iosDataProtection })` or per task (see Advanced Configuration).
+5. **Test on a real device.** The iOS Simulator's background-transfer behavior is unreliable; verify on hardware.
+</details>
+
 <details>
 <summary><strong>Downloads not resuming after app restart</strong></summary>
 

package/android/build.gradle

@@ -36,6 +36,8 @@ android {
         versionName '1.0'
 
         // Support for 16KB memory page sizes (Android 15+)
+        // Note: MMKV 2.x dropped armeabi-v7a support. If your app targets armeabi-v7a,
+        // downgrade to MMKV 1.x in your app's build.gradle (see README for details).
         ndk {
             abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
         }
@@ -78,8 +80,8 @@ dependencies {
     // MMKV dependency for persistent download state storage
     // Uses compileOnly to avoid duplicate class errors when app also uses react-native-mmkv
     // The app must provide MMKV dependency (either directly or via react-native-mmkv)
-    // MMKV 2.0.0+ is required for 16KB memory page size support (Android 15+)
-    compileOnly 'com.tencent:mmkv-shared:2.0.0'
+    // MMKV 1.3.14+ supports both armeabi-v7a (32-bit) and 16KB page sizes (Android 15+)
+    compileOnly 'com.tencent:mmkv-shared:1.3.16'
 
     implementation 'com.google.code.gson:gson:2.12.1'
 }

package/android/src/main/java/com/eko/DownloadConstants.kt

@@ -34,6 +34,9 @@ object DownloadConstants {
     /** Interval for throttling progress log messages (milliseconds) */
     const val PROGRESS_LOG_INTERVAL_MS = 500L
 
+    /** Interval for persisting in-progress resumable download recovery snapshots (milliseconds) */
+    const val RECOVERY_SNAPSHOT_INTERVAL_MS = 2_000L
+
     // ========== HTTP Headers ==========
 
     /** Keep-Alive header value for connection pooling */

package/android/src/main/java/com/eko/Downloader.kt

@@ -95,6 +95,9 @@ class Downloader(private val context: Context, private val storageManager: com.e
         pausedDownloads.putAll(loadedPaused)
       }
     }
+    // Recover any resumable downloads that were active when the app was last
+    // force-stopped (their foreground service and in-memory state were lost).
+    restoreRecoverableDownloads()
   }
 
   private fun bindToService() {
@@ -111,8 +114,18 @@ class Downloader(private val context: Context, private val storageManager: com.e
 
   /**
    * Set the download listener for resumable downloads.
+   * Also sets the UIDT listener on Android 14+ so that ongoing UIDT jobs
+   * (e.g. ones that survived app termination) can forward events to JS after
+   * the app is reopened.
    */
   fun setResumableDownloadListener(listener: ResumableDownloader.DownloadListener) {
+    // For UIDT jobs (Android 14+), set the listener directly on the registry.
+    // This reconnects event forwarding after app restart when UIDT jobs are
+    // already running but UIDTJobRegistry.downloadListener was null in the
+    // fresh process.
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+      UIDTDownloadJobService.downloadListener = listener
+    }
     executeWhenServiceReady {
       downloadService?.setDownloadListener(listener)
     }
@@ -461,6 +474,95 @@ class Downloader(private val context: Context, private val storageManager: com.e
     return pausedDownloads.toMap()
   }
 
+  /**
+   * Get all in-progress resumable downloads tracked by the foreground service.
+   * On Android 14+ active downloads run as UIDT jobs instead and are not included here.
+   */
+  fun getActiveResumableDownloads(): Map<String, ResumableDownloader.DownloadState> {
+    return resumableDownloader.getActiveDownloads()
+  }
+
+  /**
+   * Persist a recovery snapshot for an in-progress resumable download so it can be
+   * recovered after a force-stop. Called throttled from progress callbacks.
+   * The byte counter stored here is advisory only - on recovery the resume offset
+   * is recomputed from the actual on-disk file length to avoid corruption.
+   */
+  fun saveActiveDownloadSnapshot(
+    configId: String,
+    url: String,
+    destination: String,
+    headers: Map<String, String>,
+    bytesDownloaded: Long,
+    bytesTotal: Long,
+    metadata: String = "{}"
+  ) {
+    storageManager?.saveActiveDownload(
+      PausedDownloadInfo(
+        configId = configId,
+        url = url,
+        destination = destination,
+        headers = headers,
+        bytesDownloaded = bytesDownloaded,
+        bytesTotal = bytesTotal,
+        metadata = metadata
+      )
+    )
+  }
+
+  /**
+   * Remove the recovery snapshot for a download (on complete, error, pause or stop).
+   */
+  fun removeActiveDownloadSnapshot(configId: String) {
+    storageManager?.removeActiveDownload(configId)
+  }
+
+  /**
+   * Recover resumable downloads that were active when the app was force-stopped.
+   * Moves their snapshots into the paused-downloads map (so getExistingDownloadTasks
+   * surfaces them and resumeTask works), recomputing the resume offset from the
+   * partial file's actual length. Snapshots without a partial file on disk are dropped.
+   */
+  private fun restoreRecoverableDownloads() {
+    val sm = storageManager ?: return
+    val recoverable = sm.loadActiveDownloads()
+    if (recoverable.isEmpty()) {
+      return
+    }
+
+    var recoveredCount = 0
+    for ((configId, info) in recoverable) {
+      // Skip if it is already tracked as paused, or still running as a UIDT job.
+      if (pausedDownloads.containsKey(configId)) {
+        continue
+      }
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE &&
+        UIDTDownloadJobService.isActiveJob(configId)
+      ) {
+        continue
+      }
+
+      val destFile = File(info.destination)
+      val fileLength = if (destFile.exists()) destFile.length() else 0L
+      if (fileLength <= 0L) {
+        // Nothing downloaded yet - nothing to resume from.
+        continue
+      }
+
+      // Use the on-disk length as the authoritative resume offset.
+      pausedDownloads[configId] = info.copy(bytesDownloaded = fileLength)
+      recoveredCount++
+    }
+
+    if (recoveredCount > 0) {
+      savePausedDownloads()
+      RNBackgroundDownloaderModuleImpl.logD(TAG, "Recovered $recoveredCount interrupted resumable download(s) after force-stop")
+    }
+
+    // Clear the active store now that recovery has been processed.
+    sm.clearActiveDownloads()
+  }
+
   /**
    * Persist paused downloads to storage.
    */

package/android/src/main/java/com/eko/RNBackgroundDownloaderModuleImpl.kt

@@ -160,6 +160,10 @@ class RNBackgroundDownloaderModuleImpl(private val reactContext: ReactApplicatio
   // Map to store metadata for paused downloads
   private val configIdToMetadata = mutableMapOf<String, String>()
 
+  // Last time (ms) a recovery snapshot was persisted for a resumable download,
+  // used to throttle snapshot writes from the frequent progress callbacks.
+  private val configIdToLastSnapshotMs = mutableMapOf<String, Long>()
+
   /**
    * Get the event emitter, ensuring it's initialized.
    * Returns null if the module hasn't been initialized yet.
@@ -222,9 +226,14 @@ class RNBackgroundDownloaderModuleImpl(private val reactContext: ReactApplicatio
 
     override fun onProgress(id: String, bytesDownloaded: Long, bytesTotal: Long) {
       onProgressDownload(id, bytesDownloaded, bytesTotal)
+      // Persist a recovery snapshot so this download can be recovered if the app
+      // is force-stopped (which kills the foreground service and its in-memory state).
+      maybeSnapshotActiveResumable(id, bytesDownloaded, bytesTotal)
     }
 
     override fun onComplete(id: String, location: String, bytesDownloaded: Long, bytesTotal: Long) {
+      // Drop any buffered progress for this task so it cannot arrive in JS after downloadComplete
+      progressReporter.clearPendingReport(id)
       eventEmitter.emitComplete(id, location, bytesDownloaded, bytesTotal)
 
       // Clean up all download state
@@ -234,6 +243,8 @@ class RNBackgroundDownloaderModuleImpl(private val reactContext: ReactApplicatio
     }
 
     override fun onError(id: String, error: String, errorCode: Int) {
+      // Drop any buffered progress for this task so it cannot arrive in JS after downloadFailed
+      progressReporter.clearPendingReport(id)
       eventEmitter.emitFailed(id, error, errorCode)
 
       // Clean up all download state
@@ -385,6 +396,9 @@ class RNBackgroundDownloaderModuleImpl(private val reactContext: ReactApplicatio
           stopTaskProgress(config.id)
 
           synchronized(sharedLock) {
+            // Drop any buffered progress that slipped past stopTaskProgress's clearPendingReport
+            // (the polling thread may have re-added it between clearPendingReport and this lock)
+            progressReporter.clearPendingReport(config.id)
             when (status) {
               DownloadManager.STATUS_SUCCESSFUL -> {
                 onSuccessfulDownload(config, downloadStatus)
@@ -508,7 +522,10 @@ class RNBackgroundDownloaderModuleImpl(private val reactContext: ReactApplicatio
     configIdToDownloadId.remove(configId)
     configIdToHeaders.remove(configId)
     configIdToMetadata.remove(configId)
+    configIdToLastSnapshotMs.remove(configId)
     progressReporter.clearDownloadState(configId)
+    // Drop any force-stop recovery snapshot for this download.
+    downloader.removeActiveDownloadSnapshot(configId)
 
     if (downloadId != null) {
       downloadIdToConfig.remove(downloadId)
@@ -520,6 +537,42 @@ class RNBackgroundDownloaderModuleImpl(private val reactContext: ReactApplicatio
     }
   }
 
+  /**
+   * Persist a recovery snapshot for an in-progress resumable download, throttled so
+   * the frequent progress callbacks don't write to storage on every buffer read.
+   * If the app is force-stopped, restoreRecoverableDownloads() uses this snapshot to
+   * surface the download again via getExistingDownloadTasks.
+   */
+  private fun maybeSnapshotActiveResumable(configId: String, bytesDownloaded: Long, bytesTotal: Long) {
+    val now = System.currentTimeMillis()
+    val last = configIdToLastSnapshotMs[configId] ?: 0L
+    if (now - last < DownloadConstants.RECOVERY_SNAPSHOT_INTERVAL_MS) {
+      return
+    }
+    configIdToLastSnapshotMs[configId] = now
+
+    // The active state lives in the foreground-service ResumableDownloader (Android < 14)
+    // or, on Android 14+, in the UIDT job. Check both so force-stop recovery works on
+    // every supported version.
+    val state = downloader.getActiveResumableDownloads()[configId]
+      ?: (if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE)
+        UIDTDownloadJobService.getJobDownloadState(configId)
+      else null)
+      ?: return
+    val headers = configIdToHeaders[configId] ?: state.headers
+    val metadata = configIdToMetadata[configId] ?: "{}"
+
+    downloader.saveActiveDownloadSnapshot(
+      configId = configId,
+      url = state.url,
+      destination = state.destination,
+      headers = headers,
+      bytesDownloaded = bytesDownloaded,
+      bytesTotal = bytesTotal,
+      metadata = metadata
+    )
+  }
+
   /**
    * Resolve redirects for a URL up to maxRedirects limit
    * @param originalUrl The original URL to follow
@@ -834,6 +887,10 @@ class RNBackgroundDownloaderModuleImpl(private val reactContext: ReactApplicatio
             metadata = metadata
           )
 
+          // Now tracked as an explicit paused download - drop the recovery snapshot.
+          downloader.removeActiveDownloadSnapshot(configId)
+          configIdToLastSnapshotMs.remove(configId)
+
           logD(NAME, "Paused resumable download: $configId (saved state: ${state.bytesDownloaded.get()}/${state.bytesTotal} bytes)")
         }
         return
@@ -1080,11 +1137,35 @@ class RNBackgroundDownloaderModuleImpl(private val reactContext: ReactApplicatio
         processedIds.add(configId)
       }
 
-      // Phase 4: Add active resumable downloads (in-progress via ResumableDownloader)
-      val resumableDownloader = downloader.resumableDownloader
-      // Check for any paused resumable downloads that weren't in the persisted state
-      // (e.g., paused during current session but not yet persisted)
-      // This is handled by the pausedDownloads map above since we persist on pause
+      // Phase 4: Add active resumable downloads (in-progress via ResumableDownloader).
+      // These run in the foreground service (Android < 14) and are invisible to
+      // DownloadManager, so without this phase getExistingDownloadTasks misses them
+      // while they are actively downloading (it only saw them once paused, via Phase 3).
+      // On Android 14+ active downloads run as UIDT jobs and are surfaced in Phase 2.
+      for ((configId, state) in downloader.getActiveResumableDownloads()) {
+        if (processedIds.contains(configId) || state.isCancelled.get()) {
+          continue
+        }
+
+        val params = Arguments.createMap()
+        params.putString("id", configId)
+        params.putString("metadata", configIdToMetadata[configId] ?: "{}")
+        params.putInt(
+          "state",
+          if (state.isPaused.get()) DownloadConstants.TASK_SUSPENDED else DownloadConstants.TASK_RUNNING
+        )
+
+        val bytesDownloaded = state.bytesDownloaded.get()
+        val bytesTotal = state.bytesTotal
+        params.putDouble("bytesDownloaded", bytesDownloaded.toDouble())
+        params.putDouble("bytesTotal", bytesTotal.toDouble())
+        params.putString("destination", state.destination)
+
+        val percent = if (bytesTotal > 0) bytesDownloaded.toDouble() / bytesTotal else 0.0
+        foundTasks.pushMap(params)
+        processedIds.add(configId)
+        progressReporter.setPercent(configId, percent)
+      }
 
       logD(NAME, "getExistingDownloadTasks: found ${foundTasks.size()} tasks")
     }

package/android/src/main/java/com/eko/ResumableDownloader.kt

@@ -218,6 +218,13 @@ class ResumableDownloader {
 
   fun getState(id: String): DownloadState? = activeDownloads[id]
 
+  /**
+   * Returns a snapshot of all currently tracked download states.
+   * Used by getExistingDownloadTasks to surface in-progress resumable downloads
+   * (which are not visible to DownloadManager).
+   */
+  fun getActiveDownloads(): Map<String, DownloadState> = activeDownloads.toMap()
+
   fun isPaused(id: String): Boolean = activeDownloads[id]?.isPaused?.get() ?: false
 
   fun getBytesDownloaded(id: String): Long = activeDownloads[id]?.bytesDownloaded?.get() ?: 0

package/android/src/main/java/com/eko/UIDTDownloadJobService.kt

@@ -148,7 +148,7 @@ class UIDTDownloadJobService : JobService() {
         }
         val url = extras.getString(UIDTConstants.KEY_URL) ?: return false
         val destination = extras.getString(UIDTConstants.KEY_DESTINATION) ?: return false
-        val startByte = extras.getLong(UIDTConstants.KEY_START_BYTE, 0)
+        val startByteFromExtras = extras.getLong(UIDTConstants.KEY_START_BYTE, 0)
         val totalBytes = extras.getLong(UIDTConstants.KEY_TOTAL_BYTES, -1)
 
         // Extract group info from metadata (for notification grouping)
@@ -165,8 +165,36 @@ class UIDTDownloadJobService : JobService() {
             RNBackgroundDownloaderModuleImpl.logE(UIDTConstants.TAG, "Failed to parse metadata: ${e.message}")
         }
 
-        // Retrieve headers
-        val headers = UIDTJobRegistry.pendingHeaders.remove(configId) ?: emptyMap()
+        // Resolve headers and start byte.
+        // In-memory pendingHeaders is populated in the same process (scheduleDownload / onStopJob).
+        // The disk-persisted resume state is the fallback for a fresh process after a restart.
+        val inMemoryHeaders = UIDTJobRegistry.pendingHeaders.remove(configId)
+        val diskResumeState = UIDTJobRegistry.loadResumeState(this, configId)
+        // Clear disk state now that we've consumed it.
+        UIDTJobRegistry.clearResumeState(this, configId)
+
+        val headers: Map<String, String>
+        val startByte: Long
+        when {
+            inMemoryHeaders != null -> {
+                // Same-process restart: use in-memory headers.
+                // Prefer the disk byte position if it is more advanced than the extras
+                // (written by onStopJob with the actual download offset).
+                headers = inMemoryHeaders
+                startByte = if (diskResumeState != null && diskResumeState.second > startByteFromExtras)
+                    diskResumeState.second else startByteFromExtras
+            }
+            diskResumeState != null -> {
+                // Cross-process restart: use the persisted state.
+                headers = diskResumeState.first
+                startByte = diskResumeState.second
+            }
+            else -> {
+                headers = emptyMap()
+                startByte = startByteFromExtras
+            }
+        }
+        RNBackgroundDownloaderModuleImpl.logD(UIDTConstants.TAG, "onStartJob: configId=$configId, startByte=$startByte, headers=${headers.size}")
 
         // Create notification for UIDT job (required)
         val notificationId = UIDTNotificationManager.getNotificationIdForConfig(configId)
@@ -233,8 +261,12 @@ class UIDTDownloadJobService : JobService() {
                 // Save state for potential resume
                 val state = jobState.resumableDownloader.getState(configId)
                 if (state != null) {
-                    // Store resume info
+                    val bytesDownloaded = state.bytesDownloaded.get()
+                    // Keep in-memory headers so the same-process reschedule works.
                     UIDTJobRegistry.pendingHeaders[configId] = state.headers
+                    // Persist to disk so a fresh process can resume from the right position.
+                    UIDTJobRegistry.saveResumeState(this, configId, state.headers, bytesDownloaded)
+                    RNBackgroundDownloaderModuleImpl.logD(UIDTConstants.TAG, "onStopJob: saved resume state for $configId at $bytesDownloaded bytes")
                 }
             }
             UIDTJobRegistry.activeJobs.remove(configId)
@@ -364,6 +396,9 @@ class UIDTDownloadJobService : JobService() {
                 // Signal job completion - this triggers the REMOVE policy
                 jobFinished(params, false)
 
+                // Clear persisted resume state - no longer needed after successful completion
+                UIDTJobRegistry.clearResumeState(this@UIDTDownloadJobService, id)
+
                 // Notify external listener
                 UIDTJobRegistry.downloadListener?.onComplete(id, location, bytesDownloaded, bytesTotal)
             }
@@ -402,6 +437,9 @@ class UIDTDownloadJobService : JobService() {
                 // Signal job completion with no reschedule - this triggers the REMOVE policy
                 jobFinished(params, false)
 
+                // Clear persisted resume state - no longer needed after failure
+                UIDTJobRegistry.clearResumeState(this@UIDTDownloadJobService, id)
+
                 // Notify external listener
                 UIDTJobRegistry.downloadListener?.onError(id, error, errorCode)
             }

package/android/src/main/java/com/eko/uidt/UIDTJobManager.kt

@@ -66,6 +66,9 @@ object UIDTJobManager {
 
         // Store headers for later retrieval (PersistableBundle can't store Map<String, String>)
         UIDTJobRegistry.pendingHeaders[configId] = headers
+        // Also persist to disk so headers survive process death and are available
+        // in onStartJob even when the process is restarted by the JobScheduler.
+        UIDTJobRegistry.saveResumeState(context, configId, headers, startByte)
 
         // Create extras bundle
         val extras = PersistableBundle().apply {
@@ -77,9 +80,14 @@ object UIDTJobManager {
             putString(UIDTConstants.KEY_METADATA, metadata)
         }
 
-        // Build network request - require internet connectivity
+        // Build network request - require internet connectivity.
+        // Remove NET_CAPABILITY_NOT_VPN (added by Builder default) so that VPN networks
+        // (e.g. Proton VPN, full-tunnel VPNs) are accepted. Without this, the JobScheduler
+        // only considers non-VPN networks; a kill-switch VPN blocks that traffic and the
+        // job never starts, causing callbacks to never fire.
         val networkRequest = NetworkRequest.Builder()
             .addCapability(android.net.NetworkCapabilities.NET_CAPABILITY_INTERNET)
+            .removeCapability(android.net.NetworkCapabilities.NET_CAPABILITY_NOT_VPN)
             .build()
 
         // Build the job with UIDT flag
@@ -150,6 +158,8 @@ object UIDTJobManager {
         jobScheduler.cancel(jobId)
         UIDTJobRegistry.pendingHeaders.remove(configId)
         UIDTJobRegistry.activeJobs.remove(configId)
+        // Clear persisted resume state so stale headers/bytes don't affect future downloads
+        UIDTJobRegistry.clearResumeState(context, configId)
 
         // Update summary notification if grouping was enabled
         if (jobState != null && config.groupingEnabled && jobState.groupId.isNotEmpty()) {