Repository Public
1// =============================================================================2// SP BOUCHER | SOFTWARE & RESEARCH3// ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING4// =============================================================================5//6// PROJECT METADATA7// -----------------------------------------------------------------------------8// Project : Local Chat9// File : Services/LocalAPIServer/Sources/LocalAPIServer.swift10// Description : OpenAI-compatible HTTP server on Network.framework.11// Loopback by default; LAN exposure only on explicit12// configuration and always with API keys.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 Network9394public actor LocalAPIServer {95 public let configuration: ServerConfiguration96 public nonisolated let log: RequestLog97 private let service: any InferenceService98 private let keys: any APIKeyStore99 private let routes: [any HTTPRouteHandler]100 private let baseSettings: GenerationSettings101 private let queue = DispatchQueue(label: "ai.spboucher.localchat.apiserver")102 private var listener: NWListener?103 private let connections = ConnectionSet()104 public private(set) var port: UInt16?105 public var isRunning: Bool { listener != nil }106107 /// - Parameters:108 /// - routes: extra authenticated handlers consulted for paths under `/lc/`.109 /// - baseSettings: generation settings used for fields a request leaves out.110 public init(configuration: ServerConfiguration = .init(), service: any InferenceService, keys: any APIKeyStore, routes: [any HTTPRouteHandler] = [],111 baseSettings: GenerationSettings = .default, log: RequestLog = RequestLog()) {112 self.configuration = configuration; self.service = service; self.keys = keys; self.routes = routes; self.baseSettings = baseSettings; self.log = log113 }114115 /// Addresses clients can use, e.g. `http://127.0.0.1:8765/v1`.116 public var baseURL: String? { port.map { "http://127.0.0.1:\($0)/v1" } }117118 /// Starts listening and returns the bound port. Throws `ServerError.portInUse` when another process holds the port.119 @discardableResult120 public func start() async throws -> UInt16 {121 guard listener == nil else { throw ServerError.alreadyRunning }122 let parameters = NWParameters.tcp123 parameters.allowLocalEndpointReuse = true124 let requested = NWEndpoint.Port(rawValue: configuration.port) ?? .any125 if configuration.port != 0, await Self.somethingListens(on: configuration.port) { throw ServerError.portInUse(configuration.port) }126 let listener: NWListener127 do {128 if configuration.exposeOnLAN { listener = try NWListener(using: parameters, on: requested) }129 else {130 // loopback only: never reachable from another machine131 parameters.requiredLocalEndpoint = .hostPort(host: .ipv4(.loopback), port: requested)132 parameters.acceptLocalOnly = true133 listener = try NWListener(using: parameters)134 }135 } catch { throw Self.map(error, port: configuration.port) }136137 let ready = OneShot<Result<UInt16, Error>>()138 let requestedPort = configuration.port139 listener.stateUpdateHandler = { [weak listener] state in140 switch state {141 case .ready: ready.fire(.success(listener?.port?.rawValue ?? requestedPort))142 case .failed(let error): ready.fire(.failure(Self.map(error, port: requestedPort)))143 case .waiting(let error): ready.fire(.failure(Self.map(error, port: requestedPort)))144 case .cancelled: ready.fire(.failure(ServerError.startFailed("cancelled")))145 default: break146 }147 }148 let box = CoreBox()149 let connections = self.connections; let queue = self.queue150 listener.newConnectionHandler = { raw in151 guard let core = box.core else { raw.cancel(); return }152 let connection = HTTPConnection(raw)153 connections.insert(connection)154 connection.start(queue: queue, onClose: { connections.remove($0) }, serve: { await core.serve($0) })155 }156 listener.start(queue: queue)157 let bound: UInt16158 do { bound = try await ready.value().get() } catch { listener.cancel(); throw error }159 box.core = ServerCore(configuration: configuration, service: service, keys: keys, routes: routes, log: log, baseSettings: baseSettings, port: bound)160 self.listener = listener; port = bound161 return bound162 }163164 /// Stops listening and closes every open connection (running generations are cancelled).165 /// Returns once the port is released, so the server can be restarted on the same port right away.166 public func stop() async {167 guard let listener else { return }168 self.listener = nil; port = nil169 let released = OneShot<Bool>()170 listener.stateUpdateHandler = { state in if case .cancelled = state { released.fire(true) } }171 listener.cancel()172 connections.closeAll()173 DispatchQueue.global().asyncAfter(deadline: .now() + 2) { released.fire(false) }174 _ = await released.value()175 }176177 public func requestLog() async -> [RequestLogEntry] { await log.snapshot() }178 public nonisolated func requestStream() async -> AsyncStream<RequestLogEntry> { await log.stream() }179 public var openConnections: Int { connections.count }180181 private static func map(_ error: Error, port: UInt16) -> Error {182 if let nw = error as? NWError, case .posix(let code) = nw {183 if code == .EADDRINUSE { return ServerError.portInUse(port) }184 if code == .EACCES || code == .EPERM { return ServerError.startFailed("the system refused to open port \(port) (ports below 1024 and sandboxed apps without the network-server entitlement cannot listen).") }185 }186 return ServerError.startFailed(error.localizedDescription)187 }188189 /// Address reuse lets two listeners share a port silently on Darwin, so a busy port is detected by trying to connect to it first.190 private static func somethingListens(on port: UInt16) async -> Bool {191 guard let endpointPort = NWEndpoint.Port(rawValue: port) else { return false }192 let probe = NWConnection(host: .ipv4(.loopback), port: endpointPort, using: .tcp)193 let result = OneShot<Bool>()194 probe.stateUpdateHandler = { state in195 switch state {196 case .ready: result.fire(true)197 case .failed, .waiting, .cancelled: result.fire(false)198 default: break199 }200 }201 probe.start(queue: DispatchQueue.global(qos: .userInitiated))202 DispatchQueue.global().asyncAfter(deadline: .now() + 1.5) { result.fire(false) }203 let busy = await result.value()204 probe.cancel()205 return busy206 }207}208209/// Set of live connections, shared with Network.framework callbacks.210final class ConnectionSet: @unchecked Sendable {211 private let lock = NSLock()212 private var items: [UUID: HTTPConnection] = [:]213 func insert(_ c: HTTPConnection) { lock.withLock { items[c.id] = c } }214 func remove(_ id: UUID) { lock.withLock { items[id] = nil } }215 var count: Int { lock.withLock { items.count } }216 func closeAll() {217 let all = lock.withLock { () -> [HTTPConnection] in let v = Array(items.values); items.removeAll(); return v }218 for c in all { c.forceClose() }219 }220}221222final class CoreBox: @unchecked Sendable {223 private let lock = NSLock()224 private var stored: ServerCore?225 var core: ServerCore? { get { lock.withLock { stored } } set { lock.withLock { stored = newValue } } }226}227228/// A value delivered once to one awaiting task, whichever callback fires first.229final class OneShot<T: Sendable>: @unchecked Sendable {230 private let lock = NSLock()231 private var result: T?232 private var waiter: CheckedContinuation<T, Never>?233 func fire(_ value: T) {234 let waiter = lock.withLock { () -> CheckedContinuation<T, Never>? in235 guard result == nil else { return nil }236 result = value237 defer { self.waiter = nil }238 return self.waiter239 }240 waiter?.resume(returning: value)241 }242 func value() async -> T {243 await withCheckedContinuation { continuation in244 let ready = lock.withLock { () -> T? in245 if let result { return result }246 waiter = continuation; return nil247 }248 if let ready { continuation.resume(returning: ready) }249 }250 }251}252