Repository Public
1// =============================================================================2// SP BOUCHER | SOFTWARE & RESEARCH3// ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING4// =============================================================================5//6// PROJECT METADATA7// -----------------------------------------------------------------------------8// Project : Local Chat9// File : Services/LocalAPIServer/Sources/Router.swift10// Description : Request pipeline of the Local API server: origin check,11// authentication, rate limiting, OpenAI-compatible routes,12// extra /lc/ routes, diagnostics.13// Module : Services14// Repository : https://git.spboucher.ai/local-chat15// Created : 2026-11-2016// Last Modified : 2026-11-2017//18// =============================================================================19// AUTHOR & PROFESSIONAL AFFILIATION20// =============================================================================21//22// Author : Simon-Pierre Boucher23// Position : Professor of Finance24// Institution : Université du Québec en Outaouais (UQO)25// Department : Département des sciences administratives26// Organization : SP Boucher27//28// Website : https://spboucher.ai29// Git : https://git.spboucher.ai30//31// =============================================================================32// OFFICIAL CONTACT DIRECTORY33// =============================================================================34//35// General : info@spboucher.ai36// Professional : contact@spboucher.ai37// Direct : simon@spboucher.ai38// Research : research@spboucher.ai39// Development : dev@spboucher.ai40// Support : support@spboucher.ai41// Security/Admin : admin@spboucher.ai42// Notifications : notifications@spboucher.ai43//44// Preferred Contact: support@spboucher.ai45//46// =============================================================================47// COPYRIGHT & INTELLECTUAL PROPERTY48// =============================================================================49//50// Copyright (c) 202651// Simon-Pierre Boucher52//53// All rights reserved where applicable.54//55// This file is governed by the applicable project license,56// copyright notices, institutional agreements and relevant law.57//58// Unless expressly authorized by the applicable license or59// rights holder, copying, redistribution, sublicensing,60// publication and commercial exploitation are not permitted.61//62// Existing third-party rights and notices remain unaffected.63//64// =============================================================================65// CONFIDENTIALITY & SECURITY66// =============================================================================67//68// Classification : Public69// Distribution : Public repository; use is governed by the project license70// Security Contact : admin@spboucher.ai71//72// Access to this source does not independently grant permission73// to redistribute or disclose confidential materials.74//75// Do not embed credentials, private keys, access tokens,76// certificates or confidential personal information.77//78// =============================================================================79// LICENSE & MAINTENANCE80// =============================================================================81//82// License : None specified (no license file in this repository)83// Maintainer : Simon-Pierre Boucher84// Technical Contact: dev@spboucher.ai85//86// =============================================================================87// END OF SP BOUCHER SOURCE HEADER88// =============================================================================8990import Foundation91import LocalChatCore92import LocalChatNetworking9394final class ServerCore: Sendable {95 let configuration: ServerConfiguration96 let service: any InferenceService97 let keys: any APIKeyStore98 let routes: [any HTTPRouteHandler]99 let limiter: RateLimiter100 let log: RequestLog101 let baseSettings: GenerationSettings102 let port: UInt16103104 init(configuration: ServerConfiguration, service: any InferenceService, keys: any APIKeyStore, routes: [any HTTPRouteHandler], log: RequestLog,105 baseSettings: GenerationSettings, port: UInt16) {106 self.configuration = configuration; self.service = service; self.keys = keys; self.routes = routes; self.log = log107 self.baseSettings = baseSettings; self.port = port108 limiter = RateLimiter(limitPerMinute: configuration.rateLimitPerMinute)109 }110111 // MARK: Connection loop (keep-alive)112113 func serve(_ connection: HTTPConnection) async {114 var buffer = Data()115 var iterator = connection.inbound.makeAsyncIterator()116 while !Task.isCancelled {117 // request head118 var headRange = buffer.range(of: HTTPParser.headEnd)119 while headRange == nil {120 if buffer.count > 64 * 1024 { await reject(connection, 431, "Request headers are too large."); return }121 guard let more = await iterator.next() else { return }122 buffer.append(more); headRange = buffer.range(of: HTTPParser.headEnd)123 }124 guard let headRange else { return }125 let head: HTTPParser.Head126 do { head = try HTTPParser.parseHead(buffer.subdata(in: buffer.startIndex..<headRange.lowerBound)) }127 catch HTTPParseError.unsupportedEncoding { await reject(connection, 411, "Send the body with a Content-Length header (chunked request bodies are not supported)."); return }128 catch HTTPParseError.badRequest(let m) { await reject(connection, 400, m); return }129 catch { await reject(connection, 400, "Malformed request."); return }130 guard head.contentLength <= configuration.maxBodyBytes else {131 await reject(connection, 413, "The request body exceeds \(configuration.maxBodyBytes / 1_048_576) MB."); return132 }133 // body134 let bodyStart = headRange.upperBound135 while buffer.distance(from: bodyStart, to: buffer.endIndex) < head.contentLength {136 guard let more = await iterator.next() else { return }137 buffer.append(more)138 }139 let bodyEnd = buffer.index(bodyStart, offsetBy: head.contentLength)140 let request = HTTPRequestMessage(method: head.method, path: head.path, query: head.query, headers: head.headers,141 body: buffer.subdata(in: bodyStart..<bodyEnd), remoteAddress: connection.remoteAddress)142 buffer = Data(buffer[bodyEnd...])143144 let wantsClose = head.headers["connection"]?.lowercased().contains("close") == true || head.version == "HTTP/1.0"145 let completed = await handle(request, connection: connection, keepAlive: !wantsClose)146 if wantsClose || !completed { return }147 }148 }149150 private func reject(_ connection: HTTPConnection, _ status: Int, _ message: String) async {151 let writer = ResponseWriter(connection: connection, keepAlive: false, extraHeaders: [:], isHead: false)152 try? await writer.respond(.error(status, message))153 await log.append(RequestLogEntry(method: "-", path: "-", status: status, clientAddress: connection.remoteAddress, error: message))154 }155156 // MARK: Pipeline157158 /// Result of a route, for the diagnostics log.159 struct Outcome {160 var status: Int161 var model: String?162 var streamed = false163 var metrics: GenerationMetrics?164 var promptTokens: Int?165 var error: String?166 var completed = true // false when the connection must not be reused167 }168169 /// Returns false when the connection must be closed.170 private func handle(_ request: HTTPRequestMessage, connection: HTTPConnection, keepAlive: Bool) async -> Bool {171 let started = Date()172 let origin = request.headers["origin"]173 let originAllowed = origin.map(isAllowed(origin:)) ?? true174 let sameOrigin = origin.map { isSameOrigin($0, host: request.headers["host"]) } ?? false175 var cors: [String: String] = [:]176 if let origin, originAllowed, !sameOrigin {177 cors = ["Access-Control-Allow-Origin": configuration.allowedOrigins.contains("*") ? "*" : origin, "Vary": "Origin",178 "Access-Control-Allow-Headers": "Authorization, Content-Type", "Access-Control-Allow-Methods": "GET, POST, OPTIONS",179 "Access-Control-Max-Age": "600"]180 }181 let writer = ResponseWriter(connection: connection, keepAlive: keepAlive, extraHeaders: cors, isHead: request.method == "HEAD")182 var keyLabel: String?183 var outcome: Outcome184185 func plain(_ response: HTTPResponseMessage, error: String? = nil) async -> Outcome {186 do { try await writer.respond(response); return Outcome(status: response.status, error: error) }187 catch { return Outcome(status: response.status, error: "client disconnected", completed: false) }188 }189190 // A page from another origin must never drive the local server (CSRF / DNS rebinding), whatever the route.191 if origin != nil, !originAllowed, !sameOrigin {192 outcome = await plain(.error(403, "Origin not allowed. Add it to the allowed origins in Local Chat to use the API from a web page.", type: "forbidden"), error: "origin not allowed")193 } else if request.method == "OPTIONS" {194 outcome = await plain(HTTPResponseMessage(status: 204))195 } else if let open = publicRoute(request) {196 outcome = await plain(open)197 } else {198 var identity: APIKeyIdentity?199 var denied: HTTPResponseMessage?200 let presented = bearerToken(request)201 if let presented { identity = await keys.validate(presented) }202 if configuration.authenticationRequired, identity == nil {203 denied = .error(401, presented == nil ? "Missing API key. Send “Authorization: Bearer <key>”." : "Invalid or revoked API key.", type: "authentication_error")204 denied?.headers["WWW-Authenticate"] = "Bearer realm=\"LocalChat\""205 }206 keyLabel = identity?.label207 if let denied {208 outcome = await plain(denied, error: presented == nil ? "missing key" : "invalid key")209 } else if let wait = await limiter.check(identity.map { "key:\($0.id.uuidString)" } ?? "ip:\(request.remoteAddress ?? "unknown")") {210 var response = HTTPResponseMessage.error(429, "Rate limit exceeded (\(configuration.rateLimitPerMinute) requests per minute). Retry in \(wait) s.", type: "rate_limit_error")211 response.headers["Retry-After"] = String(wait)212 outcome = await plain(response, error: "rate limited")213 } else {214 outcome = await route(request, writer: writer)215 }216 }217218 let m = outcome.metrics219 await log.append(RequestLogEntry(time: started, method: request.method, path: request.path, status: outcome.status, keyLabel: keyLabel,220 clientAddress: request.remoteAddress, duration: Date().timeIntervalSince(started), model: outcome.model,221 streamed: outcome.streamed, promptTokens: m?.promptTokens ?? outcome.promptTokens, completionTokens: m?.completionTokens,222 tokensPerSecond: m?.tokensPerSecond, error: outcome.error))223 return outcome.completed224 }225226 private func isAllowed(origin: String) -> Bool {227 configuration.allowedOrigins.contains("*") || configuration.allowedOrigins.contains { $0.caseInsensitiveCompare(origin) == .orderedSame }228 }229230 /// The documentation page served by this server calls its own API.231 private func isSameOrigin(_ origin: String, host: String?) -> Bool {232 guard let host, let url = URL(string: origin), let originHost = url.host else { return false }233 let full = url.port.map { "\(originHost):\($0)" } ?? originHost234 return full.caseInsensitiveCompare(host) == .orderedSame235 }236237 private func bearerToken(_ request: HTTPRequestMessage) -> String? {238 if let header = request.headers["authorization"] {239 let parts = header.split(separator: " ", maxSplits: 1)240 if parts.count == 2, parts[0].lowercased() == "bearer" { let t = parts[1].trimmingCharacters(in: .whitespaces); return t.isEmpty ? nil : t }241 }242 if let key = request.headers["x-api-key"], !key.isEmpty { return key }243 return nil244 }245246 /// Routes that never need a key: liveness and the documentation (no user data).247 private func publicRoute(_ request: HTTPRequestMessage) -> HTTPResponseMessage? {248 guard request.method == "GET" || request.method == "HEAD" else { return nil }249 switch request.path {250 case "/health": return .json(["status": "ok"])251 case "/", "/docs":252 return HTTPResponseMessage(headers: ["Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store",253 "Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'"],254 body: Data(APIDocumentation.html(port: port, configuration: configuration).utf8))255 default: return nil256 }257 }258259 private func route(_ request: HTTPRequestMessage, writer: ResponseWriter) async -> Outcome {260 func plain(_ response: HTTPResponseMessage, error: String? = nil) async -> Outcome {261 do { try await writer.respond(response); return Outcome(status: response.status, error: error) }262 catch { return Outcome(status: response.status, error: "client disconnected", completed: false) }263 }264 let known: [String: String] = ["/v1/models": "GET", "/v1/chat/completions": "POST", "/v1/embeddings": "POST"]265 if let method = known[request.path] {266 guard request.method == method || (method == "GET" && request.method == "HEAD") else {267 var response = HTTPResponseMessage.error(405, "Use \(method) on \(request.path)."); response.headers["Allow"] = method268 return await plain(response, error: "method not allowed")269 }270 switch request.path {271 case "/v1/models": return await plain(await modelsResponse())272 case "/v1/chat/completions": return await chat(request, writer: writer)273 default: return await embeddings(request, writer: writer)274 }275 }276 if request.path.hasPrefix("/lc/") {277 for handler in routes { if let response = await handler.handle(request) { return await plain(response, error: response.status >= 400 ? "HTTP \(response.status)" : nil) } }278 }279 return await plain(.error(404, "Unknown route \(request.method) \(request.path). See /docs.", type: "not_found_error"), error: "unknown route")280 }281282 // MARK: /v1/models283284 private func modelsResponse() async -> HTTPResponseMessage {285 let created = Int(Date().timeIntervalSince1970)286 let models = await service.listModels()287 return .json(OpenAI.ModelList(data: models.map { OpenAI.Model(id: $0.id, created: Int($0.addedAt?.timeIntervalSince1970 ?? Double(created)), localChat: OpenAI.ModelDetails($0)) }))288 }289290 /// Accepts the exact id, or (case-insensitively) the display name, the repository, or the id without its backend prefix.291 private func resolveModel(_ requested: String) async -> ModelDescriptor? {292 let models = await service.listModels()293 if let exact = models.first(where: { $0.id == requested }) { return exact }294 let wanted = requested.lowercased()295 return models.first { $0.name.lowercased() == wanted || $0.repoID?.lowercased() == wanted || $0.id.lowercased().hasSuffix(":" + wanted) }296 }297298 static func status(for error: Error) -> (Int, String, String) {299 switch error {300 case let e as InferenceError:301 let message = e.errorDescription ?? "Inference error"302 switch e {303 case .modelNotFound: return (404, message, "not_found_error")304 case .unsupported: return (400, message, "invalid_request_error")305 case .insufficientMemory, .backendUnavailable, .modelNotLoaded, .loadFailed: return (503, message, "server_error")306 case .cancelled: return (499, message, "server_error")307 case .generationFailed: return (500, message, "server_error")308 }309 case let e as WireError: return (400, e.errorDescription ?? "Invalid request", "invalid_request_error")310 default: return (500, (error as? LocalizedError)?.errorDescription ?? error.localizedDescription, "server_error")311 }312 }313314 // MARK: /v1/chat/completions315316 private func chat(_ request: HTTPRequestMessage, writer: ResponseWriter) async -> Outcome {317 func fail(_ status: Int, _ message: String, type: String = "invalid_request_error", model: String? = nil) async -> Outcome {318 do { try await writer.respond(.error(status, message, type: type)); return Outcome(status: status, model: model, error: message) }319 catch { return Outcome(status: status, model: model, error: "client disconnected", completed: false) }320 }321 let wire: OpenAI.ChatRequest322 do { wire = try JSONDecoder().decode(OpenAI.ChatRequest.self, from: request.body) }323 catch { return await fail(400, "The body is not a valid chat completion request (JSON with “model” and “messages”).") }324 guard let model = await resolveModel(wire.model) else {325 return await fail(404, "The model “\(wire.model)” is not available on this node. List models with GET /v1/models.", type: "not_found_error", model: wire.model)326 }327 var base = baseSettings328 if let limit = model.contextLength, limit > 0 { base.contextLength = min(base.contextLength, limit) }329 let generation: GenerationRequest330 do { generation = try wire.generationRequest(base: base) }331 catch { let (status, message, type) = Self.status(for: error); return await fail(status, message, type: type, model: model.id) }332333 let id = "chatcmpl-" + UUID().uuidString.replacingOccurrences(of: "-", with: "").lowercased()334 let created = Int(Date().timeIntervalSince1970)335 let stream = service.generate(modelID: model.id, request: generation)336337 if wire.stream != true {338 var text = "", reasoning = ""; var calls: [ToolInvocation] = []; var metrics: GenerationMetrics?339 do {340 for try await event in stream {341 switch event {342 case .text(let t): text += t343 case .reasoning(let t): reasoning += t344 case .toolCall(let c): calls.append(c)345 case .finished(let m): metrics = m346 }347 }348 } catch {349 if Task.isCancelled { return Outcome(status: 499, model: model.id, error: "client disconnected", completed: false) }350 let (status, message, type) = Self.status(for: error); return await fail(status, message, type: type, model: model.id)351 }352 if Task.isCancelled { return Outcome(status: 499, model: model.id, error: "client disconnected", completed: false) }353 let wireCalls = calls.map { OpenAI.ToolCall(id: $0.id, function: .init(name: $0.name, arguments: $0.arguments.serialized())) }354 let message = OpenAI.Message(role: "assistant", content: .text(text), reasoningContent: reasoning.isEmpty ? nil : reasoning, toolCalls: wireCalls.isEmpty ? nil : wireCalls)355 let finish = calls.isEmpty ? (metrics?.stopReason ?? .endOfTurn).openAIFinishReason : "tool_calls"356 let response = OpenAI.ChatResponse(id: id, created: created, model: model.id, choices: [.init(message: message, finishReason: finish)],357 usage: metrics.map(OpenAI.Usage.init), localChat: metrics.map(OpenAI.ServerMetrics.init))358 do { try await writer.respond(.json(response)); return Outcome(status: 200, model: model.id, metrics: metrics) }359 catch { return Outcome(status: 200, model: model.id, metrics: metrics, error: "client disconnected", completed: false) }360 }361362 // Streaming: the response head is sent with the first event, so an immediate failure (model cannot load…) still gets a proper status.363 var begun = false; var metrics: GenerationMetrics?; var toolIndex = 0; var failure: String?364 func chunk(_ delta: OpenAI.Delta, finish: String? = nil, server: OpenAI.ServerMetrics? = nil) -> Data {365 SSEWriter.json(OpenAI.ChatChunk(id: id, created: created, model: model.id, choices: [.init(delta: delta, finishReason: finish)], localChat: server))366 }367 func begin() async throws {368 guard !begun else { return }369 begun = true370 try await writer.beginStream(headers: ["Content-Type": "text/event-stream; charset=utf-8", "Cache-Control": "no-cache", "X-Accel-Buffering": "no"])371 try await writer.chunk(chunk(OpenAI.Delta(role: "assistant", content: "")))372 }373 do {374 for try await event in stream {375 try Task.checkCancellation()376 switch event {377 case .text(let t): try await begin(); try await writer.chunk(chunk(OpenAI.Delta(content: t)))378 case .reasoning(let t): try await begin(); try await writer.chunk(chunk(OpenAI.Delta(reasoningContent: t)))379 case .toolCall(let c):380 try await begin()381 try await writer.chunk(chunk(OpenAI.Delta(toolCalls: [OpenAI.ToolCall(index: toolIndex, id: c.id, function: .init(name: c.name, arguments: c.arguments.serialized()))])))382 toolIndex += 1383 case .finished(let m): metrics = m384 }385 }386 try Task.checkCancellation()387 try await begin()388 let finish = toolIndex > 0 ? "tool_calls" : (metrics?.stopReason ?? .endOfTurn).openAIFinishReason389 try await writer.chunk(chunk(OpenAI.Delta(), finish: finish, server: metrics.map(OpenAI.ServerMetrics.init)))390 if wire.streamOptions?.includeUsage == true, let metrics {391 try await writer.chunk(SSEWriter.json(OpenAI.ChatChunk(id: id, created: created, model: model.id, choices: [], usage: OpenAI.Usage(metrics))))392 }393 try await writer.chunk(SSEWriter.done)394 try await writer.endStream()395 return Outcome(status: 200, model: model.id, streamed: true, metrics: metrics)396 } catch {397 if Task.isCancelled || error is CancellationError || writer.connection.isClosed {398 return Outcome(status: begun ? 200 : 499, model: model.id, streamed: true, metrics: metrics, error: "client disconnected", completed: false)399 }400 let (status, message, type) = Self.status(for: error)401 failure = message402 if !begun { return await fail(status, message, type: type, model: model.id) }403 // the stream already started: report the failure in-band, then end it404 try? await writer.chunk(SSEWriter.json(OpenAI.ErrorEnvelope(message, type: type)))405 try? await writer.chunk(SSEWriter.done)406 try? await writer.endStream()407 return Outcome(status: 200, model: model.id, streamed: true, metrics: metrics, error: failure, completed: false)408 }409 }410411 // MARK: /v1/embeddings412413 private func embeddings(_ request: HTTPRequestMessage, writer: ResponseWriter) async -> Outcome {414 func send(_ response: HTTPResponseMessage, model: String?, error: String? = nil, tokens: Int? = nil) async -> Outcome {415 do { try await writer.respond(response); return Outcome(status: response.status, model: model, promptTokens: tokens, error: error) }416 catch { return Outcome(status: response.status, model: model, error: "client disconnected", completed: false) }417 }418 guard let wire = try? JSONDecoder().decode(OpenAI.EmbeddingRequest.self, from: request.body) else {419 return await send(.error(400, "The body is not a valid embeddings request (JSON with “model” and “input”)."), model: nil, error: "invalid body")420 }421 if let format = wire.encodingFormat, format != "float" {422 return await send(.error(400, "Only encoding_format “float” is supported."), model: wire.model, error: "unsupported encoding_format")423 }424 guard let model = await resolveModel(wire.model) else {425 return await send(.error(404, "The model “\(wire.model)” is not available on this node.", type: "not_found_error"), model: wire.model, error: "model not found")426 }427 guard !wire.input.values.isEmpty, wire.input.values.count <= 2048 else {428 return await send(.error(400, "“input” must contain between 1 and 2048 texts."), model: model.id, error: "invalid input")429 }430 do {431 let vectors = try await service.embed(modelID: model.id, texts: wire.input.values)432 var tokens: Int?433 var total = 0; var exact = true434 for text in wire.input.values { if let n = await service.countTokens(modelID: model.id, text: text) { total += n } else { exact = false; break } }435 if exact { tokens = total } // reported only when the model's tokenizer counted them436 let response = OpenAI.EmbeddingResponse(data: vectors.enumerated().map { OpenAI.Embedding(index: $0.offset, embedding: $0.element) }, model: model.id,437 usage: tokens.map { OpenAI.Usage(promptTokens: $0, completionTokens: 0) })438 return await send(.json(response), model: model.id, tokens: tokens)439 } catch {440 let (status, message, type) = Self.status(for: error)441 return await send(.error(status, message, type: type), model: model.id, error: message)442 }443 }444}445