Fix VLC Range Cache for MKV Streams

Summary

Dreamio was refusing to range-cache MKV streams before checking the server. That made Torrentio and Real-Debrid MKV playback open in direct mode, so seek prefetch could not run. The cache probe now lets normal HTTP range capability decide whether the local cache should be used.

Changes Made

• Removed the hard-coded cache bypass for .mkv, .mk3d, .mka, .mks, and .webm URLs.
• Kept the existing non-HTTP and HLS playlist fallbacks intact.
• Updated the range probe regression test so MKV URLs are cacheable when the server returns Accept-Ranges: bytes and a valid Content-Length.

Context

The diagnostic logs showed [DreamioVLC] cache fallback reason=tail-index-container, followed by opening mode=direct and direct-mode seek logs. That fallback came from an extension check, not a failed HTTP range probe. Because many debrid MKV streams do support byte ranges, the app was leaving useful buffering behavior on the table.

Important Implementation Details

• The probe still requires either a HEAD response with byte-range support and content length, or a successful GET Range: bytes=0-0 response.
• If an MKV origin ignores range requests, Dreamio still falls back to direct playback through the existing range-probe-status-... path.
• The expected debug signal for a compatible MKV is now [DreamioVLC] opening mode=local-cache, and seeks should include byteOffset=....

Relevant Diff Snippets

271 unmodified lines
272
273
274
275
276
277
278
279
280
281
52 unmodified lines
334
335
336
337
338
339
340
341
342
343
271 unmodified lines
        guard !url.path.lowercased().hasSuffix(".m3u8") else {
            return HTTPRangeProbeResult(isCacheable: false, contentLength: nil, fallbackReason: "hls-playlist")
        }
        guard !Self.shouldBypassCache(for: url) else {
            return HTTPRangeProbeResult(isCacheable: false, contentLength: nil, fallbackReason: "tail-index-container")
        }

        if let head = try? await response(for: request(method: "HEAD")),
           (200..<400).contains(head.statusCode) {
            let acceptsRanges = header("Accept-Ranges", in: head)?.lowercased().contains("bytes") == true
52 unmodified lines
        response.value(forHTTPHeaderField: name)
    }

    private static func shouldBypassCache(for url: URL) -> Bool {
        let extensionName = url.pathExtension.lowercased()
        return ["mkv", "mk3d", "mka", "mks", "webm"].contains(extensionName)
    }
}

enum HTTPRangeCacheError: Error {
271 unmodified lines
272
273
274
275
276
277
52 unmodified lines
330
331
332
333
334
335
271 unmodified lines
        guard !url.path.lowercased().hasSuffix(".m3u8") else {
            return HTTPRangeProbeResult(isCacheable: false, contentLength: nil, fallbackReason: "hls-playlist")
        }
        if let head = try? await response(for: request(method: "HEAD")),
           (200..<400).contains(head.statusCode) {
            let acceptsRanges = header("Accept-Ranges", in: head)?.lowercased().contains("bytes") == true
52 unmodified lines
        response.value(forHTTPHeaderField: name)
    }

}

enum HTTPRangeCacheError: Error {

42 unmodified lines
43
44
45
46
47
48
49
491 unmodified lines
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
3 unmodified lines
561
562
563
564
565
566
567
568
569
42 unmodified lines
        testRangeCacheForegroundMissFetchesAlignedChunks()
        await testRangeCacheForegroundMissReprioritizesPrefetch()
        await testRangeCacheHitFollowsActualPostSeekReadArea()
        await testRangeProbeBypassesTailIndexContainers()
        await testRangeProbeFallsBackWhenServerIgnoresRange()
        await testRangeFetcherPreservesHeaders()
        print("StreamResolverTests passed")
491 unmodified lines
        try? await Task.sleep(nanoseconds: 50_000_000)
    }

    private static func testRangeProbeBypassesTailIndexContainers() async {
        var requestCount = 0
        MockURLProtocol.handler = { request in
            requestCount += 1
            let response = HTTPURLResponse(
                url: request.url!,
                statusCode: 206,
                httpVersion: nil,
                headerFields: ["Content-Range": "bytes 0-0/20"]
            )!
            return (Data([1]), response)
        }

        let fetcher = HTTPRangeRemoteFetcher(
3 unmodified lines
        )
        let probe = await fetcher.probe()

        assertEqual(probe.isCacheable, false)
        assertEqual(probe.fallbackReason, "tail-index-container")
        assertEqual(requestCount, 0)
        MockURLProtocol.handler = nil
    }

42 unmodified lines
43
44
45
46
47
48
49
491 unmodified lines
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
3 unmodified lines
565
566
567
568
569
570
571
572
573
574
42 unmodified lines
        testRangeCacheForegroundMissFetchesAlignedChunks()
        await testRangeCacheForegroundMissReprioritizesPrefetch()
        await testRangeCacheHitFollowsActualPostSeekReadArea()
        await testRangeProbeAllowsRangeCacheForMKVWhenServerSupportsRanges()
        await testRangeProbeFallsBackWhenServerIgnoresRange()
        await testRangeFetcherPreservesHeaders()
        print("StreamResolverTests passed")
491 unmodified lines
        try? await Task.sleep(nanoseconds: 50_000_000)
    }

    private static func testRangeProbeAllowsRangeCacheForMKVWhenServerSupportsRanges() async {
        var requestCount = 0
        MockURLProtocol.handler = { request in
            requestCount += 1
            assertEqual(request.httpMethod, "HEAD")
            let response = HTTPURLResponse(
                url: request.url!,
                statusCode: 200,
                httpVersion: nil,
                headerFields: [
                    "Accept-Ranges": "bytes",
                    "Content-Length": "20"
                ]
            )!
            return (Data(), response)
        }

        let fetcher = HTTPRangeRemoteFetcher(
3 unmodified lines
        )
        let probe = await fetcher.probe()

        assertEqual(probe.isCacheable, true)
        assertEqual(probe.contentLength, 20)
        assertEqual(probe.fallbackReason, nil)
        assertEqual(requestCount, 1)
        MockURLProtocol.handler = nil
    }

Expected Impact for End-Users

Compatible MKV direct-file streams should start through Dreamio's local range cache instead of direct VLC mode. Backward and forward skips can now prime nearby bytes, which should reduce stalls after seeking on supported servers.

Validation

• Passed swiftc Dreamio/StreamCandidate.swift Dreamio/StreamResolver.swift Dreamio/ProgressiveHTTPRangeCache.swift Dreamio/ExternalSubtitleTrackParser.swift Tests/StreamResolverTests.swift -o /tmp/StreamResolverTests && /tmp/StreamResolverTests
• Passed DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer xcodebuild -workspace Dreamio.xcworkspace -scheme Dreamio -configuration Debug -sdk iphonesimulator build

Issues, Limitations, and Mitigations

Follow-up Work

• Test the original Torrentio/Real-Debrid South Park stream on device and confirm logs show opening mode=local-cache.
• If startup is slower on some MKV sources, consider measuring HEAD latency and falling back to the tiny range probe sooner.
• Improve external subtitle auto-selection so English does not lose to the first parsed subtitle track.