react-native-audio-browser 0.2.0-next.75 → 0.2.0-next.77

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/android/src/main/java/com/audiobrowser/AudioBrowser.kt +20 -27
  2. package/android/src/main/java/com/audiobrowser/Service.kt +3 -0
  3. package/android/src/main/java/com/audiobrowser/browser/BrowserManager.kt +16 -8
  4. package/android/src/main/java/com/audiobrowser/browser/TrackLoadHandler.kt +5 -3
  5. package/android/src/main/java/com/audiobrowser/http/RequestConfigBuilder.kt +10 -2
  6. package/android/src/main/java/com/audiobrowser/player/EnginePlayback.kt +9 -5
  7. package/android/src/main/java/com/audiobrowser/player/InterceptingPlayer.kt +71 -39
  8. package/android/src/main/java/com/audiobrowser/player/LiveStreamExtractor.kt +65 -0
  9. package/android/src/main/java/com/audiobrowser/player/MediaFactory.kt +12 -3
  10. package/android/src/main/java/com/audiobrowser/player/NowPlayingUpdater.kt +8 -0
  11. package/android/src/main/java/com/audiobrowser/player/Player.kt +85 -37
  12. package/android/src/main/java/com/audiobrowser/player/PlayerListener.kt +38 -11
  13. package/android/src/main/java/com/audiobrowser/player/RetryLoadErrorHandlingPolicy.kt +1 -1
  14. package/android/src/main/java/com/audiobrowser/remote/RemoteSwitchingPlayer.kt +21 -0
  15. package/android/src/main/java/com/audiobrowser/util/AwaitCancellable.kt +45 -0
  16. package/android/src/test/java/androidx/media3/session/SessionViews.kt +10 -0
  17. package/android/src/test/java/com/audiobrowser/GateDecisionTest.kt +128 -0
  18. package/android/src/test/java/com/audiobrowser/ResolveFormattedErrorTest.kt +93 -0
  19. package/android/src/test/java/com/audiobrowser/ServiceTaskRemovedTest.kt +35 -0
  20. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerLayerResolutionTest.kt +75 -5
  21. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerTest.kt +42 -0
  22. package/android/src/test/java/com/audiobrowser/browser/TrackLoadHandlerTest.kt +43 -0
  23. package/android/src/test/java/com/audiobrowser/http/RequestConfigBuilderTest.kt +62 -0
  24. package/android/src/test/java/com/audiobrowser/player/BrowseTilesTest.kt +31 -32
  25. package/android/src/test/java/com/audiobrowser/player/LiveStreamEndTest.kt +372 -0
  26. package/android/src/test/java/com/audiobrowser/player/NowPlayingFormatterTest.kt +75 -0
  27. package/android/src/test/java/com/audiobrowser/player/NowPlayingUpdaterTest.kt +25 -0
  28. package/android/src/test/java/com/audiobrowser/player/PlayFromSearchTest.kt +108 -0
  29. package/android/src/test/java/com/audiobrowser/player/PlayerSetupEndedTest.kt +221 -0
  30. package/android/src/test/java/com/audiobrowser/player/PlayerSetupTest.kt +17 -7
  31. package/android/src/test/java/com/audiobrowser/player/PlayerSuppressionTest.kt +183 -7
  32. package/android/src/test/java/com/audiobrowser/player/PlayerTrackChangeTest.kt +153 -0
  33. package/android/src/test/java/com/audiobrowser/player/SessionPlayTest.kt +236 -0
  34. package/android/src/test/java/com/audiobrowser/player/SessionViewRulesTest.kt +62 -0
  35. package/android/src/test/java/com/audiobrowser/player/SessionViewTest.kt +188 -0
  36. package/android/src/test/java/com/audiobrowser/remote/FakeRemote.kt +11 -0
  37. package/android/src/test/java/com/audiobrowser/remote/RemoteSwitchingPlayerTest.kt +58 -0
  38. package/android/src/test/java/com/audiobrowser/util/AwaitCancellableTest.kt +136 -0
  39. package/android/src/test/java/com/audiobrowser/util/JsPromise.kt +44 -0
  40. package/ios/AVPlayerEngine.swift +5 -1
  41. package/ios/Browser/BrowserManager.swift +2 -2
  42. package/ios/Browser/PageResolver.swift +14 -19
  43. package/ios/Browser/RequestPipeline.swift +6 -4
  44. package/ios/CarPlay/CarPlayNowPlayingManager.swift +1 -1
  45. package/ios/CarPlay/CarPlaySession+PageLoader.swift +1 -0
  46. package/ios/CarPlay/CarPlaySession+TabBar.swift +2 -0
  47. package/ios/Extension/Promise+AwaitCallback.swift +33 -0
  48. package/ios/HybridAudioBrowser+Player.swift +1 -1
  49. package/ios/HybridAudioBrowser.swift +1 -1
  50. package/ios/Player/MediaLoader.swift +1 -1
  51. package/ios/Player/PlaybackFailure.swift +3 -3
  52. package/ios/Player/Player.swift +67 -49
  53. package/ios/Player/PlayerEngine.swift +2 -0
  54. package/ios/Player/RetryLoop.swift +72 -12
  55. package/ios/Tests/AwaitCallbackTests.swift +210 -0
  56. package/ios/Tests/GenerationMemoTests.swift +57 -0
  57. package/ios/Tests/PlaybackFailureTests.swift +7 -0
  58. package/ios/Tests/PlayerPolicyTests.swift +346 -6
  59. package/ios/Tests/PlayerTests.swift +79 -1
  60. package/ios/Tests/RetryLoopTests.swift +30 -5
  61. package/ios/Tests/Support/TestTypes.swift +15 -7
  62. package/ios/Tests/Support/TimeLimit.swift +43 -0
  63. package/ios/Util/AwaitCallback.swift +80 -0
  64. package/ios/Util/GenerationMemo.swift +11 -4
  65. package/package.json +2 -1
  66. package/android/src/test/java/com/audiobrowser/player/SessionErrorMaskTest.kt +0 -63
  67. package/ios/Player/EndOfTrackJudgement.swift +0 -25
  68. package/ios/Tests/EndOfTrackJudgementTests.swift +0 -30
@@ -26,6 +26,25 @@ private func makePlaying(live: Bool = false) throws -> (Player, MockPlayerEngine
26
26
  return (player, engine, callbacks)
27
27
  }
28
28
 
29
+ /// Playing with retries that follow the play intent, then stalled: the buffer ran dry and
30
+ /// AVPlayer waits (.buffering), with a stall timeout short enough to await.
31
+ @MainActor
32
+ private func makeStalling(givesUp: Bool = false) throws -> (Player, MockPlayerEngine, MockPlayerCallbacks) {
33
+ let engine = MockPlayerEngine()
34
+ let player = makePlayer(engine: engine, retry: makeRetryLoop(givesUp: givesUp), retries: nil)
35
+ player.retry.stallTimeout = .milliseconds(10)
36
+ let callbacks = MockPlayerCallbacks()
37
+ player.callbacks = callbacks
38
+ try player.setQueue([Track(id: "t1", src: "https://example.com/a.mp3", title: "T")], playWhenReady: true)
39
+ engine.hasItem = true
40
+ engine.hasLoadedAsset = true
41
+ engine.emit(.itemPrepared(likelyToKeepUp: true))
42
+ player.transition(.avPlayerPlaying)
43
+ engine.emit(.stalled)
44
+ player.transition(.avPlayerWaiting)
45
+ return (player, engine, callbacks)
46
+ }
47
+
29
48
  @Suite("Player - seeking")
30
49
  @MainActor
31
50
  struct PlayerSeekingTests {
@@ -211,12 +230,33 @@ struct PlayerEngineEventTests {
211
230
  #expect(engine.primeCount == 2)
212
231
  }
213
232
 
214
- @Test func aFailedLoadWithoutIntentDoesNotPrime() async throws {
233
+ @Test func aFailedLoadWithoutIntentDoesNotPrime_andWaitsForAPlay() throws {
215
234
  let (player, engine, _) = try makeLoading()
216
235
  engine.emit(.loadFailed(URLError(.timedOut)))
217
- await player.retry.pendingTask?.value
218
236
  #expect(engine.primeCount == 0)
219
- #expect(player.state == .error)
237
+ #expect(player.state == .paused)
238
+
239
+ player.setPlayWhenReady(true)
240
+ #expect(engine.resolveAndLoadCalls.count == 2)
241
+ }
242
+
243
+ @Test func aPauseWhileLoadingReachesTheEngine_aPlayDoesNot() throws {
244
+ let (player, engine, _) = try makeLoading()
245
+ player.setPlayWhenReady(true)
246
+ engine.hasItem = true
247
+ engine.hasLoadedAsset = true
248
+ engine.emit(.itemPrepared(likelyToKeepUp: false))
249
+ #expect(player.state == .loading)
250
+ let plays = engine.startPlaybackCallCount
251
+ let pauses = engine.pausePlaybackCallCount
252
+
253
+ player.setPlayWhenReady(false)
254
+ #expect(engine.pausePlaybackCallCount == pauses + 1)
255
+
256
+ player.setPlayWhenReady(true)
257
+ #expect(engine.startPlaybackCallCount == plays)
258
+ engine.emit(.likelyToKeepUp(true))
259
+ #expect(engine.startPlaybackCallCount == plays + 1)
220
260
  }
221
261
 
222
262
  @Test func anUnplayableAssetIsTerminal() throws {
@@ -238,7 +278,7 @@ struct PlayerEngineEventTests {
238
278
  #expect(player.errorStatus == .terminal(.httpStatus(404), report: 1))
239
279
  }
240
280
 
241
- @Test func aGenuineEndAdvances_aLiveEndReconnects() throws {
281
+ @Test func aGenuineEndAdvances_aLiveEndReconnectsThroughTheRetryLoop() async throws {
242
282
  let (player, engine, _) = try makePlaying()
243
283
  engine.currentTime = 300
244
284
  engine.duration = 300
@@ -246,9 +286,97 @@ struct PlayerEngineEventTests {
246
286
  #expect(player.state == .ended)
247
287
 
248
288
  let (live, liveEngine, _) = try makePlaying(live: true)
289
+ live.retry.shouldRetry = { true }
249
290
  liveEngine.emit(.playedToEnd)
291
+ await live.retry.pendingTask?.value
250
292
  #expect(live.state == .loading)
251
293
  #expect(liveEngine.resolveAndLoadCalls.count == 2)
294
+ #expect(live.retry.attempts == 1)
295
+ }
296
+
297
+ /// AVPlayer pauses an item at its end, so a seek within its window would leave it silent.
298
+ @Test func aLiveEndReconnectsEvenWithASeekableWindow() async throws {
299
+ let (player, engine, _) = try makePlaying(live: true)
300
+ player.retry.shouldRetry = { true }
301
+ engine.liveEdge = 120
302
+ engine.emit(.playedToEnd)
303
+ await player.retry.pendingTask?.value
304
+ #expect(engine.seekCalls.isEmpty)
305
+ #expect(engine.resolveAndLoadCalls.count == 2)
306
+ }
307
+
308
+ @Test func liveEndsThatKeepComingEndInATerminalErrorWithinTheBudget() async throws {
309
+ let (player, engine, callbacks) = try makePlaying(live: true)
310
+ player.retry.updatePolicy(from: .second(RetryConfig(
311
+ maxRetries: 3, maxRetryDurationMs: nil, firstConnectMaxRetryDurationMs: nil,
312
+ )))
313
+ player.retry.shouldRetry = { true }
314
+ for _ in 0 ..< 20 where player.state != .error {
315
+ engine.emit(.playedToEnd)
316
+ await player.retry.pendingTask?.value
317
+ engine.emit(.itemPrepared(likelyToKeepUp: true))
318
+ }
319
+ #expect(engine.resolveAndLoadCalls.count == 4)
320
+ #expect(player.state == .error)
321
+ #expect(player.errorStatus.error == .playbackStalled)
322
+ #expect(callbacks.errorEvents.count == 1)
323
+ }
324
+
325
+ /// Each reconnect plays long enough to refill the budget, as a stream closing once an hour does.
326
+ @Test func liveEndsFarApartNeverSpendTheBudget() async throws {
327
+ let (player, engine, callbacks) = try makePlaying(live: true)
328
+ player.retry.updatePolicy(from: .second(RetryConfig(
329
+ maxRetries: 1, maxRetryDurationMs: nil, firstConnectMaxRetryDurationMs: nil,
330
+ )))
331
+ player.retry.shouldRetry = { true }
332
+ player.retry.healthyPlaybackDuration = .milliseconds(10)
333
+ for _ in 0 ..< 5 {
334
+ engine.emit(.playedToEnd)
335
+ await player.retry.pendingTask?.value
336
+ #expect(player.retry.attempts == 1)
337
+ engine.emit(.itemPrepared(likelyToKeepUp: true))
338
+ player.transition(.avPlayerPlaying)
339
+ await player.retry.healthyPlaybackTask?.value
340
+ #expect(player.retry.attempts == 0)
341
+ }
342
+ #expect(engine.resolveAndLoadCalls.count == 6)
343
+ #expect(player.state == .playing)
344
+ #expect(callbacks.errorEvents.isEmpty)
345
+ }
346
+
347
+ @Test func aLiveEndWithRetryOffIsTerminal_withNoBufferingOnTheWay() throws {
348
+ let (player, engine, callbacks) = try makePlaying(live: true)
349
+ player.retry.updatePolicy(from: nil)
350
+ let changesBefore = callbacks.playbackChanges.count
351
+ engine.emit(.playedToEnd)
352
+ #expect(player.state == .error)
353
+ #expect(engine.resolveAndLoadCalls.count == 1)
354
+ #expect(callbacks.playbackChanges.dropFirst(changesBefore).map(\.state) == [.error])
355
+ }
356
+
357
+ /// The engine stops observing an item on a reload; a played-to-end it delivered late is stale.
358
+ @Test func aPlayedToEndDuringALoadIsIgnored() throws {
359
+ let (player, engine, _) = try makePlaying(live: true)
360
+ player.retry.shouldRetry = { true }
361
+ player.reloadResolving(startFromCurrentTime: false)
362
+ #expect(player.state == .loading)
363
+ engine.emit(.playedToEnd)
364
+ #expect(player.state == .loading)
365
+ #expect(player.retry.pendingTask == nil)
366
+ }
367
+
368
+ /// A truncated file stalls rather than ending (the stall watch's); a short end is a duration
369
+ /// AVPlayer overestimated, as for a VBR file without a header.
370
+ @Test func anOnDemandEndShortOfItsEstimatedDurationAdvances() throws {
371
+ let (player, engine, _) = try makePlaying()
372
+ try player.add([Track(id: "t2", src: "https://example.com/b.mp3", title: "B")])
373
+ engine.currentTime = 120
374
+ engine.duration = 300
375
+
376
+ engine.emit(.playedToEnd)
377
+
378
+ #expect(player.queue.currentIndex == 1)
379
+ #expect(player.retry.pendingTask == nil)
252
380
  }
253
381
 
254
382
  @Test func aStallNudgesPlayback_onlyWithIntent() throws {
@@ -277,12 +405,167 @@ struct PlayerEngineEventTests {
277
405
  @Suite("Player - recovering")
278
406
  @MainActor
279
407
  struct PlayerRecoveringTests {
280
- @Test func theNetworkReturningReconnectsAStalledStream() throws {
408
+ @Test func aStallThatOutlastsTheTimeoutIsRetried() async throws {
409
+ let (player, engine, callbacks) = try makeStalling()
410
+ await player.retry.stallTask?.value
411
+ #expect(callbacks.playbackChanges.last?.error?.code == TrackPlayerError.PlaybackError.playbackStalled.code)
412
+ #expect(callbacks.playbackChanges.last?.error?.retrying == true)
413
+ await player.retry.pendingTask?.value
414
+ #expect(engine.resolveAndLoadCalls.count == 2)
415
+ #expect(player.state == .loading)
416
+ }
417
+
418
+ @Test func aStallWithNoFailureEndsInPlaybackStalledOnceTheBudgetIsSpent() async throws {
419
+ let (player, _, callbacks) = try makeStalling(givesUp: true)
420
+ await player.retry.stallTask?.value
421
+ await player.retry.pendingTask?.value
422
+ #expect(player.state == .error)
423
+ #expect(player.errorStatus.error == .playbackStalled)
424
+ #expect(callbacks.errorEvents.count == 1)
425
+ }
426
+
427
+ @Test func aStallThatRecoversIsNotRetried() async throws {
428
+ let (player, engine, _) = try makeStalling()
429
+ player.transition(.avPlayerPlaying)
430
+ await player.retry.stallTask?.value
431
+ #expect(player.retry.pendingTask == nil)
432
+ #expect(engine.resolveAndLoadCalls.count == 1)
433
+ }
434
+
435
+ /// Without `automaticallyWaitsToMinimizeStalling`, AVPlayer reports a stall while the state
436
+ /// stays .playing, and audio may well be playing.
437
+ @Test func aStallReportedWhilePlayingStartsNoWatch() throws {
438
+ let (player, engine, _) = try makePlaying()
439
+ engine.emit(.stalled)
440
+ #expect(player.state == .playing)
441
+ #expect(player.retry.stallTask == nil)
442
+ }
443
+
444
+ @Test func aResumeIntoBufferingStartsANewWatch() throws {
445
+ let (player, engine, _) = try makeStalling()
446
+ player.pause()
447
+ engine.emit(.timeControlStatus(.paused, waitingForNoItem: false))
448
+ player.play()
449
+ engine.emit(.timeControlStatus(.waitingToPlayAtSpecifiedRate, waitingForNoItem: false))
450
+ #expect(player.state == .buffering)
451
+ #expect(player.retry.stallTask != nil)
452
+ player.retry.cancel()
453
+ }
454
+
455
+ @Test func aPauseEndsTheStallWatch() throws {
456
+ let (player, engine, _) = try makeStalling()
457
+ player.pause()
458
+ engine.emit(.timeControlStatus(.paused, waitingForNoItem: false))
459
+ #expect(player.retry.stallTask == nil)
460
+ #expect(player.load?.reloadOnPlay == false)
461
+ #expect(player.state == .paused)
462
+ }
463
+
464
+ @Test func aTrackChangeEndsTheStallWatch() throws {
465
+ let (player, _, _) = try makeStalling()
466
+ try player.setQueue([Track(id: "t2", src: "https://example.com/b.mp3", title: "B")])
467
+ #expect(player.retry.stallTask == nil)
468
+ }
469
+
470
+ /// A link slower than the bitrate rebuffers for longer than the timeout, and a reload would
471
+ /// throw away the buffer it is filling.
472
+ @Test func aStallThatStillReceivesDataKeepsWaiting_untilAWindowBringsNone() async throws {
473
+ let (player, engine, _) = try makeStalling()
474
+ engine.bufferedPosition = 12
475
+ await player.retry.stallTask?.value
476
+ #expect(player.retry.pendingTask == nil)
477
+ #expect(player.retry.stallTask != nil)
478
+ #expect(engine.resolveAndLoadCalls.count == 1)
479
+
480
+ await player.retry.stallTask?.value
481
+ await player.retry.pendingTask?.value
482
+ #expect(engine.resolveAndLoadCalls.count == 2)
483
+ }
484
+
485
+ /// Near a track's end, a pause leaves the state in .buffering, so the resume is no transition.
486
+ @Test func aResumeWhileTheStateHeldBufferingStartsANewWatch() async throws {
487
+ let (player, _, _) = try makeStalling()
488
+ player.pause()
489
+ await player.retry.stallTask?.value
490
+ #expect(player.state == .buffering)
491
+ #expect(player.retry.stallTask == nil)
492
+
493
+ player.play()
494
+ #expect(player.retry.stallTask != nil)
495
+ player.retry.cancel()
496
+ }
497
+
498
+ /// The stalled item is still alive: data arriving later must not play it under the error.
499
+ @Test func aTerminalStallLeavesNothingThatCanPlay() async throws {
500
+ let (player, engine, _) = try makeStalling()
501
+ player.retry.updatePolicy(from: nil)
502
+ let pauses = engine.pausePlaybackCallCount
503
+ await player.retry.stallTask?.value
504
+ #expect(player.state == .error)
505
+ #expect(engine.pausePlaybackCallCount == pauses + 1)
506
+
507
+ engine.startPlaybackCallCount = 0
508
+ engine.emit(.stalled)
509
+ #expect(engine.startPlaybackCallCount == 0)
510
+ }
511
+
512
+ @Test func anAirPlayStrandingInAnErrorIsNotNudged() throws {
281
513
  let (player, engine, _) = try makePlaying()
514
+ engine.isAirPlayRoute = true
515
+ engine.emit(.timeControlStatus(.waitingToPlayAtSpecifiedRate, waitingForNoItem: true))
516
+ player.transition(.errorOccurred(.playbackStalled))
517
+ engine.startPlaybackCallCount = 0
518
+ engine.emit(.timeControlStatus(.paused, waitingForNoItem: false))
519
+ #expect(engine.startPlaybackCallCount == 0)
520
+ }
521
+
522
+ @Test func aStallWithRetryOffIsTerminalAtTheTimeout() async throws {
523
+ let (player, engine, _) = try makeStalling()
524
+ player.retry.updatePolicy(from: nil)
525
+ await player.retry.stallTask?.value
526
+ #expect(player.state == .error)
527
+ #expect(player.errorStatus.error == .playbackStalled)
528
+ #expect(engine.resolveAndLoadCalls.count == 1)
529
+ }
530
+
531
+ @Test func theNetworkReturningReconnectsAStalledStream_throughTheRetryLoop() async throws {
532
+ let (player, engine, _) = try makePlaying()
533
+ player.retry.shouldRetry = { true }
282
534
  player.transition(.avPlayerWaiting)
283
535
  #expect(player.state == .buffering)
284
536
  player.networkStatusDidChange(isOnline: true)
537
+ await player.retry.pendingTask?.value
285
538
  #expect(engine.resolveAndLoadCalls.count == 2)
539
+ #expect(player.retry.attempts == 1)
540
+ }
541
+
542
+ @Test func aFlappingConnectionEndsInATerminalErrorOnceTheBudgetIsSpent() async throws {
543
+ let (player, engine, callbacks) = try makePlaying()
544
+ player.retry.updatePolicy(from: .second(RetryConfig(
545
+ maxRetries: 2, maxRetryDurationMs: nil, firstConnectMaxRetryDurationMs: nil,
546
+ )))
547
+ player.retry.shouldRetry = { true }
548
+ for flap in 1 ... 3 {
549
+ player.transition(.avPlayerWaiting)
550
+ player.networkStatusDidChange(isOnline: true)
551
+ await player.retry.pendingTask?.value
552
+ if flap == 3 { break }
553
+ engine.emit(.itemPrepared(likelyToKeepUp: true))
554
+ player.transition(.avPlayerPlaying)
555
+ }
556
+ #expect(engine.resolveAndLoadCalls.count == 3)
557
+ #expect(player.state == .error)
558
+ #expect(callbacks.errorEvents.count == 1)
559
+ }
560
+
561
+ @Test func theNetworkReturningWithRetryOffLeavesTheStallToAVPlayer() throws {
562
+ let (player, engine, callbacks) = try makePlaying()
563
+ player.retry.updatePolicy(from: nil)
564
+ player.transition(.avPlayerWaiting)
565
+ player.networkStatusDidChange(isOnline: true)
566
+ #expect(player.state == .buffering)
567
+ #expect(engine.resolveAndLoadCalls.count == 1)
568
+ #expect(callbacks.errorEvents.isEmpty)
286
569
  }
287
570
 
288
571
  @Test func theNetworkReturningLeavesAPausedOrPlayingStreamAlone() throws {
@@ -321,14 +604,16 @@ struct PlayerRecoveringTests {
321
604
  #expect(engine.resolveAndLoadCalls.count == 1)
322
605
  }
323
606
 
324
- @Test func theNetworkReturningReRendersBeforeReconnecting() throws {
607
+ @Test func theNetworkReturningReRendersBeforeReconnecting() async throws {
325
608
  let (player, engine, _) = try makePlaying()
609
+ player.retry.shouldRetry = { true }
326
610
  player.transition(.avPlayerWaiting)
327
611
  var order: [String] = []
328
612
  engine.onSeamCall = { order.append($0) }
329
613
  let loadsBefore = engine.resolveAndLoadCalls.count
330
614
 
331
615
  player.networkStatusDidChange(isOnline: true)
616
+ await player.retry.pendingTask?.value
332
617
 
333
618
  #expect(order.first == "renderNowPlaying")
334
619
  #expect(engine.resolveAndLoadCalls.count == loadsBefore + 1)
@@ -360,6 +645,37 @@ struct PlayerRecoveringTests {
360
645
  #expect(engine.recreateCount == 0)
361
646
  }
362
647
 
648
+ @Test func aRetryAfterTheAVPlayerItselfFailedReloadsOnANewOne_inTheSameLoad() async throws {
649
+ let (player, engine, _) = try makePlaying()
650
+ player.retry.shouldRetry = { true }
651
+ engine.emit(.audioDidStart)
652
+ let first = player.load
653
+ engine.playerFailed = true
654
+
655
+ engine.emit(.failed(URLError(.networkConnectionLost), httpStatusCode: nil))
656
+ await player.retry.pendingTask?.value
657
+
658
+ #expect(engine.recreateCount == 1)
659
+ #expect(engine.resolveAndLoadCalls.count == 2)
660
+ #expect(player.load?.id == first?.id)
661
+ #expect(player.load?.hasPlayed == true)
662
+ }
663
+
664
+ @Test func aMediaServicesResetDuringABackoffReloadsOnce() async throws {
665
+ let engine = MockPlayerEngine()
666
+ let player = makePlayer(engine: engine, retry: makeRetryLoop(delay: 0.05), retries: nil)
667
+ try player.setQueue([Track(id: "t1", src: "https://example.com/a.mp3", title: "T")], playWhenReady: true)
668
+ engine.hasItem = true
669
+ engine.emit(.failed(URLError(.timedOut), httpStatusCode: nil))
670
+ let retrying = player.retry.pendingTask
671
+
672
+ player.mediaServicesWereReset()
673
+ await retrying?.value
674
+
675
+ #expect(engine.resolveAndLoadCalls.count == 2)
676
+ #expect(player.retry.pendingTask == nil)
677
+ }
678
+
363
679
  @Test func aMediaServicesResetReloadsOnANewPlayer() throws {
364
680
  let (player, engine, _) = try makePlaying()
365
681
  player.mediaServicesWereReset()
@@ -397,6 +713,30 @@ struct PlayerRecoveringTests {
397
713
  #expect(stopped.deferredSeek.target == nil)
398
714
  }
399
715
 
716
+ @Test func aReloadAfterTheEndStartsOver() throws {
717
+ let (player, engine, _) = try makePlaying()
718
+ engine.currentTime = 300
719
+ engine.duration = 300
720
+ engine.resumePosition = 300
721
+ engine.emit(.playedToEnd)
722
+ #expect(player.state == .ended)
723
+
724
+ player.reloadResolving(startFromCurrentTime: true)
725
+ #expect(player.deferredSeek.target == nil)
726
+ engine.emit(.itemPrepared(likelyToKeepUp: true))
727
+ #expect(engine.seekCalls.isEmpty)
728
+ }
729
+
730
+ @Test func aReloadAfterAStopStartsOver() throws {
731
+ let (player, engine, _) = try makePlaying()
732
+ engine.seekResult = nil
733
+ player.stop()
734
+ // The stop's rewind has not landed.
735
+ engine.resumePosition = 120
736
+ player.reloadResolving(startFromCurrentTime: true)
737
+ #expect(player.deferredSeek.target == nil)
738
+ }
739
+
400
740
  @Test func aStopRewindsAFiniteTrack_notALiveOne() throws {
401
741
  let (player, engine, _) = try makePlaying()
402
742
  player.stop()
@@ -185,11 +185,13 @@ struct RetryingErrorTests {
185
185
  @Test @MainActor
186
186
  func exhaustion_hardensIntoTerminalError() async {
187
187
  let (c, retryHandler, cb, _) = makeRetrying()
188
+ retryHandler.updatePolicy(from: .second(RetryConfig(
189
+ maxRetries: 1, maxRetryDurationMs: nil, firstConnectMaxRetryDurationMs: nil,
190
+ )))
188
191
  c.transition(.trackLoading)
189
192
  c.retry.handleError(URLError(.cannotConnectToHost), context: .mediaLoad)
190
193
  await c.retry.pendingTask?.value
191
194
 
192
- retryHandler.shouldRetry = { false }
193
195
  c.retry.handleError(URLError(.cannotConnectToHost), context: .mediaLoad)
194
196
  await c.retry.pendingTask?.value
195
197
 
@@ -221,6 +223,68 @@ struct RetryingErrorTests {
221
223
  #expect(c.deferredSeek.target == 42)
222
224
  }
223
225
 
226
+ /// AVPlayer fails a paused live item once its data stalls.
227
+ @Test @MainActor
228
+ func retryableFailureWhilePaused_staysPausedAndReloadsOnPlay() throws {
229
+ let (c, eh, cb) = try makePlayingWithRetries()
230
+ eh.resumePosition = 42
231
+ c.pause()
232
+ let changesBefore = cb.playbackChanges.count
233
+
234
+ eh.emit(.failed(NSError(domain: "CoreMediaErrorDomain", code: -16830), httpStatusCode: nil))
235
+
236
+ #expect(c.state == .paused)
237
+ #expect(cb.errorEvents.isEmpty)
238
+ #expect(cb.playbackChanges.dropFirst(changesBefore).allSatisfy { $0.error == nil })
239
+ #expect(c.retry.pendingTask == nil)
240
+ #expect(eh.resolveAndLoadCalls.isEmpty)
241
+ #expect(c.getPlayback().state == .paused)
242
+ #expect(c.getPlayback().error == nil)
243
+
244
+ c.play()
245
+
246
+ #expect(eh.resolveAndLoadCalls.count == 1)
247
+ #expect(c.deferredSeek.target == 42)
248
+ }
249
+
250
+ @Test @MainActor
251
+ func aParkedLoadThatKeepsFailingAfterPlay_endsInTheTerminalErrorOnAFullBudget() async throws {
252
+ let (c, eh, cb) = try makePlayingWithRetries()
253
+ c.retry.updatePolicy(from: .second(RetryConfig(
254
+ maxRetries: 2, maxRetryDurationMs: nil, firstConnectMaxRetryDurationMs: nil,
255
+ )))
256
+ let stall = NSError(domain: "CoreMediaErrorDomain", code: -16830)
257
+ // One retry spent before the pause; the park refills the budget.
258
+ eh.emit(.failed(stall, httpStatusCode: nil))
259
+ await c.retry.pendingTask?.value
260
+ #expect(c.retry.attempts == 1)
261
+
262
+ c.pause()
263
+ eh.emit(.failed(stall, httpStatusCode: nil))
264
+ #expect(c.retry.attempts == 0)
265
+ c.play()
266
+ eh.resolveAndLoadCalls.removeAll()
267
+
268
+ for _ in 0 ..< 3 {
269
+ eh.emit(.failed(stall, httpStatusCode: nil))
270
+ await c.retry.pendingTask?.value
271
+ }
272
+
273
+ #expect(eh.resolveAndLoadCalls.count == 2)
274
+ #expect(c.state == .error)
275
+ #expect(cb.errorEvents.count == 1)
276
+ #expect(c.getPlayback().error != nil)
277
+ }
278
+
279
+ @Test @MainActor
280
+ func nonRetryableFailureWhilePaused_isTerminal() throws {
281
+ let (c, eh, cb) = try makePlayingWithRetries()
282
+ c.pause()
283
+ eh.emit(.failed(URLError(.fileDoesNotExist), httpStatusCode: 404))
284
+ #expect(c.state == .error)
285
+ #expect(cb.errorEvents.count == 1)
286
+ }
287
+
224
288
  @Test @MainActor
225
289
  func pauseDuringRetry_whileBuffering_reportsPausedWithoutTheRetryingError() throws {
226
290
  let (c, eh, cb) = try makePlayingWithRetries()
@@ -297,6 +361,20 @@ struct RetryingErrorTests {
297
361
  #expect(cb.errorEvents.isEmpty)
298
362
  }
299
363
 
364
+ @Test @MainActor
365
+ func aRetryNowDuringABackoff_reloadsOnce() async throws {
366
+ let (c, eh, cb) = try makePlayingWithRetries()
367
+ c.retry.handleError(URLError(.cannotConnectToHost), context: .playback)
368
+ let retrying = c.retry.pendingTask
369
+
370
+ c.retryNow()
371
+ await retrying?.value
372
+
373
+ #expect(eh.resolveAndLoadCalls.count == 1)
374
+ #expect(c.retry.pendingTask == nil)
375
+ #expect(cb.errorEvents.isEmpty)
376
+ }
377
+
300
378
  @Test @MainActor
301
379
  func pauseDuringRetry_thenStop_playsFromTheStart() throws {
302
380
  let (c, eh, _) = try makePlayingWithRetries()
@@ -77,8 +77,8 @@ struct RetryLoopHandleErrorTests {
77
77
  var reloads: [Bool] = []
78
78
  }
79
79
 
80
- private func makeLoop(retries: Bool = true, delay: TimeInterval = 0) -> (RetryLoop, Record) {
81
- let loop = makeRetryLoop(retries: retries, delay: delay)
80
+ private func makeLoop(givesUp: Bool = false, delay: TimeInterval = 0) -> (RetryLoop, Record) {
81
+ let loop = makeRetryLoop(givesUp: givesUp, delay: delay)
82
82
  let record = Record()
83
83
  loop.onRetryingError = { record.retrying.append($0) }
84
84
  loop.onError = { record.errors.append($0) }
@@ -128,7 +128,7 @@ struct RetryLoopHandleErrorTests {
128
128
  }
129
129
 
130
130
  @Test func givingUpReportsTheAdvisoryThenTheTerminalError() async {
131
- let (loop, record) = makeLoop(retries: false)
131
+ let (loop, record) = makeLoop(givesUp: true)
132
132
  loop.handleError(URLError(.cannotConnectToHost), context: .mediaLoad)
133
133
  await loop.pendingTask?.value
134
134
  #expect(record.retrying == [.hostUnreachable])
@@ -159,7 +159,7 @@ struct RetryLoopHandleErrorTests {
159
159
  }
160
160
 
161
161
  @Test func theHTTPStatusReachesTheReport() async {
162
- let (loop, record) = makeLoop(retries: false)
162
+ let (loop, record) = makeLoop(givesUp: true)
163
163
  loop.handleError(nil, context: .playback, httpStatusCode: 404)
164
164
  loop.handleError(URLError(.badURL), context: .playback, httpStatusCode: 503)
165
165
  await loop.pendingTask?.value
@@ -167,7 +167,7 @@ struct RetryLoopHandleErrorTests {
167
167
  }
168
168
 
169
169
  @Test func givingUpOnAnOpaqueFailureReportsTheFallback() async {
170
- let (loop, record) = makeLoop(retries: false)
170
+ let (loop, record) = makeLoop(givesUp: true)
171
171
  loop.handleError(NSError(domain: "CoreMediaErrorDomain", code: -12939), context: .mediaLoad)
172
172
  await loop.pendingTask?.value
173
173
  #expect(record.errors == [.failedToLoadKeyValue])
@@ -241,6 +241,31 @@ struct RetryLoopHandleErrorTests {
241
241
  }
242
242
  }
243
243
 
244
+ @Suite("RetryLoop.handleFailure")
245
+ @MainActor
246
+ struct RetryLoopHandleFailureTests {
247
+ private final class Sleeps: @unchecked Sendable {
248
+ var seconds: [TimeInterval] = []
249
+ }
250
+
251
+ @Test func anImmediateFailureSkipsTheBackoff_butSpendsAnAttempt() async {
252
+ let sleeps = Sleeps()
253
+ let loop = RetryLoop(sleep: { sleeps.seconds.append($0) })
254
+ loop.updatePolicy(from: .first(true))
255
+ var reloads: [Bool] = []
256
+ loop.onRetry = { reloads.append($0) }
257
+
258
+ loop.handleFailure(.stall)
259
+ await loop.pendingTask?.value
260
+ loop.handleFailure(.stall, immediately: true)
261
+ await loop.pendingTask?.value
262
+
263
+ #expect(sleeps.seconds == [1, 0])
264
+ #expect(reloads == [true, true])
265
+ #expect(loop.attempts == 2)
266
+ }
267
+ }
268
+
244
269
  @MainActor
245
270
  private final class LoopHolder {
246
271
  weak var loop: RetryLoop?
@@ -43,6 +43,7 @@ final class MockPlayerEngine: PlayerEngine {
43
43
  var liveEdge: Double?
44
44
  var isPlaybackLikelyToKeepUp = false
45
45
  var isAirPlayRoute = false
46
+ var playerFailed = false
46
47
  var volume: Float = 1
47
48
 
48
49
  var resolveAndLoadCalls: [String] = []
@@ -62,7 +63,10 @@ final class MockPlayerEngine: PlayerEngine {
62
63
  }
63
64
 
64
65
  func stopObservingItem() { stopObservingItemCount += 1 }
65
- func recreate() { recreateCount += 1 }
66
+ func recreate() {
67
+ recreateCount += 1
68
+ playerFailed = false
69
+ }
66
70
 
67
71
  var startPlaybackCallCount = 0
68
72
  var pausePlaybackCallCount = 0
@@ -148,8 +152,9 @@ final class MockPlayerEngine: PlayerEngine {
148
152
  }
149
153
  }
150
154
 
151
- /// A Player whose retries reload while `retries` and otherwise give up, or follow the play intent
152
- /// when `retries` is nil, persisting to a test-only defaults suite.
155
+ /// A Player whose retry loop sees a play intent of `retries`, or the real one when `retries` is
156
+ /// nil, persisting to a test-only defaults suite. Without a play intent, a retryable failure is
157
+ /// left to the next play.
153
158
  @MainActor
154
159
  func makePlayer(
155
160
  engine: MockPlayerEngine = MockPlayerEngine(),
@@ -249,13 +254,16 @@ final class MockPlayerCallbacks: PlayerCallbacks {
249
254
 
250
255
  // MARK: - RetryLoop
251
256
 
252
- /// An enabled RetryLoop that backs off for `delay` seconds and reloads while `retries`.
257
+ /// An enabled RetryLoop with play intent that backs off for `delay` seconds and reloads, or gives
258
+ /// up on the first retry when `givesUp`.
253
259
  @MainActor
254
- func makeRetryLoop(retries: Bool = true, delay: TimeInterval = 0) -> RetryLoop {
260
+ func makeRetryLoop(givesUp: Bool = false, delay: TimeInterval = 0) -> RetryLoop {
255
261
  let loop = RetryLoop(sleep: { _ in
256
262
  if delay > 0 { try await Task.sleep(for: .seconds(delay)) }
257
263
  })
258
- loop.updatePolicy(from: .first(true))
259
- loop.shouldRetry = { retries }
264
+ loop.updatePolicy(from: givesUp ? .second(RetryConfig(
265
+ maxRetries: 0, maxRetryDurationMs: nil, firstConnectMaxRetryDurationMs: nil,
266
+ )) : .first(true))
267
+ loop.shouldRetry = { true }
260
268
  return loop
261
269
  }
@@ -0,0 +1,43 @@
1
+ import Foundation
2
+ import Testing
3
+
4
+ struct TimeLimitExceeded: Error {}
5
+
6
+ /// `body`'s result, or a recorded issue and `TimeLimitExceeded` once `limit` elapses. Polls an
7
+ /// unstructured task rather than racing a task group, so a body that ignores cancellation fails
8
+ /// the test instead of hanging it.
9
+ func withinTimeLimit<T: Sendable>(
10
+ _ limit: Duration = .seconds(5),
11
+ sourceLocation: SourceLocation = #_sourceLocation,
12
+ _ body: @escaping @Sendable () async throws -> T,
13
+ ) async throws -> T {
14
+ let task = Task { try await body() }
15
+ let finished = Flag()
16
+ Task {
17
+ _ = await task.result
18
+ finished.set()
19
+ }
20
+ let deadline = ContinuousClock.now + limit
21
+ while !finished.isSet {
22
+ if ContinuousClock.now >= deadline {
23
+ task.cancel()
24
+ Issue.record("still running after \(limit)", sourceLocation: sourceLocation)
25
+ throw TimeLimitExceeded()
26
+ }
27
+ try await Task.sleep(for: .milliseconds(5))
28
+ }
29
+ return try await task.value
30
+ }
31
+
32
+ final class Flag: @unchecked Sendable {
33
+ private let lock = NSLock()
34
+ private var value = false
35
+
36
+ var isSet: Bool {
37
+ lock.withLock { value }
38
+ }
39
+
40
+ func set() {
41
+ lock.withLock { value = true }
42
+ }
43
+ }