react-native-queue-player 1.2.0 → 2.0.1

package/ios/Tests/TrackSourceClassifierTests.swift

@@ -1,14 +1,16 @@
 import XCTest
 @testable import QueuePlayer
 
-/// `TrackPlayer.classifyTrackSource(url:isUrlCached:)` decides how the active
-/// track is being played from lib-observable facts only: the URL scheme plus a
-/// cache-hit probe. Pure + static, so it's exercised directly without a live
-/// engine. Mirrors the Android source-classifier coverage.
+/// `TrackPlayer.classifyTrackSource` decides how the active track is being
+/// played from lib-observable facts only: the URL scheme, whether the item is
+/// routed through the read-through server, and a cache-hit probe. Pure +
+/// static, so it's exercised directly without a live engine.
 final class TrackSourceClassifierTests: XCTestCase {
 
-  private func classify(_ url: String?, cached: Bool = false) -> TrackSource? {
-    TrackPlayer.classifyTrackSource(url: url) { _ in cached }
+  private func classify(
+    _ url: String?, routed: Bool = true, cached: Bool = false
+  ) -> TrackSource? {
+    TrackPlayer.classifyTrackSource(url: url, isRouted: routed) { _ in cached }
   }
 
   func testNilUrlIsUnclassified() {
@@ -40,11 +42,35 @@ final class TrackSourceClassifierTests: XCTestCase {
 
   func testLocalFileNeverConsultsTheCacheProbe() {
     var probed = false
-    let source = TrackPlayer.classifyTrackSource(url: "file:///a.m4a") { _ in
+    let source = TrackPlayer.classifyTrackSource(url: "file:///a.m4a", isRouted: true) { _ in
       probed = true
       return true
     }
     XCTAssertEqual(source, .local)
     XCTAssertFalse(probed, "a file:// URL is local without a cache lookup")
   }
+
+  /// Cached on disk is not the same as played from disk. Only an item bound to
+  /// the read-through server reads the cache, so a complete file the player is
+  /// not routed through is still being streamed — reporting otherwise is what
+  /// made this field claim `cached` while every byte came from the origin.
+  func testACachedTrackThePlayerIsNotRoutedThroughIsStreaming() {
+    XCTAssertEqual(
+      classify("https://example.com/a.mp3", routed: false, cached: true), .streaming)
+  }
+
+  func testARoutedTrackTheCacheHoldsInFullIsCached() {
+    XCTAssertEqual(
+      classify("https://example.com/a.mp3", routed: true, cached: true), .cached)
+  }
+
+  func testARoutedTrackTheCacheDoesNotHoldIsStreaming() {
+    XCTAssertEqual(
+      classify("https://example.com/a.mp3", routed: true, cached: false), .streaming)
+  }
+
+  /// A local file is local whatever the server and cache report.
+  func testAFileTrackIsLocalRegardlessOfRouting() {
+    XCTAssertEqual(classify("file:///a.m4a", routed: false, cached: true), .local)
+  }
 }

package/ios/Tests/VoiceVocabularyOptInTests.swift

@@ -0,0 +1,38 @@
+import XCTest
+@testable import QueuePlayer
+
+/// Siri vocabulary donation is off unless the consumer opts in, and the
+/// opt-in is fixed once taken.
+///
+/// The flag stands for the `com.apple.developer.siri` entitlement, which
+/// `INVocabulary` checks at runtime and which iOS gives a process no way to
+/// read. An entitlement is decided when the app is signed, so a value that
+/// changed later could not describe anything — and re-reading one would let a
+/// consumer re-arm a path that terminates a host without the capability.
+final class VoiceVocabularyOptInTests: XCTestCase {
+
+  func testDonationIsOffUntilTheConsumerOptsIn() {
+    let player = TrackPlayer()
+    XCTAssertFalse(
+      player.voiceVocabularyDonationEnabled,
+      "an untouched player has not been given the entitlement to assert")
+  }
+
+  func testTheFirstOptInIsTheOneThatCounts() {
+    let player = TrackPlayer()
+    player.pinVoiceVocabularyDonation(true)
+    player.pinVoiceVocabularyDonation(false)
+    XCTAssertTrue(
+      player.voiceVocabularyDonationEnabled,
+      "a later value does not unset an opt-in already taken")
+  }
+
+  func testDecliningIsAlsoFixed() {
+    let player = TrackPlayer()
+    player.pinVoiceVocabularyDonation(false)
+    player.pinVoiceVocabularyDonation(true)
+    XCTAssertFalse(
+      player.voiceVocabularyDonationEnabled,
+      "a later value does not turn donation on after it was declined")
+  }
+}

package/ios/TrackPlayer+Automotive.swift

@@ -0,0 +1,101 @@
+import NitroModules
+
+extension TrackPlayer {
+  // MARK: - Automotive / voice handler registration
+
+  /// Atomically replace the cached `BrowseSnapshot` on the
+  /// process-wide [CarPlayCoordinator]. The data provider posts a
+  /// `didUpdateNotification` on the main queue; an active CarPlay
+  /// scene observes the notification + rebuilds the root template
+  /// against the new snapshot. Push semantics — most-recent call
+  /// wins. Safe to call before a CarPlay scene attaches: the
+  /// snapshot is cached on the coordinator + the next scene reads
+  /// it directly at didConnect.
+  func setBrowseSnapshot(snapshot: BrowseSnapshot) throws {
+    CarPlayCoordinator.shared.dataProvider.setSnapshot(snapshot)
+  }
+
+  func onBrowseRequest(
+    callback: @escaping (_ parentId: String) -> Promise<Promise<[BrowseItem]>>
+  ) throws -> () -> Void {
+    return CarPlayCoordinator.shared.bridge.registerOnBrowseRequest(callback)
+  }
+
+  // `onSearchRequest` is Android-only — CarPlay audio-entitled apps
+  // cannot legally present `CPSearchTemplate` (per the CarPlay App
+  // Programming Guide template-by-category rules); pushing or
+  // presenting it raises NSInvalidArgumentException at runtime. Apple
+  // Music + Spotify both dropped CarPlay search in iOS 26; the
+  // canonical CarPlay search affordance for audio apps is Siri via
+  // SiriKit's `INPlayMediaIntent`, not an in-app search template.
+  //
+  // `onPlayFromSearchRequest` IS wired on iOS — it serves the
+  // SiriKit `INPlayMediaIntent` path: Siri parses "Hey Siri play X
+  // on MyApp" into a structured `INMediaSearch`, the lib's
+  // `PlayMediaIntentHandler` maps it to `MediaSearchRequest`, and
+  // dispatches into this callback via `CarPlayBridge`.
+  //
+  // For `onSearchRequest` we accept the consumer's registration on
+  // iOS to keep the TS API shape cross-platform; the callback is
+  // discarded (`_ = callback` consumes the value), and the returned
+  // disposer is a no-op so the consumer's bookkeeping stays sane.
+  func onSearchRequest(
+    callback: @escaping (_ query: String) -> Promise<Promise<[BrowseItem]>>
+  ) throws -> () -> Void {
+    _ = callback
+    return {}
+  }
+
+  func onPlayFromSearchRequest(
+    callback: @escaping (_ request: MediaSearchRequest) -> Promise<Promise<[TrackItem]>>
+  ) throws -> () -> Void {
+    return CarPlayCoordinator.shared.bridge.registerOnPlayFromSearchRequest(callback)
+  }
+
+  func onPlayFromIdRequest(
+    callback: @escaping (_ mediaId: String) -> Promise<Promise<[TrackItem]>>
+  ) throws -> () -> Void {
+    return CarPlayCoordinator.shared.bridge.registerOnPlayFromIdRequest(callback)
+  }
+
+  // Donation Hybrid method — fire-and-forget into Siri's vocabulary
+  // donation pipeline. Real impl lives in `ios/Siri/VoiceDonation.swift`.
+  // Uses `INVocabulary.setVocabularyStrings(_:of:)` to seed Siri's NLU
+  // with the consumer's artist + playlist names.
+  func donateVoiceVocabulary(vocabulary: VoiceVocabulary) throws {
+    // Opt-in only. `INVocabulary` raises an uncatchable Objective-C exception
+    // in a process without the `com.apple.developer.siri` entitlement, and
+    // iOS gives a process no way to read its own entitlements — so the
+    // consumer declaring the capability is the only signal the library can
+    // have that this is safe to touch.
+    guard self.voiceVocabularyDonationEnabled else { return }
+    VoiceDonation.donateVoiceVocabulary(vocabulary)
+  }
+
+  func onCarConnect(callback: @escaping () -> Void) throws -> () -> Void {
+    return CarPlayCoordinator.shared.bridge.registerOnCarConnect(callback)
+  }
+
+  // `onServiceReady` is an Android-only signal. iOS apps die fully
+  // under memory pressure (no separate service lifecycle), so there's
+  // no `service-reborn` scenario to surface here. The lib accepts the
+  // registration to keep the cross-platform API shape consistent and
+  // returns a no-op disposer; the callback is consumed (so it isn't
+  // retained) and never invoked. Consumers writing for both platforms
+  // register one handler; on iOS only `onCarConnect` carries the
+  // equivalent "automotive surface available" signal.
+  func onServiceReady(
+    callback: @escaping (_ reason: ServiceReadyReason) -> Void
+  ) throws -> () -> Void {
+    _ = callback
+    return {}
+  }
+
+  func onCarDisconnect(callback: @escaping () -> Void) throws -> () -> Void {
+    return CarPlayCoordinator.shared.bridge.registerOnCarDisconnect(callback)
+  }
+
+  func isCarConnected() throws -> Bool {
+    return CarPlayCoordinator.shared.isCarConnected
+  }
+}

package/ios/TrackPlayer+Cache.swift

@@ -0,0 +1,232 @@
+import Foundation
+import NitroModules
+
+extension TrackPlayer {
+  // MARK: - Lookahead cache — runtime config + status surface
+  func setLookaheadCache(config: LookaheadCacheConfig) throws -> Promise<Void> {
+    return enqueueThrowing {
+      try self.applyLookaheadConfig(config)
+    }
+  }
+
+  func getLookaheadCacheStatus() throws -> Promise<CacheStatus> {
+    // The snapshot counts fully-cached entries, which is a filesystem check
+    // per entry — the Promise keeps that work off the calling JS thread.
+    return enqueueValue { self.buildCacheStatusSnapshot() }
+  }
+
+  func clearLookaheadCache() throws -> Promise<Void> {
+    return enqueue {
+      // Cancel any in-flight prefetch + drop everything on disk.
+      // We deliberately do NOT call rescheduleLookahead() here —
+      // an immediate refill makes `clearLookaheadCache` impossible
+      // to observe at zero from JS, and "clear" semantically means
+      // "wipe and stop" (the consumer can re-trigger prefetch by
+      // calling setLookaheadCache, skipToIndex, or setQueue again).
+      self.lookaheadCachePrefetcher?.cancel()
+      self.lookaheadCache?.clear()
+      self.emitCacheStatus()
+    }
+  }
+
+  func onCacheStatusChange(callback: @escaping (_ status: CacheStatus) -> Void) throws -> () -> Void {
+    // ListenerRegistry.add is internally serialized, so a JS consumer
+    // that does
+    //   const unsub = onCacheStatusChange(cb)
+    //   await setLookaheadCache(cfg)
+    // is guaranteed to see the post-config-change emit (the
+    // setLookaheadCache call synchronously crosses the bridge after
+    // the listener is in the registry).
+    let id = cacheStatusListeners.add(callback)
+    // Deliver the current status once. Otherwise a settings screen shows its
+    // placeholder until the next prefetch completes — which never happens for a
+    // fully-cached queue or a consumer running with prefetch off.
+    playerQueue.async { [weak self] in
+      guard let self else { return }
+      guard self.cacheStatusListeners.contains(id: id) else { return }
+      callback(self.buildCacheStatusSnapshot())
+    }
+    return { [weak self] in self?.cacheStatusListeners.remove(id: id) }
+  }
+
+  /// Apply a runtime config update. All three runtime dimensions are
+  /// live (no configure() needed):
+  /// - `enabled` toggle: build/teardown the prefetcher against the cache
+  /// - `lookaheadCount` change: live update on the prefetcher
+  /// - `allowsCellularAccess` toggle: live on the cache, applied per request
+  ///
+  /// Cache SIZE + eviction policy are NOT runtime dimensions — they are fixed
+  /// at `configure()` from `PlayerConfig` (kept consistent with Android, whose
+  /// SimpleCache is immutable after construction).
+  internal func applyLookaheadConfig(_ config: LookaheadCacheConfig) throws {
+    let previous = self.lookaheadConfig
+    self.lookaheadConfig = config
+
+    let enableChanged = config.enabled != previous.enabled
+    let countChanged = config.lookaheadCount != previous.lookaheadCount
+
+    if enableChanged {
+      rebuildCacheStack(config: config)
+    } else if config.enabled {
+      applyLiveConfigUpdates(config: config, countChanged: countChanged)
+    }
+
+    // The cache applies this per request, so it lands whether or not the
+    // branches above ran. When there is no cache yet the stored config is what
+    // the next construction reads.
+    lookaheadCache?.allowsCellularAccess = config.allowsCellularAccess ?? true
+
+    emitCacheStatus()
+  }
+
+  /// Configure-time cache disk budget in MB — `PlayerConfig.lookaheadCacheMaxSizeMb`
+  /// or the 100 MB default. Fixed at cache construction; reported read-only via
+  /// `getLookaheadCacheStatus().maxSizeMb`.
+  internal func configuredCacheMaxSizeMb() -> Double {
+    self.config.lookaheadCacheMaxSizeMb
+      ?? Double(LookaheadCache.DEFAULT_MAX_SIZE_BYTES) / Double(LookaheadCache.BYTES_PER_MB)
+  }
+
+  /// Configure-time cache eviction policy — `PlayerConfig.lookaheadCacheEvictionPolicy`
+  /// or `.lru`. Fixed at cache construction; a change at `configure()` clears the
+  /// cache and rebuilds under the new policy (see `configure`).
+  internal func configuredEvictionPolicy() -> EvictionPolicy {
+    self.config.lookaheadCacheEvictionPolicy ?? .lru
+  }
+
+  /// Bring up the server that reads through `cache`. Called from both sites
+  /// that build a cache — `configure()` and the runtime `setLookaheadCache`
+  /// — because a cache without a server is one nothing ever reads from. A
+  /// server already reading through this same cache instance is kept, its
+  /// headers refreshed: replacing it would change the port seated items
+  /// address. Blocks for the bind (milliseconds) so every item built after
+  /// this call routes; an item built before the bind is bound to its origin.
+  internal func startReadThroughServer(for cache: LookaheadCache) {
+    if let existing = readThroughServer, readThroughServerCache === cache {
+      existing.setHeaders(
+        AVQueueBuilder.mergedHeaders(
+          headers: self.config.httpHeaders, userAgent: self.config.userAgent))
+      return
+    }
+    readThroughServer?.stop()
+    let server = ReadThroughServer(
+      cachedFileForOrigin: { [weak cache] sourceURL in
+        cache?.cachedURL(forUrl: sourceURL)
+      },
+      onFirstDiskHit: { [weak cache] sourceURL in
+        cache?.touch(url: sourceURL)
+      }
+    )
+    server.setHeaders(
+      AVQueueBuilder.mergedHeaders(
+        headers: self.config.httpHeaders, userAgent: self.config.userAgent))
+    server.start()
+    if !server.waitUntilBound() {
+      NSLog("[QueuePlayer] read-through server did not bind; remote tracks play from their origin")
+    }
+    self.readThroughServer = server
+    self.readThroughServerCache = cache
+  }
+
+  /// Quiesce or re-arm the cache, prefetcher and read-through server
+  /// when the `enabled` flag flipped. Disable cancels in-flight prefetch
+  /// and quiesces the cache (URLSession STAYS alive — it is only invalidated
+  /// by full `destroy`); the server stays up too, serving seated items from
+  /// the origin while the cache answers nothing, and `routingServer` binds
+  /// new items to their origin. Enable rebuilds the prefetcher (or constructs
+  /// the pair from scratch on first enable), keeps the server and reschedules.
+  ///
+  /// Keeping the cache instance + URLSession alive across disable
+  /// avoids `Task created in a session that has been invalidated`
+  /// (Obj-C exception, uncatchable in Swift's `do-catch`) when a
+  /// prefetcher Task survived disable + tried to download against
+  /// a freshly-invalidated session before the dispatch barrier saw
+  /// the cancellation.
+  private func rebuildCacheStack(config: LookaheadCacheConfig) {
+    if !config.enabled {
+      lookaheadCachePrefetcher?.tearDown()
+      lookaheadCachePrefetcher = nil
+      lookaheadCache?.disable()
+      return
+    }
+    if lookaheadCache == nil {
+      // Size is fixed at construction from the configure-time budget.
+      lookaheadCache = LookaheadCache(
+        maxSizeBytes: LookaheadCache.maxBytes(forMb: configuredCacheMaxSizeMb()),
+        evictionPolicy: configuredEvictionPolicy(),
+        allowsCellularAccess: config.allowsCellularAccess ?? true
+      )
+    } else {
+      lookaheadCache?.enable()
+    }
+    guard let cache = lookaheadCache else { return }
+    // The cache is built here as well as at `configure()`, and a cache with no
+    // server is a cache nothing reads: every item would bind its origin and
+    // route past it. Whatever builds the cache brings the server with it.
+    startReadThroughServer(for: cache)
+    let prefetcher = LookaheadCachePrefetcher(
+      cache: cache,
+      confinedTo: self.playerQueue,
+      configHeaders: self.config.httpHeaders,
+      configUserAgent: self.config.userAgent
+    )
+    prefetcher.defaultLookaheadCount = InputGuards.validLookaheadCount(config.lookaheadCount)
+    prefetcher.onTrackProcessed = { [weak self] in self?.emitCacheStatus() }
+    lookaheadCachePrefetcher = prefetcher
+    rescheduleLookahead()
+  }
+
+  /// Apply in-place config updates when the cache stack already exists
+  /// (no enable-flag change). Only `lookaheadCount` reaches here — it updates
+  /// the prefetcher's default + reschedules. `allowsCellularAccess` is set on
+  /// the cache by the caller, and cache size is configure-time.
+  private func applyLiveConfigUpdates(
+    config: LookaheadCacheConfig, countChanged: Bool
+  ) {
+    if countChanged {
+      lookaheadCachePrefetcher?.defaultLookaheadCount =
+        InputGuards.validLookaheadCount(config.lookaheadCount)
+      rescheduleLookahead()
+    }
+  }
+
+  /// Build a [CacheStatus] snapshot from current cache + prefetcher
+  /// state. Synchronous — the caller is already on the queue that serialises
+  /// player state.
+  internal func buildCacheStatusSnapshot() -> CacheStatus {
+    // `currentlyDownloadingUrl` is prefetcher state confined to `playerQueue`,
+    // so it is read here and handed to the builder as a value.
+    return buildCacheStatusSnapshot(
+      inFlightUrl: lookaheadCachePrefetcher?.currentlyDownloadingUrl)
+  }
+
+  /// [CacheStatus] from cache + config state plus the caller-supplied
+  /// in-flight prefetch URL. Reads no prefetcher state of its own.
+  internal func buildCacheStatusSnapshot(inFlightUrl: String?) -> CacheStatus {
+    let cache = self.lookaheadCache
+    let currentBytes = cache?.currentSizeBytes() ?? 0
+    // Queue-agnostic: count fully-cached entries in the cache itself,
+    // not the intersection with `self.tracks`. Mirrors the semantics
+    // of `currentSizeBytes` (total cache disk usage) and the
+    // prefetcher's `currentlyDownloadingUrl` (active downloads) — all
+    // three reflect cache state independent of any current queue.
+    // Per-track local/stream/cache attribution for the active queue
+    // is exposed via `getCurrentTrackSource()`.
+    let fullyCached = cache?.fullyCachedCount() ?? 0
+    return CacheStatus(
+      enabled: lookaheadConfig.enabled,
+      currentSizeMb: Double(currentBytes) / Double(LookaheadCache.BYTES_PER_MB),
+      maxSizeMb: configuredCacheMaxSizeMb(),
+      tracksFullyCached: Double(fullyCached),
+      currentlyCaching: inFlightUrl.map { [$0] } ?? []
+    )
+  }
+
+  /// Fire the cache-status callback with a fresh snapshot. Caller
+  /// must already be on the queue that serialises player state.
+  internal func emitCacheStatus() {
+    guard !cacheStatusListeners.isEmpty else { return }
+    let snapshot = buildCacheStatusSnapshot()
+    cacheStatusListeners.forEach { $0(snapshot) }
+  }
+}