catalyst-core 1.0.0 → 1.0.1-canary.1

package/dist/native/iosnativeWebView/CoreLogic/Sources/CatalystCoreLogic/Utils/FrameworkServerUtils.swift

@@ -102,10 +102,10 @@ public class FrameworkServerUtils {
 
     // Server state
     private var listener: NWListener?
-    private var serverPort: UInt16 = 0
-    private var sessionId: String = ""
-    private var isServerRunning: Bool = false
-    private var isHTTPS: Bool = false
+    var serverPort: UInt16 = 0
+    var sessionId: String = ""
+    var isServerRunning: Bool = false
+    var isHTTPS: Bool = false
 
     // Connection management
     private var activeConnections: Set<ConnectionWrapper> = []
@@ -114,11 +114,11 @@ public class FrameworkServerUtils {
     private let connectionTimeoutSeconds: TimeInterval = CatalystConstants.NetworkServer.connectionTimeout
 
     // CORS configuration - store the base URL from WebView
-    private var allowedOrigin: String = "*"
+    var allowedOrigin: String = "*"
 
     // File management
-    private var servedFiles: [String: ServedFile] = [:]
-    private let fileQueue = DispatchQueue(label: "framework.server.files", attributes: .concurrent)
+    var servedFiles: [String: ServedFile] = [:]
+    let fileQueue = DispatchQueue(label: "framework.server.files", attributes: .concurrent)
 
     // Cache directory
     private var cacheDirectory: URL?
@@ -126,6 +126,21 @@ public class FrameworkServerUtils {
     // Cleanup timer
     private var cleanupTimer: Timer?
 
+    // Native AI — supplier is set by the AI engine (catalyst-ai) before POST /ai/stream is called.
+    // Kotlin equivalent: nativeAiSupplier / nativeSystemPrompt in FrameworkServerUtils.kt.
+    var nativeAiSupplier: NativeAISupplier?
+    var nativeSystemPrompt: String = ""
+    let aiLock = NSLock()
+
+    // Requests whose headers/body arrive across several reads, keyed by connection.
+    var pendingRequests: [ObjectIdentifier: Data] = [:]
+    // In-flight AI stream tasks, cancelled when the client goes away.
+    var aiStreamTasks: [ObjectIdentifier: Task<Void, Never>] = [:]
+    let requestStateLock = NSLock()
+
+    static let maxHeaderBytes = 16 * 1024
+    static let maxBodyBytes = 1024 * 1024
+
     private init() {}
 
     // MARK: - Public API
@@ -332,20 +347,35 @@ public class FrameworkServerUtils {
         return isServerRunning
     }
 
+    /**
+     * Number of client connections currently tracked by the server.
+     * Internal so tests can wait on connection lifecycle events instead of sleeping.
+     */
+    func activeConnectionCount() -> Int {
+        return connectionQueue.sync { activeConnections.count }
+    }
+
     /**
      * Get server port
      */
-    func getServerPort() -> UInt16 {
+    public func getServerPort() -> UInt16 {
         return serverPort
     }
 
     /**
      * Get current session ID
      */
-    func getSessionId() -> String {
+    public func getSessionId() -> String {
         return sessionId
     }
 
+    /// Stream and generate connections outlive the default per-connection timeout (slow on-device decoding).
+    func cancelConnectionTimeout(for connection: NWConnection) {
+        connectionQueue.sync {
+            activeConnections.first { $0.connection === connection }?.cancelTimeout()
+        }
+    }
+
     // MARK: - Private Implementation
 
     /**
@@ -529,28 +559,35 @@ public class FrameworkServerUtils {
         let port = NWEndpoint.Port(integerLiteral: serverPort)
         // parameters.requiredLocalEndpoint = .hostPort(host: host, port: port)
 
-        listener = try NWListener(using: parameters, on: port)
+        let newListener = try NWListener(using: parameters, on: port)
+        listener = newListener
 
-        listener?.newConnectionHandler = { [weak self] connection in
+        newListener.newConnectionHandler = { [weak self] connection in
             self?.handleNewConnection(connection)
         }
 
-        listener?.stateUpdateHandler = { [weak self] state in
+        newListener.stateUpdateHandler = { [weak self, weak newListener] state in
+            // NWListener delivers state changes asynchronously, so a cancelled
+            // or failed listener can report after stopServer() -> startServer()
+            // has already installed a replacement. Only the current listener
+            // may flip isServerRunning; a stale callback would otherwise mark a
+            // healthy new server as stopped.
+            let isCurrent = { self?.listener === newListener }
             switch state {
             case .ready:
                 logger.debug("NW server ready on port \(self?.serverPort ?? 0)")
             case .failed(let error):
                 logger.error("NW server failed: \(error.localizedDescription)")
-                self?.isServerRunning = false
+                if isCurrent() { self?.isServerRunning = false }
             case .cancelled:
                 logger.debug("NW server cancelled")
-                self?.isServerRunning = false
+                if isCurrent() { self?.isServerRunning = false }
             default:
                 break
             }
         }
 
-        listener?.start(queue: .global(qos: .utility))
+        newListener.start(queue: .global(qos: .utility))
     }
 
     private func handleNewConnection(_ connection: NWConnection) {
@@ -566,102 +603,73 @@ public class FrameworkServerUtils {
             let wrapper = ConnectionWrapper(connection: connection, timeout: self.connectionTimeoutSeconds)
             self.activeConnections.insert(wrapper)
 
-            connection.stateUpdateHandler = { [weak self, weak wrapper] state in
-                switch state {
-                case .ready:
-                    self?.receiveHTTPRequest(on: connection)
-                case .failed(let error):
-                    logger.debug("Connection failed: \(error.localizedDescription)")
-                    if let wrapper = wrapper {
-                        self?.removeConnection(wrapper)
-                    }
-                    connection.cancel()
-                case .cancelled:
-                    logger.debug("Connection cancelled")
-                    if let wrapper = wrapper {
-                        self?.removeConnection(wrapper)
-                    }
-                default:
-                    break
-                }
+            connection.stateUpdateHandler = { [weak self] state in
+                self?.handleConnectionStateChange(state, on: connection)
             }
 
             connection.start(queue: .global(qos: .utility))
         }
     }
 
-    private func removeConnection(_ wrapper: ConnectionWrapper) {
-        connectionQueue.sync {
-            self.activeConnections.remove(wrapper)
-            wrapper.cancelTimeout()
+    /// Reacts to a client connection's state change. Internal (not private) so
+    /// tests can drive the failed/cancelled paths directly: which one Network.framework
+    /// reports for a dropped client is timing-dependent, so real sockets cannot
+    /// exercise them reliably.
+    func handleConnectionStateChange(_ state: NWConnection.State, on connection: NWConnection) {
+        switch state {
+        case .ready:
+            receiveHTTPRequest(on: connection)
+        case .failed(let error):
+            logger.debug("Connection failed: \(error.localizedDescription)")
+            cancelAIStream(for: connection)
+            discardPendingRequest(for: connection)
+            removeTrackedConnection(for: connection)
+            connection.cancel()
+        case .cancelled:
+            logger.debug("Connection cancelled")
+            cancelAIStream(for: connection)
+            discardPendingRequest(for: connection)
+            removeTrackedConnection(for: connection)
+        default:
+            break
         }
     }
 
-    private func receiveHTTPRequest(on connection: NWConnection) {
-        connection.receive(minimumIncompleteLength: 1, maximumLength: 8192) { [weak self] data, _, isComplete, error in
-
-            if let error = error {
-                logger.error("Error receiving request: \(error.localizedDescription)")
-                connection.cancel()
-                return
-            }
-
-            guard let data = data, let requestString = String(data: data, encoding: .utf8) else {
-                self?.sendHTTPResponse(on: connection, statusCode: CatalystConstants.ErrorCodes.badRequest, body: "Bad Request")
-                return
-            }
-
-            self?.processHTTPRequest(requestString, on: connection)
-
-            if isComplete {
-                connection.cancel()
-            }
-        }
+    /// Internal for the same reason as handleConnectionStateChange.
+    func handleReceiveError(_ error: NWError, on connection: NWConnection) {
+        logger.error("Error receiving request: \(error.localizedDescription)")
+        connection.cancel()
     }
 
-    private func processHTTPRequest(_ requestString: String, on connection: NWConnection) {
-        let lines = requestString.components(separatedBy: "\r\n")
-        guard let requestLine = lines.first else {
-            sendHTTPResponse(on: connection, statusCode: CatalystConstants.ErrorCodes.badRequest, body: "Bad Request")
-            return
+    /// Internal for the same reason as handleConnectionStateChange.
+    func handleSendCompletion(_ error: NWError?, on connection: NWConnection) {
+        if let error = error {
+            logger.debug("Error sending response: \(error.localizedDescription)")
         }
+        connection.cancel()
+    }
 
-        let components = requestLine.components(separatedBy: " ")
-        guard components.count >= 2, components[0] == "GET" else {
-            sendHTTPResponse(on: connection, statusCode: 405, body: "Method Not Allowed")
-            return
+    private func removeTrackedConnection(for connection: NWConnection) {
+        let wrapper = connectionQueue.sync { activeConnections.first { $0.connection === connection } }
+        if let wrapper = wrapper {
+            removeConnection(wrapper)
         }
+    }
 
-        let path = components[1]
-
-        // Handle status endpoint
-        if path == "/framework-\(self.sessionId)/status" {
-            fileQueue.sync {
-                let statusResponse = """
-                {
-                    "status": "running",
-                    "sessionId": "\(self.sessionId)",
-                    "port": \(self.serverPort),
-                    "servedFiles": \(self.servedFiles.count)
-                }
-                """
-                sendHTTPResponse(on: connection, statusCode: 200, body: statusResponse, contentType: "application/json")
-            }
-            return
+    private func removeConnection(_ wrapper: ConnectionWrapper) {
+        connectionQueue.sync {
+            self.activeConnections.remove(wrapper)
+            wrapper.cancelTimeout()
         }
+    }
 
-        // Handle file requests
-        if path.hasPrefix("/framework-\(self.sessionId)/file-") {
-            let fileId = String(path.dropFirst("/framework-\(self.sessionId)/file-".count))
-            serveFile(fileId: fileId, on: connection)
-            return
+    func receiveHTTPRequest(on connection: NWConnection) {
+        connection.receive(minimumIncompleteLength: 1, maximumLength: 8192) { [weak self] data, _, isComplete, error in
+            self?.handleReceivedData(data, isComplete: isComplete, error: error, on: connection)
         }
-
-        // Invalid route
-        sendHTTPResponse(on: connection, statusCode: CatalystConstants.ErrorCodes.fileNotFound, body: "Not Found")
     }
 
-    private func serveFile(fileId: String, on connection: NWConnection) {
+    func serveFile(fileId: String, on connection: NWConnection) {
         fileQueue.sync {
             guard let servedFile = self.servedFiles[fileId] else {
                 logger.warning("File not found for fileId: \(fileId)")
@@ -706,7 +714,7 @@ public class FrameworkServerUtils {
 
         // Add CORS headers
         response += "Access-Control-Allow-Origin: \(allowedOrigin)\r\n"
-        response += "Access-Control-Allow-Methods: GET, OPTIONS\r\n"
+        response += "Access-Control-Allow-Methods: GET, POST, OPTIONS\r\n"
         response += "Access-Control-Allow-Headers: *\r\n"
 
         // Add headers
@@ -771,18 +779,18 @@ public class FrameworkServerUtils {
         })
     }
 
-    private func sendHTTPResponse(on connection: NWConnection, statusCode: Int, body: String, contentType: String = "text/plain") {
+    func sendHTTPResponse(on connection: NWConnection, statusCode: Int, body: String, contentType: String = "text/plain") {
         let bodyData = body.data(using: .utf8) ?? Data()
         sendHTTPResponse(on: connection, statusCode: statusCode, body: bodyData, headers: ["Content-Type": contentType])
     }
 
-    private func sendHTTPResponse(on connection: NWConnection, statusCode: Int, body: Data, headers: [String: String] = [:]) {
+    func sendHTTPResponse(on connection: NWConnection, statusCode: Int, body: Data, headers: [String: String] = [:]) {
         let statusText = HTTPURLResponse.localizedString(forStatusCode: statusCode)
         var response = "HTTP/1.1 \(statusCode) \(statusText)\r\n"
 
         // Add CORS headers
         response += "Access-Control-Allow-Origin: \(allowedOrigin)\r\n"
-        response += "Access-Control-Allow-Methods: GET, OPTIONS\r\n"
+        response += "Access-Control-Allow-Methods: GET, POST, OPTIONS\r\n"
         response += "Access-Control-Allow-Headers: *\r\n"
 
         // Add default headers
@@ -803,11 +811,8 @@ public class FrameworkServerUtils {
         }
         let responseData = responseHeaderData + body
 
-        connection.send(content: responseData, completion: .contentProcessed { error in
-            if let error = error {
-                logger.debug("Error sending response: \(error.localizedDescription)")
-            }
-            connection.cancel()
+        connection.send(content: responseData, completion: .contentProcessed { [weak self] error in
+            self?.handleSendCompletion(error, on: connection)
         })
     }
 

package/dist/native/iosnativeWebView/CoreLogic/Sources/CatalystCoreLogic/Utils/NativeAI.swift

@@ -0,0 +1,76 @@
+//
+//  NativeAI.swift
+//  iosnativeWebView
+//
+//  Types shared between the framework server's native-AI routes and the AI
+//  engine that catalyst-ai plugs in. Mirrors the Kotlin contract in
+//  FrameworkServerUtils.kt: an engine hands the server a "supplier" that
+//  turns (prompt, genConfig, conversationId) into (conversationId, token stream).
+//  catalyst-core has no knowledge of any inference library.
+//
+
+import Foundation
+
+/// Result of one native-AI request: the active conversation id plus the token stream.
+/// Kotlin equivalent: Pair<String, Flow<String>>.
+public typealias NativeAIStream = (conversationId: String, tokens: AsyncThrowingStream<String, Error>)
+
+/// Kotlin equivalent: suspend (String, JSONObject, String?) -> Pair<String, Flow<String>>.
+public typealias NativeAISupplier = (
+    _ prompt: String,
+    _ genConfig: [String: Any],
+    _ conversationId: String?
+) async throws -> NativeAIStream
+
+/// Error codes come from packages/catalyst-core/src/errors/registry.js (AI-xxx) so the
+/// JS side surfaces the same code on iOS and Android.
+public enum NativeAIErrorCode {
+    public static let invalidRequestBody = "AI-003"
+    public static let streamNotReady = "AI-005"
+    public static let requestFailed = "AI-006"
+}
+
+/// An error an engine/server can raise with the registry code that should reach JS.
+public struct NativeAIError: LocalizedError {
+    public let message: String
+    public let code: String
+
+    public init(message: String, code: String = NativeAIErrorCode.requestFailed) {
+        self.message = message
+        self.code = code
+    }
+
+    public var errorDescription: String? { message }
+}
+
+/// Server-Sent Events framing. Frame shapes match Android's /ai/stream exactly:
+/// {"conversationId"}, {"token"}, {"done":true}, {"error"} (+ "code" on iOS).
+enum NativeAISSE {
+    static func frame(_ payload: [String: Any]) -> Data {
+        // Payloads are built from Strings/Bools only, so serialization cannot fail;
+        // the fallback keeps the stream well-formed regardless.
+        let json = (try? JSONSerialization.data(withJSONObject: payload, options: [.withoutEscapingSlashes]))
+            ?? Data("{\"error\":\"serialization failed\"}".utf8)
+        return Data("data: ".utf8) + json + Data("\n\n".utf8)
+    }
+
+    static func conversationId(_ id: String) -> Data { frame(["conversationId": id]) }
+    static func token(_ text: String) -> Data { frame(["token": text]) }
+    static func done() -> Data { frame(["done": true]) }
+    static func error(_ message: String, code: String) -> Data { frame(["error": message, "code": code]) }
+}
+
+/// Parsed body of POST /ai/stream and /ai/generate: { prompt, genConfig, conversationId }.
+struct NativeAIRequest {
+    let prompt: String
+    let genConfig: [String: Any]
+    let conversationId: String?
+
+    init(body: Data) {
+        let object = (try? JSONSerialization.jsonObject(with: body)) as? [String: Any] ?? [:]
+        prompt = object["prompt"] as? String ?? ""
+        genConfig = object["genConfig"] as? [String: Any] ?? [:]
+        let id = (object["conversationId"] as? String) ?? ""
+        conversationId = id.isEmpty ? nil : id
+    }
+}

package/dist/native/iosnativeWebView/CoreLogic/Tests/CatalystCoreLogicTests/FrameworkServerUtilsConnectionHandlerTests.swift

@@ -0,0 +1,133 @@
+import XCTest
+import Foundation
+import Network
+@testable import CatalystCoreLogic
+
+/**
+ * Deterministic tests for FrameworkServerUtils' connection error paths.
+ *
+ * Whether Network.framework reports a dropped client as a `.failed` connection
+ * state, a receive error, or a send error is timing-dependent, so driving them
+ * with real sockets made the CoreLogic line-coverage number vary from run to
+ * run and turned the coverage-regression gate into a coin flip. These tests
+ * call the extracted handlers directly with synthetic errors so every branch
+ * runs every time.
+ */
+final class FrameworkServerUtilsConnectionHandlerTests: XCTestCase {
+
+    private var frameworkServer: FrameworkServerUtils!
+
+    /// A connection to a closed loopback port (discard, 9). It never carries data;
+    /// it only needs to be startable so that cancel() is observable as `.cancelled`.
+    private func makeIdleConnection() -> NWConnection {
+        NWConnection(host: "127.0.0.1", port: 9, using: .tcp)
+    }
+
+    /// Starts a connection, runs `action` on it, and asserts it ends up `.cancelled`.
+    private func assertCancelled(
+        by action: (NWConnection) -> Void,
+        file: StaticString = #filePath,
+        line: UInt = #line
+    ) {
+        let connection = makeIdleConnection()
+        let cancelled = expectation(description: "connection cancelled")
+        connection.stateUpdateHandler = { state in
+            if case .cancelled = state { cancelled.fulfill() }
+        }
+        connection.start(queue: .global(qos: .utility))
+
+        action(connection)
+
+        wait(for: [cancelled], timeout: 5)
+    }
+
+    override func setUp() {
+        super.setUp()
+        frameworkServer = FrameworkServerUtils.shared
+    }
+
+    override func tearDown() {
+        if frameworkServer.isRunning() {
+            frameworkServer.stopServer()
+        }
+        frameworkServer = nil
+        super.tearDown()
+    }
+
+    func testConnectionStateFailed_CancelsConnection() {
+        assertCancelled { connection in
+            frameworkServer.handleConnectionStateChange(.failed(.posix(.ECONNRESET)), on: connection)
+        }
+    }
+
+    func testConnectionStateCancelled_DoesNotThrowForUntrackedConnection() {
+        let connection = makeIdleConnection()
+
+        frameworkServer.handleConnectionStateChange(.cancelled, on: connection)
+
+        XCTAssertEqual(frameworkServer.activeConnectionCount(), 0)
+    }
+
+    func testConnectionStateWaiting_IsIgnored() {
+        let connection = makeIdleConnection()
+
+        frameworkServer.handleConnectionStateChange(.waiting(.posix(.ENETDOWN)), on: connection)
+
+        XCTAssertNotEqual(connection.state, .cancelled)
+        connection.cancel()
+    }
+
+    func testReceiveError_CancelsConnection() {
+        assertCancelled { connection in
+            frameworkServer.handleReceiveError(.posix(.ECONNRESET), on: connection)
+        }
+    }
+
+    func testReceivedData_WithError_CancelsConnection() {
+        assertCancelled { connection in
+            frameworkServer.handleReceivedData(nil, isComplete: false, error: .posix(.ECONNRESET), on: connection)
+        }
+    }
+
+    func testSendCompletion_WithError_CancelsConnection() {
+        assertCancelled { connection in
+            frameworkServer.handleSendCompletion(.posix(.EPIPE), on: connection)
+        }
+    }
+
+    func testSendCompletion_WithoutError_CancelsConnection() {
+        assertCancelled { connection in
+            frameworkServer.handleSendCompletion(nil, on: connection)
+        }
+    }
+
+    // MARK: - Port selection
+
+    /// findAvailablePort() must skip a port that is already bound. Which ports
+    /// are busy on a CI runner is environmental, so the skip path only ran
+    /// sometimes; occupying the first port in the range makes it run every time.
+    func testStartServer_SkipsOccupiedPort() throws {
+        let firstPort = FrameworkServerUtils.FRAMEWORK_PORT_RANGE_START
+
+        let blocker = socket(AF_INET, SOCK_STREAM, 0)
+        try XCTSkipIf(blocker == -1, "could not create blocker socket")
+        defer { close(blocker) }
+
+        var addr = sockaddr_in()
+        addr.sin_family = sa_family_t(AF_INET)
+        addr.sin_port = firstPort.bigEndian
+        addr.sin_addr.s_addr = INADDR_ANY
+        let bound = withUnsafePointer(to: &addr) {
+            $0.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                Darwin.bind(blocker, $0, socklen_t(MemoryLayout<sockaddr_in>.size))
+            }
+        }
+        // bind() failing means another process already holds the first port,
+        // which exercises the same skip path, so the assertions below still hold.
+        _ = bound
+
+        XCTAssertTrue(frameworkServer.startServer())
+        XCTAssertNotEqual(frameworkServer.getServerPort(), firstPort)
+        XCTAssertGreaterThan(frameworkServer.getServerPort(), firstPort)
+    }
+}