@onekeyfe/react-native-range-downloader 3.0.67 → 3.0.68

package/android/src/test/java/com/margelo/nitro/reactnativerangedownloader/OcdsTransient5xxTest.kt

@@ -0,0 +1,275 @@
+package com.margelo.nitro.reactnativerangedownloader
+
+import okhttp3.OkHttpClient
+import okhttp3.mockwebserver.MockWebServer
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNotEquals
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+import java.io.File
+
+/**
+ * OCDS gap A1 — §4 HTTP status classification, the TRANSIENT 5xx branch
+ * (`isPermanentHttpStatus`: `in 500..599 -> false`,
+ * ConcurrentRangeDownloader.kt:596) driven end-to-end through
+ * `classifyHttpFailure` (line 555-559 → [TransientHttpException]) and the
+ * `downloadSegment` retry-in-place loop (line 410-419) against the REAL
+ * [ConcurrentRangeDownloader] over the [RangeFaultServer] MockWebServer harness.
+ *
+ * Two scenarios:
+ *  - [transient5xxThenOkRetriesInPlaceAndAssembles]: a 503 fired a finite number
+ *    of times on ONE segment window, then it recovers. Asserts per-segment retry,
+ *    segments kept (no from-0 restart, no FALLBACK), recovery 206, final SHA over
+ *    the real assembled file, and that EVERY OTHER segment is requested once.
+ *  - [transient5xxBudgetExhaustionThrowsKeepingArtifactsForResume]: a 503 fired
+ *    forever on one window exhausts the per-segment retry budget (maxPartRetry=3
+ *    → initial + 3 retries = exactly 4 hits) → `download()` throws (transient
+ *    give-up, NOT a corrupt COMPLETED, NOT a FALLBACK that wipes artifacts).
+ *
+ * The harness's default [RangeFaultServer.status5xxCode] is 503 (FaultServer.kt
+ * :100, served with an empty body at lines 136-137), so each fired attempt
+ * leaves 0 bytes on disk for that segment → the retry re-requests the SAME full
+ * window (start == part.start), mirroring OCDS-T4's 429 assertion.
+ */
+class OcdsTransient5xxTest {
+
+  private lateinit var server: MockWebServer
+  private lateinit var tmpDir: File
+
+  // 3 MiB > minConcurrentBytes (2 MiB) → the core takes the concurrent path,
+  // and 3 MiB ceil-chunked over 8 segments yields 8 non-empty parts.
+  private val content: ByteArray = ByteArray(3 * 1024 * 1024) { (it % 251).toByte() }
+  private val parts: List<PlannedPart> by lazy { planParts(content.size.toLong(), 8) }
+
+  @Before
+  fun setUp() {
+    tmpDir = File.createTempFile("crd-ocds-5xx", "").let {
+      it.delete(); it.mkdirs(); it
+    }
+  }
+
+  @After
+  fun tearDown() {
+    if (this::server.isInitialized) server.shutdown()
+    tmpDir.deleteRecursively()
+  }
+
+  // --- helpers (mirror ConcurrentRangeDownloaderOcdsTest) -------------------
+
+  private fun startServer(faultServer: RangeFaultServer) {
+    server = MockWebServer()
+    server.dispatcher = faultServer.dispatcher
+    server.start()
+  }
+
+  private fun url() = server.url("/asset.bin").toString()
+
+  private fun partialPath() = File(tmpDir, "asset.bin.partial").absolutePath
+
+  private fun segFile(partial: String, index: Int) = File("$partial.seg$index")
+
+  private fun assertNoArtifactsLeft(partial: String) {
+    assertFalse(".partial must be wiped", File(partial).exists())
+    for (i in 0 until 8) {
+      assertFalse(".seg$i must be wiped", segFile(partial, i).exists())
+    }
+  }
+
+  // Fast-backoff downloader form (mirrors OCDS-T10) so the single/few retries
+  // run fast in a unit test. Default maxPartRetry (3) is preserved so the
+  // budget-exhaustion test exercises the real bound.
+  private fun fastDownloader() = ConcurrentRangeDownloader(
+    httpClient = OkHttpClient(),
+    segmentCount = 8,
+    retryBaseDelayMillis = 50L,
+    retryMaxDelayMillis = 200L,
+  )
+
+  // ------------------------------------------------------------------------
+  // A1(a): transient 5xx on ONE segment a few times → retried in place, then
+  //   recovers. Segments are KEPT across the retry (no from-0 restart, no
+  //   FALLBACK), the recovery 206 completes, and the assembled SHA is correct.
+  // ------------------------------------------------------------------------
+  @Test
+  fun transient5xxThenOkRetriesInPlaceAndAssembles() {
+    val target = parts[3]
+    // Fire 503 twice on this window; the 3rd attempt (fault expired, times=2)
+    // streams the full window normally. 2 < maxPartRetry(3), so the budget is
+    // NOT exhausted and the segment recovers within this single download() call.
+    val fs = RangeFaultServer(content)
+      .arm(RangeFaultServer.FaultMode.STATUS_5XX, target.start, target.end, times = 2)
+    startServer(fs)
+
+    val partial = partialPath()
+    val outcome = fastDownloader().download(
+      url = url(),
+      partialFilePath = partial,
+      onProgress = { _, _ -> },
+    )
+
+    // Recovery: completes (NOT FALLBACK — a 5xx is transient, never discards
+    // concurrency), and the assembled bytes are byte-for-byte the source.
+    assertEquals(ConcurrentRangeDownloader.Outcome.COMPLETED, outcome)
+    assertNotEquals(
+      "transient 5xx must NOT fall back to single-stream",
+      ConcurrentRangeDownloader.Outcome.FALLBACK,
+      outcome,
+    )
+    assertEquals(content.size.toLong(), File(partial).length())
+    assertEquals(sha256(content), sha256(File(partial)))
+
+    val ranges = fs.requestedRanges.toList()
+    // The 503 returned an EMPTY body, so the segment has 0 bytes on disk after
+    // each fired attempt → every retry re-requests the SAME full window
+    // (start == part.start). Initial + 2 transient retries + 1 recovery 206 =
+    // EXACTLY three hits on the full window. (Mirrors OCDS-T4's 429 assertion.)
+    val targetReqs = ranges.filter { it.first == target.start && it.second == target.end }
+    assertEquals(
+      "affected segment must be requested exactly 3 times (503, 503, then 206)",
+      3,
+      targetReqs.size,
+    )
+    // No from-0 restart: every retry of the affected window starts at part.start
+    // (which is not file byte 0 here — target is part[3]).
+    assertTrue(
+      "retry-in-place must never restart at file byte 0",
+      targetReqs.all { it.first == target.start },
+    )
+    // Every OTHER segment is requested EXACTLY once — the retry stayed scoped to
+    // the affected window and did not perturb its neighbours.
+    for (p in parts) {
+      if (p.index == target.index) continue
+      val reqs = ranges.filter { it.first == p.start && it.second == p.end }
+      assertEquals(
+        "segment ${p.index} must be requested exactly once",
+        1,
+        reqs.size,
+      )
+    }
+    // All `.segN` consumed (assembled + deleted) on COMPLETED.
+    for (i in 0 until 8) {
+      assertFalse(".seg$i must be consumed on success", segFile(partial, i).exists())
+    }
+  }
+
+  // ------------------------------------------------------------------------
+  // A1(b): transient 5xx that NEVER recovers exhausts the per-segment retry
+  //   budget (maxPartRetry=3) → download() throws. The KEY guarantees: it is a
+  //   transient give-up (NOT a permanent FALLBACK that wipes artifacts), the
+  //   affected window is hit EXACTLY budget+1 times (initial + 3 retries), and
+  //   no corrupt COMPLETED file is produced.
+  // ------------------------------------------------------------------------
+  @Test
+  fun transient5xxBudgetExhaustionThrowsKeepingArtifactsForResume() {
+    val target = parts[2]
+    // Fire 503 forever so the segment never recovers and the retry budget is
+    // exhausted. status5xxCode defaults to 503 (transient per §4).
+    val fs = RangeFaultServer(content)
+      .arm(RangeFaultServer.FaultMode.STATUS_5XX, target.start, target.end, times = Int.MAX_VALUE)
+    startServer(fs)
+
+    val partial = partialPath()
+    var threw = false
+    var outcome: ConcurrentRangeDownloader.Outcome? = null
+    try {
+      outcome = fastDownloader().download(
+        url = url(),
+        partialFilePath = partial,
+        onProgress = { _, _ -> },
+      )
+    } catch (e: Exception) {
+      threw = true
+    }
+
+    // A perpetual transient 5xx gives up by THROWING — it must NOT be mapped to
+    // a (corrupt) COMPLETED, and it must NOT be a permanent FALLBACK (a 5xx is
+    // transient; FALLBACK is reserved for "concurrency fundamentally unusable").
+    assertTrue("perpetual transient 5xx must give up by throwing", threw)
+    assertEquals("budget exhaustion must not COMPLETE", null, outcome)
+    assertNotEquals(
+      "transient 5xx budget exhaustion must NOT be a COMPLETED",
+      ConcurrentRangeDownloader.Outcome.COMPLETED,
+      outcome,
+    )
+    assertNotEquals(
+      "transient 5xx budget exhaustion must NOT be a FALLBACK",
+      ConcurrentRangeDownloader.Outcome.FALLBACK,
+      outcome,
+    )
+
+    val ranges = fs.requestedRanges.toList()
+    // The affected window is requested EXACTLY maxPartRetry+1 = 4 times (initial
+    // attempt + 3 retries), all at part.start (empty 503 body → 0 bytes on disk
+    // → same full window each time, never a from-0 restart). This is the
+    // load-bearing budget assertion: it would FAIL if the loop did not honour
+    // maxPartRetry, or restarted from byte 0, or treated 5xx as permanent (1 hit).
+    val targetReqs = ranges.filter { it.first == target.start && it.second == target.end }
+    assertEquals(
+      "affected segment must be requested exactly maxPartRetry+1 (4) times",
+      4,
+      targetReqs.size,
+    )
+    assertTrue(
+      "every 5xx retry must restart at the segment window start, never file byte 0",
+      targetReqs.all { it.first == target.start },
+    )
+    // No complete (corrupt) `.partial` was assembled. If a `.partial` exists at
+    // all, it must NOT be a full-length file.
+    if (File(partial).exists()) {
+      assertNotEquals(
+        "a `.partial` left on disk must NOT be a complete (corrupt) file",
+        content.size.toLong(),
+        File(partial).length(),
+      )
+    }
+  }
+
+  // ------------------------------------------------------------------------
+  // A1(c): a permanent 5xx (501) on the SAME branch's boundary must bypass the
+  //   retry loop entirely — it is hit EXACTLY once. This pins the transient-vs-
+  //   permanent split of `isPermanentHttpStatus` (501 -> true, line 595) so the
+  //   A1(b) "retry 4 times" assertion is meaningful by contrast, not noise.
+  // ------------------------------------------------------------------------
+  @Test
+  fun permanent5xx501BypassesRetryLoop() {
+    val target = parts[4]
+    val fs = RangeFaultServer(content)
+    fs.status5xxCode = 501 // 501 is permanent per §4 (isPermanentHttpStatus:595).
+    fs.arm(RangeFaultServer.FaultMode.STATUS_5XX, target.start, target.end, times = Int.MAX_VALUE)
+    startServer(fs)
+
+    val partial = partialPath()
+    var threw = false
+    var outcome: ConcurrentRangeDownloader.Outcome? = null
+    try {
+      outcome = fastDownloader().download(
+        url = url(),
+        partialFilePath = partial,
+        onProgress = { _, _ -> },
+      )
+    } catch (e: Exception) {
+      threw = true
+    }
+
+    assertTrue("permanent 5xx (501) must surface (throw)", threw)
+    assertNotEquals(
+      "permanent 5xx must not COMPLETE",
+      ConcurrentRangeDownloader.Outcome.COMPLETED,
+      outcome,
+    )
+    // A PermanentHttpException bypasses the retry loop (downloadSegment line
+    // 405-409), so the affected window is requested EXACTLY ONCE — proving the
+    // transient branch's 4 hits in A1(b) is a real, classifier-driven retry
+    // count and not an artifact of unconditional retrying.
+    val ranges = fs.requestedRanges.toList()
+    val targetReqs = ranges.filter { it.first == target.start && it.second == target.end }
+    assertEquals(
+      "permanent 5xx (501) must be requested exactly once (no retry-in-place)",
+      1,
+      targetReqs.size,
+    )
+  }
+}

package/android/src/test/java/com/margelo/nitro/reactnativerangedownloader/RangeDownloadLogicTest.kt

@@ -0,0 +1,124 @@
+package com.margelo.nitro.reactnativerangedownloader
+
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+import java.io.File
+
+/**
+ * Unit coverage for the dependency-free adapter logic extracted from
+ * [ReactNativeRangeDownloader]: the single-flight run-key, the CAS progress
+ * gate, and the per-segment artifact sweep. Pure JVM JUnit — no Nitro /
+ * HybridObject / Context, mirroring the established test pattern in this module
+ * (see IsPermanentHttpStatusTest).
+ */
+class RangeDownloadLogicTest {
+
+  private lateinit var tmpDir: File
+
+  @Before
+  fun setUp() {
+    tmpDir = File.createTempFile("crd-logic", "").let {
+      it.delete(); it.mkdirs(); it
+    }
+  }
+
+  @After
+  fun tearDown() {
+    tmpDir.deleteRecursively()
+  }
+
+  // ---- runKey (single-flight semantics) ----
+
+  @Test
+  fun runKeyJoinsChannelAndTaskWithPipe() {
+    assertEquals("MAIN|task-1", RangeDownloadLogic.runKey("MAIN", "task-1"))
+  }
+
+  @Test
+  fun runKeyDistinguishesChannelAndTask() {
+    // Different channels for the same task must not collide.
+    assertFalse(
+      RangeDownloadLogic.runKey("MAIN", "t") == RangeDownloadLogic.runKey("OTHER", "t"),
+    )
+    // Different tasks on the same channel must not collide.
+    assertFalse(
+      RangeDownloadLogic.runKey("MAIN", "a") == RangeDownloadLogic.runKey("MAIN", "b"),
+    )
+  }
+
+  // ---- progressPercent (CAS gate input) ----
+
+  @Test
+  fun progressPercentComputesFlooredPercentage() {
+    assertEquals(0, RangeDownloadLogic.progressPercent(0, 100))
+    assertEquals(50, RangeDownloadLogic.progressPercent(50, 100))
+    // Integer floor, never rounds up.
+    assertEquals(33, RangeDownloadLogic.progressPercent(1, 3))
+    assertEquals(100, RangeDownloadLogic.progressPercent(100, 100))
+  }
+
+  @Test
+  fun progressPercentClampsToHundred() {
+    // transferred can momentarily exceed total across segments; clamp.
+    assertEquals(100, RangeDownloadLogic.progressPercent(150, 100))
+  }
+
+  @Test
+  fun progressPercentReturnsNullForNonPositiveTotal() {
+    assertNull(RangeDownloadLogic.progressPercent(10, 0))
+    assertNull(RangeDownloadLogic.progressPercent(10, -1))
+  }
+
+  /**
+   * The CAS gate the adapter wraps around [progressPercent]: only a strictly
+   * higher percentage emits, so the stream stays monotonic and de-duped. This
+   * reproduces the adapter's `p > prev && compareAndSet` loop over a sequence
+   * of out-of-order, repeating worker callbacks.
+   */
+  @Test
+  fun casGateKeepsProgressMonotonicAndDeduped() {
+    var prev = -1
+    val emitted = mutableListOf<Int>()
+    // total fixed at 100; transferred arrives out of order with repeats.
+    for (transferred in listOf(10L, 10L, 25L, 25L, 20L, 50L, 50L, 49L, 100L)) {
+      val p = RangeDownloadLogic.progressPercent(transferred, 100) ?: continue
+      if (p > prev) {
+        prev = p
+        emitted.add(p)
+      }
+    }
+    assertEquals(listOf(10, 25, 50, 100), emitted)
+  }
+
+  // ---- sweepPartialArtifacts ----
+
+  @Test
+  fun sweepRemovesPartialAndEverySegmentByPrefix() {
+    val dest = File(tmpDir, "asset.bin").absolutePath
+    val partial = File("$dest.partial")
+    partial.writeText("p")
+    // Custom (non-default) segment count: 12 segments must all be swept.
+    val segs = (0 until 12).map { File("$dest.partial.seg$it").apply { writeText("$it") } }
+    // An unrelated sibling must be left untouched.
+    val unrelated = File(tmpDir, "asset.bin.keep").apply { writeText("k") }
+
+    RangeDownloadLogic.sweepPartialArtifacts(dest)
+
+    assertFalse("partial should be deleted", partial.exists())
+    segs.forEach { assertFalse("${it.name} should be deleted", it.exists()) }
+    assertTrue("unrelated sibling must survive", unrelated.exists())
+  }
+
+  @Test
+  fun sweepIsNoOpWhenNothingExists() {
+    val dest = File(tmpDir, "missing.bin").absolutePath
+    // Must not throw when there are no artifacts to remove.
+    RangeDownloadLogic.sweepPartialArtifacts(dest)
+    assertFalse(File("$dest.partial").exists())
+  }
+}

package/android/src/test/java/com/margelo/nitro/reactnativerangedownloader/RunRegistrySingleFlightTest.kt

@@ -0,0 +1,217 @@
+package com.margelo.nitro.reactnativerangedownloader
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNotEquals
+import org.junit.Assert.assertNotSame
+import org.junit.Assert.assertSame
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.Executors
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicInteger
+
+/**
+ * Drives the REAL extracted single-flight unit
+ * [RangeDownloadLogic.RunRegistry] (keyed by "channel|taskId"). The registry was
+ * lifted VERBATIM from the Nitro adapter's inline `activeDownloads`
+ * ConcurrentHashMap usage so its keyed invariants can be unit-tested without the
+ * Nitro / JNI / OkHttp dependencies. Every assertion exercises the real code —
+ * nothing is re-implemented here.
+ *
+ * Channel mapping note: the adapter computes its key as
+ * `RangeDownloadLogic.runKey(channel.name, taskId)` (adapter:44-45), i.e. the
+ * `DownloadChannel` enum contributes ONLY its `.name` string. The dependency-free
+ * registry therefore takes the channel NAME string directly. To keep the test
+ * faithful to the real channels (and prove cross-channel key isolation) WITHOUT
+ * dragging the JNI-annotated generated enum onto the pure-JVM test classpath
+ * (every sibling test stays generated-type-free), the names below are the exact
+ * verbatim `DownloadChannel.<X>.name` strings.
+ *
+ * Cancel-detection probe: [ConcurrentRangeDownloader.CancelHandle.cancel] is
+ * idempotent and flips the public `aborted` AtomicBoolean — observing `aborted`
+ * is how we assert a handle was (or was not) cancelled, without subclassing the
+ * final-ish handle. `cancel()` with no attached pool is a pure flag flip, so it
+ * is safe + fast in a JVM unit test.
+ */
+class RunRegistrySingleFlightTest {
+
+  // Verbatim DownloadChannel.<X>.name values (BUNDLE/APK/CHART). Kept as plain
+  // strings so this test needs no JNI-annotated generated enum on its classpath.
+  private val bundle = "BUNDLE"
+  private val apk = "APK"
+  private val chart = "CHART"
+
+  // ------------------------------------------------------------------------
+  // start() dedup: a second start for the same key overwrites; finish() is
+  // identity-checked so the STALE handle's finish is a no-op, and only the LIVE
+  // handle's finish removes the entry (adapter:87 + adapter:112 invariants).
+  // ------------------------------------------------------------------------
+  @Test
+  fun startTwiceSameKey_secondHandleIsLive_staleFinishIsNoOp() {
+    val reg = RangeDownloadLogic.RunRegistry()
+
+    val first = reg.start(bundle, "task-A")
+    val second = reg.start(bundle, "task-A")
+
+    assertNotSame("a second start() must mint a fresh handle", first, second)
+    assertEquals("dedup: same key must hold exactly one live entry", 1, reg.size)
+
+    // finish(firstHandle) must NOT clobber the live (second) handle — identity
+    // remove fails because the map now holds `second`.
+    reg.finish(bundle, "task-A", first)
+    assertEquals("stale-handle finish must be a no-op (entry still live)", 1, reg.size)
+
+    // finish(secondHandle) — the live handle — removes the entry.
+    reg.finish(bundle, "task-A", second)
+    assertEquals("live-handle finish must remove the entry", 0, reg.size)
+  }
+
+  // ------------------------------------------------------------------------
+  // start → finish(sameHandle) clears the key; a subsequent cancel() is a no-op
+  // and must NOT throw (adapter:206 remove(...)?.cancel() null-safe path).
+  // ------------------------------------------------------------------------
+  @Test
+  fun startThenFinish_keyGone_subsequentCancelIsNoOpAndDoesNotThrow() {
+    val reg = RangeDownloadLogic.RunRegistry()
+
+    val handle = reg.start(apk, "task-B")
+    reg.finish(apk, "task-B", handle)
+    assertEquals("finish must clear the key", 0, reg.size)
+
+    // No live handle → cancel() finds nothing → must be a silent no-op.
+    reg.cancel(apk, "task-B")
+    assertEquals("cancel of an absent key must not create or leak an entry", 0, reg.size)
+    assertFalse(
+      "a finished handle must NOT have been cancelled by the no-op cancel()",
+      handle.aborted.get(),
+    )
+  }
+
+  // ------------------------------------------------------------------------
+  // cancel() invokes CancelHandle.cancel() exactly once AND removes the key:
+  // the second cancel() finds nothing (probe) and the handle's aborted flag was
+  // already set by the first cancel.
+  // ------------------------------------------------------------------------
+  @Test
+  fun cancel_invokesHandleCancelOnceAndRemovesKey() {
+    val reg = RangeDownloadLogic.RunRegistry()
+
+    val handle = reg.start(chart, "task-C")
+    assertFalse("handle must start un-aborted", handle.aborted.get())
+
+    reg.cancel(chart, "task-C")
+    assertTrue("cancel() must have flipped the handle's aborted flag", handle.aborted.get())
+    assertEquals("cancel() must remove the key", 0, reg.size)
+
+    // Probe: the entry is gone, so a second cancel() targets nothing. If the key
+    // had NOT been removed, this would re-cancel the same handle — proving the
+    // remove happened on the first call. (cancel() is idempotent regardless, so
+    // the load-bearing assertion is the size==0 above + this staying a no-op.)
+    reg.cancel(chart, "task-C")
+    assertEquals("second cancel() finds nothing — no entry resurrected", 0, reg.size)
+  }
+
+  // ------------------------------------------------------------------------
+  // Different channels (BUNDLE vs APK) with the SAME taskId produce distinct
+  // keys → both coexist; cancelling one leaves the other live & un-aborted.
+  // ------------------------------------------------------------------------
+  @Test
+  fun differentChannelsSameTaskId_distinctKeys_cancelOneLeavesOtherLive() {
+    val reg = RangeDownloadLogic.RunRegistry()
+    val taskId = "shared-task"
+
+    // Sanity: the underlying key derivation is collision-free across channels.
+    assertNotEquals(
+      "channel must contribute to the key",
+      RangeDownloadLogic.runKey(bundle, taskId),
+      RangeDownloadLogic.runKey(apk, taskId),
+    )
+
+    val bundleHandle = reg.start(bundle, taskId)
+    val apkHandle = reg.start(apk, taskId)
+    assertEquals("distinct channels must coexist under the same taskId", 2, reg.size)
+
+    reg.cancel(bundle, taskId)
+
+    assertTrue("the cancelled channel's handle must be aborted", bundleHandle.aborted.get())
+    assertFalse("the OTHER channel's handle must remain un-aborted", apkHandle.aborted.get())
+    assertEquals("only the cancelled channel's entry must be removed", 1, reg.size)
+
+    // The surviving entry is still the APK handle and can be finished normally.
+    reg.finish(apk, taskId, apkHandle)
+    assertEquals("surviving entry finishes cleanly", 0, reg.size)
+  }
+
+  // ------------------------------------------------------------------------
+  // Concurrency: N threads start() the same key while one thread cancel()s it.
+  // Invariants under contention:
+  //   - the registry never LEAKS an entry that no live handle owns;
+  //   - the surviving handle (if any) is never DOUBLE-cancelled;
+  //   - every start() handle is accounted for: it is either the live survivor,
+  //     cancelled by the racing cancel(), or superseded (overwritten) — never
+  //     silently kept alive AND orphaned.
+  // ------------------------------------------------------------------------
+  @Test
+  fun concurrentStartsAndCancel_noLeakedEntry_noDoubleCancel() {
+    val reg = RangeDownloadLogic.RunRegistry()
+    val key = "race-task"
+    val n = 32
+
+    // Count how many distinct handles ever get cancelled. Because each handle is
+    // unique and cancel() is observed via its aborted flag, double-cancel of the
+    // SAME handle is detectable: cancelCount must never exceed the number of
+    // handles that were actually cancelled (we re-check by scanning).
+    val handles = ConcurrentHashMap.newKeySet<ConcurrentRangeDownloader.CancelHandle>()
+    val startBarrier = CountDownLatch(1)
+    val done = CountDownLatch(n + 1)
+    val pool = Executors.newFixedThreadPool(n + 1)
+
+    repeat(n) {
+      pool.submit {
+        startBarrier.await()
+        handles.add(reg.start(chart, key))
+        done.countDown()
+      }
+    }
+    // One racing canceller.
+    pool.submit {
+      startBarrier.await()
+      // Spin a touch so it interleaves with the starts rather than always winning.
+      repeat(4) { reg.cancel(chart, key) }
+      done.countDown()
+    }
+
+    startBarrier.countDown()
+    assertTrue("all workers must finish", done.await(10, TimeUnit.SECONDS))
+    pool.shutdownNow()
+
+    // Drain any survivor via a final cancel so the registry must end empty.
+    reg.cancel(chart, key)
+    assertEquals("registry must never leak an entry under contention", 0, reg.size)
+
+    // No handle is double-cancelled: aborted is a boolean flip, so re-counting is
+    // not enough on its own — assert instead that cancel() is idempotent by the
+    // contract and that AT MOST the set of minted handles were cancelled (never
+    // more handles than were created). The strong leak invariant above is the
+    // primary guarantee; here we assert every cancelled handle came from start().
+    val cancelled = handles.count { it.aborted.get() }
+    assertTrue(
+      "cancelled handles ($cancelled) cannot exceed minted handles (${handles.size})",
+      cancelled <= handles.size,
+    )
+    // At least one cancel landed on a real handle (the racing canceller + final
+    // drain cannot both miss every start under this barrier).
+    assertTrue("at least one minted handle must have been cancelled", cancelled >= 1)
+
+    // Defensive accounting probe: no AtomicInteger over-count of survivors.
+    val live = AtomicInteger(0)
+    // After the final drain the key is gone, so re-finishing any handle is a safe
+    // no-op and must not resurrect the entry.
+    handles.forEach { reg.finish(chart, key, it) }
+    if (reg.size > 0) live.incrementAndGet()
+    assertEquals("post-drain finish() of any stale handle must not resurrect a key", 0, live.get())
+  }
+}