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

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

@@ -42,6 +42,7 @@ class ResumableDownloadService : Service() {
     const val EXTRA_HEADERS = "headers"
     const val EXTRA_START_BYTE = "start_byte"
     const val EXTRA_TOTAL_BYTES = "total_bytes"
+    const val EXTRA_IS_ALLOWED_OVER_METERED = "is_allowed_over_metered"
   }
 
   private val binder = LocalBinder()
@@ -61,6 +62,26 @@ class ResumableDownloadService : Service() {
   // Shared ResumableDownloader instance
   val resumableDownloader = ResumableDownloader()
 
+  // Enforces isAllowedOverMetered=false on this path (no scheduler to hold the
+  // transfer): parks downloads until an unmetered network is available, binds
+  // the transfer to it, auto-pauses on loss and auto-resumes
+  private val unmeteredGate by lazy {
+    UnmeteredNetworkGate(this, resumableDownloader, object : UnmeteredNetworkGate.Host {
+      override fun createGateListener(id: String): ResumableDownloader.DownloadListener? {
+        val job = activeDownloads[id] ?: return null
+        return createValidatingListener(id, job.sessionToken, downloadGeneration[id] ?: 0)
+      }
+
+      override fun onGatedTransferStarting() {
+        acquireWakeLock()
+      }
+
+      override fun onGateStateChanged() {
+        updateNotification()
+      }
+    })
+  }
+
   inner class LocalBinder : Binder() {
     fun getService(): ResumableDownloadService = this@ResumableDownloadService
   }
@@ -70,16 +91,19 @@ class ResumableDownloadService : Service() {
    * before delegating events to the actual listener. This prevents stale events
    * from old download sessions from being processed.
    *
+   * On a valid terminal event (complete/error) the service's job entry is always
+   * removed - the session/generation check already guarantees only the current
+   * session's listener can get here, and a leaked entry would keep the foreground
+   * service (and its notification) alive forever via stopServiceIfIdle().
+   *
    * @param id The download ID
    * @param sessionToken The session token from when the download was started
    * @param generation The generation counter from when the download was started
-   * @param cleanupOnTerminal Whether to clean up state on complete/error (true for start, false for resume since job already exists)
    */
   private fun createValidatingListener(
     id: String,
     sessionToken: Long,
-    generation: Long,
-    cleanupOnTerminal: Boolean = true
+    generation: Long
   ): ResumableDownloader.DownloadListener {
     return object : ResumableDownloader.DownloadListener {
 
@@ -128,11 +152,7 @@ class ResumableDownloadService : Service() {
       override fun onComplete(id: String, location: String, bytesDownloaded: Long, bytesTotal: Long) {
         if (isValid()) {
           listener?.onComplete(id, location, bytesDownloaded, bytesTotal)
-          if (cleanupOnTerminal) {
-            activeDownloads.remove(id)
-            lastProgressLogTime.remove(id)
-          }
-          stopServiceIfIdle()
+          cleanupTerminalDownload(id)
         } else {
           logStale("onComplete")
         }
@@ -140,12 +160,22 @@ class ResumableDownloadService : Service() {
 
       override fun onError(id: String, error: String, errorCode: Int) {
         if (isValid()) {
-          listener?.onError(id, error, errorCode)
-          if (cleanupOnTerminal) {
-            activeDownloads.remove(id)
-            lastProgressLogTime.remove(id)
+          // A gated download whose bound network died raises a socket error before
+          // the ConnectivityManager onLost callback arrives - reclassify it as
+          // "waiting for unmetered network" instead of failing the download
+          if (unmeteredGate.regateAfterNetworkLoss(id, errorCode)) {
+            RNBackgroundDownloaderModuleImpl.logD(TAG, "Gated download $id lost its unmetered network mid-transfer, re-waiting (suppressed error: $error)")
+            updateNotification()
+            return
+          }
+          // The grace period inside regateAfterNetworkLoss may have raced a
+          // cancel or restart - re-check validity before reporting the error
+          if (!isValid()) {
+            logStale("onError (after network grace check)")
+            return
           }
-          stopServiceIfIdle()
+          listener?.onError(id, error, errorCode)
+          cleanupTerminalDownload(id)
         } else {
           logStale("onError")
         }
@@ -197,9 +227,10 @@ class ResumableDownloadService : Service() {
         val headers = getHeadersFromIntent(intent)
         val startByte = intent.getLongExtra(EXTRA_START_BYTE, 0)
         val totalBytes = intent.getLongExtra(EXTRA_TOTAL_BYTES, -1)
+        val isAllowedOverMetered = intent.getBooleanExtra(EXTRA_IS_ALLOWED_OVER_METERED, true)
 
         if (id != null && url != null && destination != null) {
-          startDownloadInternal(id, url, destination, headers, startByte, totalBytes)
+          startDownloadInternal(id, url, destination, headers, startByte, totalBytes, isAllowedOverMetered)
         }
       }
       ACTION_PAUSE_DOWNLOAD -> {
@@ -223,31 +254,59 @@ class ResumableDownloadService : Service() {
       ACTION_STOP_SERVICE -> {
         stopServiceIfIdle()
       }
+      else -> {
+        // Downloader starts the service with a blank intent and delivers the actual
+        // work over the binder. After Context.startForegroundService() the service
+        // MUST call startForeground() promptly or the system kills the app - do it
+        // here instead of relying on the bound startDownload call arriving in time.
+        startForegroundWithNotification()
+      }
     }
 
-    return START_STICKY
+    // NOT_STICKY: all download state is in-memory (recovery goes through the
+    // module's persisted snapshots on the next app launch), so a sticky restart
+    // with a null intent would only produce an idle foreground service whose
+    // notification nothing ever clears.
+    return START_NOT_STICKY
   }
 
   override fun onDestroy() {
     RNBackgroundDownloaderModuleImpl.logD(TAG, "Service destroyed")
+    unmeteredGate.shutdown()
     releaseWakeLock()
     executorService.shutdownNow()
+    isForeground = false
     super.onDestroy()
   }
 
+  /**
+   * Shared terminal cleanup for a download that completed or failed.
+   * Must always run on a valid terminal event or the service job entry leaks and
+   * keeps the foreground service (and its notification) alive forever.
+   */
+  private fun cleanupTerminalDownload(id: String) {
+    activeDownloads.remove(id)
+    lastProgressLogTime.remove(id)
+    unmeteredGate.clear(id)
+    stopServiceIfIdle()
+  }
+
   fun setDownloadListener(listener: ResumableDownloader.DownloadListener?) {
     this.listener = listener
   }
 
+  // isAllowedOverMetered is deliberately not defaulted: a call site that forgets
+  // it must not compile, or the metered restriction silently reverts to allowed
   fun startDownload(
     id: String,
     url: String,
     destination: String,
     headers: Map<String, String>,
     startByte: Long = 0,
-    totalBytes: Long = -1
+    totalBytes: Long = -1,
+    isAllowedOverMetered: Boolean
   ) {
-    startDownloadInternal(id, url, destination, headers, startByte, totalBytes)
+    startDownloadInternal(id, url, destination, headers, startByte, totalBytes, isAllowedOverMetered)
   }
 
   private fun startDownloadInternal(
@@ -256,13 +315,13 @@ class ResumableDownloadService : Service() {
     destination: String,
     headers: Map<String, String>,
     startByte: Long,
-    totalBytes: Long
+    totalBytes: Long,
+    isAllowedOverMetered: Boolean
   ) {
-    RNBackgroundDownloaderModuleImpl.logD(TAG, "Starting download: $id from byte $startByte")
+    RNBackgroundDownloaderModuleImpl.logD(TAG, "Starting download: $id from byte $startByte (isAllowedOverMetered=$isAllowedOverMetered)")
 
     // Start foreground service if not already
     startForegroundWithNotification()
-    acquireWakeLock()
 
     // Increment generation counter for this download ID
     // This ensures we can detect stale events even if job was removed and re-added
@@ -273,8 +332,35 @@ class ResumableDownloadService : Service() {
     val job = DownloadJob(id, url, destination, headers, startByte, totalBytes)
     activeDownloads[id] = job
 
+    if (!isAllowedOverMetered) {
+      // Park the download and let the unmetered-network gate start it: it starts
+      // immediately when an unmetered network is already connected, otherwise it
+      // waits like DownloadManager's "queued for WiFi" state. No wake lock while
+      // waiting - one is acquired when the transfer actually starts.
+      val gated = unmeteredGate.parkNewDownload(id) {
+        resumableDownloader.prepareWaitingDownload(id, url, destination, headers, startByte, totalBytes)
+      }
+      if (!gated) {
+        // The constraint can't be enforced (network callback registration
+        // failed) - fail the download loudly instead of stranding it forever
+        RNBackgroundDownloaderModuleImpl.logE(TAG, "Cannot register unmetered network callback, failing download $id")
+        activeDownloads.remove(id)
+        resumableDownloader.cancel(id)
+        listener?.onError(id, "Cannot enforce isAllowedOverMetered=false: network callback registration failed", -1)
+        stopServiceIfIdle()
+        return
+      }
+      updateNotification()
+      return
+    }
+
+    // Clear stale gate bookkeeping from a previous gated download with this ID
+    unmeteredGate.clear(id)
+
+    acquireWakeLock()
+
     // Create a validating listener wrapper
-    val serviceListener = createValidatingListener(id, job.sessionToken, generation, cleanupOnTerminal = true)
+    val serviceListener = createValidatingListener(id, job.sessionToken, generation)
 
     // Start the download using ResumableDownloader
     resumableDownloader.startDownload(
@@ -284,13 +370,19 @@ class ResumableDownloadService : Service() {
       headers = headers,
       listener = serviceListener,
       startByte = startByte,
-      totalBytes = totalBytes
+      totalBytes = totalBytes,
+      isAllowedOverMetered = isAllowedOverMetered
     )
   }
 
   fun pauseDownload(id: String): Boolean {
     RNBackgroundDownloaderModuleImpl.logD(TAG, "Pausing download: $id")
-    val result = resumableDownloader.pause(id)
+    // Atomic with the gate: a user pause takes the download out of the unmetered
+    // gate under the gate lock, so a concurrent onAvailable drain can't claim it
+    // and restart the transfer the user just paused
+    val result = unmeteredGate.withGateCleared(id) {
+      resumableDownloader.pause(id)
+    }
     if (result) {
       updateNotification()
       // Don't stop service - keep it alive for potential resume
@@ -307,20 +399,36 @@ class ResumableDownloadService : Service() {
     val generation = downloadGeneration[id] ?: 0
     RNBackgroundDownloaderModuleImpl.logD(TAG, "Resuming $id with session=$sessionToken, generation=$generation")
 
-    // Create a validating listener wrapper (don't cleanup since job already exists)
-    val serviceListener = createValidatingListener(id, sessionToken, generation, cleanupOnTerminal = false)
-
     // Make sure service is in foreground
     startForegroundWithNotification()
+
+    // Unmetered-only downloads resume through the network gate so the transfer
+    // only starts (and stays) on an unmetered network
+    val state = resumableDownloader.getState(id)
+    if (state != null && !state.isAllowedOverMetered) {
+      val gated = unmeteredGate.parkForResume(id)
+      if (gated) {
+        updateNotification()
+      }
+      return gated
+    }
+
     acquireWakeLock()
 
+    // Create a validating listener wrapper
+    val serviceListener = createValidatingListener(id, sessionToken, generation)
+
     return resumableDownloader.resume(id, serviceListener)
   }
 
   fun cancelDownload(id: String): Boolean {
     RNBackgroundDownloaderModuleImpl.logD(TAG, "Cancelling download: $id")
-    activeDownloads.remove(id)
-    val result = resumableDownloader.cancel(id)
+    // Atomic with the gate so an in-flight onAvailable drain can't restart the
+    // download between the bookkeeping removal and the downloader cancel
+    val result = unmeteredGate.withGateCleared(id) {
+      activeDownloads.remove(id)
+      resumableDownloader.cancel(id)
+    }
     stopServiceIfIdle()
     return result
   }
@@ -329,7 +437,11 @@ class ResumableDownloadService : Service() {
 
   fun getState(id: String) = resumableDownloader.getState(id)
 
+  @Volatile
+  private var isForeground = false
+
   private fun startForegroundWithNotification() {
+    if (isForeground) return
     val notification = createNotification()
     try {
       if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
@@ -337,6 +449,7 @@ class ResumableDownloadService : Service() {
       } else {
         startForeground(DownloadConstants.NOTIFICATION_ID, notification)
       }
+      isForeground = true
     } catch (e: Exception) {
       RNBackgroundDownloaderModuleImpl.logE(TAG, "Failed to start foreground service: ${e.message}")
     }
@@ -359,15 +472,17 @@ class ResumableDownloadService : Service() {
 
   private fun createNotification(): Notification {
     val activeCount = activeDownloads.size
-    val pausedCount = activeDownloads.keys.count { resumableDownloader.isPaused(it) }
-    val runningCount = activeCount - pausedCount
-
-    val contentText = when {
-      runningCount > 0 && pausedCount > 0 -> "$runningCount downloading, $pausedCount paused"
-      runningCount > 0 -> "$runningCount download${if (runningCount > 1) "s" else ""} in progress"
-      pausedCount > 0 -> "$pausedCount download${if (pausedCount > 1) "s" else ""} paused"
-      else -> "Download service running"
-    }
+    // Downloads held by the unmetered-network gate are paused-like but shown separately
+    val waitingIds = unmeteredGate.waitingIds()
+    val waitingCount = activeDownloads.keys.count { waitingIds.contains(it) }
+    val pausedCount = activeDownloads.keys.count { resumableDownloader.isPaused(it) && !waitingIds.contains(it) }
+    val runningCount = activeCount - pausedCount - waitingCount
+
+    val parts = mutableListOf<String>()
+    if (runningCount > 0) parts.add("$runningCount downloading")
+    if (waitingCount > 0) parts.add("$waitingCount waiting for unmetered network")
+    if (pausedCount > 0) parts.add("$pausedCount paused")
+    val contentText = if (parts.isEmpty()) "Download service running" else parts.joinToString(", ")
 
     // Use download icon when actively downloading, pause icon when all paused
     val icon = if (runningCount > 0) {
@@ -425,6 +540,7 @@ class ResumableDownloadService : Service() {
       RNBackgroundDownloaderModuleImpl.logD(TAG, "No active downloads, stopping service")
       releaseWakeLock()
       stopForeground(STOP_FOREGROUND_REMOVE)
+      isForeground = false
       stopSelf()
     } else {
       RNBackgroundDownloaderModuleImpl.logD(TAG, "Service has active downloads, keeping alive")

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

@@ -1,5 +1,6 @@
 package com.eko
 
+import android.net.Network
 import com.eko.utils.HeaderUtils
 import java.io.File
 import java.io.FileOutputStream
@@ -34,7 +35,12 @@ class ResumableDownloader {
     @Volatile var inputStream: InputStream? = null,
     var hasReportedBegin: Boolean = false,
     // Session counter to detect stale threads after pause/resume
-    val sessionId: AtomicLong = AtomicLong(0)
+    val sessionId: AtomicLong = AtomicLong(0),
+    // Whether this download may transfer over metered networks
+    val isAllowedOverMetered: Boolean = true,
+    // When set, the HTTP connection is opened on this specific network so an
+    // unmetered-only download can never leak onto a metered default network
+    @Volatile var network: Network? = null
   )
 
   private val activeDownloads = ConcurrentHashMap<String, DownloadState>()
@@ -51,6 +57,8 @@ class ResumableDownloader {
    * @param startByte The byte position to start from (for resuming paused DownloadManager downloads)
    * @param totalBytes The total bytes if known (for resuming)
    */
+  // isAllowedOverMetered is deliberately not defaulted: a call site that forgets
+  // it must not compile, or the metered restriction silently reverts to allowed
   fun startDownload(
     id: String,
     url: String,
@@ -58,8 +66,54 @@ class ResumableDownloader {
     headers: Map<String, String>,
     listener: DownloadListener,
     startByte: Long = 0,
-    totalBytes: Long = -1
+    totalBytes: Long = -1,
+    isAllowedOverMetered: Boolean,
+    network: Network? = null
   ) {
+    val state = registerNewDownload(id, url, destination, headers, startByte, totalBytes, isAllowedOverMetered)
+    state.network = network
+
+    val currentSessionId = state.sessionId.get()
+    val thread = Thread {
+      downloadWithResume(state, listener, currentSessionId)
+    }
+    state.thread = thread
+    thread.start()
+  }
+
+  /**
+   * Register an unmetered-only download in a paused/waiting state WITHOUT
+   * starting the transfer. Used by the unmetered-network gate on Android < 14:
+   * the state is visible to pause/cancel/getState immediately, and the actual
+   * transfer is started later via resume() once a suitable network is available.
+   */
+  fun prepareWaitingDownload(
+    id: String,
+    url: String,
+    destination: String,
+    headers: Map<String, String>,
+    startByte: Long = 0,
+    totalBytes: Long = -1
+  ): DownloadState {
+    val state = registerNewDownload(id, url, destination, headers, startByte, totalBytes, isAllowedOverMetered = false)
+    // Paused-like state so resume() can start the first transfer
+    state.isPaused.set(true)
+    return state
+  }
+
+  /**
+   * Cancel any existing download with the same ID, clean up a stale destination
+   * file, then create and register a fresh DownloadState (no thread started).
+   */
+  private fun registerNewDownload(
+    id: String,
+    url: String,
+    destination: String,
+    headers: Map<String, String>,
+    startByte: Long,
+    totalBytes: Long,
+    isAllowedOverMetered: Boolean
+  ): DownloadState {
     // Cancel any existing download with the same ID first
     val existingState = activeDownloads[id]
     if (existingState != null) {
@@ -93,7 +147,8 @@ class ResumableDownloader {
       url = url,
       destination = destination,
       headers = headers,
-      bytesTotal = totalBytes
+      bytesTotal = totalBytes,
+      isAllowedOverMetered = isAllowedOverMetered
     )
 
     // Set initial bytes downloaded (only for explicit resume with startByte > 0)
@@ -112,13 +167,7 @@ class ResumableDownloader {
     }
 
     activeDownloads[id] = state
-
-    val currentSessionId = state.sessionId.get()
-    val thread = Thread {
-      downloadWithResume(state, listener, currentSessionId)
-    }
-    state.thread = thread
-    thread.start()
+    return state
   }
 
   fun pause(id: String): Boolean {
@@ -278,7 +327,10 @@ class ResumableDownloader {
       }
 
       val url = URL(state.url)
-      connection = url.openConnection() as HttpURLConnection
+      // When the download is bound to a specific network (unmetered-network gate),
+      // open the connection on that network so bytes can't leak onto the metered
+      // default network. Otherwise use the default network.
+      connection = (state.network?.openConnection(url) ?: url.openConnection()) as HttpURLConnection
       // Store connection reference so it can be disconnected on cancel
       state.connection = connection
       connection.connectTimeout = DownloadConstants.CONNECT_TIMEOUT_MS
@@ -549,7 +601,9 @@ class ResumableDownloader {
       connection = this.connection,
       inputStream = this.inputStream,
       hasReportedBegin = this.hasReportedBegin,
-      sessionId = this.sessionId
+      sessionId = this.sessionId,
+      isAllowedOverMetered = this.isAllowedOverMetered,
+      network = this.network
     )
   }
 }

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

@@ -53,8 +53,9 @@ class UIDTDownloadJobService : JobService() {
             headers: Map<String, String>,
             startByte: Long = 0,
             totalBytes: Long = -1,
-            metadata: String = "{}"
-        ): Boolean = UIDTJobManager.scheduleDownload(context, configId, url, destination, headers, startByte, totalBytes, metadata)
+            metadata: String = "{}",
+            isAllowedOverMetered: Boolean
+        ): Boolean = UIDTJobManager.scheduleDownload(context, configId, url, destination, headers, startByte, totalBytes, metadata, isAllowedOverMetered)
 
         /**
          * Cancel a scheduled UIDT job.
@@ -76,11 +77,23 @@ class UIDTDownloadJobService : JobService() {
          */
         fun getJobDownloadState(configId: String): ResumableDownloader.DownloadState? = UIDTJobRegistry.getJobDownloadState(configId)
 
+        /**
+         * Get the metered-network permission of an active UIDT job (null if not active).
+         */
+        fun getJobIsAllowedOverMetered(configId: String): Boolean? = UIDTJobRegistry.getJobIsAllowedOverMetered(configId)
+
         /**
          * Pause an active UIDT download.
          */
         fun pauseJob(context: Context, configId: String): Boolean = UIDTJobManager.pauseJob(context, configId)
 
+        /**
+         * Cancel a scheduled-but-not-running UIDT job (e.g. held pending by its
+         * unmetered-network constraint) and return its persistable info.
+         */
+        fun cancelPendingJob(context: Context, configId: String): UIDTJobManager.PendingJobInfo? =
+            UIDTJobManager.cancelPendingJob(context, configId)
+
         /**
          * Resume a paused UIDT download.
          */
@@ -150,6 +163,7 @@ class UIDTDownloadJobService : JobService() {
         val destination = extras.getString(UIDTConstants.KEY_DESTINATION) ?: return false
         val startByteFromExtras = extras.getLong(UIDTConstants.KEY_START_BYTE, 0)
         val totalBytes = extras.getLong(UIDTConstants.KEY_TOTAL_BYTES, -1)
+        val isAllowedOverMetered = extras.getBoolean(UIDTConstants.KEY_IS_ALLOWED_OVER_METERED, true)
 
         // Extract group info from metadata (for notification grouping)
         val metadataJson = extras.getString(UIDTConstants.KEY_METADATA) ?: "{}"
@@ -223,7 +237,12 @@ class UIDTDownloadJobService : JobService() {
         // Create listener that will notify completion
         val jobListener = createJobListener(configId, params, groupId, groupName)
 
-        // Start the download asynchronously
+        // Start the download asynchronously. The network constraint is enforced by
+        // the JobScheduler; the flag is passed so the DownloadState stays truthful
+        // (it is a fallback source for pause/snapshot persistence in the module).
+        // Bind the transfer to the network that satisfied the job's constraint -
+        // otherwise the sockets use the DEFAULT network, which can be metered
+        // cellular even while the satisfying unmetered network is connected.
         resumableDownloader.startDownload(
             id = configId,
             url = url,
@@ -231,7 +250,9 @@ class UIDTDownloadJobService : JobService() {
             headers = headers,
             listener = jobListener,
             startByte = startByte,
-            totalBytes = totalBytes
+            totalBytes = totalBytes,
+            isAllowedOverMetered = isAllowedOverMetered,
+            network = params.network
         )
 
         RNBackgroundDownloaderModuleImpl.logD(UIDTConstants.TAG, "Started UIDT download: $configId from byte $startByte")