react-native-hls-cache 0.1.0

package/ios/ClientConnectionHandler.swift

@@ -0,0 +1,234 @@
+import Foundation
+import Network
+
+/// Manages a single active TCP connection from the media player.
+///
+/// This class acts as the intermediary between the client (AVPlayer) and the data source.
+/// It is responsible for parsing the raw HTTP request headers, extracting the requested
+/// byte range and target URL, and streaming the resulting data back to the client socket.
+internal final class ClientConnectionHandler: DataSourceDelegate {
+
+    // MARK: - Properties
+
+    /// Unique identifier for tracing the lifecycle of this connection.
+    let id = UUID().uuidString.prefix(4).description
+
+    /// Delegate to notify the parent server when this connection closes.
+    weak var delegate: ProxyConnectionDelegate?
+
+    /// The TCP connection provided by Network framework.
+    private let connection: NWConnection
+
+    /// Shared video cache storage.
+    private let storage: VideoCacheStorage
+
+    /// The local proxy port used for manifest rewriting.
+    private let port: Int
+
+    /// The current data source responsible for fetching or streaming the requested content.
+    private var dataSource: DataSource?
+
+    /// Buffer to accumulate incoming raw HTTP request bytes.
+    private var buffer = Data()
+
+    /// Guards against concurrent or duplicate calls to `stop()`.
+    private let stopLock = NSLock()
+    private var isStopped = false
+
+    /// Tracks whether HTTP response headers have been sent to the client.
+    /// Used to decide whether a 502 error can still be sent on network failure.
+    private var headersSent = false
+
+    /// Initial segments to cache.
+    /// If 0, all segments are cached.
+    /// If positive, only the first N segments are cached.
+    private let segmentLimit: Int
+
+    // MARK: - Initialization
+
+    /// Initializes a new connection handler.
+    ///
+    /// - Parameters:
+    ///   - connection: The accepted TCP connection.
+    ///   - storage: The shared cache storage manager.
+    ///   - port: The port number of the proxy server.
+    ///   - initialSegmentsToCache: The number of initial segments to cache.
+    init(connection: NWConnection, storage: VideoCacheStorage, port: Int, initialSegmentsToCache: Int) {
+        self.connection = connection
+        self.storage = storage
+        self.port = port
+        self.segmentLimit = initialSegmentsToCache
+    }
+
+    // MARK: - Lifecycle Methods
+
+    /// Opens the socket and begins listening for incoming data.
+    ///
+    /// Starts a background read loop and monitors connection state.
+    func start() {
+        connection.stateUpdateHandler = { [weak self] state in
+            switch state {
+            case .failed, .cancelled:
+                self?.stop()
+            default:
+                break
+            }
+        }
+
+        connection.start(queue: .global(qos: .userInteractive))
+        readHeader()
+    }
+
+    /// Terminates the connection and releases associated resources.
+    ///
+    /// Cancels any active data source and closes the socket if still open.
+    /// This method is idempotent: subsequent calls after the first are no-ops.
+    func stop() {
+        stopLock.lock()
+        guard !isStopped else {
+            stopLock.unlock()
+            return
+        }
+        isStopped = true
+        stopLock.unlock()
+
+        dataSource?.cancel()
+        dataSource = nil
+
+        if connection.state != .cancelled {
+            connection.cancel()
+        }
+
+        delegate?.connectionDidClose(id: id)
+    }
+
+    // MARK: - HTTP Parsing
+
+    /// Reads incoming TCP bytes until a full HTTP header (`\r\n\r\n`) is received.
+    ///
+    /// Accumulates bytes in `buffer` and calls `parseRequest(_:)` once complete.
+    private func readHeader() {
+        connection.receive(minimumIncompleteLength: 1, maximumLength: 65536) { [weak self] data, _, isComplete, error in
+            guard let self = self else { return }
+
+            if let data = data, !data.isEmpty {
+                self.buffer.append(data)
+
+                if let range = self.buffer.range(of: Data([0x0D, 0x0A, 0x0D, 0x0A])) {
+                    let headerData = self.buffer.subdata(in: 0..<range.lowerBound)
+                    self.parseRequest(headerData)
+                    self.buffer.removeAll(keepingCapacity: false)
+                } else {
+                    self.readHeader()
+                }
+            } else if isComplete || error != nil {
+                self.stop()
+            }
+        }
+    }
+
+    /// Parses the raw HTTP header to extract the target URL and optional byte range.
+    ///
+    /// - Parameter data: Raw HTTP header bytes.
+    /// - Returns: None. Initializes a `DataSource` and starts streaming.
+    private func parseRequest(_ data: Data) {
+        guard let string = String(data: data, encoding: .utf8) else { return stop() }
+        let lines = string.components(separatedBy: "\r\n")
+        guard let requestLine = lines.first else { return stop() }
+
+        let parts = requestLine.components(separatedBy: " ")
+        if parts.count < 2 { return stop() }
+
+        let path = parts[1]
+        guard let range = path.range(of: "url=") else { return stop() }
+
+        let urlPart = String(path[range.upperBound...]).components(separatedBy: "&")[0]
+        guard let decoded = urlPart.removingPercentEncoding, let url = URL(string: decoded) else { return stop() }
+
+        var byteRange: Range<Int>? = nil
+        for line in lines {
+            if line.lowercased().hasPrefix("range: bytes=") {
+                let val = line.dropFirst(13)
+                let components = val.components(separatedBy: "-")
+                if let start = Int(components[0]) {
+                    let end = (components.count > 1 && !components[1].isEmpty) ? Int(components[1]) : nil
+                    let safeEnd = (end != nil) ? (end! + 1) : Int.max
+                    byteRange = start..<safeEnd
+                }
+                break
+            }
+        }
+
+        dataSource = DataSource(
+            storage: storage, 
+            url: url, 
+            range: byteRange, 
+            port: port, 
+            segmentLimit: segmentLimit
+        )
+        dataSource?.delegate = self
+        dataSource?.start()
+    }
+
+    // MARK: - DataSourceDelegate Methods
+
+    /// Called when the data source is ready to send HTTP headers.
+    ///
+    /// - Parameters:
+    ///   - headers: HTTP headers (e.g., Content-Type, Content-Length).
+    ///   - status: HTTP status code (200 or 206).
+    func didReceiveHeaders(headers: [String : String], status: Int) {
+        headersSent = true
+
+        let statusText: String
+        switch status {
+        case 200: statusText = "OK"
+        case 206: statusText = "Partial Content"
+        default:  statusText = "OK"
+        }
+
+        var response = "HTTP/1.1 \(status) \(statusText)\r\n"
+        response += "Connection: close\r\n"
+        response += "Access-Control-Allow-Origin: *\r\n"
+
+        for (k, v) in headers {
+            response += "\(k): \(v)\r\n"
+        }
+        response += "\r\n"
+
+        connection.send(content: response.data(using: .utf8), completion: .contentProcessed { _ in })
+    }
+
+    /// Called when a chunk of data is available from the data source.
+    ///
+    /// - Parameter data: Raw data to be streamed to the client.
+    func didReceiveData(data: Data) {
+        connection.send(content: data, completion: .contentProcessed { _ in })
+    }
+
+    /// Called when the data source has finished or failed.
+    ///
+    /// - Parameter error: Optional error if streaming failed.
+    func didComplete(error: Error?) {
+        if error != nil {
+            if !headersSent {
+                // No headers have been sent yet — the connection can still receive a clean
+                // HTTP error. A TCP drop (the previous behaviour) causes AVPlayer to treat
+                // the failure as a connect error rather than an HTTP error, which prevents
+                // it from retrying or showing a useful error state.
+                let response = "HTTP/1.1 502 Bad Gateway\r\nConnection: close\r\nContent-Length: 0\r\n\r\n"
+                connection.send(content: response.data(using: .utf8), completion: .contentProcessed { [weak self] _ in
+                    self?.stop()
+                })
+            } else {
+                // Headers were already sent — we're mid-stream. Just close; the player
+                // will detect the truncated response and handle it.
+                stop()
+            }
+        } else {
+            connection.send(content: nil, contentContext: .defaultStream, isComplete: true, completion: .contentProcessed { [weak self] _ in
+                self?.stop()
+            })
+        }
+    }
+}

package/ios/DataSource.swift

@@ -0,0 +1,394 @@
+import Foundation
+import Network
+
+/// A delegate protocol for receiving data transfer events from the DataSource.
+protocol DataSourceDelegate: AnyObject {
+    
+    /// Called when the source is ready to transmit headers.
+    /// - Parameters:
+    ///   - headers: A dictionary of HTTP headers (e.g., `Content-Length`, `Content-Type`).
+    ///   - status: The HTTP status code (e.g., 200, 206).
+    func didReceiveHeaders(headers: [String: String], status: Int)
+    
+    /// Called when a chunk of data is available for streaming.
+    /// - Parameter data: The raw data chunk.
+    func didReceiveData(data: Data)
+    
+    /// Called when the data transfer is complete or has failed.
+    /// - Parameter error: An optional error if the transfer failed.
+    func didComplete(error: Error?)
+}
+
+/// The logic unit responsible for fulfilling a specific data request.
+///
+/// This class acts as a router that determines whether to serve data from the local disk cache
+/// or fetch it from the network via `NetworkDownloader`. It also handles the rewriting of HLS
+/// manifests to ensure subsequent segment requests are routed through the local proxy.
+internal final class DataSource: NetworkDownloaderDelegate {
+    
+    // MARK: - Properties
+    
+    private let storage: VideoCacheStorage
+    private let url: URL
+    private let range: Range<Int>?
+    private let port: Int
+    
+    weak var delegate: DataSourceDelegate?
+
+    private let dataLock = NSLock()
+    private var networkTask: NetworkTask?
+    private var fileHandle: FileHandle?
+    private var isManifest: Bool
+    private let segmentLimit: Int
+
+    private static let diskQueue = DispatchQueue(label: "com.hlscache.disk", qos: .userInitiated)
+
+    /// Character set used when percent-encoding a URL to embed as a proxy query-parameter value.
+    ///
+    /// `.urlQueryAllowed` keeps `&` and `#` unencoded, which breaks the proxy's own query-string
+    /// parser when the embedded URL contains those characters (e.g. `?token=a&sig=b` would be
+    /// silently truncated to `?token=a`). Removing them forces proper percent-encoding.
+    private static let proxyQueryAllowed: CharacterSet = {
+        var set = CharacterSet.urlQueryAllowed
+        set.remove(charactersIn: "&#")
+        return set
+    }()
+    
+    /// Generates a unique key for the file on disk.
+    ///
+    /// This key appends the byte range to the URL to prevent file collisions in fMP4 streams,
+    /// where the same URL is often used for both initialization and media segments.
+    private var storageKey: String {
+        if let r = range {
+            return "\(url.absoluteString)-\(r.lowerBound)-\(r.upperBound)"
+        }
+        return url.absoluteString
+    }
+    
+    // MARK: - Initialization
+    
+    /// Initializes a new data source request.
+    ///
+    /// - Parameters:
+    ///   - storage: The cache storage manager.
+    ///   - url: The target URL.
+    ///   - range: The requested byte range (optional).
+    ///   - port: The local proxy port (used for manifest rewriting).
+    ///   - segmentLimit: The number of initial segments to cache.
+    init(storage: VideoCacheStorage, url: URL, range: Range<Int>?, port: Int, segmentLimit: Int) {
+        self.storage = storage
+        self.url = url
+        self.range = range
+        self.port = port
+        self.segmentLimit = segmentLimit
+        
+        let urlString = url.absoluteString.lowercased()
+        self.isManifest = url.pathExtension.lowercased().contains("m3u8") || urlString.contains(".m3u8")
+    }
+    
+    // MARK: - Lifecycle
+    
+    /// Begins the data retrieval process.
+    ///
+    /// Checks the disk cache first; if the data is missing, initiates a network download.
+    func start() {
+        if storage.exists(for: storageKey) {
+            if isManifest {
+                serveManifestFromCache()
+            } else {
+                DataSource.diskQueue.async { self.serveFileFromDisk() }
+            }
+            return
+        }
+
+        // Range-keyed file not found — fall back to the full file that prefetch may have
+        // stored without a range suffix. Slice the requested bytes out of it on the fly.
+        if range != nil && !isManifest && storage.exists(for: url.absoluteString) {
+            DataSource.diskQueue.async { self.serveRangeFromFullFile() }
+            return
+        }
+
+        if isManifest {
+            downloadManifest()
+        } else {
+            startStreamDownload()
+        }
+    }
+    
+    /// Cancels any active network tasks or file I/O.
+    func cancel() {
+        dataLock.lock()
+        let task = networkTask
+        networkTask = nil
+        dataLock.unlock()
+
+        task?.cancel()
+        closeFileHandle()
+    }
+
+    private func closeFileHandle() {
+        dataLock.lock()
+        let handle = fileHandle
+        fileHandle = nil
+        dataLock.unlock()
+
+        try? handle?.close()
+    }
+    
+    // MARK: - Disk Path (Cache Hit)
+    
+    private func serveFileFromDisk() {
+        let path = storage.getFilePath(for: storageKey)
+
+        // Memory-map the file: zero-copy, OS handles paging — no read loop needed.
+        guard let data = try? Data(contentsOf: path, options: .mappedIfSafe) else {
+            delegate?.didComplete(error: NSError(domain: "DiskError", code: 500))
+            return
+        }
+
+        let fileSize = data.count
+
+        if fileSize == 0 {
+            let headers = ["Content-Length": "0", "Content-Type": getMimeType(url: url)]
+            delegate?.didReceiveHeaders(headers: headers, status: 200)
+            delegate?.didComplete(error: nil)
+            return
+        }
+
+        var status = 200
+        var headers: [String: String] = [
+            "Content-Type": getMimeType(url: url),
+            "Content-Length": "\(fileSize)",
+            "Accept-Ranges": "bytes"
+        ]
+
+        // When the original request included a Range header, the cached file contains
+        // exactly those bytes. Return 206 + Content-Range so AVPlayer treats it the
+        // same as an online range response — returning 200 here causes AVPlayer to
+        // misinterpret the data boundaries and fail to render the segment offline.
+        if let r = range {
+            status = 206
+            let endByte = r.upperBound == Int.max
+                ? (r.lowerBound + fileSize - 1)
+                : (r.upperBound - 1)
+            headers["Content-Range"] = "bytes \(r.lowerBound)-\(endByte)/*"
+        }
+
+        delegate?.didReceiveHeaders(headers: headers, status: status)
+        delegate?.didReceiveData(data: data)
+        delegate?.didComplete(error: nil)
+    }
+    
+    /// Serves a byte-range slice from a full file that was cached by prefetch (no range suffix).
+    private func serveRangeFromFullFile() {
+        let path = storage.getFilePath(for: url.absoluteString)
+        guard let fullData = try? Data(contentsOf: path, options: .mappedIfSafe),
+              let r = range else {
+            // Full file unreadable — fall through to network.
+            startStreamDownload()
+            return
+        }
+
+        let fileSize = fullData.count
+        let lower = r.lowerBound
+        let upper = r.upperBound == Int.max ? fileSize : min(r.upperBound, fileSize)
+
+        guard lower < fileSize else {
+            delegate?.didComplete(error: NSError(domain: "RangeError", code: 416))
+            return
+        }
+
+        let sliced = Data(fullData[lower..<upper])
+        let headers: [String: String] = [
+            "Content-Type": getMimeType(url: url),
+            "Content-Length": "\(sliced.count)",
+            "Accept-Ranges": "bytes",
+            "Content-Range": "bytes \(lower)-\(upper - 1)/\(fileSize)"
+        ]
+        delegate?.didReceiveHeaders(headers: headers, status: 206)
+        delegate?.didReceiveData(data: sliced)
+        delegate?.didComplete(error: nil)
+    }
+
+    // MARK: - Network Path (Cache Miss)
+    
+    private func startStreamDownload() {
+        let task = NetworkDownloader.shared.download(url: url, range: range, delegate: self)
+        dataLock.lock()
+        networkTask = task
+        dataLock.unlock()
+    }
+    
+    // MARK: - NetworkDownloaderDelegate
+    
+    func didReceiveResponse(task: NetworkTask, response: URLResponse) {
+        if let httpResponse = response as? HTTPURLResponse {
+            if (200...299).contains(httpResponse.statusCode) {
+                let handle = storage.initializeStreamFile(for: storageKey)
+                dataLock.lock()
+                fileHandle = handle
+                dataLock.unlock()
+            }
+            
+            var headers = [String:String]()
+            for (k, v) in httpResponse.allHeaderFields {
+                if let ks = k as? String, let vs = v as? String { headers[ks] = vs }
+            }
+            
+            headers["Content-Type"] = getMimeType(url: url)
+            delegate?.didReceiveHeaders(headers: headers, status: httpResponse.statusCode)
+        }
+    }
+    
+    func didReceiveData(task: NetworkTask, data: Data) {
+        delegate?.didReceiveData(data: data)
+        dataLock.lock()
+        let handle = fileHandle
+        dataLock.unlock()
+        try? handle?.write(contentsOf: data)
+    }
+    
+    func didComplete(task: NetworkTask, error: Error?) {
+        closeFileHandle()
+        
+        if error != nil {
+            if storage.exists(for: storageKey) {
+                storage.delete(for: storageKey)
+            }
+        }
+        
+        delegate?.didComplete(error: error)
+    }
+    
+    // MARK: - Manifest Handling
+    
+    private func serveManifestFromCache() {
+        guard let data = storage.getCachedData(for: storageKey),
+              let content = String(data: data, encoding: .utf8) else {
+            delegate?.didComplete(error: NSError(domain: "CacheError", code: 404))
+            return
+        }
+        sendRewrittenManifest(content)
+    }
+    
+    private func downloadManifest() {
+        // Use the shared managed session (same priority queue as segments, not URLSession.shared).
+        let task = NetworkDownloader.shared.downloadManifest(url: url) { [weak self] data, error in
+            guard let self = self else { return }
+            guard let data = data, let content = String(data: data, encoding: .utf8) else {
+                self.delegate?.didComplete(error: error ?? NSError(domain: "NetError", code: 500))
+                return
+            }
+            self.storage.save(data: data, for: self.storageKey)
+            self.sendRewrittenManifest(content)
+        }
+        dataLock.lock()
+        networkTask = task
+        dataLock.unlock()
+    }
+    
+    private func sendRewrittenManifest(_ content: String) {
+        let rewritten = rewriteManifest(content, originalUrl: url)
+
+        // Encode the rewritten manifest once so we can set an accurate Content-Length.
+        // Without Content-Length AVPlayer must wait for the connection to close to know
+        // the manifest is complete, which adds latency and can cause playback stalls.
+        guard let data = rewritten.data(using: .utf8) else {
+            delegate?.didComplete(error: NSError(domain: "ManifestError", code: 500))
+            return
+        }
+
+        let headers: [String: String] = [
+            "Content-Type": "application/vnd.apple.mpegurl",
+            "Content-Length": "\(data.count)"
+        ]
+        delegate?.didReceiveHeaders(headers: headers, status: 200)
+        delegate?.didReceiveData(data: data)
+        delegate?.didComplete(error: nil)
+    }
+    
+    /// Rewrites the HLS manifest content to route segment requests through the local proxy.
+    /// - Parameters:
+    ///   - content: The raw manifest string.
+    ///   - originalUrl: The original URL of the manifest, used for resolving relative paths.
+    /// - Returns: A modified manifest string with localhost URLs.
+    private func rewriteManifest(_ content: String, originalUrl: URL) -> String {
+        let lines = content.components(separatedBy: .newlines)
+        var rewritten: [String] = []
+        var segmentCount = 0
+        
+        let isMasterPlaylist = content.contains("#EXT-X-STREAM-INF")
+        
+        for line in lines {
+            let trimmed = line.trimmingCharacters(in: .whitespaces)
+            if trimmed.isEmpty {
+                rewritten.append(line)
+                continue
+            }
+            
+            if trimmed.hasPrefix("#") {
+                if trimmed.contains("URI=\"") {
+                    rewritten.append(rewriteHlsTag(line: line, originalUrl: originalUrl))
+                } else {
+                    rewritten.append(line)
+                }
+                continue
+            }
+            
+            if isMasterPlaylist {
+                rewritten.append(rewriteLineToProxy(line: line, originalUrl: originalUrl))
+            } else {
+                if segmentLimit == 0 || segmentCount < segmentLimit {
+                    rewritten.append(rewriteLineToProxy(line: line, originalUrl: originalUrl))
+                } else {
+                    rewritten.append(rewriteLineToDirect(line: line, originalUrl: originalUrl))
+                }
+                segmentCount += 1
+            }
+        }
+        return rewritten.joined(separator: "\n")
+    }
+    
+    private func rewriteLineToProxy(line: String, originalUrl: URL) -> String {
+        if line.hasPrefix("#") { return line }
+
+        let absolute = URL(string: line, relativeTo: originalUrl)?.absoluteString ?? line
+        guard let encoded = absolute.addingPercentEncoding(withAllowedCharacters: DataSource.proxyQueryAllowed) else { return line }
+
+        return "http://127.0.0.1:\(port)/proxy?url=\(encoded)"
+    }
+
+    private func rewriteLineToDirect(line: String, originalUrl: URL) -> String {
+        if line.hasPrefix("#") { return line }
+        return URL(string: line, relativeTo: originalUrl)?.absoluteString ?? line
+    }
+    
+    private func rewriteHlsTag(line: String, originalUrl: URL) -> String {
+        let components = line.components(separatedBy: "URI=\"")
+        if components.count < 2 { return line }
+        
+        let prefix = components[0]
+        let rest = components[1]
+        
+        if let quoteIndex = rest.firstIndex(of: "\"") {
+            let uriPart = String(rest[..<quoteIndex])
+            let suffix = String(rest[rest.index(after: quoteIndex)...])
+            
+            let newUri = rewriteLineToProxy(line: uriPart, originalUrl: originalUrl)
+            return "\(prefix)URI=\"\(newUri)\"\(suffix)"
+        }
+        return line
+    }
+    
+    private func getMimeType(url: URL) -> String {
+        let ext = url.pathExtension.lowercased()
+        switch ext {
+        case "m3u8": return "application/vnd.apple.mpegurl"
+        case "mp4": return "video/mp4"
+        case "m4s": return "video/iso.segment"
+        case "m4a": return "audio/mp4"
+        case "ts": return "video/mp2t"
+        default: return "application/octet-stream"
+        }
+    }
+}