@dvai-bridge/ios-llama-core 4.0.0

package/ios/Sources/DVAILlamaCore/ModelDownloader.swift

@@ -0,0 +1,445 @@
+// Internal/ModelDownloader.swift
+import Foundation
+import CryptoKit
+
+/// Result of `listCachedModels()` — one entry per file in the cache dir.
+public struct CachedModelInfoSwift: Sendable {
+    public let filename: String
+    public let path: String
+    public let bytes: Int64
+    public let sha256: String
+}
+
+/// Resumable, sha256-verified model downloader plus cache management.
+///
+/// Cache directory layout (per spec §9.2):
+///   - default: `<App Support>/<bundle-id>/dvai-models/<filename>`
+///   - test override: any caller-supplied URL (used by unit tests to keep
+///     real App Support clean).
+///
+/// Concurrency: an `actor` so cache-list / cache-delete operations are
+/// serialised. The download path delegates to a private `URLSessionDataDelegate`
+/// (compatible with iOS 14+, unlike the iOS-15 `bytes(for:)` API).
+public actor ModelDownloader {
+    public enum DownloadError: LocalizedError {
+        case checksumMismatch(expected: String, got: String)
+        case httpError(status: Int)
+        case missingApplicationSupport
+        case sha256Required
+        case ioError(String)
+
+        public var errorDescription: String? {
+            switch self {
+            case .checksumMismatch(let expected, let got):
+                return "ChecksumMismatchError: expected \(expected), got \(got)"
+            case .httpError(let status):
+                return "HTTP error \(status)"
+            case .missingApplicationSupport:
+                return "Could not locate Application Support directory"
+            case .sha256Required:
+                return "sha256 is required"
+            case .ioError(let msg):
+                return "I/O error: \(msg)"
+            }
+        }
+    }
+
+    private let cacheDirOverride: URL?
+
+    public init(cacheDirOverride: URL? = nil) {
+        self.cacheDirOverride = cacheDirOverride
+    }
+
+    // MARK: - Cache dir
+
+    /// Resolve and create the cache directory. Returns the directory URL.
+    func cacheDirURL() throws -> URL {
+        if let override = cacheDirOverride {
+            try FileManager.default.createDirectory(at: override, withIntermediateDirectories: true)
+            return override
+        }
+        guard let asd = try? FileManager.default.url(
+            for: .applicationSupportDirectory,
+            in: .userDomainMask,
+            appropriateFor: nil,
+            create: true
+        ) else {
+            throw DownloadError.missingApplicationSupport
+        }
+        let bundleId = Bundle.main.bundleIdentifier ?? "co.deepvoiceai.dvai-bridge"
+        let dir = asd.appendingPathComponent(bundleId).appendingPathComponent("dvai-models")
+        try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+        return dir
+    }
+
+    public func cacheDirPath() throws -> String {
+        try cacheDirURL().path
+    }
+
+    // MARK: - List / delete
+
+    /// Enumerate files in the cache dir (skipping `.partial` and dotfiles),
+    /// sha256 each, return one entry per file.
+    public func listCachedModels() throws -> [CachedModelInfoSwift] {
+        let dir = try cacheDirURL()
+        let fm = FileManager.default
+        let names = (try? fm.contentsOfDirectory(atPath: dir.path)) ?? []
+        var out: [CachedModelInfoSwift] = []
+        for name in names {
+            if name.hasPrefix(".") || name.hasSuffix(".partial") { continue }
+            let url = dir.appendingPathComponent(name)
+            var isDir: ObjCBool = false
+            if !fm.fileExists(atPath: url.path, isDirectory: &isDir) || isDir.boolValue { continue }
+            let attrs = try fm.attributesOfItem(atPath: url.path)
+            let bytes = (attrs[.size] as? NSNumber)?.int64Value ?? 0
+            let sha = try Self.sha256OfFile(at: url)
+            out.append(CachedModelInfoSwift(
+                filename: name,
+                path: url.path,
+                bytes: bytes,
+                sha256: sha
+            ))
+        }
+        return out
+    }
+
+    public func deleteCachedModel(filename: String) throws {
+        let dir = try cacheDirURL()
+        let url = dir.appendingPathComponent(filename)
+        if FileManager.default.fileExists(atPath: url.path) {
+            try FileManager.default.removeItem(at: url)
+        }
+        let partial = dir.appendingPathComponent("\(filename).partial")
+        if FileManager.default.fileExists(atPath: partial.path) {
+            try? FileManager.default.removeItem(at: partial)
+        }
+    }
+
+    // MARK: - Download
+
+    /// Download `url` into `<cacheDir>/<destFilename>`, resumable + sha256-verified.
+    ///
+    /// - Parameters:
+    ///   - expectedSha256: lowercase-hex digest the final file MUST match.
+    ///   - onProgress: bytesDone, optional bytesTotal. Caller already throttles
+    ///     ~10/sec internally; do not throttle again here.
+    /// - Returns: (final-path, cached). `cached: true` means the file was already
+    ///   present with a matching hash and no network request was made.
+    public func downloadModel(
+        url: URL,
+        expectedSha256: String,
+        destFilename: String,
+        headers: [String: String],
+        onProgress: @Sendable @escaping (Int64, Int64?) -> Void
+    ) async throws -> (path: String, cached: Bool) {
+        guard !expectedSha256.isEmpty else { throw DownloadError.sha256Required }
+        let expected = expectedSha256.lowercased()
+
+        let dir = try cacheDirURL()
+        let final = dir.appendingPathComponent(destFilename)
+        let partial = dir.appendingPathComponent("\(destFilename).partial")
+        let fm = FileManager.default
+
+        // Step 2: cache hit check.
+        if fm.fileExists(atPath: final.path) {
+            let existing = try Self.sha256OfFile(at: final)
+            if existing == expected {
+                Self.applyNoBackupAttribute(final)
+                return (final.path, true)
+            }
+            // Step 3: mismatch → delete and fall through.
+            try? fm.removeItem(at: final)
+        }
+
+        // Step 4: stream download (resumable).
+        try await StreamingDownload.run(
+            url: url,
+            partial: partial,
+            headers: headers,
+            onProgress: onProgress
+        ).verifyAndFinalize(
+            final: final,
+            partial: partial,
+            expectedSha256: expected
+        )
+
+        // Step 7: iOS no-backup attribute.
+        Self.applyNoBackupAttribute(final)
+
+        return (final.path, false)
+    }
+
+    // MARK: - Helpers
+
+    /// Compute SHA-256 of a file lazily by streaming 64 KiB chunks.
+    static func sha256OfFile(at url: URL) throws -> String {
+        var hasher = SHA256()
+        let handle = try FileHandle(forReadingFrom: url)
+        defer { try? handle.close() }
+        while true {
+            let chunk = try handle.read(upToCount: 64 * 1024) ?? Data()
+            if chunk.isEmpty { break }
+            hasher.update(data: chunk)
+        }
+        let digest = hasher.finalize()
+        return digest.map { String(format: "%02x", $0) }.joined()
+    }
+
+    /// Set `URLResourceKey.isExcludedFromBackupKey = true`. Best-effort —
+    /// failure here is non-fatal (e.g. unit tests in tmp dirs).
+    static func applyNoBackupAttribute(_ url: URL) {
+        var mutableURL = url
+        var values = URLResourceValues()
+        values.isExcludedFromBackup = true
+        try? mutableURL.setResourceValues(values)
+    }
+}
+
+// MARK: - Streaming download (URLSessionDataDelegate, iOS 14+)
+
+/// Result of a streaming download: the running SHA-256 digest as hex.
+struct StreamingDownloadResult {
+    let gotHex: String
+
+    /// Verify hash, atomic-rename, and clean up on mismatch.
+    func verifyAndFinalize(final: URL, partial: URL, expectedSha256: String) throws {
+        let fm = FileManager.default
+        if gotHex != expectedSha256 {
+            try? fm.removeItem(at: partial)
+            try? fm.removeItem(at: final)
+            throw ModelDownloader.DownloadError.checksumMismatch(
+                expected: expectedSha256,
+                got: gotHex
+            )
+        }
+        if fm.fileExists(atPath: final.path) {
+            try? fm.removeItem(at: final)
+        }
+        try fm.moveItem(at: partial, to: final)
+    }
+}
+
+/// Wraps `URLSessionDataDelegate` with a continuation so the streaming
+/// download can be `await`ed. Handles:
+///  - Replaying existing `.partial` bytes through SHA-256 (resume).
+///  - Range request + 200/206 handling (server-honoured / not-honoured).
+///  - 64 KiB-buffered hashing + appending.
+///  - Progress debounced to ~10/sec.
+final class StreamingDownload: NSObject, URLSessionDataDelegate, @unchecked Sendable {
+    private var hasher = SHA256()
+    private var written: Int64 = 0
+    private var totalBytes: Int64?
+    private var writeHandle: FileHandle?
+    private var lastEmit: Date = .distantPast
+    private let debounceInterval: TimeInterval = 0.1
+
+    private let partial: URL
+    private let onProgress: @Sendable (Int64, Int64?) -> Void
+    private var continuation: CheckedContinuation<StreamingDownloadResult, Error>?
+    private var didFinish = false
+
+    /// Whether we asked the server for a Range. If true and the server replies
+    /// 200 (full body), reset hash + truncate file before consuming data.
+    private var requestedRange = false
+    private var serverWillSendFullBody = false
+
+    private init(
+        partial: URL,
+        onProgress: @Sendable @escaping (Int64, Int64?) -> Void
+    ) {
+        self.partial = partial
+        self.onProgress = onProgress
+    }
+
+    /// Entry point. Replays existing `.partial`, performs the download,
+    /// returns the final hex digest on success.
+    static func run(
+        url: URL,
+        partial: URL,
+        headers: [String: String],
+        onProgress: @Sendable @escaping (Int64, Int64?) -> Void
+    ) async throws -> StreamingDownloadResult {
+        let runner = StreamingDownload(partial: partial, onProgress: onProgress)
+        try runner.replayPartial()
+
+        // Parity with Android: if `.partial` is larger than the remote resource,
+        // a Range request would yield 416 Range Not Satisfiable (opaque to the
+        // caller). HEAD-probe the Content-Length and discard an oversized
+        // partial before issuing the real GET. Any HEAD failure is non-fatal —
+        // we just skip the optimisation and let the GET path proceed.
+        if runner.written > 0 {
+            if let remoteLength = await Self.probeContentLength(url: url, headers: headers),
+               remoteLength >= 0,
+               runner.written > remoteLength {
+                try? FileManager.default.removeItem(at: partial)
+                runner.hasher = SHA256()
+                runner.written = 0
+            }
+        }
+
+        var request = URLRequest(url: url)
+        for (k, v) in headers {
+            request.setValue(v, forHTTPHeaderField: k)
+        }
+        if runner.written > 0 {
+            request.setValue("bytes=\(runner.written)-", forHTTPHeaderField: "Range")
+            runner.requestedRange = true
+        }
+
+        let session = URLSession(
+            configuration: .default,
+            delegate: runner,
+            delegateQueue: nil  // serial OperationQueue created internally
+        )
+        defer { session.finishTasksAndInvalidate() }
+
+        return try await withCheckedThrowingContinuation { cont in
+            runner.continuation = cont
+            let task = session.dataTask(with: request)
+            task.resume()
+        }
+    }
+
+    /// HEAD-probe the URL to learn `Content-Length`. Returns nil on any
+    /// failure (network error, non-2xx, missing/invalid header). Headers are
+    /// forwarded so authenticated endpoints work.
+    private static func probeContentLength(url: URL, headers: [String: String]) async -> Int64? {
+        var request = URLRequest(url: url)
+        request.httpMethod = "HEAD"
+        for (k, v) in headers {
+            request.setValue(v, forHTTPHeaderField: k)
+        }
+        do {
+            let (_, response) = try await URLSession.shared.data(for: request)
+            guard let http = response as? HTTPURLResponse,
+                  (200...299).contains(http.statusCode) else {
+                return nil
+            }
+            // expectedContentLength uses Content-Length when present (-1 if unknown).
+            let len = http.expectedContentLength
+            return len >= 0 ? len : nil
+        } catch {
+            return nil
+        }
+    }
+
+    /// Replay any existing .partial bytes through the hash so we can resume.
+    private func replayPartial() throws {
+        let fm = FileManager.default
+        guard fm.fileExists(atPath: partial.path) else { return }
+        let attrs = try fm.attributesOfItem(atPath: partial.path)
+        let size = (attrs[.size] as? NSNumber)?.int64Value ?? 0
+        if size <= 0 { return }
+        let handle = try FileHandle(forReadingFrom: partial)
+        defer { try? handle.close() }
+        while true {
+            let chunk = try handle.read(upToCount: 64 * 1024) ?? Data()
+            if chunk.isEmpty { break }
+            hasher.update(data: chunk)
+            written += Int64(chunk.count)
+        }
+    }
+
+    // MARK: - URLSessionDataDelegate
+
+    func urlSession(
+        _ session: URLSession,
+        dataTask: URLSessionDataTask,
+        didReceive response: URLResponse,
+        completionHandler: @escaping (URLSession.ResponseDisposition) -> Void
+    ) {
+        guard let http = response as? HTTPURLResponse else {
+            finish(with: .failure(ModelDownloader.DownloadError.httpError(status: -1)))
+            completionHandler(.cancel)
+            return
+        }
+        if !(200...206).contains(http.statusCode) {
+            finish(with: .failure(ModelDownloader.DownloadError.httpError(status: http.statusCode)))
+            completionHandler(.cancel)
+            return
+        }
+
+        let fm = FileManager.default
+
+        // If we asked for a Range and got 200 → server didn't honour it,
+        // restart hash + truncate file.
+        if requestedRange && http.statusCode == 200 {
+            hasher = SHA256()
+            written = 0
+            serverWillSendFullBody = true
+            try? fm.removeItem(at: partial)
+        }
+
+        let contentLength = http.expectedContentLength  // -1 if unknown
+        if contentLength >= 0 {
+            totalBytes = written + contentLength
+        }
+
+        // Open partial for write at current offset.
+        if !fm.fileExists(atPath: partial.path) {
+            fm.createFile(atPath: partial.path, contents: nil)
+        }
+        do {
+            let h = try FileHandle(forWritingTo: partial)
+            try h.seek(toOffset: UInt64(written))
+            writeHandle = h
+        } catch {
+            finish(with: .failure(error))
+            completionHandler(.cancel)
+            return
+        }
+
+        // Initial 0% emit so callers see we've started.
+        onProgress(written, totalBytes)
+        lastEmit = Date()
+
+        completionHandler(.allow)
+    }
+
+    func urlSession(
+        _ session: URLSession,
+        dataTask: URLSessionDataTask,
+        didReceive data: Data
+    ) {
+        guard let h = writeHandle else { return }
+        do {
+            try h.write(contentsOf: data)
+        } catch {
+            finish(with: .failure(error))
+            return
+        }
+        hasher.update(data: data)
+        written += Int64(data.count)
+        let now = Date()
+        if now.timeIntervalSince(lastEmit) >= debounceInterval {
+            onProgress(written, totalBytes)
+            lastEmit = now
+        }
+    }
+
+    func urlSession(
+        _ session: URLSession,
+        task: URLSessionTask,
+        didCompleteWithError error: Error?
+    ) {
+        try? writeHandle?.close()
+        writeHandle = nil
+        if let error = error {
+            finish(with: .failure(error))
+            return
+        }
+        // Final progress emit.
+        onProgress(written, totalBytes)
+        let digest = hasher.finalize()
+        let gotHex = digest.map { String(format: "%02x", $0) }.joined()
+        finish(with: .success(StreamingDownloadResult(gotHex: gotHex)))
+    }
+
+    private func finish(with result: Result<StreamingDownloadResult, Error>) {
+        guard !didFinish else { return }
+        didFinish = true
+        let cont = continuation
+        continuation = nil
+        cont?.resume(with: result)
+    }
+}

package/ios/Sources/DVAILlamaCore/PluginState.swift

@@ -0,0 +1,158 @@
+// Internal/PluginState.swift
+import Foundation
+#if !COCOAPODS
+import DVAILlamaCoreObjC
+#endif
+#if !COCOAPODS
+import DVAISharedCore
+#endif
+
+/// Owns the running state of the capacitor-llama plugin: the model bridge,
+/// the HTTP server, and the model metadata. All access is serialised through
+/// the actor isolation.
+public actor PluginState {
+    private var server: HttpServer?
+    private var bridge: LlamaCppBridge?
+    private(set) var modelId: String = ""
+    private(set) var isRunning: Bool = false
+    private(set) var baseUrl: String?
+    private(set) var port: Int?
+
+    public init() {}
+
+    /// Start the plugin: load model, bind server, install routes.
+    /// - Returns dictionary suitable for Capacitor's `call.resolve(...)`.
+    public func start(opts: [String: Any]) async throws -> [String: Any] {
+        if isRunning { try await stopInternal() }
+
+        guard let modelPath = opts["modelPath"] as? String, !modelPath.isEmpty else {
+            throw NSError(
+                domain: "DVAIBridgeLlama",
+                code: 400,
+                userInfo: [NSLocalizedDescriptionKey: "modelPath is required for llama backend"]
+            )
+        }
+
+        let mmprojPath = opts["mmprojPath"] as? String
+        let chatTemplate = opts["chatTemplate"] as? String
+        let gpuLayers = opts["gpuLayers"] as? Int ?? 99
+        let contextSize = opts["contextSize"] as? Int ?? 2048
+        let threads = opts["threads"] as? Int ?? 4
+        let embeddingMode = opts["embeddingMode"] as? Bool ?? false
+        let httpBasePort = opts["httpBasePort"] as? Int ?? 38883
+        let httpMaxPortAttempts = opts["httpMaxPortAttempts"] as? Int ?? 16
+        let corsRaw = opts["corsOrigin"]
+        let corsConfig = parseCors(corsRaw)
+
+        // Load model via the ObjC++ bridge (real llama.cpp under the hood).
+        let bridge = LlamaCppBridge()
+        try bridge.loadModel(
+            atPath: modelPath,
+            mmprojPath: mmprojPath,
+            gpuLayers: Int32(gpuLayers),
+            contextSize: Int32(contextSize),
+            threads: Int32(threads),
+            embeddingMode: embeddingMode
+        )
+
+        // Phase 2A Pass 2: load mmproj (if provided) so multimodal handlers
+        // can light up. A failed mmproj load is fatal for this start() call —
+        // the caller asked for a multimodal model and we couldn't deliver.
+        if let mmprojPath = mmprojPath, !mmprojPath.isEmpty {
+            do {
+                try bridge.loadMmproj(atPath: mmprojPath)
+            } catch {
+                bridge.unload()
+                throw error
+            }
+        }
+        let mmprojLoaded = bridge.isMmprojLoaded
+        // Audio encoder support implies mmproj is loaded AND mtmd reports
+        // an audio encoder is present in the projector.
+        let modelHasAudioEncoder = mmprojLoaded && bridge.hasAudioEncoder()
+
+        // Build handlers + context first; Hummingbird requires routes
+        // to be registered at Application construction time, so the
+        // installRoutes → tryBind order is mandatory. Phase 2A Pass 2:
+        // real flags mirrored from the bridge state. embeddingMode
+        // comes straight from the start opts so /v1/embeddings can
+        // short-circuit when off. chatTemplate is an optional
+        // Jinja-compatible override; nil/empty falls through to the
+        // model's bundled `tokenizer.chat_template`.
+        let handlers = LlamaHandlers(
+            bridge: bridge,
+            modelId: modelPath,
+            mmprojLoaded: mmprojLoaded,
+            modelHasAudioEncoder: modelHasAudioEncoder,
+            embeddingMode: embeddingMode,
+            chatTemplate: chatTemplate
+        )
+        let ctx = HandlerContext(modelId: modelPath, backendName: "llama")
+        let server = HttpServer()
+        await server.installRoutes(handlers: handlers, ctx: ctx, corsConfig: corsConfig)
+
+        // Bind server (with port-fallback). If bind fails, release the
+        // bridge so the loaded llama context doesn't leak until next
+        // start().
+        let port: Int
+        do {
+            port = try await server.tryBind(
+                basePort: httpBasePort,
+                maxAttempts: httpMaxPortAttempts,
+                host: "127.0.0.1"
+            )
+        } catch {
+            bridge.unload()
+            throw error
+        }
+
+        self.bridge = bridge
+        self.server = server
+        self.modelId = modelPath
+        self.port = port
+        self.baseUrl = "http://127.0.0.1:\(port)/v1"
+        self.isRunning = true
+
+        return [
+            "baseUrl": self.baseUrl!,
+            "port": port,
+            "backend": "llama",
+            "modelId": modelPath,
+        ]
+    }
+
+    /// Stop the plugin: release model, stop server.
+    public func stop() async throws {
+        try await stopInternal()
+    }
+
+    private func stopInternal() async throws {
+        await server?.stop()
+        bridge?.unload()
+        server = nil
+        bridge = nil
+        modelId = ""
+        baseUrl = nil
+        port = nil
+        isRunning = false
+    }
+
+    /// Snapshot of the current running state, suitable for Capacitor `call.resolve(...)`.
+    public func statusInfo() -> [String: Any] {
+        var dict: [String: Any] = ["running": isRunning]
+        if let baseUrl = baseUrl { dict["baseUrl"] = baseUrl }
+        if isRunning { dict["backend"] = "llama" }
+        return dict
+    }
+
+    /// Parse the CORS option from the start opts dict.
+    private func parseCors(_ raw: Any?) -> CORSConfig {
+        if let s = raw as? String {
+            return s == "*" ? .wildcard : .exact(s)
+        }
+        if let arr = raw as? [String] {
+            return .allowlist(arr)
+        }
+        return .wildcard
+    }
+}