@kesha-antonov/react-native-background-downloader 4.5.9 → 4.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/README.md +69 -4
  2. package/android/build.gradle +17 -0
  3. package/android/src/main/AndroidManifest.xml +24 -0
  4. package/android/src/main/java/com/eko/DownloadConstants.kt +14 -2
  5. package/android/src/main/java/com/eko/Downloader.kt +77 -12
  6. package/android/src/main/java/com/eko/RNBackgroundDownloaderModuleImpl.kt +81 -11
  7. package/android/src/main/java/com/eko/ResumableDownloadService.kt +0 -4
  8. package/android/src/main/java/com/eko/ResumableDownloader.kt +121 -12
  9. package/android/src/main/java/com/eko/UIDTDownloadJobService.kt +65 -9
  10. package/android/src/main/java/com/eko/uidt/CancelDownloadReceiver.kt +64 -0
  11. package/android/src/main/java/com/eko/uidt/RNBGDFileProvider.kt +17 -0
  12. package/android/src/main/java/com/eko/uidt/UIDTJobIds.kt +112 -0
  13. package/android/src/main/java/com/eko/uidt/UIDTJobManager.kt +178 -17
  14. package/android/src/main/java/com/eko/uidt/UIDTJobState.kt +23 -1
  15. package/android/src/main/java/com/eko/uidt/UIDTNotificationIds.kt +73 -0
  16. package/android/src/main/java/com/eko/uidt/UIDTNotificationManager.kt +246 -19
  17. package/android/src/main/res/xml/rnbgd_file_paths.xml +23 -0
  18. package/android/src/test/java/com/eko/ResumableDownloaderConcurrencyTest.kt +199 -0
  19. package/android/src/test/java/com/eko/uidt/UIDTJobIdsTest.kt +159 -0
  20. package/android/src/test/java/com/eko/uidt/UIDTJobManagerTest.kt +192 -0
  21. package/android/src/test/java/com/eko/uidt/UIDTNotificationIdsTest.kt +99 -0
  22. package/lib/NativeRNBackgroundDownloader.d.ts +2 -0
  23. package/lib/config.d.ts +2 -0
  24. package/lib/config.js +3 -0
  25. package/lib/index.d.ts +1 -1
  26. package/lib/index.js +9 -2
  27. package/lib/notifications.js +4 -3
  28. package/lib/types.d.ts +19 -0
  29. package/package.json +3 -2
  30. package/react-native-background-downloader.podspec +14 -1
  31. package/src/NativeRNBackgroundDownloader.ts +8 -1
  32. package/src/config.ts +5 -0
  33. package/src/index.ts +19 -1
  34. package/src/notifications.ts +1 -0
  35. package/src/types.ts +19 -0
package/README.md CHANGED
@@ -475,9 +475,9 @@ Headers given in `createDownloadTask()` are **merged** with the ones given in `s
475
475
 
476
476
  You can configure global settings for download behavior using `setConfig()`:
477
477
 
478
- #### Max Parallel Downloads (iOS only)
478
+ #### Max Parallel Downloads
479
479
 
480
- Control how many simultaneous downloads can occur per host. This is useful for managing bandwidth and server load.
480
+ Control how many downloads transfer at once. This is useful for managing bandwidth and server load.
481
481
 
482
482
  ```javascript
483
483
  import { setConfig } from '@kesha-antonov/react-native-background-downloader'
@@ -488,7 +488,7 @@ setConfig({
488
488
  })
489
489
  ```
490
490
 
491
- **Note:** This setting only affects iOS. Android's `DownloadManager` manages parallel downloads automatically and does not expose this configuration.
491
+ **Note:** the two platforms apply it at different layers. On iOS it is the download session's maximum simultaneous connections per host. On Android it caps the library's own downloader - the mechanism used on Android 16+, and whenever `DownloadManager` or a UIDT job can't take the download - while downloads that run through `DownloadManager` or the JobScheduler are queued by those schedulers instead.
492
492
 
493
493
  #### Cellular/WiFi Restrictions
494
494
 
@@ -692,6 +692,33 @@ setConfig({
692
692
  })
693
693
  ```
694
694
 
695
+ **Cancel button and completion notification (Android 14+):**
696
+
697
+ Two extras are available on top of `showNotificationsEnabled`. Both are off by default, so enabling notifications alone never adds an alerting notification or a button your app is not ready for:
698
+
699
+ ```javascript
700
+ setConfig({
701
+ showNotificationsEnabled: true,
702
+ // Adds a Cancel button to the download notification. Tapping it stops the
703
+ // download like task.stop() and fires the task's .error() handler with
704
+ // errorCode = -1, so handle that in your app before enabling it.
705
+ showCancelAction: true,
706
+ // Posts a "download complete" notification when a download finishes.
707
+ // Tapping it opens the saved file with the system chooser.
708
+ // Skipped in 'summaryOnly' grouping mode.
709
+ showCompletionNotification: true,
710
+ notificationsGrouping: {
711
+ enabled: true,
712
+ texts: {
713
+ downloadCancel: 'Cancel', // Label of the Cancel button
714
+ downloadFinished: 'Download complete', // Title of the completion notification
715
+ },
716
+ },
717
+ })
718
+ ```
719
+
720
+ Per-download notification titles are supported too - pass `metadata.notificationTitle` to override `groupName` and the default `downloadTitle` for a single download. See [Platform Notes](docs/PLATFORM_NOTES.md#download-notifications-android-14) for the full behavior.
721
+
695
722
  **Notification grouping modes:**
696
723
 
697
724
  When downloading many files (e.g., thousands of photos), you can use the `mode` option to control how notifications are displayed:
@@ -899,7 +926,45 @@ If you're using `react-native-mmkv`, you don't need to add the MMKV dependency m
899
926
  <details>
900
927
  <summary><strong>EXC_BAD_ACCESS crash on iOS with react-native-mmkv</strong></summary>
901
928
 
902
- 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.
929
+ This was fixed in v4.4.0. Update to the latest version. The podspec declares the MMKV dependency itself, so you don't need to add anything to your Podfile. If you do pin it manually, exclude the broken 2.4.1 release (see the entry below):
930
+
931
+ ```ruby
932
+ pod 'MMKV', '>= 1.0.0', '!= 2.4.1'
933
+ ```
934
+ </details>
935
+
936
+ <details>
937
+ <summary><strong>iOS build fails with "use of undeclared identifier 'memset_s'" (MMKVCore)</strong></summary>
938
+
939
+ ```text
940
+ Pods/MMKVCore/Core/aes/AESCrypt.cpp:83:11
941
+ (void)memset_s(ptr, len, 0, len);
942
+ ^ use of undeclared identifier 'memset_s'
943
+ ```
944
+
945
+ This is an upstream bug in **MMKVCore 2.4.1** ([Tencent/MMKV#1675](https://github.com/Tencent/MMKV/issues/1675)) - it does not compile on Apple platforms. Update to the latest version of this library: the podspec now excludes exactly that release, so a fresh `pod install` resolves `MMKVCore 2.4.0` instead.
946
+
947
+ If you are on a version with the fix and still hitting this, your `Podfile.lock` is pinning the broken version. Refresh it:
948
+
949
+ ```bash
950
+ cd ios
951
+ pod update MMKV MMKVCore
952
+ ```
953
+
954
+ If some other pod in your graph forces `MMKVCore 2.4.1` and you cannot move off it, define the missing feature-test macro on the command line (the `#define` inside `AESCrypt.cpp` lands too late because CocoaPods force-includes the generated prefix header first):
955
+
956
+ ```ruby
957
+ # ios/Podfile
958
+ post_install do |installer|
959
+ installer.pods_project.targets.each do |target|
960
+ next unless target.name == 'MMKVCore'
961
+ target.build_configurations.each do |config|
962
+ config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= ['$(inherited)']
963
+ config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] << '__STDC_WANT_LIB_EXT1__=1'
964
+ end
965
+ end
966
+ end
967
+ ```
903
968
  </details>
904
969
 
905
970
  <details>
@@ -66,6 +66,16 @@ android {
66
66
  useLegacyPackaging = false
67
67
  }
68
68
  }
69
+
70
+ testOptions {
71
+ unitTests {
72
+ includeAndroidResources = true
73
+ // Framework calls the tests don't exercise (e.g. Log from a class
74
+ // loaded outside a Robolectric environment) return a default instead
75
+ // of throwing "not mocked"
76
+ returnDefaultValues = true
77
+ }
78
+ }
69
79
  }
70
80
 
71
81
  repositories {
@@ -84,4 +94,11 @@ dependencies {
84
94
  compileOnly 'com.tencent:mmkv-shared:1.3.16'
85
95
 
86
96
  implementation 'com.google.code.gson:gson:2.12.1'
97
+
98
+ // Unit tests. Robolectric gives the tests a real JobScheduler, SharedPreferences
99
+ // and Log without a device; MockWebServer backs the download-transfer tests.
100
+ testImplementation 'junit:junit:4.13.2'
101
+ testImplementation 'org.robolectric:robolectric:4.14.1'
102
+ testImplementation 'androidx.test:core:1.6.1'
103
+ testImplementation 'com.squareup.okhttp3:mockwebserver:4.12.0'
87
104
  }
@@ -25,6 +25,30 @@
25
25
  android:name=".UIDTDownloadJobService"
26
26
  android:permission="android.permission.BIND_JOB_SERVICE"
27
27
  android:exported="false" />
28
+
29
+ <!-- Receiver for the in-notification "Cancel" action -->
30
+ <receiver
31
+ android:name=".uidt.CancelDownloadReceiver"
32
+ android:exported="false">
33
+ <intent-filter>
34
+ <action android:name="com.eko.uidt.ACTION_CANCEL_DOWNLOAD" />
35
+ </intent-filter>
36
+ </receiver>
37
+
38
+ <!-- Library-owned FileProvider so tapping the "download complete"
39
+ notification can open the saved file via the system viewer with no
40
+ host-app configuration. A dedicated subclass + unique authority avoid
41
+ manifest-merger / authority collisions with the host app's own
42
+ FileProvider. -->
43
+ <provider
44
+ android:name=".uidt.RNBGDFileProvider"
45
+ android:authorities="${applicationId}.rnbackgrounddownloader.fileprovider"
46
+ android:exported="false"
47
+ android:grantUriPermissions="true">
48
+ <meta-data
49
+ android:name="android.support.FILE_PROVIDER_PATHS"
50
+ android:resource="@xml/rnbgd_file_paths" />
51
+ </provider>
28
52
  </application>
29
53
 
30
54
  </manifest>
@@ -97,6 +97,18 @@ object DownloadConstants {
97
97
  /** Wake lock timeout (milliseconds) - 1 hour */
98
98
  const val WAKELOCK_TIMEOUT_MS = 60 * 60 * 1000L
99
99
 
100
- /** Number of concurrent download threads */
101
- const val DOWNLOAD_THREAD_POOL_SIZE = 3
100
+ /**
101
+ * Transfers the library's own downloader runs at once by default, matching
102
+ * the JS `maxParallelDownloads` default. Downloads over the limit wait for a
103
+ * slot instead of each taking a thread and a socket of their own.
104
+ */
105
+ const val DEFAULT_MAX_PARALLEL_DOWNLOADS = 4
106
+
107
+ /**
108
+ * How long a download may wait for the download service to connect before it
109
+ * is failed. Binding normally completes in milliseconds; the wait only runs
110
+ * long when the system refused to start the service at all, and a download
111
+ * left parked there would never report anything to JS.
112
+ */
113
+ const val SERVICE_START_TIMEOUT_MS = 15_000L
102
114
  }
@@ -7,12 +7,15 @@ import android.content.Intent
7
7
  import android.content.ServiceConnection
8
8
  import android.database.Cursor
9
9
  import android.os.Build
10
+ import android.os.Handler
10
11
  import android.os.IBinder
12
+ import android.os.Looper
11
13
  import android.util.Log
12
14
  import com.facebook.react.bridge.Arguments
13
15
  import com.facebook.react.bridge.WritableMap
14
16
  import java.io.File
15
17
  import java.util.concurrent.ConcurrentHashMap
18
+ import java.util.concurrent.atomic.AtomicBoolean
16
19
 
17
20
  /**
18
21
  * Wrapper around Android's DownloadManager for managing file downloads.
@@ -305,8 +308,17 @@ class Downloader(private val context: Context, private val storageManager: com.e
305
308
  * - Work properly on Android 16+ where foreground services are restricted
306
309
  *
307
310
  * On Android < 14, uses the foreground service with dataSync type.
311
+ *
312
+ * @param allowServiceFallback when false, a download that can't get a UIDT job
313
+ * is reported back to the caller (`false`) instead of being handed to
314
+ * the foreground service, so the caller can pick another mechanism.
315
+ * @return whether a mechanism took the download.
308
316
  */
309
- private fun startDownloadService(info: PausedDownloadInfo, listener: ResumableDownloader.DownloadListener) {
317
+ private fun startDownloadService(
318
+ info: PausedDownloadInfo,
319
+ listener: ResumableDownloader.DownloadListener,
320
+ allowServiceFallback: Boolean = true
321
+ ): Boolean {
310
322
  // On Android 14+, use UIDT jobs for better background execution
311
323
  if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
312
324
  // Set the listener for UIDT job callbacks
@@ -327,11 +339,18 @@ class Downloader(private val context: Context, private val storageManager: com.e
327
339
 
328
340
  if (scheduled) {
329
341
  RNBackgroundDownloaderModuleImpl.logD(TAG, "Using UIDT job for download: ${info.configId}")
330
- return
342
+ return true
343
+ }
344
+
345
+ if (!allowServiceFallback) {
346
+ RNBackgroundDownloaderModuleImpl.logW(TAG, "UIDT scheduling failed for ${info.configId}, leaving the mechanism to the caller")
347
+ return false
331
348
  }
332
349
 
333
350
  // Fall through to foreground service if UIDT scheduling fails
334
351
  RNBackgroundDownloaderModuleImpl.logW(TAG, "UIDT scheduling failed, falling back to foreground service")
352
+ } else if (!allowServiceFallback) {
353
+ return false
335
354
  }
336
355
 
337
356
  // On Android < 14 or if UIDT fails, use foreground service.
@@ -352,7 +371,11 @@ class Downloader(private val context: Context, private val storageManager: com.e
352
371
  }
353
372
 
354
373
  // Now use the direct service call path
374
+ val settled = AtomicBoolean(false)
355
375
  executeWhenServiceReady {
376
+ // Lost the race to the watchdog below - the download was already failed
377
+ if (!settled.compareAndSet(false, true)) return@executeWhenServiceReady
378
+
356
379
  downloadService?.setDownloadListener(listener)
357
380
  downloadService?.startDownload(
358
381
  info.configId,
@@ -364,16 +387,43 @@ class Downloader(private val context: Context, private val storageManager: com.e
364
387
  info.isAllowedOverMetered
365
388
  )
366
389
  }
390
+
391
+ if (settled.get()) return true
392
+
393
+ // The service wasn't connected, so the download is parked until it is. That
394
+ // normally takes milliseconds, but when the system refuses to start the
395
+ // service - a background start on Android 12+, say - nothing ever runs the
396
+ // parked operation, and the task would stay pending in JS with no event
397
+ // either way. Fail it instead of letting it hang.
398
+ Handler(Looper.getMainLooper()).postDelayed({
399
+ if (settled.compareAndSet(false, true)) {
400
+ RNBackgroundDownloaderModuleImpl.logE(TAG, "Download service never started for ${info.configId}")
401
+ listener.onError(info.configId, "Could not start the download service", -1)
402
+ }
403
+ }, DownloadConstants.SERVICE_START_TIMEOUT_MS)
404
+
405
+ return true
367
406
  }
368
407
 
369
408
  /**
370
- * Start a new download using ResumableDownloader (HTTP-based download).
371
- * This is used as a fallback when DownloadManager can't handle the external storage path
372
- * on devices like OnePlus that return invalid paths from getExternalFilesDir().
409
+ * Start a new download using ResumableDownloader (HTTP-based download): a UIDT
410
+ * job on Android 14+, the foreground service below that.
411
+ *
412
+ * @param allowServiceFallback when false, a download that can't get a UIDT job
413
+ * is reported back as `false` instead of falling back to the foreground
414
+ * service - used where DownloadManager is still a viable next choice.
415
+ * @return whether a mechanism took the download.
373
416
  */
374
- fun startResumableDownload(info: PausedDownloadInfo, listener: ResumableDownloader.DownloadListener) {
375
- startDownloadService(info, listener)
376
- RNBackgroundDownloaderModuleImpl.logD(TAG, "Started ResumableDownloader for ${info.configId} (DownloadManager fallback)")
417
+ fun startResumableDownload(
418
+ info: PausedDownloadInfo,
419
+ listener: ResumableDownloader.DownloadListener,
420
+ allowServiceFallback: Boolean = true
421
+ ): Boolean {
422
+ val started = startDownloadService(info, listener, allowServiceFallback)
423
+ if (started) {
424
+ RNBackgroundDownloaderModuleImpl.logD(TAG, "Started ResumableDownloader for ${info.configId}")
425
+ }
426
+ return started
377
427
  }
378
428
 
379
429
  /**
@@ -502,14 +552,22 @@ class Downloader(private val context: Context, private val storageManager: com.e
502
552
  }
503
553
 
504
554
  var recoveredCount = 0
555
+ val stillLive = mutableSetOf<String>()
505
556
  for ((configId, info) in recoverable) {
506
- // Skip if it is already tracked as paused, or still running as a UIDT job.
557
+ // Skip if it is already tracked as paused, or still live as a UIDT job.
507
558
  if (pausedDownloads.containsKey(configId)) {
559
+ stillLive.add(configId)
508
560
  continue
509
561
  }
562
+ // isActiveJob only knows jobs that already started in this process, and
563
+ // this runs at startup - ask the JobScheduler, which still holds the job
564
+ // whether it is running or waiting on a constraint. Recovering one of
565
+ // those as paused would double-track a download that is about to start.
510
566
  if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE &&
511
- UIDTDownloadJobService.isActiveJob(configId)
567
+ (UIDTDownloadJobService.isActiveJob(configId) ||
568
+ UIDTDownloadJobService.isScheduledJob(context, configId))
512
569
  ) {
570
+ stillLive.add(configId)
513
571
  continue
514
572
  }
515
573
 
@@ -528,8 +586,15 @@ class Downloader(private val context: Context, private val storageManager: com.e
528
586
  RNBackgroundDownloaderModuleImpl.logD(TAG, "Recovered $recoveredCount interrupted resumable download(s) after force-stop")
529
587
  }
530
588
 
531
- // Clear the active store now that recovery has been processed.
532
- sm.clearActiveDownloads()
589
+ // Drop the snapshots recovery consumed, but keep the ones belonging to
590
+ // downloads that are still live: a scheduled job that hasn't transferred a
591
+ // byte yet has no progress callback to re-save its snapshot, so clearing the
592
+ // whole store would lose it if the app is force-stopped again.
593
+ for (configId in recoverable.keys) {
594
+ if (configId !in stillLive) {
595
+ sm.removeActiveDownload(configId)
596
+ }
597
+ }
533
598
  }
534
599
 
535
600
  /**
@@ -63,6 +63,26 @@ class RNBackgroundDownloaderModuleImpl(private val reactContext: ReactApplicatio
63
63
  if (isLogsEnabled) Log.e(tag, message)
64
64
  }
65
65
 
66
+ // The live module instance, set once initialize() has run and cleared on
67
+ // invalidate(). Lets native-only entry points (the notification Cancel
68
+ // action) reuse the exact same teardown as a call coming from JS.
69
+ @Volatile
70
+ private var activeInstance: RNBackgroundDownloaderModuleImpl? = null
71
+
72
+ /**
73
+ * Stop a download from native code, going through the same path as a
74
+ * task.stop() call from JS (progress tracking, resumable/DownloadManager
75
+ * cancellation, persisted state cleanup).
76
+ *
77
+ * @return `true` when the module was alive and handled the stop, `false`
78
+ * when there is no instance yet (e.g. a broadcast cold-started the process)
79
+ * and the caller has to fall back to a narrower cancellation.
80
+ */
81
+ fun stopTaskFromNative(configId: String): Boolean {
82
+ val instance = activeInstance ?: return false
83
+ instance.stopTask(configId)
84
+ return true
85
+ }
66
86
  }
67
87
 
68
88
  // Storage manager for persistent state
@@ -255,9 +275,11 @@ class RNBackgroundDownloaderModuleImpl(private val reactContext: ReactApplicatio
255
275
  }
256
276
 
257
277
  fun setMaxParallelDownloads(max: Int) {
258
- // Android DownloadManager doesn't support setting max parallel downloads
259
- // This is a no-op on Android, but we keep the method for API consistency
260
- logD(NAME, "setMaxParallelDownloads called with $max (no-op on Android)")
278
+ // Caps the transfers the library's own downloader runs at once - the path
279
+ // with no scheduler in front of it. DownloadManager and the JobScheduler
280
+ // queue their own work, so downloads running through them are unaffected.
281
+ ResumableDownloader.setMaxConcurrentTransfers(max)
282
+ logD(NAME, "setMaxParallelDownloads: $max")
261
283
  }
262
284
 
263
285
  fun setAllowsCellularAccess(allows: Boolean) {
@@ -270,6 +292,8 @@ class RNBackgroundDownloaderModuleImpl(private val reactContext: ReactApplicatio
270
292
  fun setNotificationGroupingConfig(config: ReadableMap) {
271
293
  val enabled = if (config.hasKey("enabled")) config.getBoolean("enabled") else false
272
294
  val showNotificationsEnabled = if (config.hasKey("showNotificationsEnabled")) config.getBoolean("showNotificationsEnabled") else false
295
+ val showCompletionNotification = if (config.hasKey("showCompletionNotification")) config.getBoolean("showCompletionNotification") else false
296
+ val showCancelAction = if (config.hasKey("showCancelAction")) config.getBoolean("showCancelAction") else false
273
297
  val mode = if (config.hasKey("mode")) config.getString("mode") ?: "individual" else "individual"
274
298
  val texts = if (config.hasKey("texts")) config.getMap("texts") else null
275
299
 
@@ -284,15 +308,23 @@ class RNBackgroundDownloaderModuleImpl(private val reactContext: ReactApplicatio
284
308
 
285
309
  // Store the config for use by UIDTDownloadJobService
286
310
  if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
287
- UIDTDownloadJobService.setNotificationGroupingConfig(enabled, showNotificationsEnabled, mode, textsMap)
311
+ UIDTDownloadJobService.setNotificationGroupingConfig(
312
+ enabled,
313
+ showNotificationsEnabled,
314
+ showCompletionNotification,
315
+ showCancelAction,
316
+ mode,
317
+ textsMap
318
+ )
288
319
  }
289
320
 
290
- logD(NAME, "setNotificationGroupingConfig: enabled=$enabled, showNotificationsEnabled=$showNotificationsEnabled, mode=$mode, texts=$textsMap")
321
+ logD(NAME, "setNotificationGroupingConfig: enabled=$enabled, showNotificationsEnabled=$showNotificationsEnabled, showCompletionNotification=$showCompletionNotification, showCancelAction=$showCancelAction, mode=$mode, texts=$textsMap")
291
322
  }
292
323
 
293
324
  fun initialize() {
294
325
  ee = reactContext.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
295
326
  isInitialized = true
327
+ activeInstance = this
296
328
  registerDownloadReceiver()
297
329
 
298
330
  // Set the listener for resumable downloads (used by the background service)
@@ -338,6 +370,10 @@ class RNBackgroundDownloaderModuleImpl(private val reactContext: ReactApplicatio
338
370
 
339
371
  unregisterDownloadReceiver()
340
372
  downloader.unbindService()
373
+
374
+ if (activeInstance === this) {
375
+ activeInstance = null
376
+ }
341
377
  }
342
378
 
343
379
  private fun registerDownloadReceiver() {
@@ -696,8 +732,12 @@ class RNBackgroundDownloaderModuleImpl(private val reactContext: ReactApplicatio
696
732
  }
697
733
  }
698
734
 
699
- // Helper function to fall back to ResumableDownloader
700
- fun startWithResumableDownloader() {
735
+ // Helper function to run the download through the library's own downloader:
736
+ // a UIDT job on Android 14+, the foreground service below that.
737
+ // Returns whether a mechanism took it; with allowServiceFallback = false a
738
+ // download that can't get a UIDT job comes back unstarted so the caller can
739
+ // try DownloadManager instead.
740
+ fun startWithResumableDownloader(allowServiceFallback: Boolean = true): Boolean {
701
741
  val spec = Downloader.PausedDownloadInfo(
702
742
  configId = id,
703
743
  url = url,
@@ -724,7 +764,17 @@ class RNBackgroundDownloaderModuleImpl(private val reactContext: ReactApplicatio
724
764
  downloader.saveActiveDownloadSnapshot(spec)
725
765
  configIdToLastSnapshotMs[id] = System.currentTimeMillis()
726
766
  }
727
- downloader.startResumableDownload(spec, resumableDownloadListener)
767
+
768
+ val started = downloader.startResumableDownload(spec, resumableDownloadListener, allowServiceFallback)
769
+ if (!started) {
770
+ // Nothing took the download - drop the bookkeeping so the mechanism the
771
+ // caller tries next starts from a clean slate
772
+ synchronized(sharedLock) {
773
+ downloader.removeActiveDownloadSnapshot(id)
774
+ configIdToLastSnapshotMs.remove(id)
775
+ }
776
+ }
777
+ return started
728
778
  }
729
779
 
730
780
  // On Android 16+ (API 36), DownloadManager has strict path restrictions and throws
@@ -735,6 +785,21 @@ class RNBackgroundDownloaderModuleImpl(private val reactContext: ReactApplicatio
735
785
  return
736
786
  }
737
787
 
788
+ // On Android 14/15, prefer a UIDT job: it isn't subject to App Standby
789
+ // quotas, and it is the only path where the library manages the download's
790
+ // notification, so grouping, the completion notification, the Cancel action
791
+ // and per-download titles work for a fresh download instead of only after a
792
+ // pause/resume. DownloadManager stays as the fallback for when the job can't
793
+ // be scheduled - most importantly download() called from the background,
794
+ // where user-initiated jobs are refused.
795
+ if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
796
+ if (startWithResumableDownloader(allowServiceFallback = false)) {
797
+ logD(NAME, "Android 14+: using a UIDT job for download: $id")
798
+ return
799
+ }
800
+ logD(NAME, "Android 14+: no UIDT job for $id, using DownloadManager")
801
+ }
802
+
738
803
  if (isValidExternalPath) {
739
804
  // Use DownloadManager with valid external storage path
740
805
  // Download directly to final destination to avoid file duplication
@@ -1042,11 +1107,16 @@ class RNBackgroundDownloaderModuleImpl(private val reactContext: ReactApplicatio
1042
1107
  logE(NAME, "getExistingDownloadTasks: ${Log.getStackTraceString(e)}")
1043
1108
  }
1044
1109
 
1045
- // Phase 2: Query active UIDT jobs (Android 14+)
1046
- // On Android 14+, downloads may use UIDT instead of DownloadManager
1110
+ // Phase 2: Query UIDT jobs (Android 14+)
1111
+ // On Android 14+, downloads may use UIDT instead of DownloadManager.
1112
+ // Scheduled-but-not-yet-started jobs are included: they have no registry
1113
+ // entry (that is filled in onStartJob), so without them a download waiting
1114
+ // on its network constraint - or every job at all after a process restart -
1115
+ // would be missing from the list while its transfer is still coming.
1047
1116
  if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
1048
1117
  try {
1049
- val uidtJobs = UIDTDownloadJobService.getAllActiveJobs()
1118
+ val uidtJobs = UIDTDownloadJobService.getAllActiveJobs() +
1119
+ UIDTDownloadJobService.getScheduledJobs(reactContext)
1050
1120
 
1051
1121
  for (job in uidtJobs) {
1052
1122
  // Skip if already processed from DownloadManager
@@ -12,8 +12,6 @@ import android.os.IBinder
12
12
  import android.os.PowerManager
13
13
  import androidx.core.app.NotificationCompat
14
14
  import java.util.concurrent.ConcurrentHashMap
15
- import java.util.concurrent.ExecutorService
16
- import java.util.concurrent.Executors
17
15
 
18
16
  /**
19
17
  * A foreground service that manages resumable downloads in the background.
@@ -46,7 +44,6 @@ class ResumableDownloadService : Service() {
46
44
  }
47
45
 
48
46
  private val binder = LocalBinder()
49
- private val executorService: ExecutorService = Executors.newFixedThreadPool(DownloadConstants.DOWNLOAD_THREAD_POOL_SIZE)
50
47
  private val activeDownloads = ConcurrentHashMap<String, DownloadJob>()
51
48
  private var wakeLock: PowerManager.WakeLock? = null
52
49
  private var listener: ResumableDownloader.DownloadListener? = null
@@ -274,7 +271,6 @@ class ResumableDownloadService : Service() {
274
271
  RNBackgroundDownloaderModuleImpl.logD(TAG, "Service destroyed")
275
272
  unmeteredGate.shutdown()
276
273
  releaseWakeLock()
277
- executorService.shutdownNow()
278
274
  isForeground = false
279
275
  super.onDestroy()
280
276
  }