react-native-queue-player 1.2.0 → 2.0.1

package/android/src/test/java/com/margelo/nitro/queueplayer/LookaheadCacheTest.kt

@@ -1,11 +1,16 @@
 package com.margelo.nitro.queueplayer
 
+import android.net.Uri
 import androidx.media3.common.util.UnstableApi
+import androidx.media3.datasource.DataSource
+import androidx.media3.datasource.DataSpec
 import androidx.media3.datasource.DefaultHttpDataSource
+import androidx.media3.datasource.TransferListener
 import androidx.media3.datasource.cache.CacheDataSource
 import androidx.test.core.app.ApplicationProvider
 import org.junit.After
 import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
 import org.junit.Assert.assertNotNull
 import org.junit.Assert.assertTrue
 import org.junit.Before
@@ -20,8 +25,8 @@ import java.io.File
  *
  * Exercises the cache directly without going through ExoPlayer:
  * - Constructor creates the cache directory under `context.cacheDir`.
- * - `wrapDataSourceFactory` returns a [CacheDataSource.Factory]-shaped
- *   factory rooted at this cache.
+ * - `wrapDataSourceFactory` hands out a [CacheDataSource] while the cache
+ *   serves playback and the bare upstream source while it does not.
  * - `release()` is idempotent, and a fresh cache can be constructed
  *   at the same directory afterwards (the SimpleCache one-instance-
  *   per-directory invariant is restored on release).
@@ -69,25 +74,88 @@ class LookaheadCacheTest {
   }
 
   @Test
-  fun `wrapDataSourceFactory returns a CacheDataSource Factory`() {
+  fun `the wrapped factory reads through the cache while it serves playback`() {
     val upstream = DefaultHttpDataSource.Factory()
     val wrapped = cache.wrapDataSourceFactory(upstream)
-    assertNotNull(wrapped)
+    val source = wrapped.createDataSource()
     assertTrue(
-      "wrapped factory must produce a CacheDataSource so reads check the LRU first",
-      wrapped is CacheDataSource.Factory
+      "a data source opened while the cache is enabled checks the disk first",
+      source is CacheDataSource
     )
   }
 
+  /**
+   * Only the prefetcher fills the cache. The playback factory is built with a
+   * null cache-write sink, which is what Media3 reads as `cacheIsReadOnly`, so
+   * a body pulled all the way through it leaves nothing on disk.
+   */
+  @Test
+  fun `a body read through the playback factory is not written to the cache`() {
+    val body = ByteArray(4096) { it.toByte() }
+    val url = "https://example.com/playback-read.mp3"
+    val source = cache.wrapDataSourceFactory(FixedBodyDataSource.Factory(body))
+      .createDataSource()
+
+    source.open(DataSpec.Builder().setUri(url).setKey(url).build())
+    val buffer = ByteArray(1024)
+    var total = 0
+    while (true) {
+      val read = source.read(buffer, 0, buffer.size)
+      if (read == -1) break
+      total += read
+    }
+    source.close()
+
+    assertEquals("the whole body reaches the caller", body.size, total)
+    assertEquals("nothing is written to disk", 0L, cache.currentSizeBytes())
+    assertFalse("and the url is not held as cached", cache.isFullyCached(url))
+  }
+
+  /** Serves a fixed body for any [DataSpec], honouring its position. */
+  private class FixedBodyDataSource(private val body: ByteArray) : DataSource {
+    class Factory(private val body: ByteArray) : DataSource.Factory {
+      override fun createDataSource(): DataSource = FixedBodyDataSource(body)
+    }
+
+    private var uri: Uri? = null
+    private var position = 0
+
+    override fun open(dataSpec: DataSpec): Long {
+      uri = dataSpec.uri
+      position = dataSpec.position.toInt()
+      return (body.size - position).toLong()
+    }
+
+    override fun read(buffer: ByteArray, offset: Int, length: Int): Int {
+      if (position >= body.size) return -1
+      val take = minOf(length, body.size - position)
+      body.copyInto(buffer, offset, position, position + take)
+      position += take
+      return take
+    }
+
+    override fun getUri(): Uri? = uri
+    override fun close() {}
+    override fun addTransferListener(transferListener: TransferListener) {}
+  }
+
+  /**
+   * Disabled means every read goes to the origin and nothing is written,
+   * whatever the disk holds — the wrapper hands out the bare upstream source.
+   * Decided per data source, so a change reaches the next item load.
+   */
   @Test
-  fun `wrapped factory creates DataSources rooted at the same SimpleCache`() {
+  fun `the wrapped factory bypasses the cache while it does not serve playback`() {
     val upstream = DefaultHttpDataSource.Factory()
     val wrapped = cache.wrapDataSourceFactory(upstream)
-    val source = wrapped.createDataSource()
-    assertTrue(
-      "createDataSource must produce a CacheDataSource — the cache check happens at read time",
-      source is androidx.media3.datasource.cache.CacheDataSource
-    )
+
+    cache.servesPlayback = false
+    val bypassed = wrapped.createDataSource()
+    cache.servesPlayback = true
+    val served = wrapped.createDataSource()
+
+    assertTrue("disabled: the upstream source, no cache in front", bypassed !is CacheDataSource)
+    assertTrue("re-enabled: the next source goes through the cache again", served is CacheDataSource)
   }
 
   @Test
@@ -125,13 +193,11 @@ class LookaheadCacheTest {
   }
 
   @Test
-  fun `default max size constant matches the documented bootstrap budget`() {
-    // Guards against an accidental tweak — the bootstrap budget is
-    // load-bearing for the 1.24-1.27 interim (consumers see the
-    // library's automatic disk usage before the runtime config API
-    // ships).
+  fun `default max size is 100 MB`() {
+    // The default is what a consumer that omits `lookaheadCacheMaxSizeMb`
+    // from `configure()` gets, so it is part of the public contract.
     assertEquals(
-      "bootstrap budget should be 100 MB the runtime config",
+      "default disk budget",
       100L * 1024L * 1024L,
       LookaheadCache.DEFAULT_MAX_SIZE_BYTES
     )

package/android/src/test/java/com/margelo/nitro/queueplayer/LookaheadCacheWriterCancelTest.kt

@@ -0,0 +1,85 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.util.UnstableApi
+import androidx.test.core.app.ApplicationProvider
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+
+/**
+ * Cancelling a prefetch stops the write that is running, not only the
+ * coroutine around it.
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+@UnstableApi
+class LookaheadCacheWriterCancelTest {
+
+  private fun httpTrack(id: String) = TrackItem(
+    id = id, url = "https://example.com/$id.m4a", title = null, artist = null, album = null,
+    duration = null, artworkUrl = null, extras = null,
+    replayGainTrackGain = null, replayGainTrackPeak = null,
+    replayGainAlbumGain = null, replayGainAlbumPeak = null)
+
+  /**
+   * `CacheWriter.cache()` blocks and polls only its own cancelled flag, so a
+   * cancelled coroutine alone would leave it writing. The download body
+   * relays the cancellation onto the writer; `CacheWriter` then closes its
+   * source, which is what this observes.
+   */
+  @Test
+  fun `cancel stops the running download, not just its coroutine`() {
+    val cache = LookaheadCache(
+      context = ApplicationProvider.getApplicationContext(),
+      maxSizeBytes = 4L * 1024L * 1024L,
+      cacheDirName = "writer-cancel-${System.nanoTime()}"
+    )
+    val source = TricklingDataSource()
+    val writer = LookaheadCacheWriter.create(
+      cache = cache,
+      httpFactory = androidx.media3.datasource.DataSource.Factory { source },
+      isOnCellular = { false }
+    )
+    try {
+      // The window is the tracks ahead of the current one.
+      writer.reschedule(listOf(httpTrack("current"), httpTrack("slow")), currentIndex = 0, lookaheadCount = 1)
+      assertTrue("the download must have opened its source", source.opened.await(5, TimeUnit.SECONDS))
+
+      writer.cancel()
+
+      assertTrue("a cancelled write closes its source", source.closed.await(5, TimeUnit.SECONDS))
+    } finally {
+      writer.release()
+      cache.release()
+    }
+  }
+
+  /** A source that hands out one byte at a time, forever, until closed. */
+  private class TricklingDataSource : androidx.media3.datasource.DataSource {
+    val opened = CountDownLatch(1)
+    val closed = CountDownLatch(1)
+    private var uri: android.net.Uri? = null
+
+    override fun addTransferListener(transferListener: androidx.media3.datasource.TransferListener) {}
+    override fun open(dataSpec: androidx.media3.datasource.DataSpec): Long {
+      uri = dataSpec.uri
+      opened.countDown()
+      return androidx.media3.common.C.LENGTH_UNSET.toLong()
+    }
+    override fun read(buffer: ByteArray, offset: Int, length: Int): Int {
+      if (length == 0) return 0
+      Thread.sleep(2)
+      buffer[offset] = 0
+      return 1
+    }
+    override fun getUri(): android.net.Uri? = uri
+    override fun close() {
+      closed.countDown()
+    }
+  }
+
+}

package/android/src/test/java/com/margelo/nitro/queueplayer/LookaheadCacheWriterTest.kt

@@ -57,6 +57,18 @@ class LookaheadCacheWriterTest {
     assertTrue(w.computeTargets(emptyList(), currentIndex = 0, lookaheadCount = 3).isEmpty())
   }
 
+  @Test
+  fun `computeTargets clamps a lookaheadCount that would overflow the range`() {
+    // The count arrives as a JS Double, so Infinity reaches Int.MAX_VALUE here
+    // and `start + count` wraps negative — a range subList rejects outright.
+    val w = newWriter()
+    val tracks = (1..3).map { httpTrack("t$it") }
+    assertEquals(
+      2,
+      w.computeTargets(tracks, currentIndex = 0, lookaheadCount = Int.MAX_VALUE).size
+    )
+  }
+
   @Test
   fun `computeTargets returns empty for non-positive lookaheadCount`() {
     val w = newWriter()
@@ -632,6 +644,103 @@ class LookaheadCacheWriterTest {
 
   // --- Helpers
 
+  // --- allowsCellularAccess
+
+  @Test
+  fun `prefetch is skipped while cellular is not permitted and the network is cellular`() = runTest {
+    val downloads = mutableListOf<String>()
+    val writer = LookaheadCacheWriter(
+      downloader = { track -> downloads.add(track.id ?: "") },
+      scope = CoroutineScope(StandardTestDispatcher(testScheduler) + SupervisorJob()),
+      isOnCellular = { true }
+    )
+    writer.allowsCellularAccess = false
+
+    writer.reschedule((0..4).map { httpTrack("t$it") }, currentIndex = 0, lookaheadCount = 3)
+    advanceUntilIdle()
+
+    assertTrue(downloads.isEmpty())
+    assertNull(writer.orchestratorJob)
+  }
+
+  @Test
+  fun `prefetch runs on a non-cellular network even when cellular is not permitted`() = runTest {
+    val downloads = mutableListOf<String>()
+    val writer = LookaheadCacheWriter(
+      downloader = { track -> downloads.add(track.id ?: "") },
+      scope = CoroutineScope(StandardTestDispatcher(testScheduler) + SupervisorJob()),
+      isOnCellular = { false }
+    )
+    writer.allowsCellularAccess = false
+
+    writer.reschedule((0..4).map { httpTrack("t$it") }, currentIndex = 0, lookaheadCount = 3)
+    advanceUntilIdle()
+
+    assertEquals(listOf("t1", "t2", "t3"), downloads)
+  }
+
+  @Test
+  fun `prefetch runs on cellular while it is permitted`() = runTest {
+    val downloads = mutableListOf<String>()
+    val writer = LookaheadCacheWriter(
+      downloader = { track -> downloads.add(track.id ?: "") },
+      scope = CoroutineScope(StandardTestDispatcher(testScheduler) + SupervisorJob()),
+      isOnCellular = { true }
+    )
+
+    writer.reschedule((0..4).map { httpTrack("t$it") }, currentIndex = 0, lookaheadCount = 3)
+    advanceUntilIdle()
+
+    assertEquals(listOf("t1", "t2", "t3"), downloads)
+  }
+
+  @Test
+  fun `handing off to cellular cancels the download in flight`() = runBlocking<Unit> {
+    val started = CompletableDeferred<Unit>()
+    val release = CompletableDeferred<Unit>()
+    var onCellular = false
+    val writer = LookaheadCacheWriter(
+      downloader = { started.complete(Unit); release.await() },
+      scope = CoroutineScope(SupervisorJob()),
+      isOnCellular = { onCellular }
+    )
+    writer.allowsCellularAccess = false
+    val queue = (0..4).map { httpTrack("t$it") }
+    writer.reschedule(queue, currentIndex = 0, lookaheadCount = 3)
+    started.await()
+    // Captured before the handoff: the orchestrator clears `inFlightJob` on its
+    // own thread once the cancelled download resumes it, so reading the slot
+    // afterwards races that clear.
+    val inFlightBefore = writer.inFlightJob
+
+    onCellular = true
+    writer.reschedule(queue, currentIndex = 0, lookaheadCount = 3)
+
+    assertTrue("the download in flight must be cancelled", inFlightBefore?.isCancelled == true)
+    release.complete(Unit)
+  }
+
+  @Test
+  fun `turning cellular back on refills the window on the next reschedule`() = runTest {
+    val downloads = mutableListOf<String>()
+    val writer = LookaheadCacheWriter(
+      downloader = { track -> downloads.add(track.id ?: "") },
+      scope = CoroutineScope(StandardTestDispatcher(testScheduler) + SupervisorJob()),
+      isOnCellular = { true }
+    )
+    val queue = (0..4).map { httpTrack("t$it") }
+    writer.allowsCellularAccess = false
+    writer.reschedule(queue, currentIndex = 0, lookaheadCount = 3)
+    advanceUntilIdle()
+    assertTrue(downloads.isEmpty())
+
+    writer.allowsCellularAccess = true
+    writer.reschedule(queue, currentIndex = 0, lookaheadCount = 3)
+    advanceUntilIdle()
+
+    assertEquals(listOf("t1", "t2", "t3"), downloads)
+  }
+
   private fun httpTrack(id: String): TrackItem =
     makeTrack(id, "https://example.com/$id.m4a")
 
@@ -644,6 +753,8 @@ class LookaheadCacheWriterTest {
       album = null,
       duration = null,
       artworkUrl = null,
-      extras = null
+      extras = null,
+      replayGainTrackGain = null, replayGainTrackPeak = null,
+      replayGainAlbumGain = null, replayGainAlbumPeak = null
     )
 }

package/android/src/test/java/com/margelo/nitro/queueplayer/MediaItemBuilderTest.kt

@@ -171,7 +171,7 @@ class MediaItemBuilderTest {
     // Parity with iOS `AVQueueBuilderTests.testMakeItemForFileURL
     // SkipsHeaderDictionary`: the test asserts the URI scheme is
     // preserved, but does NOT assert the file/remote routing
-    // downstream. The factory plumbing is opaque post-build on
+    // downstream. What the factory built is unreadable post-build on
     // both platforms (AVURLAsset options can't be read back on
     // iOS; DefaultDataSource.Factory wiring is internal on
     // Android), so the documented contract is the test.
@@ -184,7 +184,7 @@ class MediaItemBuilderTest {
     assertEquals("file", uri?.scheme)
   }
 
-  // --- buildMediaItems MIME plumbing
+  // --- buildMediaItems MIME handling
 
   @Test
   fun `buildMediaItems sets MIME from URL extension for http urls`() {
@@ -474,6 +474,8 @@ class MediaItemBuilderTest {
       album = album,
       duration = duration,
       artworkUrl = artworkUrl,
-      extras = null
+      extras = null,
+      replayGainTrackGain = null, replayGainTrackPeak = null,
+      replayGainAlbumGain = null, replayGainAlbumPeak = null
     )
 }

package/android/src/test/java/com/margelo/nitro/queueplayer/MediaResponseCheckTest.kt

@@ -0,0 +1,163 @@
+package com.margelo.nitro.queueplayer
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+
+/**
+ * What the cache will and will not believe is a track, judged from a response's
+ * declared type and the first bytes of its body. Mirrors iOS's
+ * `MediaResponseCheckTests` case for case so the two platforms refuse and
+ * accept the same responses.
+ */
+class MediaResponseCheckTest {
+
+  private val xmlEnvelope =
+    """<api-response status="failed"><error code="70"/></api-response>""".toByteArray()
+  private val mp3 = byteArrayOf(0x49, 0x44, 0x33, 0x04, 0, 0, 0, 0)
+
+  private fun rejection(
+    contentType: String?,
+    body: ByteArray,
+    whole: Boolean = true
+  ): MediaResponseCheck.Rejection? =
+    MediaResponseCheck.rejection(contentType, body, headIsStartOfResource = whole)
+
+  @Test
+  fun markupAndJsonContentTypesAreRefused() {
+    for (type in listOf(
+      "application/xml", "text/xml", "text/html",
+      "application/xhtml+xml", "application/json", "text/json",
+    )) {
+      assertEquals(
+        "$type is a document type",
+        MediaResponseCheck.Rejection.MarkupContentType(type),
+        rejection(type, xmlEnvelope)
+      )
+    }
+  }
+
+  @Test
+  fun theDeclaredTypeIsReadWithoutItsParameters() {
+    assertEquals(
+      MediaResponseCheck.Rejection.MarkupContentType("application/xml"),
+      rejection("application/xml; charset=utf-8", xmlEnvelope)
+    )
+    assertEquals(
+      MediaResponseCheck.Rejection.MarkupContentType("application/xml"),
+      rejection("APPLICATION/XML", xmlEnvelope)
+    )
+  }
+
+  @Test
+  fun aDeclaredDocumentIsRefusedOnAPartialBodyToo() {
+    assertEquals(
+      MediaResponseCheck.Rejection.MarkupContentType("application/xml"),
+      rejection("application/xml", byteArrayOf(0x3C, 0x00), whole = false)
+    )
+  }
+
+  @Test
+  fun aPartialBodyIsNotJudgedByItsLeadingBytes() {
+    // The same markup, under a type that is not itself a document, so only the
+    // leading-byte rule can decide: refused as a whole resource, accepted as a
+    // range, which is what separates the two inputs.
+    val markup = "<api-response/>".toByteArray()
+    assertEquals(
+      MediaResponseCheck.Rejection.MarkupBody,
+      rejection("application/octet-stream", markup)
+    )
+    assertNull(
+      "a body that begins part way into a file says nothing about its first bytes",
+      rejection("application/octet-stream", markup, whole = false)
+    )
+  }
+
+  @Test
+  fun textWithoutAContainerSignatureIsRefused() {
+    assertEquals(
+      MediaResponseCheck.Rejection.TextWithoutMediaSignature("text/plain"),
+      rejection("text/plain", "not found".toByteArray())
+    )
+  }
+
+  @Test
+  fun textCarryingAContainerSignatureIsAccepted() {
+    assertNull(
+      "a server mislabelling audio as text does not make it a document",
+      rejection("text/plain", mp3)
+    )
+  }
+
+  @Test
+  fun aPlaylistDeclaredAsTextIsAccepted() {
+    assertNull(rejection("text/plain", "#EXTM3U\n#EXT-X-VERSION:3".toByteArray()))
+  }
+
+  @Test
+  fun aMarkupBodyIsRefusedWhenNothingUsableIsDeclared() {
+    assertEquals(MediaResponseCheck.Rejection.MarkupBody, rejection(null, xmlEnvelope))
+    assertEquals(
+      MediaResponseCheck.Rejection.MarkupBody,
+      rejection("application/octet-stream", xmlEnvelope)
+    )
+    assertEquals(
+      MediaResponseCheck.Rejection.MarkupBody,
+      rejection(null, "<!DOCTYPE html><html>".toByteArray())
+    )
+    assertEquals(
+      MediaResponseCheck.Rejection.MarkupBody,
+      rejection(null, """{"error":"not found"}""".toByteArray())
+    )
+  }
+
+  @Test
+  fun leadingSpaceAndAByteOrderMarkDoNotHideAMarkupBody() {
+    assertEquals(
+      MediaResponseCheck.Rejection.MarkupBody,
+      rejection(null, "\n  <?xml version=\"1.0\"?>".toByteArray())
+    )
+    assertEquals(
+      MediaResponseCheck.Rejection.MarkupBody,
+      rejection(null, byteArrayOf(0xEF.toByte(), 0xBB.toByte(), 0xBF.toByte()) + "<error/>".toByteArray())
+    )
+    // `FF FE` also satisfies the MPEG frame sync, so a UTF-16 document would
+    // read as audio if the mark were not dropped first.
+    assertEquals(
+      MediaResponseCheck.Rejection.MarkupBody,
+      rejection(null, byteArrayOf(0xFF.toByte(), 0xFE.toByte()) + "<e/>".toByteArray())
+    )
+  }
+
+  @Test
+  fun recognisedContainersAreAccepted() {
+    val bodies = mapOf(
+      "ID3" to byteArrayOf(0x49, 0x44, 0x33, 0x04, 0, 0, 0, 0),
+      "MPEG frame sync" to byteArrayOf(0xFF.toByte(), 0xFB.toByte(), 0x90.toByte(), 0, 0, 0, 0, 0),
+      "ADTS AAC" to byteArrayOf(0xFF.toByte(), 0xF1.toByte(), 0x50, 0x80.toByte(), 0, 0, 0, 0),
+      "FLAC" to byteArrayOf(0x66, 0x4C, 0x61, 0x43, 0, 0, 0, 0),
+      "Ogg" to byteArrayOf(0x4F, 0x67, 0x67, 0x53, 0, 0, 0, 0),
+      "WAV" to byteArrayOf(0x52, 0x49, 0x46, 0x46, 0, 0, 0, 0),
+      "AIFF" to byteArrayOf(0x46, 0x4F, 0x52, 0x4D, 0, 0, 0, 0),
+      "CAF" to byteArrayOf(0x63, 0x61, 0x66, 0x66, 0, 0, 0, 0),
+      "MP4" to byteArrayOf(0, 0, 0, 0x20, 0x66, 0x74, 0x79, 0x70),
+    )
+    for ((name, bytes) in bodies) {
+      assertNull("$name is media", rejection("text/plain", bytes))
+      assertNull("$name is media", rejection(null, bytes))
+    }
+  }
+
+  @Test
+  fun anUndeclaredOrOpaqueBinaryBodyIsAccepted() {
+    val binary = byteArrayOf(0x00, 0x01, 0x02, 0x03, 0x04)
+    assertNull("an unrecognised container is not a document", rejection(null, binary))
+    assertNull(rejection("application/octet-stream", binary))
+    assertNull(rejection("audio/mpeg", binary))
+  }
+
+  @Test
+  fun anEmptyBodyIsNotJudged() {
+    assertNull(rejection(null, ByteArray(0)))
+  }
+}