@onekeyfe/react-native-range-downloader 3.0.53 → 3.0.55

package/README.md

@@ -5,20 +5,38 @@ react-native-range-downloader
 ## Installation
 
 ```sh
-npm install react-native-range-downloader react-native-nitro-modules
+npm install @onekeyfe/react-native-range-downloader react-native-nitro-modules
 
 > `react-native-nitro-modules` is required as this library relies on [Nitro Modules](https://nitro.margelo.com/).
 ```
 
 ## Usage
 
-```js
-import { ReactNativeRangeDownloader } from 'react-native-range-downloader';
+```ts
+import { ReactNativeRangeDownloader } from '@onekeyfe/react-native-range-downloader';
 
 // ...
 
-const result = await ReactNativeRangeDownloader.hello({ message: 'World' });
-console.log(result); // { success: true, data: 'Hello, World!' }
+const taskId = 'chart-assets';
+const destFilePath = `${ReactNativeRangeDownloader.getDownloadsDir()}/chart-assets.zip`;
+
+const listenerId = ReactNativeRangeDownloader.addDownloadListener((event) => {
+  if (event.channel === 'chart' && event.taskId === taskId) {
+    console.log(event.type, event.progress, event.message);
+  }
+});
+
+try {
+  const result = await ReactNativeRangeDownloader.download({
+    channel: 'chart',
+    taskId,
+    url: 'https://example.com/chart-assets.zip',
+    destFilePath,
+  });
+  console.log(result.outcome, result.filePath, result.fallbackReason);
+} finally {
+  ReactNativeRangeDownloader.removeDownloadListener(listenerId);
+}
 ```
 
 ## Contributing

package/android/src/main/java/com/margelo/nitro/reactnativerangedownloader/ConcurrentRangeDownloader.kt

@@ -44,7 +44,35 @@ class ConcurrentRangeDownloader(
     /** Thrown internally when a segment proves concurrency can't be used. */
     private class FallbackException(message: String) : Exception(message)
 
-    private class Part(val index: Int, val start: Long, val end: Long, @Volatile var done: Long) {
+    /**
+     * Cooperative-cancel handle the caller can register a download against. The
+     * adapter keeps these in a per-taskId registry so `cancel`/`discardArtifacts`
+     * can flip [aborted] and `shutdownNow()` the worker pool BEFORE deleting the
+     * `.partial`/`.progress`, so no in-flight worker resurrects a deleted file.
+     */
+    class CancelHandle {
+        val aborted = AtomicBoolean(false)
+
+        @Volatile
+        private var pool: java.util.concurrent.ExecutorService? = null
+
+        internal fun attach(pool: java.util.concurrent.ExecutorService) {
+            this.pool = pool
+            // If cancel() already raced in before the pool was attached, honor it.
+            if (aborted.get()) pool.shutdownNow()
+        }
+
+        /** Flip the abort flag and stop the worker pool. Idempotent. */
+        fun cancel() {
+            aborted.set(true)
+            pool?.shutdownNow()
+        }
+    }
+
+    private class Part(val index: Int, val start: Long, val end: Long, done: Long) {
+        // AtomicLong so manifest snapshots read a consistent value even if the
+        // owning thread ever changes (cross-thread reads in flushManifest).
+        val done = AtomicLong(done)
         val length: Long get() = end - start + 1
     }
 
@@ -59,6 +87,7 @@ class ConcurrentRangeDownloader(
     fun download(
         url: String,
         partialFilePath: String,
+        cancelHandle: CancelHandle? = null,
         onProgress: (transferred: Long, total: Long) -> Unit,
     ): Outcome {
         val partialFile = File(partialFilePath)
@@ -78,30 +107,41 @@ class ConcurrentRangeDownloader(
         }
         val total = probe.totalSize
         val etag = probe.etag
+        // A strong validator (ETag) is what lets If-Range pin a resumed range to
+        // the exact object the partial was started against. Without it we cannot
+        // safely trust or persist `.partial`/`.progress` across attempts, so we
+        // start fresh and skip manifest persistence (the caller's whole-file
+        // SHA256 check after promotion remains the final correctness backstop).
+        val hasValidator = !etag.isNullOrEmpty()
 
         partialFile.parentFile?.let { if (!it.exists()) it.mkdirs() }
         dropOrphanManifest(partialFile, manifestFile)
-        val parts = loadOrInitManifest(manifestFile, partialFile, total, etag)
+        val parts = loadOrInitManifest(manifestFile, partialFile, total, etag, hasValidator)
 
-        val transferred = AtomicLong(parts.sumOf { it.done })
+        val transferred = AtomicLong(parts.sumOf { it.done.get() })
         onProgress(transferred.get(), total)
 
-        val aborted = AtomicBoolean(false)
+        // Share the abort flag with the cancel handle so an external cancel() is
+        // observed by the per-segment loops; default to a private flag otherwise.
+        val aborted = cancelHandle?.aborted ?: AtomicBoolean(false)
         val fallback = AtomicBoolean(false)
         val firstError = AtomicReference<Exception?>(null)
-        val lastFlushed = LongArray(parts.size) { parts[it].done }
+        val lastFlushed = LongArray(parts.size) { parts[it].done.get() }
 
         val pool = Executors.newFixedThreadPool(minOf(segmentCount, parts.size))
+        cancelHandle?.attach(pool)
         try {
             val futures = parts.map { part ->
                 pool.submit {
                     try {
                         downloadPart(url, etag, partialFile, part, aborted) { delta ->
                             val t = transferred.addAndGet(delta)
-                            synchronized(lastFlushed) {
-                                if (part.done - lastFlushed[part.index] >= manifestFlushBytes) {
-                                    lastFlushed[part.index] = part.done
-                                    flushManifest(manifestFile, total, etag, parts)
+                            if (hasValidator) {
+                                synchronized(lastFlushed) {
+                                    if (part.done.get() - lastFlushed[part.index] >= manifestFlushBytes) {
+                                        lastFlushed[part.index] = part.done.get()
+                                        flushManifest(manifestFile, total, etag, parts)
+                                    }
                                 }
                             }
                             onProgress(t, total)
@@ -128,13 +168,23 @@ class ConcurrentRangeDownloader(
         }
         val err = firstError.get()
         if (err != null) {
-            // Transient — persist progress so the next attempt resumes, then bubble up.
-            flushManifest(manifestFile, total, etag, parts)
+            if (hasValidator) {
+                // Transient — persist progress so the next attempt resumes, then bubble up.
+                flushManifest(manifestFile, total, etag, parts)
+            } else {
+                // No validator: resume state is untrustworthy, so don't persist
+                // it — discard and let the next attempt start clean.
+                discard(partialFile, manifestFile)
+            }
             throw err
         }
-        val got = parts.sumOf { it.done }
+        val got = parts.sumOf { it.done.get() }
         if (got < total) {
-            flushManifest(manifestFile, total, etag, parts)
+            if (hasValidator) {
+                flushManifest(manifestFile, total, etag, parts)
+            } else {
+                discard(partialFile, manifestFile)
+            }
             throw java.io.IOException("Concurrent download incomplete ($got/$total)")
         }
 
@@ -195,11 +245,14 @@ class ConcurrentRangeDownloader(
         partialFile: File,
         total: Long,
         etag: String?,
+        hasValidator: Boolean,
     ): List<Part> {
-        if (manifestFile.exists() && partialFile.exists()) {
+        // Only trust an existing manifest when a strong validator pins it to the
+        // server object; otherwise always start fresh.
+        if (hasValidator && manifestFile.exists() && partialFile.exists()) {
             val parsed = parseManifest(manifestFile, total, etag, partialFile.length())
             if (parsed != null) {
-                log("concurrent: resuming, transferred=${parsed.sumOf { it.done }}/$total")
+                log("concurrent: resuming, transferred=${parsed.sumOf { it.done.get() }}/$total")
                 return parsed
             }
         }
@@ -215,7 +268,8 @@ class ConcurrentRangeDownloader(
             parts.add(Part(parts.size, start, end, 0))
             i += 1
         }
-        writeManifest(manifestFile, total, etag, parts)
+        // Persist the manifest only when it can be safely resumed later.
+        if (hasValidator) writeManifest(manifestFile, total, etag, parts)
         return parts
     }
 
@@ -226,7 +280,7 @@ class ConcurrentRangeDownloader(
         sb.append(total).append('|').append(etag ?: "").append('\n')
         for (p in parts) {
             sb.append(p.index).append(',').append(p.start).append(',')
-                .append(p.end).append(',').append(p.done).append('\n')
+                .append(p.end).append(',').append(p.done.get()).append('\n')
         }
         manifestFile.writeText(sb.toString())
     }
@@ -284,7 +338,7 @@ class ConcurrentRangeDownloader(
         var retry = 0
         while (true) {
             if (aborted.get()) throw java.io.IOException("aborted")
-            val rangeStart = part.start + part.done
+            val rangeStart = part.start + part.done.get()
             if (rangeStart > part.end) return
             try {
                 fetchSegment(url, etag, partialFile, part, rangeStart, aborted, onBytes)
@@ -330,7 +384,7 @@ class ConcurrentRangeDownloader(
                         val read = input.read(buffer)
                         if (read == -1) break
                         raf.write(buffer, 0, read)
-                        part.done += read
+                        part.done.addAndGet(read.toLong())
                         onBytes(read.toLong())
                     }
                 }

package/android/src/main/java/com/margelo/nitro/reactnativerangedownloader/ReactNativeRangeDownloader.kt

@@ -6,6 +6,7 @@ import com.margelo.nitro.core.Promise
 import com.margelo.nitro.nativelogger.OneKeyLog
 import java.io.File
 import java.security.MessageDigest
+import java.util.concurrent.ConcurrentHashMap
 import java.util.concurrent.CopyOnWriteArrayList
 import java.util.concurrent.atomic.AtomicLong
 
@@ -31,6 +32,15 @@ class ReactNativeRangeDownloader : HybridReactNativeRangeDownloaderSpec() {
   private val listeners = CopyOnWriteArrayList<Listener>()
   private val nextListenerId = AtomicLong(1)
 
+  // Active downloads keyed by "channel|taskId" so cancel/discardArtifacts can
+  // flip the abort flag + stop the worker pool BEFORE deleting files, instead of
+  // racing live workers that would resurrect a just-deleted .partial.
+  private val activeDownloads =
+    ConcurrentHashMap<String, ConcurrentRangeDownloader.CancelHandle>()
+
+  private fun runKey(channel: DownloadChannel, taskId: String): String =
+    "${channel.name}|$taskId"
+
   // HTTPS-only client: reject any redirect to a non-HTTPS hop. Mirrors the
   // existing react-native-bundle-update configuration verbatim.
   private val httpClient = okhttp3.OkHttpClient.Builder()
@@ -69,20 +79,29 @@ class ReactNativeRangeDownloader : HybridReactNativeRangeDownloaderSpec() {
 
       sendEvent(channel, taskId, type = "start")
 
+      val runKey = runKey(channel, taskId)
+      val cancelHandle = ConcurrentRangeDownloader.CancelHandle()
+      activeDownloads[runKey] = cancelHandle
+
       var lastProgress = -1
-      val outcome = ConcurrentRangeDownloader(
-        httpClient = httpClient,
-        segmentCount = segmentCount,
-        minConcurrentBytes = minConcurrentBytes,
-        log = { msg -> OneKeyLog.info("RangeDownloader", msg) },
-      ).download(downloadUrl, partialFilePath) { transferred, total ->
-        if (total > 0) {
-          val p = ((transferred * 100) / total).toInt().coerceIn(0, 100)
-          if (p != lastProgress) {
-            sendEvent(channel, taskId, type = "progress", progress = p)
-            lastProgress = p
+      val outcome = try {
+        ConcurrentRangeDownloader(
+          httpClient = httpClient,
+          segmentCount = segmentCount,
+          minConcurrentBytes = minConcurrentBytes,
+          log = { msg -> OneKeyLog.info("RangeDownloader", msg) },
+        ).download(downloadUrl, partialFilePath, cancelHandle) { transferred, total ->
+          if (total > 0) {
+            val p = ((transferred * 100) / total).toInt().coerceIn(0, 100)
+            if (p != lastProgress) {
+              sendEvent(channel, taskId, type = "progress", progress = p)
+              lastProgress = p
+            }
           }
         }
+      } finally {
+        // Only deregister our own handle (a concurrent cancel may have replaced it).
+        activeDownloads.remove(runKey, cancelHandle)
       }
 
       if (outcome == ConcurrentRangeDownloader.Outcome.FALLBACK) {
@@ -99,9 +118,12 @@ class ReactNativeRangeDownloader : HybridReactNativeRangeDownloaderSpec() {
 
       // COMPLETED: `.partial` is fully on disk. Promote -> final, then run the
       // optional in-module SHA256 self-check (mirrors the source finalize path).
-      if (destFile.exists()) destFile.delete()
-      if (!File(partialFilePath).renameTo(destFile)) {
-        OneKeyLog.error("RangeDownloader", "download: rename .partial -> final failed")
+      // Use an atomic move so a kill mid-finalize never leaves NEITHER file:
+      // the destination is replaced in one step, preserving the previous file on
+      // failure (vs. the old delete-then-rename, which had a window with both
+      // gone if the rename then failed).
+      if (!promoteAtomically(File(partialFilePath), destFile)) {
+        OneKeyLog.error("RangeDownloader", "download: promote .partial -> final failed")
         sendEvent(channel, taskId, type = "error", message = "Failed to finalize download")
         throw Exception("Failed to finalize download")
       }
@@ -132,6 +154,10 @@ class ReactNativeRangeDownloader : HybridReactNativeRangeDownloaderSpec() {
     destFilePath: String
   ): Promise<Unit> {
     return Promise.async {
+      // Cancel-then-delete: stop any live workers for this task before removing
+      // files, otherwise a still-running segment could re-create the .partial we
+      // just deleted.
+      cancelActive(channel, taskId)
       // Manifest first so it never outlives the partial it describes.
       File("$destFilePath.partial.progress").delete()
       File("$destFilePath.partial").delete()
@@ -140,6 +166,65 @@ class ReactNativeRangeDownloader : HybridReactNativeRangeDownloaderSpec() {
     }
   }
 
+  override fun cancel(
+    channel: DownloadChannel,
+    taskId: String,
+    destFilePath: String
+  ): Promise<Unit> {
+    return Promise.async {
+      // Stop workers first, then delete artifacts so nothing resurrects them.
+      cancelActive(channel, taskId)
+      File("$destFilePath.partial.progress").delete()
+      File("$destFilePath.partial").delete()
+      OneKeyLog.info("RangeDownloader", "cancel: channel=$channel taskId=$taskId")
+      Unit
+    }
+  }
+
+  // Flip the abort flag + shutdown the pool for an in-flight download (if any).
+  private fun cancelActive(channel: DownloadChannel, taskId: String) {
+    activeDownloads.remove(runKey(channel, taskId))?.cancel()
+  }
+
+  // Atomically replace [dest] with [src] so a kill mid-finalize never leaves
+  // NEITHER file. On API 26+ uses Files.move with ATOMIC_MOVE/REPLACE_EXISTING
+  // (single-step rename onto the destination). On older APIs (java.nio.file is
+  // API 26+) File.renameTo onto an existing dest is itself an atomic rename on a
+  // POSIX filesystem (the kernel replaces the inode in one step), which gives
+  // the same "old file preserved until the new one lands" guarantee.
+  private fun promoteAtomically(src: File, dest: File): Boolean {
+    if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.O) {
+      try {
+        java.nio.file.Files.move(
+          src.toPath(), dest.toPath(),
+          java.nio.file.StandardCopyOption.ATOMIC_MOVE,
+          java.nio.file.StandardCopyOption.REPLACE_EXISTING,
+        )
+        return true
+      } catch (e: Exception) {
+        // ATOMIC_MOVE may be unsupported across the source/dest (e.g. different
+        // stores) — retry a plain replace, still single-step on one filesystem.
+        try {
+          java.nio.file.Files.move(
+            src.toPath(), dest.toPath(),
+            java.nio.file.StandardCopyOption.REPLACE_EXISTING,
+          )
+          return true
+        } catch (e2: Exception) {
+          OneKeyLog.error(
+            "RangeDownloader",
+            "promoteAtomically: Files.move failed (${e2.javaClass.simpleName}), falling back to renameTo",
+          )
+        }
+      }
+    }
+    // API < 26 (or Files.move unsupported): rename directly onto the dest. On a
+    // POSIX filesystem this replaces the destination atomically and keeps the old
+    // file until the rename lands. Do NOT pre-delete the dest — that reintroduces
+    // the both-files-gone window we are fixing.
+    return src.renameTo(dest)
+  }
+
   override fun addDownloadListener(callback: (event: RangeDownloadEvent) -> Unit): Double {
     val id = nextListenerId.getAndIncrement().toDouble()
     listeners.add(Listener(id, callback))

package/ios/ReactNativeRangeDownloader.swift

@@ -42,7 +42,23 @@ class ReactNativeRangeDownloader: HybridReactNativeRangeDownloaderSpec {
     destFilePath: String
   ) throws -> Promise<Void> {
     return Promise.async {
-      RangeDownloader.shared.discardArtifacts(filePath: destFilePath)
+      // Cancel-then-delete: cancel any in-flight tasks for this run before
+      // removing files so a running task can't resurrect a deleted segment.
+      await RangeDownloader.shared.cancel(
+        channel: channel, taskId: taskId, filePath: destFilePath
+      )
+    }
+  }
+
+  func cancel(
+    channel: DownloadChannel,
+    taskId: String,
+    destFilePath: String
+  ) throws -> Promise<Void> {
+    return Promise.async {
+      await RangeDownloader.shared.cancel(
+        channel: channel, taskId: taskId, filePath: destFilePath
+      )
     }
   }
 
@@ -145,6 +161,12 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
     var continuation: CheckedContinuation<Void, Error>?
     var prevProgress = -1
     var fellBack = false
+    /// Set when a segment could not be stashed (move/size-check failure). Carries
+    /// the terminal error so didCompleteWithError finalizes instead of hanging.
+    var stashError: Error?
+    /// Whether a strong validator (ETag) was captured for this run. When false,
+    /// resumable `.segN` state must not be trusted across attempts.
+    var hasValidator = false
     let sessionIdentifier: String
 
     init(channel: DownloadChannel, taskId: String, filePath: String,
@@ -344,6 +366,7 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
     )
     state.totalSize = probe.total
     state.etag = probe.etag
+    state.hasValidator = (probe.etag?.isEmpty == false)
     state.ranges = Self.planRanges(total: probe.total, segments: segCount)
     state.segmentWritten = [Int64](repeating: 0, count: state.ranges.count)
 
@@ -353,6 +376,14 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
 
     let ranges = state.ranges
 
+    // Without a strong validator (ETag) we cannot pin stashed `.segN` to a
+    // specific server object via If-Range, so any leftover segments from a prior
+    // attempt are untrustworthy. Start fresh and only proceed on the resumable
+    // path when expectedSha256 will gate the assembled file (verified below).
+    if !state.hasValidator {
+      cleanupSegments(state: state, ranges: ranges)
+    }
+
     emit(channel: channel, taskId: taskId, type: "start", progress: 0, message: "")
 
     do {
@@ -461,6 +492,22 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
     return Int64(tail.trimmingCharacters(in: .whitespaces))
   }
 
+  /// Parses the start/end of a "bytes <start>-<end>/<total>" Content-Range.
+  static func parseContentRangeBounds(_ header: String) -> (start: Int64, end: Int64)? {
+    // Drop the leading "bytes " and the trailing "/<total>".
+    let trimmed = header.trimmingCharacters(in: .whitespaces)
+    guard let spaceIdx = trimmed.firstIndex(of: " ") else { return nil }
+    var rangePart = String(trimmed[trimmed.index(after: spaceIdx)...])
+    if let slash = rangePart.firstIndex(of: "/") {
+      rangePart = String(rangePart[..<slash])
+    }
+    let bounds = rangePart.split(separator: "-", maxSplits: 1).map { String($0) }
+    guard bounds.count == 2,
+          let start = Int64(bounds[0].trimmingCharacters(in: .whitespaces)),
+          let end = Int64(bounds[1].trimmingCharacters(in: .whitespaces)) else { return nil }
+    return (start, end)
+  }
+
   // MARK: - Task reconciliation (handles app relaunch)
 
   /// Ensures exactly one in-flight (or completed) artifact per missing segment:
@@ -563,15 +610,50 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
                   didFinishDownloadingTo location: URL) {
     guard let desc = downloadTask.taskDescription,
           let (state, idx) = run(for: desc) else { return }
-    // A 200 means the server ignored Range / the ETag changed — we cannot
-    // safely assemble. Flag fallback; finalize happens in didCompleteWithError.
-    if let http = downloadTask.response as? HTTPURLResponse, http.statusCode == 200 {
+    let ranges = lock.withLockValue { state.ranges }
+    guard idx < ranges.count else { return }
+    let range = ranges[idx]
+    let expectedLen = range.end - range.start + 1
+
+    // We require a 206 Partial Content that matches the requested byte range.
+    // Anything else — 200 (Range ignored / ETag changed) or an out-of-range
+    // Content-Range — means we cannot safely assemble this segment, so flag
+    // fallback; finalize happens in didCompleteWithError.
+    guard let http = downloadTask.response as? HTTPURLResponse else {
+      lock.lock(); state.fellBack = true; lock.unlock()
+      return
+    }
+    if http.statusCode != 206 {
+      lock.lock(); state.fellBack = true; lock.unlock()
+      return
+    }
+    // Verify the server's Content-Range start/end matches what we asked for so a
+    // stashed `.segN` can't be a slice of a different object/range.
+    if let cr = http.value(forHTTPHeaderField: "Content-Range") {
+      guard let parsed = Self.parseContentRangeBounds(cr),
+            parsed.start == range.start, parsed.end == range.end else {
+        lock.lock(); state.fellBack = true; lock.unlock()
+        return
+      }
+    } else {
+      // 206 without a Content-Range header is non-conforming — don't trust it.
       lock.lock(); state.fellBack = true; lock.unlock()
       return
     }
-    // Move the segment into place atomically (temp file is deleted after return).
+
+    // Validate the downloaded body length BEFORE moving it into place: a
+    // truncated 206 must never be stashed as a valid segment.
     let dest = state.segPath(idx)
     do {
+      let attrs = try FileManager.default.attributesOfItem(atPath: location.path)
+      let size = attrs[.size] as? Int64
+      guard let size = size, size == expectedLen else {
+        throw NSError(domain: "RangeDownloader", code: -2, userInfo: [
+          NSLocalizedDescriptionKey:
+            "segment \(idx) truncated (got \(size.map(String.init) ?? "nil"), expected \(expectedLen))"
+        ])
+      }
+      // Move the segment into place (temp file is deleted after return).
       let dir = (dest as NSString).deletingLastPathComponent
       if !FileManager.default.fileExists(atPath: dir) {
         try FileManager.default.createDirectory(atPath: dir, withIntermediateDirectories: true)
@@ -583,6 +665,12 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
     } catch {
       OneKeyLog.error("RangeDownloader",
                       "\(state.channel.stringValue)/\(state.taskId): failed to stash segment \(idx): \(error)")
+      // Record the failure so didCompleteWithError finalizes the run with this
+      // terminal error instead of waiting forever for a segment that will never
+      // appear.
+      lock.lock()
+      if state.stashError == nil { state.stashError = error }
+      lock.unlock()
     }
   }
 
@@ -621,10 +709,45 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
                          ranges: ranges)
       return
     }
+    // A segment failed to stash (move/size-check failure in didFinishDownloadingTo).
+    // That segment will never appear, so finalize terminally instead of waiting.
+    if let stashErr = lock.withLockValue({ state.stashError }) {
+      finishContinuation(state: state, with: stashErr, ranges: ranges)
+      return
+    }
     if allSegmentsPresent(state: state, ranges: ranges) {
       finishContinuation(state: state, with: nil, ranges: ranges)
+      return
+    }
+    // This task finished error==nil but not all segments are present. If any
+    // tasks for THIS run are still in flight, wait for their completions.
+    // Otherwise nothing will ever resume the continuation — finalize with a
+    // descriptive terminal error so the JS promise resolves (as fallback).
+    let channel = state.channel
+    let taskId = state.taskId
+    session.getAllTasks { [weak self] tasks in
+      guard let self = self else { return }
+      let stillInFlight = tasks.contains { t in
+        guard let d = t.taskDescription,
+              let decoded = Self.decodeTaskDescription(d),
+              decoded.channel.stringValue == channel.stringValue,
+              decoded.taskId == taskId else { return false }
+        return t.state == .running || t.state == .suspended
+      }
+      if stillInFlight { return }
+      // Re-check under no-in-flight: a just-finished stash may have completed.
+      if self.allSegmentsPresent(state: state, ranges: ranges) {
+        self.finishContinuation(state: state, with: nil, ranges: ranges)
+        return
+      }
+      let missing = ranges.indices.first {
+        !FileManager.default.fileExists(atPath: state.segPath($0))
+      }
+      let reason = "segment \(missing.map(String.init) ?? "?") missing/truncated after completion"
+      self.finishContinuation(state: state,
+                              with: FallbackError(reason: reason),
+                              ranges: ranges)
     }
-    // else: other segments still in flight; wait for their completions.
   }
 
   /// Called on the session delegate queue when all background events for this
@@ -675,9 +798,22 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
                     userInfo: [NSLocalizedDescriptionKey: "cannot open partial for write"])
     }
     defer { try? out.close() }
+    // Stream each segment in fixed-size chunks so a full segment is never held
+    // in RAM (mirrors the streamed SHA256 backstop below).
+    let chunkSize = 1 * 1024 * 1024
     for idx in 0..<ranges.count {
-      let segData = try Data(contentsOf: URL(fileURLWithPath: state.segPath(idx)))
-      try out.write(contentsOf: segData)
+      let segPath = state.segPath(idx)
+      guard let inHandle = FileHandle(forReadingAtPath: segPath) else {
+        throw NSError(domain: "RangeDownloader", code: -3,
+                      userInfo: [NSLocalizedDescriptionKey: "cannot open segment \(idx) for read"])
+      }
+      defer { try? inHandle.close() }
+      while try autoreleasepool(invoking: { () -> Bool in
+        let data = inHandle.readData(ofLength: chunkSize)
+        if data.isEmpty { return false }
+        try out.write(contentsOf: data)
+        return true
+      }) {}
     }
     try? out.close()
     if FileManager.default.fileExists(atPath: filePath) {
@@ -694,8 +830,36 @@ public final class RangeDownloader: NSObject, URLSessionDownloadDelegate {
     try? FileManager.default.removeItem(atPath: "\(state.filePath).partial")
   }
 
+  /// Cancels any in-flight background tasks for (channel|taskId) and then
+  /// discards all segment artifacts. Cancel-then-delete prevents a still-running
+  /// `nsurlsessiond` task from resurrecting a `.segN` we just deleted.
+  public func cancel(channel: DownloadChannel, taskId: String,
+                     filePath: String) async {
+    let session = session(forChannel: channel, segmentCount: Self.defaultSegmentCount)
+    // Cancel matching tasks first and wait for getAllTasks to return so the
+    // cancels have been issued before we touch the files.
+    await withCheckedContinuation { (cont: CheckedContinuation<Void, Never>) in
+      session.getAllTasks { tasks in
+        for t in tasks {
+          if let d = t.taskDescription,
+             let decoded = Self.decodeTaskDescription(d),
+             decoded.channel.stringValue == channel.stringValue,
+             decoded.taskId == taskId {
+            t.cancel()
+          }
+        }
+        cont.resume()
+      }
+    }
+    // Drop the run state so a late delegate callback can't re-stash a segment.
+    clearRun(key: Self.runKey(channel: channel, taskId: taskId))
+    discardArtifacts(filePath: filePath)
+  }
+
   /// Discards all segment artifacts (used by the caller when falling back to
-  /// single-stream so the bare slot is clean).
+  /// single-stream so the bare slot is clean). Prefer `cancel(...)` when tasks
+  /// may still be in flight; this file-only delete is for the post-fallback
+  /// case where tasks have already been abandoned.
   public func discardArtifacts(filePath: String) {
     for idx in 0..<Self.defaultSegmentCount {
       try? FileManager.default.removeItem(atPath: "\(filePath).seg\(idx)")

package/lib/typescript/src/ReactNativeRangeDownloader.nitro.d.ts

@@ -28,6 +28,7 @@ export interface ReactNativeRangeDownloader extends HybridObject<{
 }> {
     download(params: RangeDownloadParams): Promise<RangeDownloadResult>;
     discardArtifacts(channel: DownloadChannel, taskId: string, destFilePath: string): Promise<void>;
+    cancel(channel: DownloadChannel, taskId: string, destFilePath: string): Promise<void>;
     addDownloadListener(callback: (event: RangeDownloadEvent) => void): number;
     removeDownloadListener(id: number): void;
     getDownloadsDir(): string;

package/lib/typescript/src/ReactNativeRangeDownloader.nitro.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ReactNativeRangeDownloader.nitro.d.ts","sourceRoot":"","sources":["../../../src/ReactNativeRangeDownloader.nitro.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAM/D,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,KAAK,GAAG,OAAO,CAAC;AAEzD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,eAAe,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,oBAAoB,GAC5B,WAAW,GACX,UAAU,CAAC;AAEf,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,oBAAoB,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,eAAe,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,0BACf,SAAQ,YAAY,CAAC;IAAE,GAAG,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,QAAQ,CAAA;CAAE,CAAC;IAIzD,QAAQ,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAIpE,gBAAgB,CACd,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IAGjB,mBAAmB,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,GAAG,MAAM,CAAC;IAC3E,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAKzC,eAAe,IAAI,MAAM,CAAC;CAC3B"}
+{"version":3,"file":"ReactNativeRangeDownloader.nitro.d.ts","sourceRoot":"","sources":["../../../src/ReactNativeRangeDownloader.nitro.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAM/D,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,KAAK,GAAG,OAAO,CAAC;AAEzD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,eAAe,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,oBAAoB,GAC5B,WAAW,GACX,UAAU,CAAC;AAEf,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,oBAAoB,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,eAAe,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,0BACf,SAAQ,YAAY,CAAC;IAAE,GAAG,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,QAAQ,CAAA;CAAE,CAAC;IAIzD,QAAQ,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAMpE,gBAAgB,CACd,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IAKjB,MAAM,CACJ,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IAGjB,mBAAmB,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,GAAG,MAAM,CAAC;IAC3E,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAKzC,eAAe,IAAI,MAAM,CAAC;CAC3B"}

package/nitrogen/generated/android/c++/JHybridReactNativeRangeDownloaderSpec.cpp

@@ -99,6 +99,21 @@ namespace margelo::nitro::reactnativerangedownloader {
       return __promise;
     }();
   }
+  std::shared_ptr<Promise<void>> JHybridReactNativeRangeDownloaderSpec::cancel(DownloadChannel channel, const std::string& taskId, const std::string& destFilePath) {
+    static const auto method = javaClassStatic()->getMethod<jni::local_ref<JPromise::javaobject>(jni::alias_ref<JDownloadChannel> /* channel */, jni::alias_ref<jni::JString> /* taskId */, jni::alias_ref<jni::JString> /* destFilePath */)>("cancel");
+    auto __result = method(_javaPart, JDownloadChannel::fromCpp(channel), jni::make_jstring(taskId), jni::make_jstring(destFilePath));
+    return [&]() {
+      auto __promise = Promise<void>::create();
+      __result->cthis()->addOnResolvedListener([=](const jni::alias_ref<jni::JObject>& /* unit */) {
+        __promise->resolve();
+      });
+      __result->cthis()->addOnRejectedListener([=](const jni::alias_ref<jni::JThrowable>& __throwable) {
+        jni::JniException __jniError(__throwable);
+        __promise->reject(std::make_exception_ptr(__jniError));
+      });
+      return __promise;
+    }();
+  }
   double JHybridReactNativeRangeDownloaderSpec::addDownloadListener(const std::function<void(const RangeDownloadEvent& /* event */)>& callback) {
     static const auto method = javaClassStatic()->getMethod<double(jni::alias_ref<JFunc_void_RangeDownloadEvent::javaobject> /* callback */)>("addDownloadListener_cxx");
     auto __result = method(_javaPart, JFunc_void_RangeDownloadEvent_cxx::fromCpp(callback));

package/nitrogen/generated/android/c++/JHybridReactNativeRangeDownloaderSpec.hpp

@@ -56,6 +56,7 @@ namespace margelo::nitro::reactnativerangedownloader {
     // Methods
     std::shared_ptr<Promise<RangeDownloadResult>> download(const RangeDownloadParams& params) override;
     std::shared_ptr<Promise<void>> discardArtifacts(DownloadChannel channel, const std::string& taskId, const std::string& destFilePath) override;
+    std::shared_ptr<Promise<void>> cancel(DownloadChannel channel, const std::string& taskId, const std::string& destFilePath) override;
     double addDownloadListener(const std::function<void(const RangeDownloadEvent& /* event */)>& callback) override;
     void removeDownloadListener(double id) override;
     std::string getDownloadsDir() override;

package/nitrogen/generated/android/kotlin/com/margelo/nitro/reactnativerangedownloader/HybridReactNativeRangeDownloaderSpec.kt

@@ -54,6 +54,10 @@ abstract class HybridReactNativeRangeDownloaderSpec: HybridObject() {
   @Keep
   abstract fun discardArtifacts(channel: DownloadChannel, taskId: String, destFilePath: String): Promise<Unit>
   
+  @DoNotStrip
+  @Keep
+  abstract fun cancel(channel: DownloadChannel, taskId: String, destFilePath: String): Promise<Unit>
+  
   abstract fun addDownloadListener(callback: (event: RangeDownloadEvent) -> Unit): Double
   
   @DoNotStrip

package/nitrogen/generated/ios/c++/HybridReactNativeRangeDownloaderSpecSwift.hpp

@@ -93,6 +93,14 @@ namespace margelo::nitro::reactnativerangedownloader {
       auto __value = std::move(__result.value());
       return __value;
     }
+    inline std::shared_ptr<Promise<void>> cancel(DownloadChannel channel, const std::string& taskId, const std::string& destFilePath) override {
+      auto __result = _swiftPart.cancel(static_cast<int>(channel), taskId, destFilePath);
+      if (__result.hasError()) [[unlikely]] {
+        std::rethrow_exception(__result.error());
+      }
+      auto __value = std::move(__result.value());
+      return __value;
+    }
     inline double addDownloadListener(const std::function<void(const RangeDownloadEvent& /* event */)>& callback) override {
       auto __result = _swiftPart.addDownloadListener(callback);
       if (__result.hasError()) [[unlikely]] {

package/nitrogen/generated/ios/swift/HybridReactNativeRangeDownloaderSpec.swift

@@ -16,6 +16,7 @@ public protocol HybridReactNativeRangeDownloaderSpec_protocol: HybridObject {
   // Methods
   func download(params: RangeDownloadParams) throws -> Promise<RangeDownloadResult>
   func discardArtifacts(channel: DownloadChannel, taskId: String, destFilePath: String) throws -> Promise<Void>
+  func cancel(channel: DownloadChannel, taskId: String, destFilePath: String) throws -> Promise<Void>
   func addDownloadListener(callback: @escaping (_ event: RangeDownloadEvent) -> Void) throws -> Double
   func removeDownloadListener(id: Double) throws -> Void
   func getDownloadsDir() throws -> String

package/nitrogen/generated/ios/swift/HybridReactNativeRangeDownloaderSpec_cxx.swift

@@ -155,6 +155,25 @@ open class HybridReactNativeRangeDownloaderSpec_cxx {
     }
   }
   
+  @inline(__always)
+  public final func cancel(channel: Int32, taskId: std.string, destFilePath: std.string) -> bridge.Result_std__shared_ptr_Promise_void___ {
+    do {
+      let __result = try self.__implementation.cancel(channel: margelo.nitro.reactnativerangedownloader.DownloadChannel(rawValue: channel)!, taskId: String(taskId), destFilePath: String(destFilePath))
+      let __resultCpp = { () -> bridge.std__shared_ptr_Promise_void__ in
+        let __promise = bridge.create_std__shared_ptr_Promise_void__()
+        let __promiseHolder = bridge.wrap_std__shared_ptr_Promise_void__(__promise)
+        __result
+          .then({ __result in __promiseHolder.resolve() })
+          .catch({ __error in __promiseHolder.reject(__error.toCpp()) })
+        return __promise
+      }()
+      return bridge.create_Result_std__shared_ptr_Promise_void___(__resultCpp)
+    } catch (let __error) {
+      let __exceptionPtr = __error.toCpp()
+      return bridge.create_Result_std__shared_ptr_Promise_void___(__exceptionPtr)
+    }
+  }
+  
   @inline(__always)
   public final func addDownloadListener(callback: bridge.Func_void_RangeDownloadEvent) -> bridge.Result_double_ {
     do {

package/nitrogen/generated/shared/c++/HybridReactNativeRangeDownloaderSpec.cpp

@@ -16,6 +16,7 @@ namespace margelo::nitro::reactnativerangedownloader {
     registerHybrids(this, [](Prototype& prototype) {
       prototype.registerHybridMethod("download", &HybridReactNativeRangeDownloaderSpec::download);
       prototype.registerHybridMethod("discardArtifacts", &HybridReactNativeRangeDownloaderSpec::discardArtifacts);
+      prototype.registerHybridMethod("cancel", &HybridReactNativeRangeDownloaderSpec::cancel);
       prototype.registerHybridMethod("addDownloadListener", &HybridReactNativeRangeDownloaderSpec::addDownloadListener);
       prototype.registerHybridMethod("removeDownloadListener", &HybridReactNativeRangeDownloaderSpec::removeDownloadListener);
       prototype.registerHybridMethod("getDownloadsDir", &HybridReactNativeRangeDownloaderSpec::getDownloadsDir);

package/nitrogen/generated/shared/c++/HybridReactNativeRangeDownloaderSpec.hpp

@@ -63,6 +63,7 @@ namespace margelo::nitro::reactnativerangedownloader {
       // Methods
       virtual std::shared_ptr<Promise<RangeDownloadResult>> download(const RangeDownloadParams& params) = 0;
       virtual std::shared_ptr<Promise<void>> discardArtifacts(DownloadChannel channel, const std::string& taskId, const std::string& destFilePath) = 0;
+      virtual std::shared_ptr<Promise<void>> cancel(DownloadChannel channel, const std::string& taskId, const std::string& destFilePath) = 0;
       virtual double addDownloadListener(const std::function<void(const RangeDownloadEvent& /* event */)>& callback) = 0;
       virtual void removeDownloadListener(double id) = 0;
       virtual std::string getDownloadsDir() = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/react-native-range-downloader",
-  "version": "3.0.53",
+  "version": "3.0.55",
   "description": "react-native-range-downloader",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",

package/src/ReactNativeRangeDownloader.nitro.ts

@@ -43,12 +43,23 @@ export interface ReactNativeRangeDownloader
 
   // Clean the concurrent artifacts (.segN / .partial / .progress) for one task.
   // Caller invokes before falling back to its own single-stream path.
+  // Cancel-then-delete: any in-flight tasks/workers for (channel,taskId) are
+  // cancelled before the files are removed so they cannot be resurrected.
   discardArtifacts(
     channel: DownloadChannel,
     taskId: string,
     destFilePath: string
   ): Promise<void>;
 
+  // Cancel an in-flight download for (channel,taskId) and remove its artifacts.
+  // iOS cancels the matching background URLSession tasks; Android flips the
+  // worker pool's abort flag and shuts it down — both before deleting files.
+  cancel(
+    channel: DownloadChannel,
+    taskId: string,
+    destFilePath: string
+  ): Promise<void>;
+
   // Event listening: all consumers share one listener registry and filter by channel.
   addDownloadListener(callback: (event: RangeDownloadEvent) => void): number;
   removeDownloadListener(id: number): void;