@kesha-antonov/react-native-background-downloader 4.5.4 → 4.5.6

package/README.md

@@ -523,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>
 
@@ -865,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/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() {
@@ -471,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,6 +226,9 @@ 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) {
@@ -515,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)
@@ -527,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
@@ -841,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
@@ -1087,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/utils/StorageManager.kt

@@ -20,6 +20,7 @@ class StorageManager(context: Context, private val name: String) {
         private const val TAG = "StorageManager"
         private const val KEY_DOWNLOAD_ID_TO_CONFIG = "_downloadIdToConfig"
         private const val KEY_PAUSED_DOWNLOADS = "_pausedDownloads"
+        private const val KEY_ACTIVE_DOWNLOADS = "_activeDownloads"
         private const val KEY_UPLOAD_CONFIGS = "_uploadConfigs"
         private const val KEY_PROGRESS_INTERVAL = "_progressInterval"
         private const val KEY_PROGRESS_MIN_BYTES = "_progressMinBytes"
@@ -280,6 +281,100 @@ class StorageManager(context: Context, private val name: String) {
         }
     }
 
+    /**
+     * Save the set of in-progress resumable downloads ("recovery snapshots").
+     * These let getExistingDownloadTasks recover an active download after the app
+     * is force-stopped (which kills the foreground service and loses in-memory
+     * state). Stored separately from paused downloads so it never interferes with
+     * the live pause/resume bookkeeping.
+     */
+    fun saveActiveDownloads(activeDownloads: Map<String, Downloader.PausedDownloadInfo>) {
+        try {
+            val gson = Gson()
+            val mapCopy = activeDownloads.mapValues { (_, info) ->
+                PausedDownloadInfoData(
+                    configId = info.configId,
+                    url = info.url,
+                    destination = info.destination,
+                    headers = info.headers,
+                    bytesDownloaded = info.bytesDownloaded,
+                    bytesTotal = info.bytesTotal,
+                    metadata = info.metadata
+                )
+            }
+            val str = gson.toJson(mapCopy)
+
+            if (isMMKVAvailable && mmkv != null) {
+                mmkv!!.encode("$name$KEY_ACTIVE_DOWNLOADS", str)
+            } else {
+                sharedPreferences.edit()
+                    .putString("$name$KEY_ACTIVE_DOWNLOADS", str)
+                    .commit()
+            }
+        } catch (e: Exception) {
+            RNBackgroundDownloaderModuleImpl.logE(TAG, "Failed to save active downloads: ${e.message}")
+        }
+    }
+
+    /**
+     * Load the in-progress resumable download recovery snapshots.
+     */
+    fun loadActiveDownloads(): MutableMap<String, Downloader.PausedDownloadInfo> {
+        try {
+            val str = if (isMMKVAvailable && mmkv != null) {
+                mmkv!!.decodeString("$name$KEY_ACTIVE_DOWNLOADS")
+            } else {
+                sharedPreferences.getString("$name$KEY_ACTIVE_DOWNLOADS", null)
+            }
+
+            if (str != null && str.isNotEmpty()) {
+                val gson = Gson()
+                val mapType = object : TypeToken<Map<String, PausedDownloadInfoData>>() {}.type
+                val dataMap: Map<String, PausedDownloadInfoData> = gson.fromJson(str, mapType)
+                return dataMap.mapValues { (_, data) ->
+                    Downloader.PausedDownloadInfo(
+                        configId = data.configId,
+                        url = data.url,
+                        destination = data.destination,
+                        headers = data.headers,
+                        bytesDownloaded = data.bytesDownloaded,
+                        bytesTotal = data.bytesTotal,
+                        metadata = data.metadata
+                    )
+                }.toMutableMap()
+            }
+        } catch (e: Exception) {
+            RNBackgroundDownloaderModuleImpl.logE(TAG, "Failed to load active downloads: ${e.message}")
+        }
+        return mutableMapOf()
+    }
+
+    /**
+     * Upsert a single in-progress resumable download recovery snapshot.
+     */
+    fun saveActiveDownload(info: Downloader.PausedDownloadInfo) {
+        val map = loadActiveDownloads()
+        map[info.configId] = info
+        saveActiveDownloads(map)
+    }
+
+    /**
+     * Remove a single recovery snapshot by config ID.
+     */
+    fun removeActiveDownload(configId: String) {
+        val map = loadActiveDownloads()
+        if (map.remove(configId) != null) {
+            saveActiveDownloads(map)
+        }
+    }
+
+    /**
+     * Clear all recovery snapshots.
+     */
+    fun clearActiveDownloads() {
+        saveActiveDownloads(emptyMap())
+    }
+
     /**
      * Save upload configs map.
      */

package/ios/RNBGDTaskConfig.h

@@ -14,6 +14,9 @@ NS_ASSUME_NONNULL_BEGIN
 @property (nonatomic, assign) NSInteger state;
 @property (nonatomic, assign) NSInteger errorCode;
 @property (nonatomic, assign) BOOL hasResumeData;
+// iOS Data Protection level key for the saved file
+// (e.g. NSFileProtectionCompleteUntilFirstUserAuthentication). nil = library default.
+@property (nonatomic, copy, nullable) NSString *dataProtection;
 
 - (instancetype)initWithDictionary:(NSDictionary *)dict;
 

package/ios/RNBGDTaskConfig.mm

@@ -16,6 +16,7 @@
         self.url = dict[@"url"];
         self.destination = dict[@"destination"];
         self.metadata = dict[@"metadata"];
+        self.dataProtection = dict[@"dataProtection"];
         self.reportedBegin = NO;
         self.bytesDownloaded = 0;
         self.bytesTotal = 0;
@@ -33,6 +34,7 @@
     [aCoder encodeObject:self.url forKey:@"url"];
     [aCoder encodeObject:self.destination forKey:@"destination"];
     [aCoder encodeObject:self.metadata forKey:@"metadata"];
+    [aCoder encodeObject:self.dataProtection forKey:@"dataProtection"];
     [aCoder encodeBool:self.reportedBegin forKey:@"reportedBegin"];
     [aCoder encodeInt64:self.bytesDownloaded forKey:@"bytesDownloaded"];
     [aCoder encodeInt64:self.bytesTotal forKey:@"bytesTotal"];
@@ -52,6 +54,7 @@
         self.destination = [aDecoder decodeObjectOfClass:[NSString class] forKey:@"destination"];
         NSString *metadata = [aDecoder decodeObjectOfClass:[NSString class] forKey:@"metadata"];
         self.metadata = metadata != nil ? metadata : @"{}";
+        self.dataProtection = [aDecoder decodeObjectOfClass:[NSString class] forKey:@"dataProtection"];
         self.reportedBegin = [aDecoder decodeBoolForKey:@"reportedBegin"];
         self.bytesDownloaded = [aDecoder decodeInt64ForKey:@"bytesDownloaded"];
         self.bytesTotal = [aDecoder decodeInt64ForKey:@"bytesTotal"];