Repository Public
1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: SPChat/Core/Streaming/GenerationEngine.swift3// Description: Drives one assistant turn: idempotent POST with retries, SSE consumption, silence watchdog, re-attachment to the detached server run after a drop.4import Foundation56public enum GenerationPhase: String, Sendable, Equatable { case idle, sending, streaming, reconnecting }78public enum GenerationEnd: Sendable, Equatable {9 /// The run reached its `end` event: the message is final.10 case completed11 /// The run is no longer in the server's memory (finished long ago, or the server restarted): reload the conversation.12 case runGone13 /// The request had already been processed (idempotency key): reload that conversation.14 case deduplicated(conversationId: String)15 /// Nothing reached the server: the text must go back to the composer.16 case notSent(APIError)17 /// The server refused the turn (busy conversation, budget reached, validation…).18 case refused(APIError)19 case sessionEnded20}2122public enum GenerationUpdate: Sendable, Equatable {23 case phase(GenerationPhase)24 case event(ChatEvent)25 case warning(String)26 case ended(GenerationEnd)27}2829public enum TurnEndpoint: String, Sendable {30 case send = "/api/chat", regenerate = "/api/chat/regenerate", edit = "/api/chat/edit", approve = "/api/chat/approve"31}3233/// The server runs every generation detached from the HTTP connection. This engine therefore treats the SSE stream as a34/// *view* of the run: when the connection drops it re-attaches with the index of the last event it saw, and when the run35/// is gone it tells the caller to reload the conversation, whose rows hold the truth.36public final class GenerationEngine: Sendable {37 public struct Timing: Sendable {38 public var postAttempts = 439 public var postBackoff: Duration = .milliseconds(800)40 public var silenceTimeout: Duration = .seconds(45) // the server sends a heartbeat every 15 s41 public var reconnectBase: Duration = .seconds(1)42 public var reconnectCap: Duration = .seconds(15)43 public var warnAfterTries = 1244 public var onlinePoll: Duration = .seconds(1)45 public init() {}46 }4748 private let api: APIClient49 private let timing: Timing50 private let isOnline: @Sendable () -> Bool51 private let sleep: @Sendable (Duration) async throws -> Void5253 public init(api: APIClient, timing: Timing = Timing(), isOnline: @escaping @Sendable () -> Bool = { true },54 sleep: @escaping @Sendable (Duration) async throws -> Void = { try await Task.sleep(for: $0) }) {55 self.api = api; self.timing = timing; self.isOnline = isOnline; self.sleep = sleep56 }5758 /// 18 random bytes, base64url — matches the server's `clientRequestId` pattern.59 public static func requestId() -> String {60 var bytes = [UInt8](repeating: 0, count: 18)61 _ = SecRandomCopyBytes(kSecRandomDefault, bytes.count, &bytes)62 return Data(bytes).base64URLEncodedString()63 }6465 /// Starts a turn. Safe to retry: the request carries an idempotency key. Cancel by cancelling the consuming task.66 public func start(_ endpoint: TurnEndpoint, payload: [String: JSONValue], requestId: String = GenerationEngine.requestId()) -> AsyncStream<GenerationUpdate> {67 var payload = payload; payload["clientRequestId"] = .string(requestId)68 let body = Data(JSONValue.object(payload).jsonString().utf8)69 return makeStream { [self] yield in70 yield(.phase(.sending))71 var opening: APIClient.StreamOpening?72 var lastError = APIError(.network(offline: false), message: "Réseau indisponible : le message n'a pas été envoyé.", code: "network")73 for attempt in 0..<timing.postAttempts {74 if Task.isCancelled { return }75 do { opening = try await api.openStream(.post, endpoint.rawValue, body: body); break }76 catch let e as APIError {77 switch e.kind {78 case .network: lastError = e; yield(.phase(.reconnecting)); try? await sleep(timing.postBackoff * (1 << attempt))79 case .locked: yield(.ended(.sessionEnded)); return80 case .cancelled: return81 default: yield(.ended(.refused(e))); return82 }83 } catch { return }84 }85 guard let opening else {86 let offline = !isOnline()87 yield(.ended(.notSent(APIError(.network(offline: offline), message: offline ? "Hors ligne : le message n'a pas été envoyé." : lastError.message, code: "network")))); return88 }89 switch opening {90 case .json(_, let j):91 if j["deduplicated"]?.boolValue == true, let cid = j["conversationId"]?.stringValue { yield(.ended(.deduplicated(conversationId: cid))) }92 else { yield(.ended(.refused(APIError(.decoding, message: "Réponse inattendue du serveur.")))) }93 case .events(_, let bytes):94 yield(.phase(.streaming))95 let r = await consume(bytes, after: -1, yield: yield)96 if r.ended { yield(.ended(.completed)) }97 else if Task.isCancelled { return }98 else if let run = r.runId { await follow(run, after: r.last, yield: yield) }99 else { yield(.ended(.runGone)) }100 }101 }102 }103104 /// Re-attaches to a run that is still alive on the server (app relaunched, another device started it, connection lost).105 public func follow(runId: String, after: Int = -1) -> AsyncStream<GenerationUpdate> {106 makeStream { [self] yield in await follow(runId, after: after, yield: yield) }107 }108109 // MARK: Internals110111 private func makeStream(_ work: @escaping @Sendable (@escaping @Sendable (GenerationUpdate) -> Void) async -> Void) -> AsyncStream<GenerationUpdate> {112 let (stream, continuation) = AsyncStream<GenerationUpdate>.makeStream(bufferingPolicy: .unbounded)113 let task = Task { await work { continuation.yield($0) }; continuation.finish() }114 continuation.onTermination = { @Sendable _ in task.cancel() }115 return stream116 }117118 private struct Consumed { var ended: Bool; var last: Int; var runId: String? }119120 private final class Activity: @unchecked Sendable {121 private let lock = NSLock(); private var at = ContinuousClock.now122 func touch() { lock.withLock { at = .now } }123 var idle: Duration { lock.withLock { ContinuousClock.now - at } }124 }125126 /// Reads one SSE body until `end`, the body closes, it errors, or it stays silent for too long.127 private func consume(_ bytes: AsyncThrowingStream<Data, Error>, after: Int, yield: @escaping @Sendable (GenerationUpdate) -> Void) async -> Consumed {128 let activity = Activity()129 let timeout = timing.silenceTimeout130 return await withTaskGroup(of: Consumed?.self) { group in131 group.addTask {132 var parser = SSEParser(); var out = Consumed(ended: false, last: after, runId: nil)133 do {134 for try await chunk in bytes {135 activity.touch()136 for sse in parser.feed(chunk) {137 if let i = sse.index { out.last = i }138 let ev = ChatEvent(sse)139 if case .run(let id) = ev, !id.isEmpty { out.runId = id }140 if case .end = ev { out.ended = true; return out }141 yield(.event(ev))142 }143 }144 } catch { /* dropped connection: the caller re-attaches */ }145 return out146 }147 group.addTask {148 let step = max(timeout / 9, .milliseconds(20))149 while !Task.isCancelled {150 try? await Task.sleep(for: step)151 if activity.idle > timeout { return nil } // dead connection that never errored152 }153 return nil154 }155 var result = Consumed(ended: false, last: after, runId: nil)156 if let first = await group.next() { if let r = first { result = r } }157 group.cancelAll()158 for await rest in group { if let r = rest { result = r } }159 return result160 }161 }162163 private func follow(_ runId: String, after: Int, yield: @escaping @Sendable (GenerationUpdate) -> Void) async {164 var last = after; var tries = 0165 while !Task.isCancelled {166 yield(.phase(.reconnecting))167 do {168 let opening = try await api.openStream(.get, "/api/chat/stream", query: ["run": runId, "after": String(last)])169 guard case .events(_, let bytes) = opening else { yield(.ended(.runGone)); return }170 yield(.phase(.streaming)); tries = 0171 let r = await consume(bytes, after: last, yield: yield)172 last = r.last173 if r.ended { yield(.ended(.completed)); return }174 } catch let e as APIError {175 switch e.kind {176 case .locked: yield(.ended(.sessionEnded)); return177 case .server(let status) where status == 410 || status == 404: yield(.ended(.runGone)); return178 case .cancelled: return179 default: break180 }181 } catch { return }182 if Task.isCancelled { return }183 tries += 1184 if tries == timing.warnAfterTries + 1 { yield(.warning("Connexion perdue. La réponse continue sur le serveur ; elle s'affichera au retour du réseau.")) }185 yield(.phase(.reconnecting))186 let backoff = min(timing.reconnectBase * (1 << min(tries, 4)), timing.reconnectCap)187 try? await sleep(backoff + .milliseconds(Int.random(in: 0...400)))188 while !isOnline() && !Task.isCancelled { try? await sleep(timing.onlinePoll) }189 }190 }191}192193public extension Data {194 func base64URLEncodedString() -> String {195 base64EncodedString().replacingOccurrences(of: "+", with: "-").replacingOccurrences(of: "/", with: "_").replacingOccurrences(of: "=", with: "")196 }197 init?(base64URLEncoded s: String) {198 var b = s.replacingOccurrences(of: "-", with: "+").replacingOccurrences(of: "_", with: "/")199 while b.count % 4 != 0 { b.append("=") }200 self.init(base64Encoded: b)201 }202}203