react-native-queue-player 1.2.0 → 2.0.1

package/ios/Tests/LookaheadCachePrefetcherTests.swift

@@ -25,9 +25,8 @@ private let ASYNC_DISPATCH_TIMEOUT: TimeInterval = 30.0
 ///    look-back tail, the in-flight keep/cancel rule, and the
 ///    drain-on-tearDown contract.
 ///
-/// `@MainActor` because `reschedule` / `cancel` / `tearDown` enforce
-/// `dispatchPrecondition(condition: .onQueue(.main))` — tests must
-/// invoke them on main to match the production caller contract.
+/// `@MainActor` because `reschedule` / `cancel` / `tearDown` assert the queue
+/// the prefetcher was confined to, and these tests confine it to main.
 @MainActor
 final class LookaheadCachePrefetcherTests: XCTestCase {
 
@@ -135,9 +134,33 @@ final class LookaheadCachePrefetcherTests: XCTestCase {
 
   // MARK: - Orchestration
 
+  func testRescheduleRunsOnTheInjectedQueueRatherThanMain() async {
+    let downloader = StubDownloader()
+    let confinement = DispatchQueue(label: "test.prefetcher.confinement")
+    let p = LookaheadCachePrefetcher(downloader: downloader, confinedTo: confinement)
+    let tracks = (0 ..< 3).map { httpTrack("q\($0)") }
+
+    // The precondition inside `reschedule` fails the run if the caller is not
+    // on the confinement queue, so entering from it is the assertion.
+    let scheduled = expectation(description: "reschedule accepted from the injected queue")
+    // A `DispatchWorkItem` rather than a trailing closure: the prefetcher is
+    // confined to `confinement`, not shared across threads, so it does not
+    // belong in a `@Sendable` closure.
+    confinement.async(execute: DispatchWorkItem {
+      p.reschedule(tracks: tracks, currentIndex: 0, lookaheadCount: 2)
+      scheduled.fulfill()
+    })
+    await fulfillment(of: [scheduled], timeout: 2.0)
+    await p.awaitCurrent()
+
+    XCTAssertEqual(
+      downloader.invocations, ["q1", "q2"],
+      "the lookahead covers the tracks ahead of the current one, in order")
+  }
+
   func testRescheduleWithEmptyTargetsLeavesOrchestratorIdle() async {
     let downloader = StubDownloader()
-    let p = LookaheadCachePrefetcher(downloader: downloader)
+    let p = LookaheadCachePrefetcher(downloader: downloader, confinedTo: .main)
     p.reschedule(tracks: [], currentIndex: 0, lookaheadCount: 3)
     await p.awaitCurrent()
     XCTAssertFalse(p.hasInFlightTask)
@@ -146,7 +169,7 @@ final class LookaheadCachePrefetcherTests: XCTestCase {
 
   func testRescheduleDispatchesDownloadsSequentiallyInQueueOrder() async {
     let downloader = StubDownloader()
-    let p = LookaheadCachePrefetcher(downloader: downloader)
+    let p = LookaheadCachePrefetcher(downloader: downloader, confinedTo: .main)
     let q = (0..<5).map { httpTrack("t\($0)") }
 
     p.reschedule(tracks: q, currentIndex: 0, lookaheadCount: 3)
@@ -158,7 +181,7 @@ final class LookaheadCachePrefetcherTests: XCTestCase {
 
   func testRescheduleSwallowsPerTrackErrorAndContinues() async {
     let downloader = StubDownloader(failingTrackIds: ["t2"])
-    let p = LookaheadCachePrefetcher(downloader: downloader)
+    let p = LookaheadCachePrefetcher(downloader: downloader, confinedTo: .main)
     let q = (0..<5).map { httpTrack("t\($0)") }
 
     p.reschedule(tracks: q, currentIndex: 0, lookaheadCount: 3)
@@ -173,7 +196,7 @@ final class LookaheadCachePrefetcherTests: XCTestCase {
     // download attempt without marking the URL "done"; the next
     // reschedule that still wants that URL must retry it.
     let downloader = StubDownloader(failingTrackIds: ["t2"])
-    let p = LookaheadCachePrefetcher(downloader: downloader)
+    let p = LookaheadCachePrefetcher(downloader: downloader, confinedTo: .main)
     let q = (0..<5).map { httpTrack("t\($0)") }
 
     p.reschedule(tracks: q, currentIndex: 0, lookaheadCount: 3)
@@ -204,7 +227,7 @@ final class LookaheadCachePrefetcherTests: XCTestCase {
     // leaving the prefetcher idle and ready for a fresh reschedule
     // when connectivity returns.
     let downloader = StubDownloader(failingTrackIds: ["t1", "t2", "t3"])
-    let p = LookaheadCachePrefetcher(downloader: downloader)
+    let p = LookaheadCachePrefetcher(downloader: downloader, confinedTo: .main)
     let q = (0..<5).map { httpTrack("t\($0)") }
 
     p.reschedule(tracks: q, currentIndex: 0, lookaheadCount: 3)
@@ -237,7 +260,7 @@ final class LookaheadCachePrefetcherTests: XCTestCase {
       onStart: { firstStarted.fulfill() },
       hold: firstHold
     )
-    let p = LookaheadCachePrefetcher(downloader: downloader)
+    let p = LookaheadCachePrefetcher(downloader: downloader, confinedTo: .main)
     let queue = [
       httpTrack("cur"), httpTrack("old-1"), httpTrack("old-2"),
       httpTrack("old-3"), httpTrack("old-4"),
@@ -268,7 +291,7 @@ final class LookaheadCachePrefetcherTests: XCTestCase {
       onStart: { firstStarted.fulfill() },
       hold: firstHold
     )
-    let p = LookaheadCachePrefetcher(downloader: downloader)
+    let p = LookaheadCachePrefetcher(downloader: downloader, confinedTo: .main)
 
     p.reschedule(
       tracks: [httpTrack("cur"), httpTrack("old-1"), httpTrack("old-2")],
@@ -296,7 +319,7 @@ final class LookaheadCachePrefetcherTests: XCTestCase {
 
   func testRescheduleAppendsLookbackAsLastTargetAfterForwardWindow() async {
     let downloader = StubDownloader()
-    let p = LookaheadCachePrefetcher(downloader: downloader)
+    let p = LookaheadCachePrefetcher(downloader: downloader, confinedTo: .main)
     let q = (0..<10).map { httpTrack("t\($0)") }
 
     // currentIndex = 5 → forward window [6,7,8] + look-back t0.
@@ -309,7 +332,7 @@ final class LookaheadCachePrefetcherTests: XCTestCase {
 
   func testRescheduleOmitsLookbackWhenCurrentTrackIsTrackZero() async {
     let downloader = StubDownloader()
-    let p = LookaheadCachePrefetcher(downloader: downloader)
+    let p = LookaheadCachePrefetcher(downloader: downloader, confinedTo: .main)
     let q = (0..<5).map { httpTrack("t\($0)") }
 
     p.reschedule(tracks: q, currentIndex: 0, lookaheadCount: 3)
@@ -321,7 +344,7 @@ final class LookaheadCachePrefetcherTests: XCTestCase {
 
   func testRescheduleOmitsLookbackWhenTrackZeroIsNonRemote() async {
     let downloader = StubDownloader()
-    let p = LookaheadCachePrefetcher(downloader: downloader)
+    let p = LookaheadCachePrefetcher(downloader: downloader, confinedTo: .main)
     let q: [TrackItem] = [
       makeTrack(id: "local-0", url: "file:///tmp/0.m4a"),
       httpTrack("t1"), httpTrack("t2"), httpTrack("t3"), httpTrack("t4"),
@@ -338,7 +361,7 @@ final class LookaheadCachePrefetcherTests: XCTestCase {
 
   func testRescheduleDoesNotReEnqueueAlreadyCachedUrl() async {
     let downloader = StubDownloader(cachedUrls: ["https://example.com/t2.m4a"])
-    let p = LookaheadCachePrefetcher(downloader: downloader)
+    let p = LookaheadCachePrefetcher(downloader: downloader, confinedTo: .main)
     let q = (0..<5).map { httpTrack("t\($0)") }
 
     p.reschedule(tracks: q, currentIndex: 0, lookaheadCount: 3)
@@ -355,7 +378,7 @@ final class LookaheadCachePrefetcherTests: XCTestCase {
     // exercised on subsequent overlapping windows. Verify every
     // remote track within reach downloads exactly once.
     let downloader = TrackingDownloader()
-    let p = LookaheadCachePrefetcher(downloader: downloader)
+    let p = LookaheadCachePrefetcher(downloader: downloader, confinedTo: .main)
     let q = (0..<8).map { httpTrack("t\($0)") }
 
     for cur in 0..<7 {
@@ -388,7 +411,7 @@ final class LookaheadCachePrefetcherTests: XCTestCase {
       onStart: { firstStarted.fulfill() },
       hold: firstHold
     )
-    let p = LookaheadCachePrefetcher(downloader: downloader)
+    let p = LookaheadCachePrefetcher(downloader: downloader, confinedTo: .main)
 
     p.reschedule(
       tracks: [httpTrack("cur"), httpTrack("old-1"), httpTrack("old-2")],
@@ -435,7 +458,7 @@ final class LookaheadCachePrefetcherTests: XCTestCase {
       onStart: { started.fulfill() },
       hold: hold
     )
-    let p = LookaheadCachePrefetcher(downloader: downloader)
+    let p = LookaheadCachePrefetcher(downloader: downloader, confinedTo: .main)
     p.reschedule(
       tracks: [httpTrack("cur"), httpTrack("gated"), httpTrack("after")],
       currentIndex: 0,
@@ -455,7 +478,7 @@ final class LookaheadCachePrefetcherTests: XCTestCase {
   // MARK: - Helpers
 
   private func newPrefetcher() -> LookaheadCachePrefetcher {
-    return LookaheadCachePrefetcher(downloader: StubDownloader())
+    return LookaheadCachePrefetcher(downloader: StubDownloader(), confinedTo: .main)
   }
 
   private func httpTrack(_ id: String) -> TrackItem {
@@ -465,7 +488,9 @@ final class LookaheadCachePrefetcherTests: XCTestCase {
   private func makeTrack(id: String, url: String) -> TrackItem {
     return TrackItem(
       id: id, url: url, title: nil, artist: nil, album: nil,
-      duration: nil, artworkUrl: nil, extras: nil
+      duration: nil, artworkUrl: nil, extras: nil,
+      replayGainTrackGain: nil, replayGainTrackPeak: nil,
+      replayGainAlbumGain: nil, replayGainAlbumPeak: nil
     )
   }
 }
@@ -500,15 +525,15 @@ final class StubDownloader: LookaheadCacheDownloader, @unchecked Sendable {
   }
 
   func download(track: TrackItem, headers: [String: String]?) async throws {
-    lock.lock()
     // Test fixtures supply non-nil track.id values; the `?? ""`
     // satisfies the optional type while keeping the assertions
     // simple. The lib itself never assumes track.id is non-empty —
     // these tests verify orchestration order using fixture-supplied
     // identifiers.
-    _invocations.append(track.id ?? "")
-    let shouldFail = _failingTrackIds.contains(track.id ?? "")
-    lock.unlock()
+    let shouldFail = lock.withLock {
+      _invocations.append(track.id ?? "")
+      return _failingTrackIds.contains(track.id ?? "")
+    }
     if shouldFail {
       throw LookaheadCacheError.httpError(statusCode: 500)
     }
@@ -534,10 +559,10 @@ final class TrackingDownloader: LookaheadCacheDownloader, @unchecked Sendable {
   }
 
   func download(track: TrackItem, headers: [String: String]?) async throws {
-    lock.lock()
-    _invocations.append(track.id ?? "")
-    _completed.insert(track.url)
-    lock.unlock()
+    lock.withLock {
+      _invocations.append(track.id ?? "")
+      _completed.insert(track.url)
+    }
   }
 
   func isFullyCached(url: String) -> Bool {
@@ -570,10 +595,8 @@ final class GatedDownloader: LookaheadCacheDownloader, @unchecked Sendable {
   }
 
   func download(track: TrackItem, headers: [String: String]?) async throws {
-    lock.lock()
     // See `StubDownloader.download` — same `?? ""` rationale.
-    _invocations.append(track.id ?? "")
-    lock.unlock()
+    lock.withLock { _invocations.append(track.id ?? "") }
     if track.id == gateTrackId {
       onStart()
       await hold.wait()

package/ios/Tests/LookaheadCacheRuntimeConfigTests.swift

@@ -89,6 +89,27 @@ final class LookaheadCacheRuntimeConfigTests: XCTestCase {
     XCTAssertTrue(cache.isFullyCached(url: track.url))
   }
 
+  /// A disabled cache serves nothing, whatever is on disk; the file is still
+  /// there for the next enable.
+  func testADisabledCacheAnswersNoCachedURL() async throws {
+    let cache = LookaheadCache(
+      directory: tempDir, maxSizeBytes: 1024 * 1024, urlSession: session
+    )
+    let url = URL(string: "https://example.com/held.m4a")!
+    StubURLProtocol.stub(url: url, data: Data("payload".utf8), statusCode: 200)
+    try await cache.download(
+      track: makeTrack(id: "held", url: url.absoluteString), headers: nil
+    )
+    let fileURL = try XCTUnwrap(cache.cachedURL(forUrl: url.absoluteString))
+
+    cache.disable()
+    XCTAssertNil(cache.cachedURL(forUrl: url.absoluteString), "disabled means every request goes to the origin")
+    XCTAssertTrue(FileManager.default.fileExists(atPath: fileURL.path), "the file waits for the next enable")
+
+    cache.enable()
+    XCTAssertEqual(cache.cachedURL(forUrl: url.absoluteString), fileURL)
+  }
+
   func testIsFullyCachedReturnsFalseWhenFileMissing() async throws {
     let cache = LookaheadCache(
       directory: tempDir, maxSizeBytes: 1024 * 1024, urlSession: session
@@ -164,6 +185,7 @@ final class LookaheadCacheRuntimeConfigTests: XCTestCase {
     )
     let prefetcher = LookaheadCachePrefetcher(
       cache: cache,
+      confinedTo: .main,
       configHeaders: ["X-Auth": "token-1"],
       configUserAgent: "rnqp/1"
     )
@@ -241,7 +263,144 @@ final class LookaheadCacheRuntimeConfigTests: XCTestCase {
   private func makeTrack(id: String, url: String) -> TrackItem {
     return TrackItem(
       id: id, url: url, title: nil, artist: nil, album: nil,
-      duration: nil, artworkUrl: nil, extras: nil
+      duration: nil, artworkUrl: nil, extras: nil,
+      replayGainTrackGain: nil, replayGainTrackPeak: nil,
+      replayGainAlbumGain: nil, replayGainAlbumPeak: nil
+    )
+  }
+
+  // MARK: - The live protected set guards every eviction, not just a shrink
+
+  func testCommitEvictionSparesTheProtectedPlayingTrack() async throws {
+    // Budget fits two entries. The third commit forces an eviction, and the
+    // oldest entry is the one playing — the LRU victim without protection.
+    let cache = LookaheadCache(
+      directory: tempDir, maxSizeBytes: 8_000, urlSession: session
+    )
+    let playingUrl = "https://example.com/playing.m4a"
+    cache.setProtectedUrls([playingUrl])
+
+    for id in ["playing", "b", "c"] {
+      let url = URL(string: "https://example.com/\(id).m4a")!
+      StubURLProtocol.stub(url: url, data: Data(repeating: 0x41, count: 4_000), statusCode: 200)
+      try await cache.download(
+        track: makeTrack(id: id, url: url.absoluteString), headers: nil
+      )
+    }
+
+    XCTAssertTrue(
+      cache.isFullyCached(url: playingUrl),
+      "a prefetch commit must not evict the track that is playing"
     )
   }
+
+  func testCommitEvictionStillTakesUnprotectedEntries() async throws {
+    let cache = LookaheadCache(
+      directory: tempDir, maxSizeBytes: 8_000, urlSession: session
+    )
+    cache.setProtectedUrls([])
+
+    for id in ["a", "b", "c"] {
+      let url = URL(string: "https://example.com/\(id).m4a")!
+      StubURLProtocol.stub(url: url, data: Data(repeating: 0x41, count: 4_000), statusCode: 200)
+      try await cache.download(
+        track: makeTrack(id: id, url: url.absoluteString), headers: nil
+      )
+    }
+
+    XCTAssertLessThanOrEqual(
+      cache.currentSizeBytes(), 8_000,
+      "with nothing protected the budget must still be enforced"
+    )
+    XCTAssertFalse(
+      cache.isFullyCached(url: "https://example.com/a.m4a"),
+      "the oldest unprotected entry is still the eviction victim"
+    )
+  }
+
+  // MARK: - A download shorter than declared is never committed
+
+  private func downloadStubbed(
+    _ cache: LookaheadCache, id: String, body: Data, headers: [String: String]?
+  ) async throws {
+    let url = URL(string: "https://example.com/\(id).m4a")!
+    StubURLProtocol.stub(url: url, data: body, statusCode: 200, headerFields: headers)
+    try await cache.download(track: makeTrack(id: id, url: url.absoluteString), headers: nil)
+  }
+
+  func testTruncatedBodyIsRejected() async throws {
+    let cache = LookaheadCache(
+      directory: tempDir, maxSizeBytes: 1024 * 1024, urlSession: session
+    )
+    do {
+      try await downloadStubbed(
+        cache, id: "short", body: Data(repeating: 0x41, count: 400),
+        headers: ["Content-Length": "1000"])
+      XCTFail("a body shorter than the declared length must not be committed")
+    } catch LookaheadCacheError.truncatedBody(let expected, let received) {
+      XCTAssertEqual(expected, 1000)
+      XCTAssertEqual(received, 400)
+    }
+    XCTAssertFalse(
+      cache.isFullyCached(url: "https://example.com/short.m4a"),
+      "a rejected download must leave no cache entry to poison later plays")
+  }
+
+  func testExactLengthBodyIsAccepted() async throws {
+    let cache = LookaheadCache(
+      directory: tempDir, maxSizeBytes: 1024 * 1024, urlSession: session
+    )
+    try await downloadStubbed(
+      cache, id: "exact", body: Data(repeating: 0x41, count: 400),
+      headers: ["Content-Length": "400"])
+    XCTAssertTrue(cache.isFullyCached(url: "https://example.com/exact.m4a"))
+  }
+
+  func testChunkedBodyWithNoDeclaredLengthIsAccepted() async throws {
+    let cache = LookaheadCache(
+      directory: tempDir, maxSizeBytes: 1024 * 1024, urlSession: session
+    )
+    try await downloadStubbed(
+      cache, id: "chunked", body: Data(repeating: 0x41, count: 400), headers: nil)
+    XCTAssertTrue(
+      cache.isFullyCached(url: "https://example.com/chunked.m4a"),
+      "no declared length means nothing to compare against, not a rejection")
+  }
+
+  func testBodyLongerThanDeclaredIsAccepted() async throws {
+    let cache = LookaheadCache(
+      directory: tempDir, maxSizeBytes: 1024 * 1024, urlSession: session
+    )
+    // A decoded body can exceed the declared compressed length; only short
+    // is a truncation.
+    try await downloadStubbed(
+      cache, id: "longer", body: Data(repeating: 0x41, count: 400),
+      headers: ["Content-Length": "200"])
+    XCTAssertTrue(cache.isFullyCached(url: "https://example.com/longer.m4a"))
+  }
+
+  // MARK: - buildCacheStatusSnapshot
+
+  func testCacheStatusSnapshotReportsTheSuppliedInFlightUrl() {
+    let player = TrackPlayer()
+    let status = player.buildCacheStatusSnapshot(
+      inFlightUrl: "https://example.com/inflight.m4a")
+    XCTAssertEqual(status.currentlyCaching, ["https://example.com/inflight.m4a"])
+  }
+
+  func testCacheStatusSnapshotReportsNothingCachingWithoutAnInFlightUrl() {
+    let player = TrackPlayer()
+    XCTAssertEqual(player.buildCacheStatusSnapshot(inFlightUrl: nil).currentlyCaching, [])
+  }
+
+  func testCacheStatusSnapshotReportsTheDefaultCacheCeilingBeforeConfigure() {
+    let player = TrackPlayer()
+    let status = player.buildCacheStatusSnapshot(inFlightUrl: nil)
+    XCTAssertTrue(status.enabled)
+    XCTAssertEqual(status.currentSizeMb, 0)
+    XCTAssertEqual(status.tracksFullyCached, 0)
+    XCTAssertEqual(
+      status.maxSizeMb,
+      Double(LookaheadCache.DEFAULT_MAX_SIZE_BYTES) / Double(LookaheadCache.BYTES_PER_MB))
+  }
 }

package/ios/Tests/LookaheadCacheTests.swift

@@ -240,6 +240,31 @@ final class LookaheadCacheTests: XCTestCase {
     XCTAssertNil(cache.cachedURL(forUrl: "wipe"))
   }
 
+  // MARK: - Teardown quiescence
+
+  func testDownloadAfterTearDownIsANoOp() async throws {
+    // A prefetcher Task can reach `download` after the owning player has
+    // torn the cache down. Creating a URLSession task on the invalidated
+    // session raises an Obj-C exception that no Swift `do-catch` can
+    // intercept, so the teardown has to quiesce the cache first.
+    let cache = LookaheadCache(
+      directory: tempDir, maxSizeBytes: LookaheadCache.DEFAULT_MAX_SIZE_BYTES,
+      urlSession: session)
+    let url = URL(string: "https://example.com/after-teardown.m4a")!
+    StubURLProtocol.stub(url: url, data: Data("x".utf8), statusCode: 200)
+    let track = makeTrack(id: "after-teardown", url: url.absoluteString)
+
+    cache.tearDown()
+    try await cache.download(track: track, headers: nil)
+
+    XCTAssertNil(
+      cache.cachedURL(forUrl: track.url),
+      "a download issued after tearDown must not populate the cache")
+    XCTAssertEqual(
+      StubURLProtocol.requestCount(for: url), 0,
+      "a download issued after tearDown must not reach the session")
+  }
+
   // MARK: - Eviction integration
 
   func testDownloadEvictsOldestWhenBudgetExceeded() async throws {
@@ -498,17 +523,16 @@ final class LookaheadCacheTests: XCTestCase {
 
   // MARK: - URL → bytes round-trip correctness
   //
-  // These tests pin the contract that downloading URL A's bytes
+  // These tests cover the contract that downloading URL A's bytes
   // surfaces those exact bytes via cachedURL(forUrl: A) — and that
   // a sibling download of URL B doesn't disturb URL A's mapping.
-  // Caught a regression where the lookahead-cache served the wrong
-  // file's bytes after a sequence of forward + look-back prefetches.
+  // The cache serves each URL its own bytes after any sequence of
+  // forward and look-back prefetches.
 
   func testCachedFileBytesMatchSourceUrlBytes() async throws {
     // The fundamental contract: download URL A → cachedURL(A)'s file
     // contains A's bytes. No way for the cache to serve B's bytes
-    // for A's URL. This is the core invariant the user-reported
-    // wrong-file-mapping bug would violate.
+    // for A's URL. This is the core invariant.
     let cache = LookaheadCache(directory: tempDir, maxSizeBytes: LookaheadCache.DEFAULT_MAX_SIZE_BYTES, urlSession: session)
     let urlA = URL(string: "https://example.com/song-a.m4a")!
     let bytesA = Data("AAAAAAAAAAAAAAAAAAA-payload-for-track-A".utf8)
@@ -553,7 +577,7 @@ final class LookaheadCacheTests: XCTestCase {
   }
 
   func testLookbackPathPreservesPerUrlBytes() async throws {
-    // Reproduces the user-reported flow: forward-prefetch t1/t2/t3,
+    // Forward-prefetch t1/t2/t3,
     // then look-back-prefetch t0. After the sequence, every URL
     // resolves to its own bytes — the look-back doesn't clobber the
     // forward window's mappings.
@@ -584,10 +608,9 @@ final class LookaheadCacheTests: XCTestCase {
   }
 
   func testFileNameUniquenessAcrossSimilarUrls() {
-    // Belt-and-braces against any future change to fileName(forUrl:)
-    // that might silently introduce collisions for URLs with similar
-    // prefixes — e.g. Subsonic stream URLs that differ only in an
-    // ?id=N query parameter.
+    // fileName(forUrl:) must not collide for URLs with similar
+    // prefixes — e.g. stream URLs that differ only in an ?id=N query
+    // parameter.
     let urls = [
       "https://music.example.com/rest/stream?id=1&u=test",
       "https://music.example.com/rest/stream?id=2&u=test",
@@ -601,10 +624,8 @@ final class LookaheadCacheTests: XCTestCase {
 
   func testCollisionCandidateUrlsRoundTripDistinctBytes() async throws {
     // End-to-end correctness: download four URLs whose only difference
-    // is an `?id=N` query parameter (a common Subsonic-style shape) and
-    // verify each resolves to its own bytes. Catches a regression where
-    // fileName uniqueness holds but `download` -> `cachedURL` keying
-    // ever drifted to use a non-URL field.
+    // is an `?id=N` query parameter and verify each resolves to its own
+    // bytes: `download` and `cachedURL` must key on the same URL.
     let cache = LookaheadCache(directory: tempDir, maxSizeBytes: LookaheadCache.DEFAULT_MAX_SIZE_BYTES, urlSession: session)
     let urlBytes: [(url: URL, bytes: Data)] = [
       "https://music.example.com/rest/stream?id=1&u=test",
@@ -638,7 +659,9 @@ final class LookaheadCacheTests: XCTestCase {
   private func makeTrack(id: String, url: String) -> TrackItem {
     return TrackItem(
       id: id, url: url, title: nil, artist: nil, album: nil,
-      duration: nil, artworkUrl: nil, extras: nil
+      duration: nil, artworkUrl: nil, extras: nil,
+      replayGainTrackGain: nil, replayGainTrackPeak: nil,
+      replayGainAlbumGain: nil, replayGainAlbumPeak: nil
     )
   }
 }
@@ -654,15 +677,18 @@ final class StubURLProtocol: URLProtocol {
   private struct Stub {
     let data: Data
     let statusCode: Int
+    let headerFields: [String: String]?
   }
 
   private static let lock = NSLock()
   private static var stubs: [URL: Stub] = [:]
   private static var requests: [URL: [URLRequest]] = [:]
 
-  static func stub(url: URL, data: Data, statusCode: Int) {
+  static func stub(
+    url: URL, data: Data, statusCode: Int, headerFields: [String: String]? = nil
+  ) {
     lock.lock(); defer { lock.unlock() }
-    stubs[url] = Stub(data: data, statusCode: statusCode)
+    stubs[url] = Stub(data: data, statusCode: statusCode, headerFields: headerFields)
   }
 
   static func reset() {
@@ -706,7 +732,7 @@ final class StubURLProtocol: URLProtocol {
 
     let response = HTTPURLResponse(
       url: url, statusCode: stub.statusCode,
-      httpVersion: "HTTP/1.1", headerFields: nil
+      httpVersion: "HTTP/1.1", headerFields: stub.headerFields
     )!
     client?.urlProtocol(self, didReceive: response, cacheStoragePolicy: .notAllowed)
     client?.urlProtocol(self, didLoad: stub.data)

package/ios/Tests/MediaHTTPConnectionTests.swift

@@ -161,3 +161,82 @@ final class MediaHTTPConnectionTests: XCTestCase {
     XCTAssertTrue(head.contains("Content-Length: 0\r\n"))
   }
 }
+
+/// The head the read-through leg relays from the origin to the player.
+///
+/// The player is AVFoundation reading media: it needs the status, the type, the
+/// length and the range, and nothing else the origin chose to say.
+final class MediaHTTPRelayHeadTests: XCTestCase {
+
+  private func response(
+    status: Int,
+    headers: [String: String]
+  ) -> HTTPURLResponse {
+    HTTPURLResponse(
+      url: URL(string: "https://example.com/track.mp3")!,
+      statusCode: status,
+      httpVersion: "HTTP/1.1",
+      headerFields: headers
+    )!
+  }
+
+  func testRelaysTheOriginStatusLine() {
+    let head = MediaHTTPConnection.relayHead(response(status: 206, headers: [:]))
+    XCTAssertTrue(head.hasPrefix("HTTP/1.1 206 Partial Content\r\n"), head)
+  }
+
+  /// The status line stays ASCII whatever the device locale; an unlisted
+  /// status carries an empty reason phrase, which HTTP/1.1 permits.
+  func testTheReasonPhraseIsFixedTextNotLocalisedText() {
+    XCTAssertEqual(MediaHTTPConnection.reasonPhrase(for: 404), "Not Found")
+    XCTAssertEqual(MediaHTTPConnection.reasonPhrase(for: 418), "")
+    let head = MediaHTTPConnection.relayHead(response(status: 418, headers: [:]))
+    XCTAssertTrue(head.hasPrefix("HTTP/1.1 418 \r\n"), head)
+  }
+
+  /// An HTTP error reaches the player as an HTTP error, so it classifies as the
+  /// server's answer rather than as a transport failure.
+  func testRelaysAnErrorStatusRatherThanMaskingIt() {
+    let head = MediaHTTPConnection.relayHead(response(status: 404, headers: [:]))
+    XCTAssertTrue(head.hasPrefix("HTTP/1.1 404 "), head)
+  }
+
+  func testCarriesTheHeadersThePlayerReadsMediaWith() {
+    let head = MediaHTTPConnection.relayHead(response(status: 206, headers: [
+      "Content-Type": "audio/mpeg",
+      "Content-Length": "1024",
+      "Content-Range": "bytes 0-1023/8192",
+      "Accept-Ranges": "bytes",
+    ]))
+    XCTAssertTrue(head.contains("Content-Type: audio/mpeg"), head)
+    XCTAssertTrue(head.contains("Content-Length: 1024"), head)
+    XCTAssertTrue(head.contains("Content-Range: bytes 0-1023/8192"), head)
+    XCTAssertTrue(head.contains("Accept-Ranges: bytes"), head)
+  }
+
+  func testDropsEverythingElseTheOriginSaid() {
+    let head = MediaHTTPConnection.relayHead(response(status: 200, headers: [
+      "Content-Type": "audio/mpeg",
+      "Set-Cookie": "session=secret",
+      "WWW-Authenticate": "Bearer realm=\"origin\"",
+      "Location": "https://elsewhere.example.com/track.mp3",
+      "Server": "origin/1.0",
+    ]))
+    XCTAssertFalse(head.lowercased().contains("set-cookie"), head)
+    XCTAssertFalse(head.lowercased().contains("www-authenticate"), head)
+    XCTAssertFalse(head.lowercased().contains("location"), head)
+    XCTAssertFalse(head.lowercased().contains("server:"), head)
+  }
+
+  func testHeadIsTerminatedSoABodyCanFollow() {
+    let head = MediaHTTPConnection.relayHead(response(status: 200, headers: ["Content-Length": "1"]))
+    XCTAssertTrue(head.hasSuffix("\r\n\r\n"), head.debugDescription)
+  }
+
+  /// An absent header is omitted rather than sent empty — a `Content-Range: `
+  /// with no value is a malformed response to a range request.
+  func testOmitsHeadersTheOriginDidNotSend() {
+    let head = MediaHTTPConnection.relayHead(response(status: 200, headers: ["Content-Type": "audio/mpeg"]))
+    XCTAssertFalse(head.contains("Content-Range"), head)
+  }
+}