react-native-hls-cache 0.1.0

package/ios/HlsCache.swift

@@ -0,0 +1,121 @@
+import Foundation
+import NitroModules
+
+public class HybridHlsCache: HybridHlsCacheSpec {
+
+    // MARK: - State
+
+    private let stateLock = NSLock()
+    private var proxyServer: VideoProxyServer?
+    private var activePort: Int = 9000
+
+    // MARK: - HybridHlsCacheSpec
+
+    /// Light sync method — NWListener setup is < 1ms, no Promise needed.
+    public func startServer(port: Double?, maxCacheSize: Double?, headOnlyCache: Bool?) throws -> Void {
+        let cacheLimit = maxCacheSize.map { Int($0) } ?? 1_073_741_824
+        let targetPort = port.map { Int($0) } ?? 9000
+
+        stateLock.lock()
+        let currentServer = proxyServer
+        let currentPort = activePort
+        stateLock.unlock()
+
+        if let server = currentServer, server.isRunning {
+            if currentPort == targetPort { return }
+            throw NSError(
+                domain: "HlsCache",
+                code: 409,
+                userInfo: [NSLocalizedDescriptionKey: "Server active on \(currentPort). Reload required."]
+            )
+        }
+
+        let newServer = VideoProxyServer(
+            port: targetPort,
+            maxCacheSize: cacheLimit,
+            headOnlyCache: headOnlyCache ?? false
+        )
+
+        do {
+            try newServer.start()
+        } catch {
+            throw NSError(
+                domain: "HlsCache",
+                code: 500,
+                userInfo: [NSLocalizedDescriptionKey: "Port bind failed: \(error.localizedDescription)"]
+            )
+        }
+
+        stateLock.lock()
+        proxyServer = newServer
+        activePort = targetPort
+        stateLock.unlock()
+    }
+
+    /// Light sync method — just builds a URL string.
+    public func convertUrl(url: String, isCacheable: Bool?) throws -> String {
+        if isCacheable == false { return url }
+
+        stateLock.lock()
+        let server = proxyServer
+        let port = activePort
+        stateLock.unlock()
+
+        guard let server = server, server.isRunning else {
+            return url
+        }
+
+        var allowed = CharacterSet.urlQueryAllowed
+        allowed.remove(charactersIn: "&#")
+        guard let encoded = url.addingPercentEncoding(withAllowedCharacters: allowed) else {
+            return url
+        }
+
+        return "http://127.0.0.1:\(port)/proxy?url=\(encoded)"
+    }
+
+    /// Heavy async method — file I/O runs on a background thread via Promise.async.
+    public func clearCache() throws -> Promise<Void> {
+        stateLock.lock()
+        let server = proxyServer
+        stateLock.unlock()
+
+        return Promise.async {
+            if let server = server {
+                server.clearCache()
+            } else {
+                VideoCacheStorage(maxCacheSize: 0).clearAll()
+            }
+        }
+    }
+
+    /// Prefetches an HLS stream into cache. Returns a taskId for cancellation.
+    /// Runs entirely in the background — JS thread returns immediately.
+    public func prefetch(url: String, segmentCount: Double?) throws -> String {
+        guard let parsedURL = URL(string: url) else {
+            throw NSError(
+                domain: "HlsCache",
+                code: 400,
+                userInfo: [NSLocalizedDescriptionKey: "Invalid URL: \(url)"]
+            )
+        }
+
+        stateLock.lock()
+        let server = proxyServer
+        stateLock.unlock()
+
+        // Reuse the server's storage if running, otherwise create a temporary one.
+        let storage = server?.storage ?? VideoCacheStorage(maxCacheSize: 1_073_741_824)
+        let count = segmentCount.map { Int($0) } ?? 3
+
+        return PrefetchManager.shared.prefetch(url: parsedURL, storage: storage, segmentCount: count)
+    }
+
+    public func cancelPrefetch(taskId: String) throws -> Void {
+        PrefetchManager.shared.cancel(taskId: taskId)
+    }
+
+    public func cancelAllPrefetch() throws -> Void {
+        PrefetchManager.shared.cancelAll()
+    }
+}

package/ios/NetworkDownloader.swift

@@ -0,0 +1,220 @@
+import Foundation
+
+/// Delegate protocol for receiving data transfer events from the NetworkDownloader.
+protocol NetworkDownloaderDelegate: AnyObject {
+    func didReceiveResponse(task: NetworkTask, response: URLResponse)
+    func didReceiveData(task: NetworkTask, data: Data)
+    func didComplete(task: NetworkTask, error: Error?)
+}
+
+/// A robust download manager that handles concurrent HTTP range requests with prioritization.
+///
+/// Uses a semaphore to limit concurrent heavy downloads (preventing socket exhaustion)
+/// while allowing manifests and small files to bypass the queue for instant startup.
+final class NetworkDownloader {
+
+    // MARK: - Shared Instance
+
+    static let shared = NetworkDownloader()
+
+    // MARK: - Properties
+
+    /// Actor-isolated task registry — replaces NSLock + Dictionary on the hot didReceiveData path.
+    private let router = SessionRouter()
+
+    /// Limits concurrent heavy segment downloads to prevent OS-level connection refusals.
+    private let semaphore = DispatchSemaphore(value: 32)
+
+    /// Serial queue: ensures FIFO for heavy tasks and prevents thread explosion.
+    private let queue = DispatchQueue(label: "com.videocache.downloader")
+
+    private lazy var session: URLSession = {
+        let config = URLSessionConfiguration.default
+        config.timeoutIntervalForRequest = 60.0
+        config.httpMaximumConnectionsPerHost = 32
+        return URLSession(configuration: config, delegate: router, delegateQueue: nil)
+    }()
+
+    // MARK: - API
+
+    /// Fetches a manifest (m3u8) using the managed session and returns the full data via callback.
+    /// Bypasses the semaphore — manifests are always high-priority.
+    @discardableResult
+    func downloadManifest(url: URL, completion: @escaping (Data?, Error?) -> Void) -> NetworkTask {
+        var request = URLRequest(url: url)
+        request.cachePolicy = .reloadIgnoringLocalCacheData
+
+        let dataTask = session.dataTask(with: request)
+        let task = NetworkTask(dataTask: dataTask, delegate: nil, url: url.absoluteString)
+        task.setManifestCompletion(completion)
+
+        router.register(task: task)
+        dataTask.resume()
+        return task
+    }
+
+    /// Initiates a streaming download for a segment or other resource.
+    func download(url: URL, range: Range<Int>?, delegate: NetworkDownloaderDelegate) -> NetworkTask {
+        var request = URLRequest(url: url)
+        request.cachePolicy = .reloadIgnoringLocalCacheData
+
+        if let range = range {
+            let end = (range.upperBound == Int.max) ? "" : "\(range.upperBound - 1)"
+            request.addValue("bytes=\(range.lowerBound)-\(end)", forHTTPHeaderField: "Range")
+        }
+
+        let dataTask = session.dataTask(with: request)
+        let task = NetworkTask(dataTask: dataTask, delegate: delegate, url: url.absoluteString)
+
+        let urlString = url.absoluteString.lowercased()
+        var isPriority = url.pathExtension.lowercased() == "m3u8"
+                      || urlString.contains(".m3u8")
+                      || urlString.contains("init.mp4")
+        if let r = range, (r.upperBound - r.lowerBound) < 1024 { isPriority = true }
+
+        router.register(task: task)
+
+        if isPriority {
+            dataTask.resume()
+        } else {
+            queue.async {
+                task.setOnComplete { [weak self] in self?.semaphore.signal() }
+                self.semaphore.wait()
+                if task.dataTask.state == .canceling || task.dataTask.state == .completed {
+                    task.finish()
+                    return
+                }
+                dataTask.resume()
+            }
+        }
+
+        return task
+    }
+}
+
+// MARK: - NetworkTask
+
+final class NetworkTask: Hashable {
+
+    let id = UUID()
+    let dataTask: URLSessionDataTask
+    weak var delegate: NetworkDownloaderDelegate?
+    let urlString: String
+
+    private let lock = NSLock()
+    private var onComplete: (() -> Void)?
+
+    /// Accumulator + callback for manifest (full-body) downloads.
+    private var manifestBuffer = Data()
+    private var manifestCompletion: ((Data?, Error?) -> Void)?
+
+    init(dataTask: URLSessionDataTask, delegate: NetworkDownloaderDelegate?, url: String) {
+        self.dataTask = dataTask
+        self.delegate = delegate
+        self.urlString = url
+    }
+
+    func setOnComplete(_ block: @escaping () -> Void) {
+        lock.lock(); defer { lock.unlock() }
+        onComplete = block
+    }
+
+    func setManifestCompletion(_ block: @escaping (Data?, Error?) -> Void) {
+        lock.lock(); defer { lock.unlock() }
+        manifestCompletion = block
+    }
+
+    /// Appends data for manifest accumulation.
+    func appendManifestData(_ data: Data) {
+        lock.lock(); defer { lock.unlock() }
+        manifestBuffer.append(data)
+    }
+
+    /// Fires the manifest completion handler exactly once.
+    func finishManifest(error: Error?) {
+        lock.lock()
+        let completion = manifestCompletion
+        let buffer = manifestBuffer
+        manifestCompletion = nil
+        lock.unlock()
+
+        completion?(error == nil ? buffer : nil, error)
+    }
+
+    func finish() {
+        lock.lock(); defer { lock.unlock() }
+        onComplete?()
+        onComplete = nil
+    }
+
+    func cancel() {
+        dataTask.cancel()
+        finish()
+    }
+
+    static func == (lhs: NetworkTask, rhs: NetworkTask) -> Bool { lhs.id == rhs.id }
+    func hash(into hasher: inout Hasher) { hasher.combine(id) }
+}
+
+// MARK: - SessionRouter
+
+/// URLSession delegate that maps callbacks to NetworkTask instances.
+///
+/// Uses NSLock for thread safety — URLSession delegate methods are called on URLSession's
+/// internal dispatch queue (not a Swift async context), so NSLock is valid here.
+private final class SessionRouter: NSObject, URLSessionDataDelegate {
+
+    private var tasks = [Int: NetworkTask]()
+    private let lock = NSLock()
+
+    func register(task: NetworkTask) {
+        lock.lock()
+        tasks[task.dataTask.taskIdentifier] = task
+        lock.unlock()
+    }
+
+    private func unregister(taskIdentifier: Int) -> NetworkTask? {
+        lock.lock()
+        defer { lock.unlock() }
+        return tasks.removeValue(forKey: taskIdentifier)
+    }
+
+    private func task(for identifier: Int) -> NetworkTask? {
+        lock.lock()
+        defer { lock.unlock() }
+        return tasks[identifier]
+    }
+
+    // MARK: - URLSessionDataDelegate
+
+    func urlSession(
+        _ session: URLSession,
+        dataTask: URLSessionDataTask,
+        didReceive response: URLResponse,
+        completionHandler: @escaping (URLSession.ResponseDisposition) -> Void
+    ) {
+        if let task = task(for: dataTask.taskIdentifier) {
+            task.delegate?.didReceiveResponse(task: task, response: response)
+        }
+        completionHandler(.allow)
+    }
+
+    func urlSession(_ session: URLSession, dataTask: URLSessionDataTask, didReceive data: Data) {
+        guard let task = task(for: dataTask.taskIdentifier) else { return }
+        if task.delegate != nil {
+            task.delegate?.didReceiveData(task: task, data: data)
+        } else {
+            task.appendManifestData(data)
+        }
+    }
+
+    func urlSession(_ session: URLSession, task urlSessionTask: URLSessionTask, didCompleteWithError error: Error?) {
+        guard let networkTask = unregister(taskIdentifier: urlSessionTask.taskIdentifier) else { return }
+        if networkTask.delegate != nil {
+            networkTask.delegate?.didComplete(task: networkTask, error: error)
+        } else {
+            networkTask.finishManifest(error: error)
+        }
+        networkTask.finish()
+    }
+}

package/ios/PrefetchManager.swift

@@ -0,0 +1,235 @@
+import Foundation
+
+/// Manages background prefetch tasks for HLS streams.
+///
+/// Each prefetch task downloads the manifest + first N segments into the disk cache
+/// so they are instantly served from cache when the video player requests them.
+internal final class PrefetchManager {
+
+    static let shared = PrefetchManager()
+
+    private let lock = NSLock()
+    private var activeTasks: [String: PrefetchTask] = [:]
+
+    /// Starts prefetching an HLS stream. Returns a taskId that can be used to cancel.
+    func prefetch(url: URL, storage: VideoCacheStorage, segmentCount: Int) -> String {
+        let taskId = UUID().uuidString
+        let task = PrefetchTask(url: url, storage: storage, segmentCount: segmentCount)
+
+        lock.lock()
+        activeTasks[taskId] = task
+        lock.unlock()
+
+        task.start { [weak self] in
+            self?.lock.lock()
+            self?.activeTasks.removeValue(forKey: taskId)
+            self?.lock.unlock()
+        }
+
+        return taskId
+    }
+
+    func cancel(taskId: String) {
+        lock.lock()
+        let task = activeTasks.removeValue(forKey: taskId)
+        lock.unlock()
+        task?.cancel()
+    }
+
+    func cancelAll() {
+        lock.lock()
+        let tasks = Array(activeTasks.values)
+        activeTasks.removeAll()
+        lock.unlock()
+        tasks.forEach { $0.cancel() }
+    }
+}
+
+// MARK: - PrefetchTask
+
+private final class PrefetchTask {
+
+    private let url: URL
+    private let storage: VideoCacheStorage
+    private let segmentCount: Int
+
+    private let lock = NSLock()
+    private var networkTasks: [NetworkTask] = []
+    private var isCancelled = false
+
+    init(url: URL, storage: VideoCacheStorage, segmentCount: Int) {
+        self.url = url
+        self.storage = storage
+        self.segmentCount = segmentCount
+    }
+
+    func start(onComplete: @escaping () -> Void) {
+        fetchManifest(url: url, onComplete: onComplete)
+    }
+
+    func cancel() {
+        lock.lock()
+        isCancelled = true
+        let tasks = networkTasks
+        networkTasks.removeAll()
+        lock.unlock()
+        tasks.forEach { $0.cancel() }
+    }
+
+    // MARK: - Private
+
+    private func fetchManifest(url: URL, onComplete: @escaping () -> Void) {
+        let task = NetworkDownloader.shared.downloadManifest(url: url) { [weak self] data, error in
+            guard let self = self, !self.isCancelled else { onComplete(); return }
+            guard let data = data, let content = String(data: data, encoding: .utf8) else {
+                onComplete(); return
+            }
+            self.storage.save(data: data, for: url.absoluteString)
+            self.processManifest(content: content, baseURL: url, onComplete: onComplete)
+        }
+        addNetworkTask(task)
+    }
+
+    private func processManifest(content: String, baseURL: URL, onComplete: @escaping () -> Void) {
+        if content.contains("#EXT-X-STREAM-INF") {
+            // Master playlist — cache ALL variant manifests so any quality AVPlayer picks is available.
+            let variantURLs = parseAllVariantURLs(content: content, baseURL: baseURL)
+            guard !variantURLs.isEmpty else { onComplete(); return }
+
+            let group = DispatchGroup()
+            for variantURL in variantURLs {
+                guard !isCancelled else { break }
+                group.enter()
+                fetchManifest(url: variantURL, onComplete: { group.leave() })
+            }
+            group.notify(queue: .global(qos: .background)) { onComplete() }
+        } else {
+            // Media playlist — download init segment (if any) + first N segments.
+            var urls: [URL] = []
+            if let initURL = parseInitSegmentURL(content: content, baseURL: baseURL) {
+                urls.append(initURL)
+            }
+            urls.append(contentsOf: parseSegmentURLs(content: content, baseURL: baseURL))
+            downloadSegments(urls: urls, onComplete: onComplete)
+        }
+    }
+
+    private func downloadSegments(urls: [URL], onComplete: @escaping () -> Void) {
+        guard !urls.isEmpty else { onComplete(); return }
+
+        let group = DispatchGroup()
+
+        for url in urls {
+            guard !isCancelled else { break }
+            if storage.exists(for: url.absoluteString) { continue }
+
+            group.enter()
+            let delegate = SegmentAccumulator(storage: storage, url: url) {
+                group.leave()
+            }
+            let task = NetworkDownloader.shared.download(url: url, range: nil, delegate: delegate)
+            addNetworkTask(task)
+        }
+
+        group.notify(queue: .global(qos: .background)) { [weak self] in
+            _ = self // retain until done
+            onComplete()
+        }
+    }
+
+    private func addNetworkTask(_ task: NetworkTask) {
+        lock.lock()
+        networkTasks.append(task)
+        lock.unlock()
+    }
+
+    // MARK: - HLS Parsing
+
+    /// Returns ALL variant/rendition playlist URLs from a master playlist.
+    /// Caching every variant ensures AVPlayer can pick any quality while offline.
+    private func parseAllVariantURLs(content: String, baseURL: URL) -> [URL] {
+        var urls: [URL] = []
+        let lines = content.components(separatedBy: .newlines)
+        var i = 0
+        while i < lines.count {
+            let line = lines[i].trimmingCharacters(in: .whitespaces)
+            if line.hasPrefix("#EXT-X-STREAM-INF") {
+                let nextIndex = i + 1
+                if nextIndex < lines.count {
+                    let urlLine = lines[nextIndex].trimmingCharacters(in: .whitespaces)
+                    if !urlLine.isEmpty, !urlLine.hasPrefix("#"),
+                       let resolved = URL(string: urlLine, relativeTo: baseURL)?.absoluteURL {
+                        urls.append(resolved)
+                    }
+                }
+            }
+            i += 1
+        }
+        return urls
+    }
+
+    /// Parses the `#EXT-X-MAP` init segment URI from a media playlist.
+    /// fMP4 streams require the init segment for every quality level.
+    private func parseInitSegmentURL(content: String, baseURL: URL) -> URL? {
+        for line in content.components(separatedBy: .newlines) {
+            let trimmed = line.trimmingCharacters(in: .whitespaces)
+            guard trimmed.hasPrefix("#EXT-X-MAP:") else { continue }
+            if let uriStart = trimmed.range(of: "URI=\""),
+               let uriEnd = trimmed.range(of: "\"", range: uriStart.upperBound..<trimmed.endIndex) {
+                let uri = String(trimmed[uriStart.upperBound..<uriEnd.lowerBound])
+                return URL(string: uri, relativeTo: baseURL)?.absoluteURL
+            }
+        }
+        return nil
+    }
+
+    /// Parses up to `segmentCount` media segment URLs from a media playlist.
+    private func parseSegmentURLs(content: String, baseURL: URL) -> [URL] {
+        var urls: [URL] = []
+        for line in content.components(separatedBy: .newlines) {
+            guard urls.count < segmentCount else { break }
+            let trimmed = line.trimmingCharacters(in: .whitespaces)
+            guard !trimmed.isEmpty, !trimmed.hasPrefix("#") else { continue }
+            if let resolved = URL(string: trimmed, relativeTo: baseURL)?.absoluteURL {
+                urls.append(resolved)
+            }
+        }
+        return urls
+    }
+}
+
+// MARK: - SegmentAccumulator
+
+/// Accumulates streaming segment data and saves it to cache on completion.
+private final class SegmentAccumulator: NetworkDownloaderDelegate {
+
+    private let storage: VideoCacheStorage
+    private let url: URL
+    private let onComplete: () -> Void
+    private var buffer = Data()
+    private let lock = NSLock()
+
+    init(storage: VideoCacheStorage, url: URL, onComplete: @escaping () -> Void) {
+        self.storage = storage
+        self.url = url
+        self.onComplete = onComplete
+    }
+
+    func didReceiveResponse(task: NetworkTask, response: URLResponse) {}
+
+    func didReceiveData(task: NetworkTask, data: Data) {
+        lock.lock()
+        buffer.append(data)
+        lock.unlock()
+    }
+
+    func didComplete(task: NetworkTask, error: Error?) {
+        if error == nil {
+            lock.lock()
+            let data = buffer
+            lock.unlock()
+            storage.save(data: data, for: url.absoluteString)
+        }
+        onComplete()
+    }
+}