Repository Public
1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: Services/RemoteInference/Sources/RemoteNodeClient.swift3// Description: Client of one OpenAI-compatible node: model discovery, health with measured latency, and step-by-step connection diagnostics.4import Foundation5import LocalChatCore6import LocalChatNetworking78public struct DiagnosticCheck: Sendable, Hashable, Identifiable {9 public enum Outcome: String, Sendable { case passed, failed, skipped }10 public var name: String11 public var outcome: Outcome12 public var detail: String13 public var id: String { name }14 public init(name: String, outcome: Outcome, detail: String) { self.name = name; self.outcome = outcome; self.detail = detail }15}1617public struct RemoteNodeClient: Sendable {18 public let node: RemoteNode19 public let apiKey: String?20 public let http: HTTPClient2122 public init(node: RemoteNode, apiKey: String?, http: HTTPClient = HTTPClient()) { self.node = node; self.apiKey = apiKey; self.http = http }2324 /// Validated base URL without a trailing slash, e.g. `http://studio.local:8765/v1`.25 public func baseURL() throws -> URL {26 var text = node.baseURL.trimmingCharacters(in: .whitespacesAndNewlines)27 while text.hasSuffix("/") { text.removeLast() }28 return try URLPolicy.validate(text, allowInsecureHTTP: node.allowInsecureHTTP)29 }3031 public func endpoint(_ path: String) throws -> URL { try baseURL().appendingPathComponent(path) }3233 public static func modelID(node: UUID, remoteModel: String) -> String { "remote:\(node.uuidString):\(remoteModel)" }3435 /// The model name the node knows, from a descriptor id of the form `remote:<node uuid>:<model id>`.36 public static func remoteModelName(fromID id: String) -> String? {37 let parts = id.split(separator: ":", maxSplits: 2, omittingEmptySubsequences: false)38 guard parts.count == 3, parts[0] == "remote", !parts[2].isEmpty else { return nil }39 return String(parts[2])40 }4142 public func listModels(timeout: TimeInterval = 10) async throws -> [OpenAI.Model] {43 try await http.json(OpenAI.ModelList.self, "GET", try endpoint("models"), bearer: apiKey, timeout: timeout).data44 }4546 public func descriptor(for model: OpenAI.Model) -> ModelDescriptor {47 let d = model.localChat48 var capabilities = Set((d?.capabilities ?? []).compactMap(ModelCapability.init(rawValue:)))49 if capabilities.isEmpty { capabilities = model.id.lowercased().contains("embed") ? [.embeddings] : [.chat] }50 return ModelDescriptor(id: Self.modelID(node: node.id, remoteModel: model.id), name: d?.name ?? model.id, backend: .remote, format: .remote,51 architecture: d?.architecture, parameterCount: d?.parameterCount, parameterProvenance: d?.parameterCount == nil ? .unknown : .declared,52 quantization: d?.quantization, contextLength: d?.contextLength, capabilities: capabilities, sizeBytes: d?.sizeBytes,53 localPath: nil, remoteNodeID: node.id)54 }5556 /// One models request; the latency is the measured round trip of that request.57 public func health(timeout: TimeInterval = 8) async -> NodeHealth {58 let started = Date()59 do {60 let (data, response) = try await http.send("GET", try endpoint("models"), bearer: apiKey, timeout: timeout)61 let latency = Date().timeIntervalSince(started)62 switch response.statusCode {63 case 200..<300:64 guard let list = try? JSONDecoder().decode(OpenAI.ModelList.self, from: data) else {65 return NodeHealth(state: .offline, latency: latency, detail: "The server answered, but not with an OpenAI-compatible model list.")66 }67 return NodeHealth(state: .online, latency: latency, models: list.data.map(\.id))68 case 401, 403:69 return NodeHealth(state: .unauthorized, latency: latency, detail: HTTPClient.errorMessage(data) ?? "The API key was refused (HTTP \(response.statusCode)).")70 default:71 return NodeHealth(state: .offline, latency: latency, detail: HTTPClient.errorMessage(data) ?? "HTTP \(response.statusCode)")72 }73 } catch {74 return NodeHealth(state: .offline, detail: Self.describe(error))75 }76 }7778 /// Named checks in the order a connection is established. A failed check marks the following ones as skipped.79 public func diagnostics(timeout: TimeInterval = 8) async -> [DiagnosticCheck] {80 var checks: [DiagnosticCheck] = []81 func skipRest(from names: [String]) { for n in names { checks.append(.init(name: n, outcome: .skipped, detail: "Not reached.")) } }8283 let url: URL84 do {85 url = try endpoint("models")86 let host = url.host ?? ""87 let secure = url.scheme?.lowercased() == "https"88 let detail = secure ? "HTTPS to \(host)." : "Plain HTTP to \(host) (\(URLPolicy.classify(host: host).rawValue))\(node.allowInsecureHTTP ? ", allowed explicitly" : "")."89 checks.append(.init(name: "URL policy", outcome: .passed, detail: detail))90 } catch {91 checks.append(.init(name: "URL policy", outcome: .failed, detail: Self.describe(error)))92 skipRest(from: ["Connection", "TLS", "Authentication", "Models"]); return checks93 }94 let secure = url.scheme?.lowercased() == "https"95 let started = Date()96 let data: Data, response: HTTPURLResponse97 do { (data, response) = try await http.send("GET", url, bearer: apiKey, timeout: timeout) }98 catch {99 let code = (error as? URLError)?.code100 let tlsCodes: [URLError.Code] = [.secureConnectionFailed, .serverCertificateUntrusted, .serverCertificateHasBadDate, .serverCertificateHasUnknownRoot,101 .serverCertificateNotYetValid, .clientCertificateRejected, .clientCertificateRequired, .appTransportSecurityRequiresSecureConnection]102 if let code, tlsCodes.contains(code) {103 checks.append(.init(name: "Connection", outcome: .passed, detail: "Reached \(url.host ?? "host"):\(url.port ?? (secure ? 443 : 80))."))104 checks.append(.init(name: "TLS", outcome: .failed, detail: Self.describe(error)))105 skipRest(from: ["Authentication", "Models"])106 } else {107 checks.append(.init(name: "Connection", outcome: .failed, detail: Self.describe(error)))108 skipRest(from: ["TLS", "Authentication", "Models"])109 }110 return checks111 }112 let ms = Int((Date().timeIntervalSince(started) * 1000).rounded())113 checks.append(.init(name: "Connection", outcome: .passed, detail: "Answered in \(ms) ms (HTTP \(response.statusCode))."))114 checks.append(.init(name: "TLS", outcome: secure ? .passed : .skipped, detail: secure ? "Certificate accepted by the system trust store." : "Not used: the connection is plain HTTP."))115 if response.statusCode == 401 || response.statusCode == 403 {116 let why = apiKey?.isEmpty == false ? "The API key was refused" : "The node requires an API key and none is set"117 checks.append(.init(name: "Authentication", outcome: .failed, detail: "\(why) (HTTP \(response.statusCode))."))118 skipRest(from: ["Models"]); return checks119 }120 checks.append(.init(name: "Authentication", outcome: .passed, detail: apiKey?.isEmpty == false ? "API key accepted." : "The node did not ask for a key."))121 guard (200..<300).contains(response.statusCode), let list = try? JSONDecoder().decode(OpenAI.ModelList.self, from: data) else {122 checks.append(.init(name: "Models", outcome: .failed, detail: (200..<300).contains(response.statusCode)123 ? "The answer is not an OpenAI-compatible model list. Check that the URL ends with /v1." : (HTTPClient.errorMessage(data) ?? "HTTP \(response.statusCode)")))124 return checks125 }126 checks.append(.init(name: "Models", outcome: list.data.isEmpty ? .failed : .passed,127 detail: list.data.isEmpty ? "The node lists no model." : "\(list.data.count) model\(list.data.count == 1 ? "" : "s"): \(list.data.prefix(4).map(\.id).joined(separator: ", "))\(list.data.count > 4 ? "…" : "")"))128 return checks129 }130131 static func describe(_ error: Error) -> String {132 if let url = error as? URLError {133 switch url.code {134 case .cannotFindHost, .dnsLookupFailed: return "The host name could not be resolved."135 case .cannotConnectToHost: return "The host refused the connection (is the server running, is the port right?)."136 case .timedOut: return "The host did not answer in time."137 case .notConnectedToInternet, .networkConnectionLost: return "The network connection is down."138 case .appTransportSecurityRequiresSecureConnection: return "The system blocked a plain HTTP connection (App Transport Security)."139 default: return url.localizedDescription140 }141 }142 return (error as? LocalizedError)?.errorDescription ?? error.localizedDescription143 }144}145