SPB Git

Repository Public

QuoteStream.swift 25.7 KB 499 lines swift

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
Files main
Menu

Theme