react-native-queue-player 2.0.0 → 2.0.1

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

@@ -0,0 +1,189 @@
+package com.margelo.nitro.queueplayer
+
+import android.net.Uri
+import androidx.media3.common.PlaybackException
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.datasource.DataSource
+import androidx.media3.datasource.DataSpec
+import androidx.media3.datasource.HttpDataSource
+import androidx.media3.datasource.TransferListener
+import org.junit.Assert.assertArrayEquals
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Assert.fail
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+
+/**
+ * A response that is a document rather than media fails before any of its bytes
+ * are returned, so neither cache write path — the prefetcher's `CacheWriter` nor
+ * the playback read path's own sink — ever sees them.
+ *
+ * `android.net.Uri` is a framework type, so this runs under Robolectric like
+ * every other test here that parses one.
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+@UnstableApi
+class MediaValidatingDataSourceTest {
+
+  /** An HTTP source that answers with fixed headers and a fixed body. */
+  private class FakeHttpSource(
+    private val body: ByteArray,
+    private val contentType: String?,
+    /** Bytes to hand back per read, so a body arriving in dribs is covered. */
+    private val chunk: Int = Int.MAX_VALUE
+  ) : HttpDataSource {
+    private var position = 0
+    var readCount = 0
+      private set
+
+    override fun open(dataSpec: DataSpec): Long {
+      position = dataSpec.position.toInt()
+      return (body.size - position).toLong()
+    }
+
+    override fun read(buffer: ByteArray, offset: Int, length: Int): Int {
+      readCount += 1
+      if (position >= body.size) return -1
+      val take = minOf(length, chunk, body.size - position)
+      body.copyInto(buffer, offset, position, position + take)
+      position += take
+      return take
+    }
+
+    override fun getUri(): Uri = Uri.parse("https://example.com/track")
+    override fun close() {}
+    override fun addTransferListener(transferListener: TransferListener) {}
+    override fun getResponseHeaders(): Map<String, List<String>> =
+      if (contentType == null) emptyMap() else mapOf("Content-Type" to listOf(contentType))
+
+    override fun setRequestProperty(name: String, value: String) {}
+    override fun clearRequestProperty(name: String) {}
+    override fun clearAllRequestProperties() {}
+    override fun getResponseCode(): Int = 200
+  }
+
+  /** A non-HTTP source, which carries no declared type and is passed through. */
+  private class FakeLocalSource(private val body: ByteArray) : DataSource {
+    private var position = 0
+    override fun open(dataSpec: DataSpec): Long = body.size.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.parse("file:///track.mp3")
+    override fun close() {}
+    override fun addTransferListener(transferListener: TransferListener) {}
+  }
+
+  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) + ByteArray(120)
+
+  private fun openAndRead(
+    source: DataSource,
+    position: Long = 0L,
+    uri: String = "https://example.com/track"
+  ): ByteArray {
+    source.open(DataSpec.Builder().setUri(uri).setPosition(position).build())
+    val out = ArrayList<Byte>()
+    val buffer = ByteArray(32)
+    while (true) {
+      val read = source.read(buffer, 0, buffer.size)
+      if (read == -1) break
+      for (i in 0 until read) out.add(buffer[i])
+    }
+    return out.toByteArray()
+  }
+
+  @Test
+  fun aDeclaredDocumentFailsBeforeAnythingIsRead() {
+    val upstream = FakeHttpSource(xmlEnvelope, "application/xml")
+    val source = MediaValidatingDataSource(upstream)
+    try {
+      source.open(DataSpec(Uri.parse("https://example.com/track")))
+      fail("a declared document must not open")
+    } catch (e: HttpDataSource.HttpDataSourceException) {
+      assertEquals(PlaybackException.ERROR_CODE_IO_INVALID_HTTP_CONTENT_TYPE, e.reason)
+    }
+    assertEquals("nothing may be read from a refused response", 0, upstream.readCount)
+  }
+
+  @Test
+  fun anUndeclaredMarkupBodyFailsOnTheFirstRead() {
+    val source = MediaValidatingDataSource(FakeHttpSource(xmlEnvelope, null))
+    source.open(DataSpec(Uri.parse("https://example.com/track")))
+    try {
+      source.read(ByteArray(32), 0, 32)
+      fail("a markup body must not be returned")
+    } catch (e: HttpDataSource.HttpDataSourceException) {
+      assertEquals(PlaybackException.ERROR_CODE_IO_INVALID_HTTP_CONTENT_TYPE, e.reason)
+    }
+  }
+
+  @Test
+  fun plainTextWithNoContainerSignatureFailsOnTheFirstRead() {
+    val source = MediaValidatingDataSource(FakeHttpSource("not found".toByteArray(), "text/plain"))
+    source.open(DataSpec(Uri.parse("https://example.com/track")))
+    try {
+      source.read(ByteArray(32), 0, 32)
+      fail("text with no container signature must not be returned")
+    } catch (e: HttpDataSource.HttpDataSourceException) {
+      assertEquals(PlaybackException.ERROR_CODE_IO_INVALID_HTTP_CONTENT_TYPE, e.reason)
+    }
+  }
+
+  @Test
+  fun mediaIsPassedThroughWhole() {
+    val source = MediaValidatingDataSource(FakeHttpSource(mp3, "audio/mpeg"))
+    assertArrayEquals("every byte reaches the caller unchanged", mp3, openAndRead(source))
+  }
+
+  @Test
+  fun mediaArrivingInSmallChunksIsStillPassedThroughWhole() {
+    val source = MediaValidatingDataSource(FakeHttpSource(mp3, "audio/mpeg", chunk = 3))
+    assertArrayEquals(mp3, openAndRead(source))
+  }
+
+  @Test
+  fun aRangedRequestIsJudgedOnItsDeclaredTypeOnly() {
+    // The served window opens with `<`, so the leading-byte rule would refuse it
+    // if it were applied. A body read from an offset says nothing about the
+    // resource's first bytes, so it is not.
+    val markupAtOffset = "....<api-response/>".toByteArray()
+    val ranged = MediaValidatingDataSource(
+      FakeHttpSource(markupAtOffset, "application/octet-stream")
+    )
+    val read = openAndRead(ranged, position = 4L)
+    assertTrue("a partial body is not judged by its first byte", read.isNotEmpty())
+
+    // The same bytes as the whole resource are refused — which is what shows the
+    // acceptance above turns on the range and not on the bytes.
+    val whole = MediaValidatingDataSource(
+      FakeHttpSource("<api-response/>".toByteArray(), "application/octet-stream")
+    )
+    whole.open(DataSpec(Uri.parse("https://example.com/track")))
+    try {
+      whole.read(ByteArray(32), 0, 32)
+      fail("the same markup read from the start of the resource must be refused")
+    } catch (e: HttpDataSource.HttpDataSourceException) {
+      assertEquals(PlaybackException.ERROR_CODE_IO_INVALID_HTTP_CONTENT_TYPE, e.reason)
+    }
+  }
+
+  @Test
+  fun aLocalSourceIsPassedThroughUnjudged() {
+    val source = MediaValidatingDataSource(FakeLocalSource(xmlEnvelope))
+    assertArrayEquals(
+      "a file:// source is not fetched from a server and is not the case this guards",
+      xmlEnvelope,
+      openAndRead(source, uri = "file:///track.mp3")
+    )
+  }
+}

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

@@ -182,6 +182,40 @@ class TrackPlayerEventsTest {
     assertEquals("nothing reaches a removed subscriber", 1, fired)
   }
 
+  /**
+   * A source that answered with something that is not media is a format
+   * problem, not a reachability one: it was reached, and a retry cannot change
+   * what it sends. Classing it transient would spend an automatic attempt on a
+   * body that can never become audio.
+   */
+  @Test
+  fun aNonMediaResponseClassifiesAsAFormatFailureAndIsFatal() {
+    val invalidContentType = PlaybackException(
+      "msg", null,
+      PlaybackException.ERROR_CODE_IO_INVALID_HTTP_CONTENT_TYPE
+    )
+    assertEquals(
+      PlaybackErrorCode.FILE_FORMAT_NOT_RECOGNIZED,
+      PlaybackErrorMapping.classify(invalidContentType)
+    )
+    assertFalse(
+      PlaybackErrorMapping.isTransient(PlaybackErrorCode.FILE_FORMAT_NOT_RECOGNIZED)
+    )
+  }
+
+  /** A source that is genuinely missing stays a reachability failure. */
+  @Test
+  fun aMissingFileStillClassifiesAsUnreachable() {
+    val notFound = PlaybackException(
+      "msg", null,
+      PlaybackException.ERROR_CODE_IO_FILE_NOT_FOUND
+    )
+    assertEquals(
+      PlaybackErrorCode.SOURCE_UNREACHABLE,
+      PlaybackErrorMapping.classify(notFound)
+    )
+  }
+
   // --- PlaybackErrorMapping.isTransient classification
   //
   // `PlaybackErrorMapping.isTransient` operates on the lib-

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

@@ -232,6 +232,92 @@ class TrackPlayerLifecycleTest {
     "boom", null,
     androidx.media3.common.PlaybackException.ERROR_CODE_IO_NETWORK_CONNECTION_FAILED)
 
+  /**
+   * Under crossfade the standby leg prerolls the next track, so a broken one
+   * fails while the leading track is still playing and is surfaced there. The
+   * engine then seats it and it fails again as the current track — the listener
+   * asked for one thing and must be told once.
+   */
+  @Test
+  fun `a track reported while it was prerolling does not report again when it is seated`() {
+    seedThreeTrackQueue(autoRetries = 0.0)
+
+    var reported = 0
+    val dispose = player.onError { reported += 1 }
+
+    // The standby leg prerolling track 1 fails while track 0 is playing.
+    player.onError(serviceHandle.engine, fatalFailure(), 1)
+    assertEquals("the listener is told their next track is broken", 1, reported)
+
+    // The fade begins, so track 1 is the one being heard, and it fails again as
+    // the current track.
+    player.onCrossfadeBegin(serviceHandle.engine, 1)
+    assertEquals("the fade seats the track that was prerolling", 1, player.currentTrackIndex)
+    player.onError(serviceHandle.engine, fatalFailure(), 1)
+    dispose()
+
+    assertEquals("and not told a second time about the same track", 1, reported)
+  }
+
+  /**
+   * A shuffle renumbers every position, so a record against the pre-shuffle
+   * current index names a different track afterwards. Nothing is carried.
+   */
+  @Test
+  fun `a shuffle leaves no track marked as stopped`() {
+    seedThreeTrackQueue(autoRetries = 0.0)
+    player.onError(serviceHandle.engine, fatalFailure(), 0)
+
+    player.shuffleQueueInternal()
+
+    assertEquals("a shuffle seats position 0", 0, player.currentTrackIndex)
+    // A stop standing against the current track silences every other track's
+    // failure, so a report for one of them is what shows the set is empty.
+    var reported = 0
+    val dispose = player.onError { reported += 1 }
+    player.onError(serviceHandle.engine, fatalFailure(), 1)
+    dispose()
+
+    assertEquals("no track is holding the queue after a shuffle", 1, reported)
+  }
+
+  /**
+   * `-1` means "no track", so a failure that carries no index — an engine that
+   * reports without one, or a queue that has been cleared — must not enter the
+   * set. A member equal to `currentTrackIndex` is what "stopped" means, and at
+   * `-1` that would read as stopped and silence every later failure.
+   */
+  @Test
+  fun `a failure with no track does not mark the queue as stopped`() {
+    player.configureInternal(config(autoRetries = 0.0), context())
+    player.setQueueInternal(emptyList())
+    assertEquals("an empty queue seats no track", -1, player.currentTrackIndex)
+
+    // An engine that reports without an index — AirPlay does — while the queue
+    // is empty. There is no position to record.
+    player.onError(serviceHandle.engine, fatalFailure())
+
+    // The add empties the set and restores the current track's entry, so with
+    // -1 a member that restore is what carries it forward. It leaves the index
+    // at -1 by design, which is what keeps it a member.
+    player.addToQueueInternal(
+      (0 until 2).map { track("https://example.com/$it.mp3") }, insertBefore = 0)
+    assertEquals("an add into an empty queue seats nothing", -1, player.currentTrackIndex)
+
+    var reported = 0
+    val dispose = player.onError { reported += 1 }
+    player.onError(serviceHandle.engine, fatalFailure(), 1)
+    dispose()
+
+    assertEquals(
+      "a track's failure still reaches the listener — nothing is holding the queue",
+      1, reported)
+  }
+
+  private fun fatalFailure() = androidx.media3.common.PlaybackException(
+    "boom", null,
+    androidx.media3.common.PlaybackException.ERROR_CODE_IO_INVALID_HTTP_CONTENT_TYPE)
+
   private fun seedThreeTrackQueue(autoRetries: Double? = null) {
     player.configureInternal(config(autoRetries = autoRetries), context())
     player.setQueueInternal((0 until 3).map { track("https://example.com/$it.mp3") })

package/ios/CrossfadeEngine.swift

@@ -1235,6 +1235,18 @@ final class CrossfadeEngine: PlaybackEngine {
   /// standby to leading.
   private func runFade(durationSeconds: TimeInterval) {
     if released { return }
+    // One envelope per boundary. The arm chain that reaches here is
+    // asynchronous — a standby-ready wait, then a `tracks` key load, then a hop
+    // back to the owner queue — and every step of it checks `standbyArmed`
+    // only, so a boundary whose chain is entered more than once arrives here
+    // more than once. Each arrival would schedule another fifty sub-ramps onto
+    // the same `AVMutableAudioMixInputParameters` (`fadeParams` reuses the
+    // leg's existing one so its audio tap survives the fade), and those windows
+    // overlap the ones already on it: `setVolumeRamp` answers an overlapping
+    // window by raising, which is not catchable from Swift and takes the
+    // process with it. The envelope is also simply wrong once it is scheduled
+    // twice, crash or no crash.
+    if fadeInFlight { return }
     guard let leading = leadingPlayer.currentItem,
           let standby = standbyPlayer.currentItem else { return }
 

package/ios/LookaheadCache.swift

@@ -519,6 +519,18 @@ public final class LookaheadCache: @unchecked Sendable {
     )
   }
 
+  /// Enough of a body to carry any container signature the media check reads.
+  private static let mediaCheckHeadBytes = 64
+
+  /// The first `bytes` of a file, or empty when it cannot be read. An
+  /// unreadable head is not itself a rejection — the size check above has
+  /// already established the file is there.
+  private static func head(ofFileAt url: URL, bytes: Int) -> Data {
+    guard let handle = try? FileHandle(forReadingFrom: url) else { return Data() }
+    defer { try? handle.close() }
+    return (try? handle.read(upToCount: bytes)) ?? Data()
+  }
+
   /// Remove a rejected download's temp file. Cleanup failures are logged
   /// rather than thrown — the caller is already failing the download, and a
   /// leaked temp file should be diagnosable without masking that reason.
@@ -599,6 +611,17 @@ public final class LookaheadCache: @unchecked Sendable {
     }
 
     let contentType = httpResponse.value(forHTTPHeaderField: "Content-Type")
+    // A 2xx of the right length can still be a server's error envelope rather
+    // than a track. Committing one puts a permanent non-audio file behind a
+    // "fully cached" entry, which outlives the server being well again.
+    if let rejection = MediaResponseCheck.rejection(
+      contentType: contentType,
+      head: Self.head(ofFileAt: tempLocation, bytes: Self.mediaCheckHeadBytes),
+      headIsStartOfResource: request.value(forHTTPHeaderField: "Range") == nil
+    ) {
+      discardTemp(at: tempLocation, reason: "non-media body")
+      throw LookaheadCacheError.nonMediaBody(rejection)
+    }
     return (tempLocation, sizeBytes, contentType)
   }
 
@@ -951,6 +974,10 @@ public enum LookaheadCacheError: Error {
   /// The downloaded file's size could not be read, so the truncation check
   /// cannot run; the file is discarded rather than committed unchecked.
   case sizeUnreadable
+  /// The body is a document rather than media — typically a server reporting
+  /// an API-level failure as a `200` carrying an XML or JSON envelope.
+  /// Committing it would serve that envelope as the track on every later play.
+  case nonMediaBody(MediaResponseCheck.Rejection)
 }
 
 /// Abstraction over `LookaheadCache.download` so the prefetcher

package/ios/MediaResponseCheck.swift

@@ -0,0 +1,122 @@
+import Foundation
+
+/// Decides whether an HTTP response that claims to carry a track can be
+/// believed, from its `Content-Type` and the first bytes of its body.
+///
+/// A server that answers an API-level failure with `200` and an XML or JSON
+/// envelope is the case this exists for: media servers commonly report
+/// errors that way by design, and a proxy answering with an HTML page does the
+/// same. Such a body passes every length and status check, so without this it
+/// is committed to the cache as a complete track and served from disk on every
+/// later play — the track stays broken after the server is well again.
+///
+/// The rules identify what is **not** media rather than demanding proof of what
+/// is. The two mistakes are not equal: a false rejection costs a prefetch and
+/// the track still plays from its origin, while a false acceptance breaks the
+/// track until the cache is cleared by hand.
+///
+/// Mirrored rule for rule by `MediaResponseCheck.kt` on Android.
+public enum MediaResponseCheck {
+
+  /// Why a response was refused. Each case carries what was judged so a
+  /// caller's log names the response rather than just the verdict.
+  public enum Rejection: Equatable {
+    /// The declared type is a markup or JSON document, which no audio
+    /// container is.
+    case markupContentType(String)
+    /// The declared type is text of some other kind and the body carries no
+    /// recognised container signature. `text/plain` is not refused on the
+    /// label alone — media servers do mislabel audio — so the body is given
+    /// the chance to prove itself.
+    case textWithoutMediaSignature(String)
+    /// No usable declared type, and the body begins as a markup or JSON
+    /// document.
+    case markupBody
+  }
+
+  /// Types that are documents, never audio. Narrow on purpose:
+  /// `application/octet-stream` and `text/plain` are missing because servers
+  /// serve real audio under both.
+  private static let markupTypes: Set<String> = [
+    "text/html", "application/xhtml+xml",
+    "application/xml", "text/xml",
+    "application/json", "text/json",
+  ]
+
+  /// The verdict for a response, or nil to accept it.
+  ///
+  /// `head` is the first bytes of the body — 64 is plenty for every signature
+  /// below. `headIsStartOfResource` is false when the request carried a
+  /// `Range`, and then only the declared type is judged: a body that begins
+  /// part way into a file says nothing about the file's first bytes.
+  public static func rejection(
+    contentType: String?, head: Data, headIsStartOfResource: Bool
+  ) -> Rejection? {
+    let declared = normalised(contentType)
+    if let declared, markupTypes.contains(declared) {
+      return .markupContentType(declared)
+    }
+    guard headIsStartOfResource else { return nil }
+    let body = droppingByteOrderMark(head)
+    if let declared, declared.hasPrefix("text/") {
+      return hasMediaSignature(body) ? nil : .textWithoutMediaSignature(declared)
+    }
+    return beginsAsMarkup(body) ? .markupBody : nil
+  }
+
+  /// Lowercased type with any `; charset=…` parameter and surrounding space
+  /// removed. Nil for a missing or empty header.
+  private static func normalised(_ contentType: String?) -> String? {
+    guard let raw = contentType, !raw.isEmpty else { return nil }
+    let head = raw.prefix(while: { $0 != ";" })
+    let trimmed = String(head).trimmingCharacters(in: .whitespaces).lowercased()
+    return trimmed.isEmpty ? nil : trimmed
+  }
+
+  /// Drop a byte-order mark so the checks below read the first real byte. A
+  /// UTF-16 mark matters twice over: `FF FE` also satisfies the MPEG frame
+  /// sync pattern, so a UTF-16 document would otherwise read as audio.
+  private static func droppingByteOrderMark(_ head: Data) -> Data {
+    let bytes = [UInt8](head)
+    if bytes.count >= 3, bytes[0] == 0xEF, bytes[1] == 0xBB, bytes[2] == 0xBF {
+      return head.dropFirst(3)
+    }
+    if bytes.count >= 2,
+       (bytes[0] == 0xFF && bytes[1] == 0xFE) || (bytes[0] == 0xFE && bytes[1] == 0xFF) {
+      return head.dropFirst(2)
+    }
+    return head
+  }
+
+  /// Whether the body opens with the magic bytes of a container either
+  /// platform plays, or with an HLS playlist's own first line.
+  private static func hasMediaSignature(_ body: Data) -> Bool {
+    let bytes = [UInt8](body)
+    guard !bytes.isEmpty else { return false }
+    // MPEG audio frame sync: eleven set bits across the first two bytes. ADTS
+    // AAC shares it.
+    if bytes.count >= 2, bytes[0] == 0xFF, bytes[1] & 0xE0 == 0xE0 { return true }
+    let prefixes = ["ID3", "fLaC", "OggS", "RIFF", "FORM", "caff", "#!AMR", "#EXTM3U"]
+    if prefixes.contains(where: { starts(bytes, with: $0) }) { return true }
+    // ISO base media (MP4 / M4A / ALAC): a box length, then the type.
+    if bytes.count >= 8, starts(Array(bytes.dropFirst(4)), with: "ftyp") { return true }
+    return false
+  }
+
+  /// Whether the body opens as an XML / HTML document or a JSON value. No
+  /// container above begins with either character.
+  private static func beginsAsMarkup(_ body: Data) -> Bool {
+    guard let first = [UInt8](body).first(where: { !isAsciiSpace($0) }) else { return false }
+    return first == UInt8(ascii: "<") || first == UInt8(ascii: "{")
+  }
+
+  private static func isAsciiSpace(_ byte: UInt8) -> Bool {
+    byte == 0x20 || byte == 0x09 || byte == 0x0A || byte == 0x0D
+  }
+
+  private static func starts(_ bytes: [UInt8], with ascii: String) -> Bool {
+    let pattern = [UInt8](ascii.utf8)
+    guard bytes.count >= pattern.count else { return false }
+    return Array(bytes.prefix(pattern.count)) == pattern
+  }
+}

package/ios/Tests/MediaResponseCheckTests.swift

@@ -0,0 +1,128 @@
+import XCTest
+@testable import QueuePlayer
+
+/// 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.
+final class MediaResponseCheckTests: XCTestCase {
+
+  private let xmlEnvelope = Data("""
+    <api-response status="failed"><error code="70"/></api-response>
+    """.utf8)
+  private let mp3 = Data([0x49, 0x44, 0x33, 0x04, 0x00, 0x00, 0x00, 0x00])  // "ID3"
+
+  private func rejection(
+    _ contentType: String?, _ body: Data, whole: Bool = true
+  ) -> MediaResponseCheck.Rejection? {
+    MediaResponseCheck.rejection(
+      contentType: contentType, head: body, headIsStartOfResource: whole)
+  }
+
+  // MARK: - A declared document is refused whatever its body
+
+  func testMarkupAndJsonContentTypesAreRefused() {
+    for type in [
+      "application/xml", "text/xml", "text/html",
+      "application/xhtml+xml", "application/json", "text/json",
+    ] {
+      XCTAssertEqual(
+        rejection(type, xmlEnvelope), .markupContentType(type),
+        "\(type) is a document type")
+    }
+  }
+
+  func testTheDeclaredTypeIsReadWithoutItsParameters() {
+    XCTAssertEqual(
+      rejection("application/xml; charset=utf-8", xmlEnvelope),
+      .markupContentType("application/xml"))
+    XCTAssertEqual(rejection("APPLICATION/XML", xmlEnvelope), .markupContentType("application/xml"))
+  }
+
+  /// A ranged request answers from an arbitrary offset, so only the declared
+  /// type can be judged — but that much still holds.
+  func testADeclaredDocumentIsRefusedOnAPartialBodyToo() {
+    XCTAssertEqual(
+      rejection("application/xml", Data([0x3C, 0x00]), whole: false),
+      .markupContentType("application/xml"))
+  }
+
+  func testAPartialBodyIsNotJudgedByItsLeadingBytes() {
+    // 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.
+    let markup = Data("<api-response/>".utf8)
+    XCTAssertEqual(
+      rejection("application/octet-stream", markup),
+      .markupBody)
+    XCTAssertNil(
+      rejection("application/octet-stream", markup, whole: false),
+      "a body that begins part way into a file says nothing about its first bytes")
+  }
+
+  // MARK: - Plain text has to prove itself
+
+  func testTextWithoutAContainerSignatureIsRefused() {
+    XCTAssertEqual(
+      rejection("text/plain", Data("not found".utf8)),
+      .textWithoutMediaSignature("text/plain"))
+  }
+
+  func testTextCarryingAContainerSignatureIsAccepted() {
+    XCTAssertNil(
+      rejection("text/plain", mp3),
+      "a server mislabelling audio as text does not make it a document")
+  }
+
+  func testAPlaylistDeclaredAsTextIsAccepted() {
+    XCTAssertNil(rejection("text/plain", Data("#EXTM3U\n#EXT-X-VERSION:3".utf8)))
+  }
+
+  // MARK: - An unusable declared type falls to the body
+
+  func testAMarkupBodyIsRefusedWhenNothingUsableIsDeclared() {
+    XCTAssertEqual(rejection(nil, xmlEnvelope), .markupBody)
+    XCTAssertEqual(rejection("application/octet-stream", xmlEnvelope), .markupBody)
+    XCTAssertEqual(rejection(nil, Data("<!DOCTYPE html><html>".utf8)), .markupBody)
+    XCTAssertEqual(rejection(nil, Data("{\"error\":\"not found\"}".utf8)), .markupBody)
+  }
+
+  func testLeadingSpaceAndAByteOrderMarkDoNotHideAMarkupBody() {
+    XCTAssertEqual(rejection(nil, Data("\n  <?xml version=\"1.0\"?>".utf8)), .markupBody)
+    XCTAssertEqual(
+      rejection(nil, Data([0xEF, 0xBB, 0xBF]) + Data("<error/>".utf8)), .markupBody)
+    // `FF FE` also satisfies the MPEG frame sync, so a UTF-16 document would
+    // read as audio if the mark were not dropped first.
+    XCTAssertEqual(
+      rejection(nil, Data([0xFF, 0xFE]) + Data("<e/>".utf8)), .markupBody)
+  }
+
+  // MARK: - Real media is accepted, however it is labelled
+
+  func testRecognisedContainersAreAccepted() {
+    let bodies: [String: [UInt8]] = [
+      "ID3": [0x49, 0x44, 0x33, 0x04, 0, 0, 0, 0],
+      "MPEG frame sync": [0xFF, 0xFB, 0x90, 0x00, 0, 0, 0, 0],
+      "ADTS AAC": [0xFF, 0xF1, 0x50, 0x80, 0, 0, 0, 0],
+      "FLAC": [0x66, 0x4C, 0x61, 0x43, 0, 0, 0, 0],
+      "Ogg": [0x4F, 0x67, 0x67, 0x53, 0, 0, 0, 0],
+      "WAV": [0x52, 0x49, 0x46, 0x46, 0, 0, 0, 0],
+      "AIFF": [0x46, 0x4F, 0x52, 0x4D, 0, 0, 0, 0],
+      "CAF": [0x63, 0x61, 0x66, 0x66, 0, 0, 0, 0],
+      "MP4": [0, 0, 0, 0x20, 0x66, 0x74, 0x79, 0x70],
+    ]
+    for (name, bytes) in bodies {
+      XCTAssertNil(rejection("text/plain", Data(bytes)), "\(name) is media")
+      XCTAssertNil(rejection(nil, Data(bytes)), "\(name) is media")
+    }
+  }
+
+  func testAnUndeclaredOrOpaqueBinaryBodyIsAccepted() {
+    let binary = Data([0x00, 0x01, 0x02, 0x03, 0x04])
+    XCTAssertNil(rejection(nil, binary), "an unrecognised container is not a document")
+    XCTAssertNil(rejection("application/octet-stream", binary))
+    XCTAssertNil(rejection("audio/mpeg", binary))
+  }
+
+  func testAnEmptyBodyIsNotJudged() {
+    XCTAssertNil(rejection(nil, Data()))
+  }
+}