Repository Public
1// SP Wallet Core2// File: Sources/SPWalletCore/Domains/Ops/QuoteStream.swift3// Description: Client of the owner's live quote websocket (GET /api/v1/stream, services/api/src/quotes/engine.ts), the native4// counterpart of apps/web/src/quotes.ts. It connects with the session `Cookie` and the wallet's `Origin` (the5// server refuses any other origin), waits for `hello`, subscribes (venue statuses always come along), applies6// book deltas only in sequence and only when the checksum matches, watches the heartbeat (no frame for 2.57// periods → reconnect), reconnects with capped exponential backoff and jitter, subscribes again, and STOPS for8// good when the server says the session ended (close 4001 / handshake 401).9// Nothing here invents a figure. A value held while the stream is down is no longer maintained: it keeps its10// `freshAt` timestamp, `freshness` stops answering `live` at once, and a `.stale` event names what is affected.11// READ-ONLY public market data: nothing in this file can place, sign or cancel anything.12//13// Author: Simon-Pierre Boucher14// Contact: contact@spboucher.ai15import Foundation1617// MARK: the socket, behind a protocol (URLSessionWebSocketTask in the apps, a scripted socket in tests)1819public enum QuoteSocketError: Error, Sendable, Equatable {20 /** The peer closed (or the socket was closed locally) with this code. */21 case closed(code: Int, reason: String?)22 /** The HTTP upgrade was answered with this status instead of 101 (401, 403 `origin_refused`, 429 `too_many_connections`, 503). */23 case handshake(status: Int)24 /** No frame for 2.5 heartbeat periods: the connection is considered frozen. */25 case watchdog26 case transport(String)27}2829public protocol QuoteSocket: Sendable {30 func send(_ text: String) async throws31 /** The next TEXT frame. Throws `QuoteSocketError` when the socket closes or fails; must return (by throwing) once `close` was called. */32 func receive() async throws -> String33 func close(code: Int, reason: String?)34}3536public protocol QuoteSocketConnecting: Sendable {37 /** Starts the handshake of `request`. A refused handshake may be reported here or by the first `receive()`. */38 func connect(_ request: URLRequest) async throws -> any QuoteSocket39}4041/** URLSession without a cookie jar or a cache, TLS 1.2+, that never follows a redirect (a redirect could carry the session elsewhere). */42public final class URLSessionQuoteSocketConnector: NSObject, QuoteSocketConnecting, URLSessionTaskDelegate, @unchecked Sendable {43 private var session: URLSession!4445 public override init() {46 super.init()47 let c = URLSessionConfiguration.ephemeral48 c.httpCookieStorage = nil49 c.httpShouldSetCookies = false50 c.httpCookieAcceptPolicy = .never51 c.urlCache = nil52 c.urlCredentialStorage = nil53 c.tlsMinimumSupportedProtocolVersion = .TLSv1254 c.waitsForConnectivity = false55 session = URLSession(configuration: c, delegate: self, delegateQueue: nil)56 }5758 public func connect(_ request: URLRequest) async throws -> any QuoteSocket {59 let task = session.webSocketTask(with: request)60 task.maximumMessageSize = 4 * 1024 * 102461 task.resume()62 return Socket(task: task)63 }6465 public func urlSession(_ session: URLSession, task: URLSessionTask, willPerformHTTPRedirection response: HTTPURLResponse,66 newRequest request: URLRequest) async -> URLRequest? { nil }6768 private struct Socket: QuoteSocket {69 let task: URLSessionWebSocketTask7071 func send(_ text: String) async throws {72 do { try await task.send(.string(text)) } catch { throw failure(error) }73 }74 func receive() async throws -> String {75 while true {76 let m: URLSessionWebSocketTask.Message77 do { m = try await task.receive() } catch { throw failure(error) }78 // the protocol is JSON text frames only; a binary frame is not part of it and is skipped79 if case .string(let s) = m { return s }80 }81 }82 func close(code: Int, reason: String?) {83 task.cancel(with: URLSessionWebSocketTask.CloseCode(rawValue: code) ?? .normalClosure, reason: reason.map { Data($0.utf8) })84 }85 private func failure(_ error: Error) -> QuoteSocketError {86 if task.closeCode != .invalid { return .closed(code: task.closeCode.rawValue, reason: task.closeReason.flatMap { String(data: $0, encoding: .utf8) }) }87 if let http = task.response as? HTTPURLResponse, http.statusCode != 101 { return .handshake(status: http.statusCode) }88 return .transport(error.localizedDescription)89 }90 }91}9293// MARK: events9495public enum QuoteStreamEvent: Sendable, Hashable {96 case state(QuoteStreamState)97 case hello(StreamHello)98 /** The server accepted the channel; its snapshot (if any) follows as data events. */99 case subscribed(key: String, staleAfterMs: Int64?, source: String?)100 case unsubscribed(key: String)101 case quote(LiveQuote)102 case book(LiveBook)103 /** New trades of a market, oldest first; `history` is true for the recent prints sent with a subscription. */104 case trades(id: String, trades: [StreamTrade], history: Bool)105 case candle(StreamCandleMessage, freshAt: Date)106 case venue(StreamVenueStatus)107 /** Trades the server did not send because this client was slow. */108 case tradesDropped(id: String, count: Int, total: Int)109 /** The local book had a hole or a wrong checksum: it is not patched until the fresh snapshot that was just asked for arrives. */110 case bookResync(key: String)111 /** An `error` frame of the server (a refused channel carries it in `channel`). */112 case error(StreamErrorMessage)113 case heartbeat(subscriptions: Int)114 case pong(t: Double?)115 /** The socket closed with this code (see `QuoteProtocol.Close`). A `.state` event follows. */116 case closed(code: Int)117 /** These keys (`quote|…`, `book|…`, `candle|…`) are no longer maintained: the stream is down or ended. Whatever is on screen must stop saying « live ». */118 case stale(keys: [String])119}120121public enum QuoteStreamError: Error, Sendable, Equatable {122 case invalidChannel(String)123 /** The connection's subscription limit (the server's `hello.limits.maxSubscriptions`, 300 by default; one is taken by the venue statuses). */124 case tooManySubscriptions(limit: Int)125}126127// MARK: the client128129public actor QuoteStream {130 public struct Options: Sendable {131 public var backoffMinMs: Double = 1000132 public var backoffMaxMs: Double = 30_000133 /** No frame for `heartbeatMs × watchdogFactor` → the connection is considered frozen and re-opened. */134 public var watchdogFactor: Double = 2.5135 /** Used until `hello` gives the server's own period. */136 public var heartbeatMs: Int = QuoteProtocol.heartbeatMs137 /** Assumed until `hello` gives the server's own limits. */138 public var maxSubscriptions: Int = 300139 public var maxMessagesPerSec: Int = 20140 /** Channels per subscribe frame (the server accepts 200 and 16 KiB per frame). */141 public var channelsPerFrame: Int = 100142 /** Trade ids remembered per market to drop duplicates across snapshots. */143 public var tradesKept: Int = 60144 public init() {}145 }146147 /** Clock, randomness and sleeping, replaceable in tests. */148 public struct Environment: Sendable {149 public var now: @Sendable () -> Date150 /** Uniform in 0…1 (the jitter of the reconnect delay). */151 public var random: @Sendable () -> Double152 public var sleep: @Sendable (Duration) async throws -> Void153 public init(now: @escaping @Sendable () -> Date = { Date() }, random: @escaping @Sendable () -> Double = { Double.random(in: 0...1) },154 sleep: @escaping @Sendable (Duration) async throws -> Void = { try await Task.sleep(for: $0) }) {155 self.now = now; self.random = random; self.sleep = sleep156 }157 }158159 private struct BookState { var bids: [StreamLevel]; var asks: [StreamLevel]; var seq: Int64; var awaiting: Bool }160161 private let client: APIClient162 private let connector: any QuoteSocketConnecting163 private let options: Options164 private let env: Environment165166 private var continuations: [UUID: AsyncStream<QuoteStreamEvent>.Continuation] = [:]167 private var order: [String] = [] // keys, in the order they were first subscribed168 private var desired: [String: StreamChannel] = [:]169 private var refused: [String: String] = [:] // key → the server's error code170 private var staleAfter: [String: Int64] = [:]171 private var quotes: [String: LiveQuote] = [:]172 private var books: [String: BookState] = [:]173 private var liveBooks: [String: LiveBook] = [:]174 private var candles: [String: Date] = [:]175 private var tradeIds: [String: [String]] = [:]176 private var statuses: [String: StreamVenueStatus] = [:]177 private var hello: StreamHello?178 private var socket: (any QuoteSocket)?179 private var runTask: Task<Void, Never>?180 private var sessionTask: Task<Void, Never>?181 private var generation = 0182 private var attempt = 0183 private var sendTimes: [Date] = []184 public private(set) var state: QuoteStreamState = .idle185186 public init(client: APIClient, connector: any QuoteSocketConnecting = URLSessionQuoteSocketConnector(), options: Options = Options(), environment: Environment = Environment()) {187 self.client = client; self.connector = connector; self.options = options; self.env = environment188 }189190 deinit { runTask?.cancel(); sessionTask?.cancel(); socket?.close(code: 1000, reason: nil) }191192 // MARK: reading193194 /** Every event from now on. Several consumers may each hold their own stream. */195 public func events() -> AsyncStream<QuoteStreamEvent> {196 let id = UUID()197 return AsyncStream(bufferingPolicy: .bufferingNewest(2048)) { c in198 continuations[id] = c199 c.onTermination = { [weak self] _ in Task { await self?.drop(id) } }200 }201 }202 private func drop(_ id: UUID) { continuations[id] = nil }203 private func emit(_ e: QuoteStreamEvent) { for c in continuations.values { c.yield(e) } }204 private func set(_ s: QuoteStreamState) { if state != s { state = s; emit(.state(s)) } }205206 /** The last quote received for a market, with its freshness NOW. A quote held while the stream is down never reads `live`. */207 public func quote(_ id: String) -> (quote: LiveQuote, freshness: StreamFreshness)? {208 guard let q = quotes["quote|\(id)|"] else { return nil }209 return (q, q.freshness(connection: state, now: env.now(), venue: statuses[q.venue]?.status))210 }211 /** The rebuilt book; nil while it waits for a snapshot (after a hole, a checksum failure or a reconnection). */212 public func book(_ id: String, depth: Int = 20) -> (book: LiveBook, freshness: StreamFreshness)? {213 let key = "book|\(id)|\(depth)"214 guard let b = liveBooks[key], books[key]?.awaiting == false else { return nil }215 let venue = statuses[String(id.prefix { $0 != ":" })]?.status216 return (b, .evaluate(freshAt: b.freshAt, serverStale: b.stale, staleAfterMs: staleAfter[key], connection: state, now: env.now(), venue: venue))217 }218 public func venueStatuses() -> [String: StreamVenueStatus] { statuses }219 /** Why the server refused this channel (`unknown_instrument`, `unsupported_channel`, `restricted`), or nil. */220 public func refusal(of channel: StreamChannel) -> String? { refused[channel.key] }221 public func subscriptions() -> [StreamChannel] { order.compactMap { desired[$0] } }222 /** The limits the server announced in `hello`; nil before the first connection. */223 public func serverLimits() -> StreamHello.Limits? { hello?.limits }224225 // MARK: subscriptions226227 /** Subscribe (idempotent per channel) and start the stream if it is idle (not after `.ended`). The venue statuses (`status|*|`) are always subscribed. */228 public func subscribe(_ channels: [StreamChannel]) throws {229 var fresh: [StreamChannel] = []230 for ch in channels where ch.type != .status {231 guard ch.isValid else { throw QuoteStreamError.invalidChannel(ch.key) }232 if desired[ch.key] == nil, !fresh.contains(ch) { fresh.append(ch) }233 }234 let limit = hello?.limits.maxSubscriptions ?? options.maxSubscriptions235 guard desired.count + fresh.count + 1 <= limit else { throw QuoteStreamError.tooManySubscriptions(limit: limit) }236 for ch in fresh { desired[ch.key] = ch; order.append(ch.key); refused[ch.key] = nil }237 if state == .live, !fresh.isEmpty { let g = generation; Task { await self.sendSubscribe(fresh, generation: g) } }238 // after the server ended the session nothing reconnects by itself: `start()` is called once the owner has signed in again239 if case .ended = state { return }240 start()241 }242243 public func unsubscribe(_ channels: [StreamChannel]) {244 var gone: [StreamChannel] = []245 for ch in channels where desired[ch.key] != nil {246 let k = ch.key247 desired[k] = nil; order.removeAll { $0 == k }; refused[k] = nil; staleAfter[k] = nil248 quotes[k] = nil; books[k] = nil; liveBooks[k] = nil; candles[k] = nil; tradeIds[k] = nil249 gone.append(ch)250 }251 guard state == .live, !gone.isEmpty else { return }252 let g = generation253 Task { await self.sendFrames(gone, generation: g) { .unsubscribe(Array($0)) } }254 }255256 /** An application ping; the server answers `pong` with the same `t`. Also what keeps a connection without subscription from being closed as idle. */257 public func ping() async {258 guard state == .live else { return }259 await send(.ping(t: (env.now().timeIntervalSince1970 * 1000).rounded()), generation: generation)260 }261262 // MARK: lifecycle263264 /** Connect (no-op when already running). After `.ended`, call it again once the owner has signed in. */265 public func start() {266 guard runTask == nil else { return }267 generation += 1268 let g = generation269 attempt = 0270 if sessionTask == nil {271 // the session ended elsewhere (lock, or an API call answered « unauthenticated »): close now, do not knock at a door that answers 401272 sessionTask = Task { [weak self, client] in273 for await e in await client.events() {274 guard let self else { return }275 if e == .unauthenticated || e == .signedOut { await self.sessionEnded() }276 }277 }278 }279 runTask = Task { await self.run(g) }280 }281282 /** Close cleanly (code 1000) and stay idle. Subscriptions are kept for the next `start()`; what is held turns stale at once. */283 public func stop() { halt(.idle) }284285 /** The owner's session ended: close and do not reconnect. */286 public func sessionEnded() { if runTask != nil || state == .live { halt(.ended(.unauthorized)) } }287288 private func halt(_ s: QuoteStreamState) {289 generation += 1290 runTask?.cancel(); runTask = nil291 socket?.close(code: 1000, reason: nil); socket = nil292 hello = nil293 markStale()294 set(s)295 }296297 /** What is held is no longer maintained: books must restart from a snapshot, quotes keep their age and stop reading `live`. */298 private func markStale() {299 for k in books.keys { books[k]?.awaiting = true }300 let keys = order.filter { quotes[$0] != nil || liveBooks[$0] != nil || candles[$0] != nil }301 if !keys.isEmpty { emit(.stale(keys: keys)) }302 }303304 private func run(_ g: Int) async {305 var tried = false306 while g == generation, !Task.isCancelled {307 guard let cookie = await client.cookieHeader() else { finish(g, .ended(.signedOut)); return }308 if !tried { set(.connecting) }309 tried = true310 var failure: QuoteSocketError311 do {312 let s = try await connector.connect(request(cookie: cookie))313 guard g == generation else { s.close(code: 1000, reason: nil); return }314 socket = s315 failure = await pump(s, g)316 } catch let e as QuoteSocketError { failure = e }317 catch is CancellationError { return }318 catch { failure = .transport(String(describing: error)) }319 guard g == generation, !Task.isCancelled else { return }320 socket = nil; hello = nil321322 switch failure {323 case .closed(let code, _):324 emit(.closed(code: code))325 if code == QuoteProtocol.Close.unauthorized { finish(g, .ended(.unauthorized)); return }326 if code == QuoteProtocol.Close.idle, desired.isEmpty { finish(g, .idle); return }327 case .handshake(let status):328 if status == 401 { finish(g, .ended(.unauthorized)); return }329 if status == 403 { finish(g, .ended(.refused(status: status))); return }330 case .watchdog, .transport: break331 }332 markStale()333 let delay = QuoteProtocol.backoffMs(attempt: attempt, min: options.backoffMinMs, max: options.backoffMaxMs, random: min(max(env.random(), 0), 1))334 attempt += 1335 set(.reconnecting(attempt: attempt, delayMs: Int(delay.rounded())))336 do { try await env.sleep(.milliseconds(Int(delay.rounded()))) } catch { return }337 }338 }339340 private func finish(_ g: Int, _ s: QuoteStreamState) {341 guard g == generation else { return }342 runTask = nil; socket = nil; hello = nil343 markStale()344 set(s)345 }346347 private func request(cookie: String) -> URLRequest {348 let cfg = client.configuration349 var req = URLRequest(url: cfg.webSocketOrigin.appendingPathComponent(QuoteProtocol.path))350 req.httpShouldHandleCookies = false351 req.setValue(cookie, forHTTPHeaderField: "Cookie")352 // the CSRF defence of a websocket: the server compares this header with its own origin, exactly353 req.setValue(cfg.originHeader, forHTTPHeaderField: "Origin")354 req.setValue(cfg.userAgent, forHTTPHeaderField: "User-Agent")355 return req356 }357358 /** Reads frames until the socket fails; returns why. */359 private func pump(_ s: any QuoteSocket, _ g: Int) async -> QuoteSocketError {360 while g == generation, !Task.isCancelled {361 let timeout = Duration.milliseconds(Int((Double(hello?.heartbeatMs ?? options.heartbeatMs) * options.watchdogFactor).rounded()))362 let text: String363 do { text = try await Self.receive(s, timeout: timeout, sleep: env.sleep) }364 catch let e as QuoteSocketError { return e }365 catch { return .transport(String(describing: error)) }366 guard g == generation else { break }367 await handle(text, g)368 }369 return .transport("stopped")370 }371372 private static func receive(_ s: any QuoteSocket, timeout: Duration, sleep: @escaping @Sendable (Duration) async throws -> Void) async throws -> String {373 try await withThrowingTaskGroup(of: String?.self) { group in374 group.addTask { try await s.receive() }375 group.addTask { try await sleep(timeout); return nil }376 defer { group.cancelAll() }377 do {378 if let first = try await group.next(), let text = first { return text }379 } catch { s.close(code: 1000, reason: nil); throw error }380 s.close(code: 1000, reason: "no frame from the server") // ends the pending receive381 throw QuoteSocketError.watchdog382 }383 }384385 // MARK: sending386387 private func send(_ m: StreamClientMessage, generation g: Int) async {388 // the server allows `maxMessagesPerSec` frames a second (burst twice that) and closes after repeated violations: stay under it389 let limit = max(1, hello?.limits.maxMessagesPerSec ?? options.maxMessagesPerSec)390 while g == generation {391 let now = env.now()392 sendTimes.removeAll { now.timeIntervalSince($0) >= 1 }393 if sendTimes.count < limit { break }394 do { try await env.sleep(.milliseconds(50)) } catch { return }395 }396 guard g == generation, let s = socket else { return }397 sendTimes.append(env.now())398 try? await s.send(m.text) // a failed send is followed by a failed receive, which reconnects399 }400 private func sendFrames(_ channels: [StreamChannel], generation g: Int, _ make: (ArraySlice<StreamChannel>) -> StreamClientMessage) async {401 var i = 0402 let n = min(max(options.channelsPerFrame, 1), QuoteProtocol.maxChannelsPerFrame)403 while i < channels.count { await send(make(channels[i..<min(i + n, channels.count)]), generation: g); i += n }404 }405 private func sendSubscribe(_ channels: [StreamChannel], generation g: Int) async {406 await sendFrames(channels, generation: g) { .subscribe(Array($0)) }407 }408409 // MARK: frames410411 private func handle(_ text: String, _ g: Int) async {412 guard let m = try? StreamServerMessage.decode(text) else { return } // not JSON, another protocol version, or a malformed frame: ignored, never guessed at413 let now = env.now()414 switch m {415 case .hello(let h):416 hello = h; attempt = 0417 set(.live)418 emit(.hello(h))419 // the venue statuses always come along: a figure must be able to say that its venue is reconnecting420 await sendSubscribe([.status()] + order.compactMap { refused[$0] == nil ? desired[$0] : nil }, generation: g)421 case .subscribed(let s):422 emit(.subscribed(key: s.key, staleAfterMs: s.staleAfterMs, source: s.source))423 if s.key.hasPrefix("status|") {424 for v in (try? s.snapshot?.decode([StreamVenueStatus].self)) ?? [] { statuses[v.venue] = v; emit(.venue(v)) }425 return426 }427 guard let ch = desired[s.key] else { return }428 staleAfter[s.key] = s.staleAfterMs429 let at = now.addingTimeInterval(-Double(s.snapshotAgeMs ?? 0) / 1000)430 let snap = s.snapshot.flatMap { $0.isNull ? nil : $0 }431 if ch.type == .book, books[s.key] != nil { books[s.key]?.awaiting = snap == nil }432 guard let snap else { return }433 for part in snap.arrayValue ?? [snap] { if let d = try? part.decode(StreamServerMessage.self) { await data(d, at: at, g) } }434 case .unsubscribed(let key): emit(.unsubscribed(key: key))435 case .error(let e):436 if let ch = e.channel, e.isPermanentForChannel, desired[ch.key] != nil { refused[ch.key] = e.code }437 emit(.error(e))438 case .dropped(let id, let count, let total): emit(.tradesDropped(id: id, count: count, total: total))439 case .heartbeat(_, let n): emit(.heartbeat(subscriptions: n))440 case .pong(let t, _): emit(.pong(t: t))441 case .unknown: break442 default: await data(m, at: now, g)443 }444 }445446 private func data(_ m: StreamServerMessage, at: Date, _ g: Int) async {447 switch m {448 case .quote(let q):449 let key = "quote|\(q.id)|"450 guard desired[key] != nil else { return }451 // the age of the FIGURE on this clock: arrival, minus what the server measured between the source's own date and its receipt452 let lag = q.venueTs.map { max(0, q.recvTs - $0) } ?? 0453 let live = LiveQuote(quote: q, freshAt: at.addingTimeInterval(-Double(lag) / 1000), staleAfterMs: staleAfter[key])454 quotes[key] = live455 emit(.quote(live))456 case .book(let b):457 let key = "book|\(b.id)|\(b.depth)"458 guard let ch = desired[key] else { return }459 var st: BookState460 if b.kind == "snapshot" { st = BookState(bids: b.bids, asks: b.asks, seq: b.seq, awaiting: false) }461 else if b.kind == "delta" {462 guard let cur = books[key], !cur.awaiting else { return } // waiting for the snapshot it asked for463 guard b.prevSeq == cur.seq else { await resync(key, ch, g); return } // a hole: never patch across it464 st = BookState(bids: QuoteProtocol.applyLevels(cur.bids, changes: b.bids, bids: true, depth: b.depth),465 asks: QuoteProtocol.applyLevels(cur.asks, changes: b.asks, bids: false, depth: b.depth), seq: b.seq, awaiting: false)466 } else { return }467 books[key] = st468 guard QuoteProtocol.bookChecksum(bids: st.bids, asks: st.asks) == b.checksum else { await resync(key, ch, g); return }469 let live = LiveBook(id: b.id, depth: b.depth, bids: st.bids, asks: st.asks, seq: st.seq, freshAt: at, venueTs: b.venueTs, source: b.source, stale: b.stale)470 liveBooks[key] = live471 emit(.book(live))472 case .trade(let t):473 let key = "trades|\(t.id)|"474 guard desired[key] != nil else { return }475 let seen = Set(tradeIds[key] ?? [])476 let fresh = t.trades.filter { !seen.contains($0.id) }477 guard !fresh.isEmpty else { return }478 tradeIds[key] = Array(((tradeIds[key] ?? []) + fresh.map(\.id)).suffix(options.tradesKept))479 emit(.trades(id: t.id, trades: fresh, history: t.snapshot == true))480 case .candle(let c):481 let key = "candle|\(c.id)|\(c.interval)"482 guard desired[key] != nil else { return }483 candles[key] = at484 emit(.candle(c, freshAt: at))485 case .status(let v):486 statuses[v.venue] = v487 emit(.venue(v))488 default: break489 }490 }491492 /** The local book can no longer be trusted: it is withheld until the snapshot asked for here arrives (subscribing again = « send the snapshot again »). */493 private func resync(_ key: String, _ ch: StreamChannel, _ g: Int) async {494 books[key]?.awaiting = true495 emit(.bookResync(key: key))496 await sendSubscribe([ch], generation: g)497 }498}499