SPB Git

Repository Public

QuoteStreamProtocol.swift 22.6 KB 466 lines swift

1// SP Wallet Core2// File: Sources/SPWalletCore/Domains/Ops/QuoteStreamProtocol.swift3// Description: Wire protocol (version 1) of the live quote stream, ported from services/api/src/quotes/protocol.ts and4//              shared.ts: channels, client and server messages, close codes, the book checksum (CRC-32), decimal comparison5//              without floats, delta application, the reconnect delay, and the freshness rule of apps/web/src/quotes.ts.6//              READ-ONLY public market data. Every price, size and rate is the server's canonical decimal STRING; a field the7//              source does not publish is nil — nothing is interpolated, defaulted or carried over.8//9// Author: Simon-Pierre Boucher10// Contact: contact@spboucher.ai11import Foundation1213public enum QuoteProtocol {14    public static let version = 115    /** The server sends a `heartbeat` frame this often; a client that sees no frame for 2.5 periods reconnects. */16    public static let heartbeatMs = 15_00017    public static let bookDepths = [5, 10, 20]18    public static let candleIntervals = ["1m", "5m", "15m", "1h", "4h", "1d"]19    /** Levels per side covered by the book checksum. */20    public static let checksumLevels = 1021    /** Channels per subscribe / unsubscribe frame accepted by the server. */22    public static let maxChannelsPerFrame = 20023    public static let path = "/api/v1/stream"2425    /** Close codes of the stream (4000–4999 is the application range of RFC 6455). */26    public enum Close {27        /** The server is shutting down or restarting: reconnect. */28        public static let goingAway = 100129        /** Frame larger than the limit. */30        public static let tooBig = 100931        /** Too many stream connections for this principal (sent when two handshakes raced past the gate). */32        public static let tryAgainLater = 101333        /** The session ended (logout, expiry, revoked device): do NOT reconnect with the same credential. */34        public static let unauthorized = 400135        public static let rateLimited = 400236        public static let slowConsumer = 400337        /** Nothing subscribed and nothing sent for the idle timeout. */38        public static let idle = 400439        public static let deadPeer = 400540        /** Protocol violation repeated. */41        public static let `protocol` = 400642    }4344    // MARK: helpers shared by value with the server (shared.ts)4546    private static let crcTable: [UInt32] = (0..<256).map { n in47        var c = UInt32(n)48        for _ in 0..<8 { c = c & 1 == 1 ? 0xedb8_8320 ^ (c >> 1) : c >> 1 }49        return c50    }51    /** CRC-32 (IEEE) of an ASCII string. */52    public static func crc32(_ s: String) -> UInt32 {53        var c: UInt32 = 0xffff_ffff54        for u in s.utf16 { c = crcTable[Int((c ^ UInt32(u)) & 0xff)] ^ (c >> 8) }55        return c ^ 0xffff_ffff56    }57    /** CRC-32 of `p:s|p:s…;p:s|…` over the best 10 levels of each side (bids first), the decimal strings exactly as sent. */58    public static func bookChecksum(bids: [StreamLevel], asks: [StreamLevel]) -> UInt32 {59        func side(_ l: [StreamLevel]) -> String { l.prefix(checksumLevels).map { "\($0.price):\($0.size)" }.joined(separator: "|") }60        return crc32("\(side(bids));\(side(asks))")61    }62    /** Compares two canonical decimal strings without a float: −1, 0 or 1. */63    public static func compareDecimal(_ a: String, _ b: String) -> Int {64        let na = a.hasPrefix("-"), nb = b.hasPrefix("-")65        if na != nb { return na ? -1 : 1 }66        func parts(_ x: Substring) -> (Substring, Substring) {67            guard let dot = x.firstIndex(of: ".") else { return (x, "") }68            return (x[..<dot], x[x.index(after: dot)...])69        }70        func magnitude(_ x: Substring, _ y: Substring) -> Int {71            let (xi, xf) = parts(x), (yi, yf) = parts(y)72            if xi.count != yi.count { return xi.count < yi.count ? -1 : 1 }73            if xi != yi { return xi < yi ? -1 : 1 }74            let n = max(xf.count, yf.count)75            let pf = xf + String(repeating: "0", count: n - xf.count), qf = yf + String(repeating: "0", count: n - yf.count)76            return pf == qf ? 0 : (pf < qf ? -1 : 1)77        }78        let r = magnitude(na ? a.dropFirst() : Substring(a), nb ? b.dropFirst() : Substring(b))79        return na ? -r : r80    }81    /** Applies a delta to one side: a size of "0" removes the price; the result is sorted (bids descending, asks ascending) and cut at `depth`. */82    public static func applyLevels(_ levels: [StreamLevel], changes: [StreamLevel], bids: Bool, depth: Int) -> [StreamLevel] {83        if changes.isEmpty { return Array(levels.prefix(depth)) }84        var order: [String] = [], sizes: [String: String] = [:]85        for l in levels { if sizes[l.price] == nil { order.append(l.price) }; sizes[l.price] = l.size }86        for c in changes {87            if c.size == "0" { sizes[c.price] = nil }88            else { if sizes[c.price] == nil, !order.contains(c.price) { order.append(c.price) }; sizes[c.price] = c.size }89        }90        let out = order.compactMap { p in sizes[p].map { StreamLevel(price: p, size: $0) } }91            .sorted { bids ? compareDecimal($0.price, $1.price) > 0 : compareDecimal($0.price, $1.price) < 0 }92        return Array(out.prefix(depth))93    }94    /** Reconnect delay in milliseconds: `min · 2^attempt` capped at `max`, with full jitter in the upper half. `random` in 0…1. */95    public static func backoffMs(attempt: Int, min: Double = 1000, max: Double = 30_000, random: Double) -> Double {96        Swift.min(max, min * pow(2, Double(Swift.min(Swift.max(attempt, 0), 16)))) * (0.5 + 0.5 * random)97    }98}99100// MARK: channels101102public enum StreamChannelType: String, Codable, Sendable, CaseIterable { case quote, book, trades, candle, status }103104/** One subscription. `id` is `venue:symbol` (`hyperliquid:BTC`, `dydx:BTC-USD`, `spot:BTC`…); for `status`, `*` or a venue id. */105public struct StreamChannel: Codable, Sendable, Hashable {106    public let type: StreamChannelType107    public let id: String108    /** Book only: levels per side (5, 10 or 20; the server's default is 20). */109    public let depth: Int?110    /** Candle only (the server's default is 1m). */111    public let interval: String?112113    public static func quote(_ id: String) -> StreamChannel { StreamChannel(type: .quote, id: id, depth: nil, interval: nil) }114    public static func book(_ id: String, depth: Int = 20) -> StreamChannel { StreamChannel(type: .book, id: id, depth: depth, interval: nil) }115    public static func trades(_ id: String) -> StreamChannel { StreamChannel(type: .trades, id: id, depth: nil, interval: nil) }116    public static func candle(_ id: String, interval: String = "1m") -> StreamChannel { StreamChannel(type: .candle, id: id, depth: nil, interval: interval) }117    public static func status(_ venue: String = "*") -> StreamChannel { StreamChannel(type: .status, id: venue, depth: nil, interval: nil) }118119    /** `type|id|param` — the identity of a subscription on both sides of the socket (`channelKey`). */120    public var key: String {121        switch type {122        case .book: "\(type.rawValue)|\(id)|\(depth ?? 20)"123        case .candle: "\(type.rawValue)|\(id)|\(interval ?? "1m")"124        default: "\(type.rawValue)|\(id)|"125        }126    }127128    /** What the server's schema accepts; a channel that fails here would be answered `bad_message` and counted as a violation. */129    public var isValid: Bool {130        let allowed = CharacterSet(charactersIn: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789*._:/[] -")131        guard !id.isEmpty, id.utf8.count <= 80, id.unicodeScalars.allSatisfy(allowed.contains) else { return false }132        if let depth, !QuoteProtocol.bookDepths.contains(depth) { return false }133        if let interval, !QuoteProtocol.candleIntervals.contains(interval) { return false }134        return true135    }136}137138/** `[price, size]` on the wire. */139public struct StreamLevel: Codable, Sendable, Hashable {140    public let price: String141    public let size: String142    public init(price: String, size: String) { self.price = price; self.size = size }143    public init(from decoder: Decoder) throws {144        var c = try decoder.unkeyedContainer()145        price = try c.decode(String.self); size = try c.decode(String.self)146    }147    public func encode(to encoder: Encoder) throws { var c = encoder.unkeyedContainer(); try c.encode(price); try c.encode(size) }148}149150public enum StreamVenueState: Sendable, Hashable, Codable {151    case connected, reconnecting, stale, down, idle152    case unknown(String)153    public var rawValue: String {154        switch self { case .connected: "connected"; case .reconnecting: "reconnecting"; case .stale: "stale"; case .down: "down"; case .idle: "idle"; case .unknown(let s): s }155    }156    public init(rawValue: String) {157        switch rawValue {158        case "connected": self = .connected; case "reconnecting": self = .reconnecting; case "stale": self = .stale159        case "down": self = .down; case "idle": self = .idle; default: self = .unknown(rawValue)160        }161    }162    public init(from decoder: Decoder) throws { self.init(rawValue: try decoder.singleValueContainer().decode(String.self)) }163    public func encode(to encoder: Encoder) throws { var c = encoder.singleValueContainer(); try c.encode(rawValue) }164    /** The venue's figures are no longer maintained. An unknown state is treated as troubled: never as healthy. */165    public var isTroubled: Bool { switch self { case .connected, .idle: false; default: true } }166}167168// MARK: server → client data169170public struct StreamQuoteMessage: Codable, Sendable, Hashable {171    public let id: String172    public let bid: String?173    public let bidSize: String?174    public let ask: String?175    public let askSize: String?176    /** (bid + ask) / 2 when the source gives both sides, else the venue's own mid; nil when it gives neither. */177    public let mid: String?178    public let mark: String?179    public let index: String?180    public let last: String?181    /** Per funding interval of the venue, as the venue publishes it. */182    public let funding: String?183    public let openInterest: String?184    /** Fraction (0.01 = 1 %). */185    public let change24h: String?186    public let volume24h: String?187    /** The venue's own timestamp (ms) of the newest part of this quote; nil when the venue gives none. */188    public let venueTs: Int64?189    /** When the server received the newest part (ms, the server's clock). */190    public let recvTs: Int64191    /** Per channel, increasing; a jump means conflated updates, never lost state. */192    public let seq: Int64193    /** `hyperliquid-ws`, `coinbase-ws`, `coingecko-rest`… */194    public let source: String195    /** The server's verdict when the frame was built. */196    public let stale: Bool197}198199public struct StreamBookMessage: Codable, Sendable, Hashable {200    public let id: String201    public let depth: Int202    /** `snapshot` (replace) or `delta` (changed prices only; a size of "0" removes the price). */203    public let kind: String204    public let bids: [StreamLevel]205    public let asks: [StreamLevel]206    public let seq: Int64207    /** A delta applies only when this is the `seq` of the last message applied. */208    public let prevSeq: Int64?209    /** CRC-32 of the best 10 levels per side AFTER this message. */210    public let checksum: UInt32211    public let venueTs: Int64?212    public let recvTs: Int64213    public let source: String214    public let stale: Bool215}216217public struct StreamTrade: Codable, Sendable, Hashable, Identifiable {218    public let id: String219    public let price: String220    public let size: String221    /** `buy` or `sell`. */222    public let side: String223    /** The venue's time of the trade (ms). */224    public let ts: Int64225}226227public struct StreamTradeMessage: Codable, Sendable, Hashable {228    public let id: String229    /** Oldest first. */230    public let trades: [StreamTrade]231    public let seq: Int64232    public let recvTs: Int64233    public let source: String234    /** True for recent history sent with a subscription (not live prints). */235    public let snapshot: Bool?236}237238public struct StreamCandleMessage: Codable, Sendable, Hashable {239    public let id: String240    public let interval: String241    /** Open time of the bar (ms); the bar is in progress until a bar with a later `ts` arrives. */242    public let ts: Int64243    public let open: String244    public let high: String245    public let low: String246    public let close: String247    public let volume: String248    public let seq: Int64249    public let recvTs: Int64250    public let source: String251}252253public struct StreamVenueStatus: Codable, Sendable, Hashable {254    public let venue: String255    public let status: StreamVenueState256    public let since: Int64257    /** Age of the last message the server received from the venue; nil before the first one. */258    public let ageMs: Int64?259    /** `stream` or `poll`. */260    public let transport: String261    public let source: String262    public let detail: String?263    public let ts: Int64264}265266public struct StreamHello: Codable, Sendable, Hashable {267    public struct Limits: Codable, Sendable, Hashable {268        public let maxSubscriptions: Int269        public let maxFrameBytes: Int270        public let maxMessagesPerSec: Int271        public let idleTimeoutMs: Int272    }273    public let connId: String274    public let heartbeatMs: Int275    public let serverTs: Int64276    public let limits: Limits277}278279public struct StreamChannelEcho: Codable, Sendable, Hashable {280    public let type: String281    public let id: String282    public let depth: Int?283    public let interval: String?284    public var key: String {285        switch type {286        case "book": "\(type)|\(id)|\(depth ?? 20)"287        case "candle": "\(type)|\(id)|\(interval ?? "1m")"288        default: "\(type)|\(id)|"289        }290    }291}292293public struct StreamSubscribed: Codable, Sendable, Hashable {294    public let channel: StreamChannelEcho295    public let key: String296    /** A quote of this channel is stale once it is older than this (re-evaluated with the client's own clock). */297    public let staleAfterMs: Int64?298    public let source: String?299    /** The last known value (a quote, a book snapshot, a trade batch, a candle, or the status list); nil when nothing was received yet. */300    public let snapshot: JSONValue?301    public let snapshotAgeMs: Int64?302}303304/** An `error` frame. Stable codes: bad_frame, bad_message, unsupported_version, unknown_instrument, unsupported_channel, restricted, too_many_subscriptions, rate_limited, upstream_unavailable, internal. */305public struct StreamErrorMessage: Codable, Sendable, Hashable {306    public let code: String307    public let message: String308    public let channel: StreamChannelEcho?309    /** These codes mean the channel will never be served on this connection or the next: it is not subscribed again. */310    public var isPermanentForChannel: Bool { ["unknown_instrument", "unsupported_channel", "restricted"].contains(code) }311}312313/** One decoded server frame. */314public enum StreamServerMessage: Sendable, Hashable, Decodable {315    case hello(StreamHello)316    case subscribed(StreamSubscribed)317    case unsubscribed(key: String)318    case quote(StreamQuoteMessage)319    case book(StreamBookMessage)320    case trade(StreamTradeMessage)321    case candle(StreamCandleMessage)322    case status(StreamVenueStatus)323    /** Trades the server did NOT send because this client is slow. */324    case dropped(id: String, count: Int, total: Int)325    case heartbeat(ts: Int64, subscriptions: Int)326    case pong(t: Double?, ts: Int64)327    case error(StreamErrorMessage)328    /** A frame type added by a newer server: ignored, never guessed at. */329    case unknown(String)330331    private enum Keys: String, CodingKey { case v, type, key, id, count, total, ts, subscriptions, t }332333    public init(from decoder: Decoder) throws {334        let c = try decoder.container(keyedBy: Keys.self)335        let v = try c.decode(Int.self, forKey: .v)336        guard v == QuoteProtocol.version else { throw DecodingError.dataCorruptedError(forKey: .v, in: c, debugDescription: "protocol version \(v)") }337        let type = try c.decode(String.self, forKey: .type)338        switch type {339        case "hello": self = .hello(try StreamHello(from: decoder))340        case "subscribed": self = .subscribed(try StreamSubscribed(from: decoder))341        case "unsubscribed": self = .unsubscribed(key: try c.decode(String.self, forKey: .key))342        case "quote": self = .quote(try StreamQuoteMessage(from: decoder))343        case "book": self = .book(try StreamBookMessage(from: decoder))344        case "trade": self = .trade(try StreamTradeMessage(from: decoder))345        case "candle": self = .candle(try StreamCandleMessage(from: decoder))346        case "status": self = .status(try StreamVenueStatus(from: decoder))347        case "dropped": self = .dropped(id: try c.decode(String.self, forKey: .id), count: try c.decode(Int.self, forKey: .count), total: try c.decode(Int.self, forKey: .total))348        case "heartbeat": self = .heartbeat(ts: try c.decode(Int64.self, forKey: .ts), subscriptions: try c.decode(Int.self, forKey: .subscriptions))349        case "pong": self = .pong(t: try c.decodeIfPresent(Double.self, forKey: .t), ts: try c.decode(Int64.self, forKey: .ts))350        case "error": self = .error(try StreamErrorMessage(from: decoder))351        default: self = .unknown(type)352        }353    }354355    public static func decode(_ text: String) throws -> StreamServerMessage { try JSONDecoder().decode(StreamServerMessage.self, from: Data(text.utf8)) }356}357358// MARK: client → server359360enum StreamClientMessage: Encodable, Sendable {361    case subscribe([StreamChannel])362    case unsubscribe([StreamChannel])363    case ping(t: Double)364365    private enum Keys: String, CodingKey { case v, op, channels, t }366    func encode(to encoder: Encoder) throws {367        var c = encoder.container(keyedBy: Keys.self)368        try c.encode(QuoteProtocol.version, forKey: .v)369        switch self {370        case .subscribe(let ch): try c.encode("subscribe", forKey: .op); try c.encode(ch, forKey: .channels)371        case .unsubscribe(let ch): try c.encode("unsubscribe", forKey: .op); try c.encode(ch, forKey: .channels)372        case .ping(let t): try c.encode("ping", forKey: .op); try c.encode(t, forKey: .t)373        }374    }375    var text: String { String(decoding: (try? APICoding.encoder().encode(self)) ?? Data(), as: UTF8.self) }376}377378// MARK: what the client holds, with its freshness379380/** The state of the client's own connection. */381public enum QuoteStreamState: Sendable, Hashable {382    /** Not started, stopped, or closed by the server for being idle. */383    case idle384    case connecting385    /** Greeted by the server (`hello`): subscriptions are (re)sent and data flows. */386    case live387    /** The connection was lost; a new attempt is scheduled after `delayMs`. Everything held is no longer maintained. */388    case reconnecting(attempt: Int, delayMs: Int)389    /** The stream will not reconnect by itself. */390    case ended(QuoteStreamEnd)391}392393public enum QuoteStreamEnd: Sendable, Hashable {394    /** No session token: nothing was sent. */395    case signedOut396    /** The server closed with 4001 or refused the handshake with 401: the session ended. Re-check the session; never retry with the same credential. */397    case unauthorized398    /** The handshake was refused for a reason a retry cannot fix (403: `origin_refused`). */399    case refused(status: Int)400}401402public enum StreamFreshnessState: String, Sendable, Codable { case live, delayed, stale, reconnecting, none }403404/** live / delayed / stale / reconnecting for one value, with its age — the server's verdict AND this device's clock (`freshnessOf`). */405public struct StreamFreshness: Sendable, Hashable {406    public let state: StreamFreshnessState407    public let ageMs: Int64?408    /** Only `live` may be presented as a live figure. */409    public var isLive: Bool { state == .live }410411    /** Shown as « delayed » past this age, before the source's own staleness bound. */412    public static let delayedAfterMs: Int64 = 5000413414    /**415     - Parameters:416       - freshAt: when the figure was fresh on THIS clock (arrival, minus the snapshot's age and the source's own lag); nil when there is no value.417       - serverStale: the `stale` flag of the frame.418       - staleAfterMs: the cadence of the source (`subscribed.staleAfterMs`); 30 s when the server gave none.419       - venue: the state of the value's upstream as the server reports it.420     A stream that is not live never yields `live`; one that ended or was stopped yields `stale` at once.421     */422    public static func evaluate(freshAt: Date?, serverStale: Bool, staleAfterMs: Int64?, connection: QuoteStreamState, now: Date, venue: StreamVenueState? = nil) -> StreamFreshness {423        let isLive = connection == .live424        guard let freshAt else {425            switch connection { case .connecting, .reconnecting: return StreamFreshness(state: .reconnecting, ageMs: nil); default: return StreamFreshness(state: .none, ageMs: nil) }426        }427        let age = max(0, Int64((now.timeIntervalSince(freshAt) * 1000).rounded())), bound = staleAfterMs ?? 30_000, troubled = venue?.isTroubled ?? false428        if age > bound || (serverStale && isLive && !troubled) { return StreamFreshness(state: .stale, ageMs: age) }429        switch connection {430        case .idle, .ended: return StreamFreshness(state: .stale, ageMs: age) // nobody is coming back for this figure431        case .connecting, .reconnecting: return StreamFreshness(state: .reconnecting, ageMs: age)432        case .live: break433        }434        if troubled { return StreamFreshness(state: .reconnecting, ageMs: age) }435        return StreamFreshness(state: age > min(delayedAfterMs, bound / 2) ? .delayed : .live, ageMs: age)436    }437}438439/** A quote as received, plus when it was fresh on this device's clock. It is never a live figure by itself: ask `freshness`. */440public struct LiveQuote: Sendable, Hashable {441    public let quote: StreamQuoteMessage442    /** Arrival on this clock, minus the snapshot's age and minus the lag the server measured between the source's own date and its receipt. */443    public let freshAt: Date444    public let staleAfterMs: Int64?445    public var id: String { quote.id }446    public var venue: String { String(quote.id.prefix { $0 != ":" }) }447448    public func freshness(connection: QuoteStreamState, now: Date, venue: StreamVenueState? = nil) -> StreamFreshness {449        .evaluate(freshAt: freshAt, serverStale: quote.stale, staleAfterMs: staleAfterMs, connection: connection, now: now, venue: venue)450    }451}452453/** A book the client rebuilt: only produced when every delta applied in sequence and the checksum matched. */454public struct LiveBook: Sendable, Hashable {455    public let id: String456    public let depth: Int457    public let bids: [StreamLevel]458    public let asks: [StreamLevel]459    public let seq: Int64460    public let freshAt: Date461    public let venueTs: Int64?462    public let source: String463    public let stale: Bool464    public var key: String { "book|\(id)|\(depth)" }465}466
Files main
Menu

Theme