Repository Public
1// SP Wallet Core2// File: Tests/SPWalletCoreTests/QuoteStreamTests.swift3// Description: The live quote stream against a scripted socket (no network): handshake headers, hello → subscribe, snapshots4// and deltas with the checksum, heartbeat timeout → reconnect → resubscribe, the session-ended close code (no5// reconnect), staleness, limits; and the helpers shared with the server against vectors generated from6// services/api/src/quotes/shared.ts. Frame shapes are those of services/api/src/quotes/protocol.ts and of the7// scripted frames of apps/web/test/quotes.test.ts.8//9// Author: Simon-Pierre Boucher10// Contact: contact@spboucher.ai11import Foundation12import Testing13@testable import SPWalletCore1415// MARK: scripted socket1617private final class FakeSocket: QuoteSocket, @unchecked Sendable {18 private let lock = NSLock()19 private var queue: [Result<String, QuoteSocketError>] = []20 private var waiter: CheckedContinuation<String, Error>?21 private var _sent: [JSONValue] = []22 private var _closedByClient: Int?2324 var sent: [JSONValue] { lock.withLock { _sent } }25 var closedByClient: Int? { lock.withLock { _closedByClient } }2627 func send(_ text: String) async throws { let v = try JSONDecoder().decode(JSONValue.self, from: Data(text.utf8)); lock.withLock { _sent.append(v) } }28 func receive() async throws -> String {29 try await withCheckedThrowingContinuation { c in30 let ready: Result<String, QuoteSocketError>? = lock.withLock { if queue.isEmpty { waiter = c; return nil }; return queue.removeFirst() }31 if let ready { c.resume(with: ready.mapError { $0 as Error }) }32 }33 }34 func close(code: Int, reason: String?) { lock.withLock { if _closedByClient == nil { _closedByClient = code } }; push(.failure(.closed(code: code, reason: reason))) }3536 private func push(_ r: Result<String, QuoteSocketError>) {37 let w: CheckedContinuation<String, Error>? = lock.withLock { if let w = waiter { waiter = nil; return w }; queue.append(r); return nil }38 w?.resume(with: r.mapError { $0 as Error })39 }40 /** a frame from the server */41 func serve(_ json: String) { push(.success(json)) }42 func serverCloses(_ code: Int) { push(.failure(.closed(code: code, reason: nil))) }43 func fail(_ e: QuoteSocketError) { push(.failure(e)) }44}4546private final class FakeConnector: QuoteSocketConnecting, @unchecked Sendable {47 private let lock = NSLock()48 private var _requests: [URLRequest] = [], _sockets: [FakeSocket] = [], refusals: [QuoteSocketError] = []49 var requests: [URLRequest] { lock.withLock { _requests } }50 var sockets: [FakeSocket] { lock.withLock { _sockets } }51 func refuseNext(_ e: QuoteSocketError) { lock.withLock { refusals.append(e) } }52 func connect(_ request: URLRequest) async throws -> any QuoteSocket {53 let r: Result<FakeSocket, QuoteSocketError> = lock.withLock {54 _requests.append(request)55 if !refusals.isEmpty { return .failure(refusals.removeFirst()) }56 let s = FakeSocket(); _sockets.append(s); return .success(s)57 }58 return try r.get()59 }60}6162private struct Timeout: Error {}63/** Polls a condition (the client runs on its own tasks). */64private func eventually(_ what: String, timeout: Double = 5, _ cond: @Sendable () async -> Bool) async throws {65 let end = Date().addingTimeInterval(timeout)66 while Date() < end { if await cond() { return }; try await Task.sleep(for: .milliseconds(5)) }67 Issue.record("timed out waiting for: \(what)"); throw Timeout()68}6970private final class Recorder: @unchecked Sendable {71 private let lock = NSLock()72 private var _events: [QuoteStreamEvent] = []73 var events: [QuoteStreamEvent] { lock.withLock { _events } }74 func add(_ e: QuoteStreamEvent) { lock.withLock { _events.append(e) } }75 var states: [QuoteStreamState] { events.compactMap { if case .state(let s) = $0 { s } else { nil } } }76 func has(_ e: QuoteStreamEvent) -> Bool { events.contains(e) }77}7879private func hello(heartbeatMs: Int = 15000, maxSubscriptions: Int = 300) -> String {80 #"{"v":1,"type":"hello","connId":"c0ffee","heartbeatMs":\#(heartbeatMs),"serverTs":1795000000000,"limits":{"maxSubscriptions":\#(maxSubscriptions),"maxFrameBytes":16384,"maxMessagesPerSec":20,"idleTimeoutMs":120000}}"#81}82private func quote(_ id: String, mid: String, seq: Int, stale: Bool = false, venueTs: String = "null", recvTs: Int64 = 1_795_000_000_000) -> String {83 #"{"v":1,"type":"quote","id":"\#(id)","bid":"\#(mid)","bidSize":"1.5","ask":null,"askSize":null,"mid":"\#(mid)","mark":null,"index":null,"last":null,"funding":"0.0000125","openInterest":null,"change24h":"-0.0123","volume24h":null,"venueTs":\#(venueTs),"recvTs":\#(recvTs),"seq":\#(seq),"source":"hyperliquid-ws","stale":\#(stale)}"#84}85private func subscribed(_ key: String, type: String, id: String, snapshot: String = "null", ageMs: String = "null", staleAfterMs: String = "15000", extra: String = "") -> String {86 #"{"v":1,"type":"subscribed","channel":{"type":"\#(type)","id":"\#(id)"\#(extra)},"key":"\#(key)","staleAfterMs":\#(staleAfterMs),"source":"hyperliquid-ws","snapshot":\#(snapshot),"snapshotAgeMs":\#(ageMs)}"#87}88private func levels(_ l: [StreamLevel]) -> String { "[" + l.map { #"["\#($0.price)","\#($0.size)"]"# }.joined(separator: ",") + "]" }89private func book(kind: String, seq: Int, prev: Int?, bids: [StreamLevel], asks: [StreamLevel], after: (bids: [StreamLevel], asks: [StreamLevel]), checksum: UInt32? = nil) -> String {90 #"{"v":1,"type":"book","id":"hyperliquid:BTC","depth":20,"kind":"\#(kind)","bids":\#(levels(bids)),"asks":\#(levels(asks)),"seq":\#(seq),"prevSeq":\#(prev.map(String.init) ?? "null"),"checksum":\#(checksum ?? QuoteProtocol.bookChecksum(bids: after.bids, asks: after.asks)),"venueTs":null,"recvTs":1795000000000,"source":"hyperliquid-ws","stale":false}"#91}92private func L(_ p: String, _ s: String) -> StreamLevel { StreamLevel(price: p, size: s) }9394private struct Rig {95 let stream: QuoteStream, connector = FakeConnector(), recorder = Recorder(), store: InMemoryTokenStore, client: APIClient9697 init(token: String? = "test-session-token", options: QuoteStream.Options = fastOptions(), random: Double = 0) async {98 let (c, _, s) = MockTransport.client(token: token)99 client = c; store = s100 stream = QuoteStream(client: c, connector: connector, options: options, environment: .init(random: { random }))101 let events = await stream.events(), rec = recorder102 Task { for await e in events { rec.add(e) } }103 }104 /** reconnect delays of 10–20 ms instead of 1–30 s; the watchdog still follows the server's heartbeat period */105 static func fastOptions() -> QuoteStream.Options { var o = QuoteStream.Options(); o.backoffMinMs = 20; o.backoffMaxMs = 80; return o }106107 func socket(_ n: Int) async throws -> FakeSocket {108 try await eventually("connection #\(n + 1)") { connector.sockets.count > n }109 return connector.sockets[n]110 }111 func greet(_ n: Int, heartbeatMs: Int = 15000) async throws -> FakeSocket {112 let s = try await socket(n)113 s.serve(hello(heartbeatMs: heartbeatMs))114 try await eventually("the subscribe frame after hello #\(n + 1)") { !s.sent.isEmpty }115 return s116 }117}118119// MARK: tests120121@Suite struct QuoteProtocolTests {122 // Vectors/ops-quote-shared.json is generated from services/api/src/quotes/shared.ts123 static let v = try! TestResources.json("ops-quote-shared.json", in: "Vectors")124125 @Test func constantsAndCloseCodesAreTheServers() {126 let v = Self.v127 #expect(v["protocol"]?.intValue == Int64(QuoteProtocol.version) && v["heartbeatMs"]?.intValue == Int64(QuoteProtocol.heartbeatMs))128 #expect(v["bookDepths"]?.arrayValue?.compactMap(\.intValue) == QuoteProtocol.bookDepths.map(Int64.init))129 #expect(v["candleIntervals"]?.arrayValue?.compactMap(\.stringValue) == QuoteProtocol.candleIntervals)130 #expect(v["channelTypes"]?.arrayValue?.compactMap(\.stringValue) == StreamChannelType.allCases.map(\.rawValue))131 let mine: [String: Int] = ["goingAway": QuoteProtocol.Close.goingAway, "tooBig": QuoteProtocol.Close.tooBig, "unauthorized": QuoteProtocol.Close.unauthorized, "rateLimited": QuoteProtocol.Close.rateLimited,132 "slowConsumer": QuoteProtocol.Close.slowConsumer, "idle": QuoteProtocol.Close.idle, "deadPeer": QuoteProtocol.Close.deadPeer, "protocol": QuoteProtocol.Close.protocol]133 #expect(v["close"]?.objectValue?.mapValues { Int($0.intValue ?? -1) } == mine)134 }135136 @Test func crcChecksumDecimalOrderDeltasKeysAndBackoffMatchTheServer() throws {137 let v = Self.v138 func lv(_ a: JSONValue?) -> [StreamLevel] { (a?.arrayValue ?? []).map { L($0[0]?.stringValue ?? "", $0[1]?.stringValue ?? "") } }139 #expect(QuoteProtocol.crc32("123456789") == 0xcbf4_3926)140 for c in try #require(v["crc32"]?.arrayValue) { #expect(Int64(QuoteProtocol.crc32(c["text"]?.stringValue ?? "?")) == c["crc"]?.intValue) }141 for c in try #require(v["checksum"]?.arrayValue) { #expect(Int64(QuoteProtocol.bookChecksum(bids: lv(c["bids"]), asks: lv(c["asks"]))) == c["checksum"]?.intValue) }142 for c in try #require(v["cmp"]?.arrayValue) { #expect(Int64(QuoteProtocol.compareDecimal(c["a"]?.stringValue ?? "", c["b"]?.stringValue ?? "")) == c["r"]?.intValue, "\(c)") }143 for c in try #require(v["apply"]?.arrayValue) {144 #expect(QuoteProtocol.applyLevels(lv(c["levels"]), changes: lv(c["changes"]), bids: c["side"]?.stringValue == "bids", depth: Int(c["depth"]?.intValue ?? 0)) == lv(c["out"]))145 }146 for c in try #require(v["channelKey"]?.arrayValue) {147 let ch: StreamChannel = try #require(c["channel"]).decode()148 #expect(ch.key == c["key"]?.stringValue && ch.isValid)149 #expect(try c["channel"]!.decode(StreamChannelEcho.self).key == c["key"]?.stringValue)150 }151 for c in try #require(v["backoff"]?.arrayValue) {152 #expect(QuoteProtocol.backoffMs(attempt: Int(c["attempt"]?.intValue ?? 0), random: c["random"]?.doubleValue ?? 0) == c["ms"]?.doubleValue)153 }154 }155156 @Test func channelsTheServerWouldRefuseAreInvalid() {157 #expect(StreamChannel.quote("gmx:BTC/USD [WBTC-USDC]").isValid && StreamChannel.book("dydx:BTC-USD", depth: 5).isValid && StreamChannel.candle("spot:BTC", interval: "4h").isValid)158 #expect(!StreamChannel.quote("").isValid && !StreamChannel.quote(String(repeating: "a", count: 81)).isValid && !StreamChannel.quote("hl:BTC\"}").isValid && !StreamChannel.quote("hl:é").isValid)159 #expect(!StreamChannel.book("hyperliquid:BTC", depth: 7).isValid && !StreamChannel.candle("spot:BTC", interval: "2m").isValid)160 }161162 @Test func framesDecodeAndAnythingElseIsRefused() throws {163 guard case .quote(let q) = try StreamServerMessage.decode(quote("hyperliquid:BTC", mid: "65000.5", seq: 7, venueTs: "1794999999000")) else { Issue.record("quote"); return }164 #expect(q.mid == "65000.5" && q.ask == nil && q.funding == "0.0000125" && q.change24h == "-0.0123" && q.venueTs == 1_794_999_999_000 && q.seq == 7 && !q.stale)165 #expect(try StreamServerMessage.decode(#"{"v":1,"type":"heartbeat","ts":1795000000000,"subscriptions":3}"#) == .heartbeat(ts: 1_795_000_000_000, subscriptions: 3))166 #expect(try StreamServerMessage.decode(#"{"v":1,"type":"pong","t":null,"ts":1}"#) == .pong(t: nil, ts: 1))167 #expect(try StreamServerMessage.decode(#"{"v":1,"type":"dropped","channel":"trades","id":"hyperliquid:BTC","count":4,"total":9}"#) == .dropped(id: "hyperliquid:BTC", count: 4, total: 9))168 #expect(try StreamServerMessage.decode(#"{"v":1,"type":"unsubscribed","channel":{"type":"quote","id":"spot:BTC"},"key":"quote|spot:BTC|"}"#) == .unsubscribed(key: "quote|spot:BTC|"))169 #expect(try StreamServerMessage.decode(#"{"v":1,"type":"something_new","x":1}"#) == .unknown("something_new"))170 guard case .status(let s) = try StreamServerMessage.decode(#"{"v":1,"type":"status","venue":"dydx","status":"degraded","since":1,"ageMs":null,"transport":"stream","source":"dydx-ws","detail":null,"ts":2}"#) else { Issue.record("status"); return }171 #expect(s.status == .unknown("degraded") && s.status.isTroubled && !StreamVenueState.idle.isTroubled)172 guard case .trade(let t) = try StreamServerMessage.decode(#"{"v":1,"type":"trade","id":"hyperliquid:BTC","trades":[{"id":"t1","price":"65000","size":"0.01","side":"sell","ts":5}],"seq":1,"recvTs":6,"source":"hyperliquid-ws","snapshot":true}"#) else { Issue.record("trade"); return }173 #expect(t.trades == [StreamTrade(id: "t1", price: "65000", size: "0.01", side: "sell", ts: 5)] && t.snapshot == true)174 guard case .candle(let c) = try StreamServerMessage.decode(#"{"v":1,"type":"candle","id":"spot:BTC","interval":"1m","ts":60000,"open":"1","high":"2","low":"0.5","close":"1.5","volume":"10","seq":1,"recvTs":6,"source":"coinbase-ws"}"#) else { Issue.record("candle"); return }175 #expect(c.close == "1.5" && c.interval == "1m")176 // another protocol version, a number where a decimal string is required, not JSON177 #expect(throws: (any Error).self) { try StreamServerMessage.decode(#"{"v":2,"type":"heartbeat","ts":1,"subscriptions":0}"#) }178 #expect(throws: (any Error).self) { try StreamServerMessage.decode(quote("hyperliquid:BTC", mid: "1", seq: 1).replacingOccurrences(of: #""mid":"1""#, with: #""mid":1"#)) }179 #expect(throws: (any Error).self) { try StreamServerMessage.decode("not json") }180 }181182 @Test func clientFramesAreWhatTheServersStrictSchemaAccepts() throws {183 func obj(_ m: StreamClientMessage) throws -> JSONValue { try JSONDecoder().decode(JSONValue.self, from: Data(m.text.utf8)) }184 #expect(try obj(.subscribe([.quote("hyperliquid:BTC"), .book("hyperliquid:BTC", depth: 10), .candle("spot:BTC", interval: "1h")])) ==185 ["v": 1, "op": "subscribe", "channels": [["type": "quote", "id": "hyperliquid:BTC"], ["type": "book", "id": "hyperliquid:BTC", "depth": 10], ["type": "candle", "id": "spot:BTC", "interval": "1h"]]])186 #expect(try obj(.unsubscribe([.trades("dydx:BTC-USD")])) == ["v": 1, "op": "unsubscribe", "channels": [["type": "trades", "id": "dydx:BTC-USD"]]])187 #expect(try obj(.ping(t: 12)) == ["v": 1, "op": "ping", "t": 12])188 }189190 @Test func freshnessIsTheWebClientsRuleAndNeverLiveWhenTheStreamIsNot() {191 // the cases of apps/web/test/quotes.test.ts (« live → delayed → stale by age… »)192 let t0 = Date(timeIntervalSince1970: 1_795_000_000)193 func f(_ ageMs: Double, stale: Bool = false, bound: Int64? = 15000, conn: QuoteStreamState = .live, venue: StreamVenueState? = nil) -> StreamFreshness {194 .evaluate(freshAt: t0, serverStale: stale, staleAfterMs: bound, connection: conn, now: t0.addingTimeInterval(ageMs / 1000), venue: venue)195 }196 #expect(f(1000) == StreamFreshness(state: .live, ageMs: 1000) && f(1000).isLive)197 #expect(f(6000) == StreamFreshness(state: .delayed, ageMs: 6000))198 #expect(f(16000) == StreamFreshness(state: .stale, ageMs: 16000))199 #expect(f(10, stale: true).state == .stale)200 #expect(f(2000, conn: .reconnecting(attempt: 1, delayMs: 500)).state == .reconnecting && f(2000, conn: .connecting).state == .reconnecting)201 #expect(f(2000, venue: .reconnecting).state == .reconnecting && f(2000, venue: .down).state == .reconnecting && f(16000, venue: .reconnecting).state == .stale && f(2000, venue: .connected).state == .live)202 #expect(f(20000, conn: .reconnecting(attempt: 3, delayMs: 1)).state == .stale)203 #expect(f(2500, bound: 4000).state == .delayed) // never « live » past half the source's bound204 #expect(f(1000, bound: nil).state == .live && f(31000, bound: nil).state == .stale) // 30 s when the server gave no bound205 // native addition: a stream that ended or was stopped yields stale at once (nobody is coming back for the figure)206 #expect(f(10, conn: .ended(.unauthorized)).state == .stale && f(10, conn: .idle).state == .stale && !f(10, conn: .idle).isLive)207 let none = StreamFreshness.evaluate(freshAt: nil, serverStale: false, staleAfterMs: nil, connection: .live, now: t0)208 #expect(none == StreamFreshness(state: .none, ageMs: nil))209 #expect(StreamFreshness.evaluate(freshAt: nil, serverStale: false, staleAfterMs: nil, connection: .connecting, now: t0).state == .reconnecting)210 }211}212213@Suite struct QuoteStreamTests {214 @Test func connectsWithTheSessionCookieAndTheWalletsOrigin() async throws {215 let rig = await Rig()216 try await rig.stream.subscribe([.quote("hyperliquid:BTC")])217 let s = try await rig.socket(0)218 let req = rig.connector.requests[0]219 #expect(req.url?.absoluteString == "wss://wallet.example.test/api/v1/stream")220 #expect(req.value(forHTTPHeaderField: "Cookie") == "__Host-spw=test-session-token")221 #expect(req.value(forHTTPHeaderField: "Origin") == "https://wallet.example.test")222 #expect(req.value(forHTTPHeaderField: "User-Agent") == "SPWalletCoreTests" && !req.httpShouldHandleCookies)223 #expect(s.sent.isEmpty) // nothing is sent before the server's hello224 await rig.stream.stop()225 }226227 @Test func helloSubscribeSnapshotThenLiveQuotesWithAFreshnessTimestamp() async throws {228 let rig = await Rig()229 try await rig.stream.subscribe([.quote("hyperliquid:BTC"), .quote("spot:WBTC")])230 let s = try await rig.greet(0)231 // one frame: the venue statuses always come along, then the channels in the order they were asked232 #expect(s.sent == [["v": 1, "op": "subscribe", "channels": [["type": "status", "id": "*"], ["type": "quote", "id": "hyperliquid:BTC"], ["type": "quote", "id": "spot:WBTC"]]]])233 #expect(await rig.stream.state == .live)234 #expect(await rig.stream.serverLimits()?.maxSubscriptions == 300)235236 let status = #"{"v":1,"type":"status","venue":"hyperliquid","status":"connected","since":1,"ageMs":20,"transport":"stream","source":"hyperliquid-ws","detail":null,"ts":2}"#237 s.serve(subscribed("status|*|", type: "status", id: "*", snapshot: "[\(status)]", ageMs: "0", staleAfterMs: "null"))238 // the snapshot is 7 s old on the server: the figure is 7 s old here too239 s.serve(subscribed("quote|hyperliquid:BTC|", type: "quote", id: "hyperliquid:BTC", snapshot: quote("hyperliquid:BTC", mid: "65000.5", seq: 1), ageMs: "7000"))240 try await eventually("the snapshot quote") { await rig.stream.quote("hyperliquid:BTC") != nil }241 var held = try #require(await rig.stream.quote("hyperliquid:BTC"))242 #expect(held.quote.quote.mid == "65000.5" && held.quote.quote.ask == nil && held.quote.staleAfterMs == 15000)243 #expect(abs(Date().timeIntervalSince(held.quote.freshAt) - 7) < 1 && held.freshness.state == .delayed)244 #expect(await rig.stream.venueStatuses()["hyperliquid"]?.status == .connected)245246 s.serve(quote("hyperliquid:BTC", mid: "65001", seq: 2))247 try await eventually("the live quote") { await rig.stream.quote("hyperliquid:BTC")?.quote.quote.seq == 2 }248 held = try #require(await rig.stream.quote("hyperliquid:BTC"))249 #expect(held.quote.quote.mid == "65001" && held.freshness.state == .live && held.freshness.isLive && abs(Date().timeIntervalSince(held.quote.freshAt)) < 1)250251 // a polled source that dated its price 3 minutes before the server received it: 3 minutes old here too252 s.serve(subscribed("quote|spot:WBTC|", type: "quote", id: "spot:WBTC", staleAfterMs: "900000"))253 s.serve(quote("spot:WBTC", mid: "64990", seq: 1, venueTs: "1794999820000"))254 try await eventually("the polled quote") { await rig.stream.quote("spot:WBTC") != nil }255 let polled = try #require(await rig.stream.quote("spot:WBTC"))256 #expect(abs(Date().timeIntervalSince(polled.quote.freshAt) - 180) < 1 && polled.freshness.state == .delayed && polled.quote.staleAfterMs == 900_000)257258 // the server's own stale flag is obeyed; a quote of a channel nobody asked for is ignored259 s.serve(quote("hyperliquid:BTC", mid: "65002", seq: 3, stale: true))260 s.serve(quote("hyperliquid:DOGE", mid: "1", seq: 1))261 try await eventually("the stale quote") { await rig.stream.quote("hyperliquid:BTC")?.freshness.state == .stale }262 #expect(await rig.stream.quote("hyperliquid:DOGE") == nil)263 try await eventually("events recorded") { rig.recorder.events.filter { if case .quote = $0 { true } else { false } }.count == 4 }264 #expect(rig.recorder.states == [.connecting, .live])265 #expect(rig.recorder.has(.subscribed(key: "quote|hyperliquid:BTC|", staleAfterMs: 15000, source: "hyperliquid-ws")))266 await rig.stream.stop()267 }268269 @Test func subscribeAndUnsubscribeWhileLive() async throws {270 let rig = await Rig()271 try await rig.stream.subscribe([.quote("hyperliquid:BTC")])272 let s = try await rig.greet(0)273 try await rig.stream.subscribe([.book("hyperliquid:ETH", depth: 5), .quote("hyperliquid:BTC")]) // the second is already subscribed274 try await eventually("the second subscribe frame") { s.sent.count == 2 }275 #expect(s.sent[1] == ["v": 1, "op": "subscribe", "channels": [["type": "book", "id": "hyperliquid:ETH", "depth": 5]]])276 await rig.stream.unsubscribe([.quote("hyperliquid:BTC"), .quote("never:subscribed")])277 try await eventually("the unsubscribe frame") { s.sent.count == 3 }278 #expect(s.sent[2] == ["v": 1, "op": "unsubscribe", "channels": [["type": "quote", "id": "hyperliquid:BTC"]]])279 #expect(await rig.stream.subscriptions() == [.book("hyperliquid:ETH", depth: 5)])280 s.serve(#"{"v":1,"type":"unsubscribed","channel":{"type":"quote","id":"hyperliquid:BTC"},"key":"quote|hyperliquid:BTC|"}"#)281 await rig.stream.ping()282 try await eventually("the ping") { s.sent.count == 4 }283 #expect(s.sent[3]["op"] == "ping" && s.sent[3]["t"]?.doubleValue != nil)284 s.serve(#"{"v":1,"type":"pong","t":5,"ts":1795000000000}"#)285 try await eventually("pong and unsubscribed events") { rig.recorder.has(.pong(t: 5)) && rig.recorder.has(.unsubscribed(key: "quote|hyperliquid:BTC|")) }286 await rig.stream.stop()287 }288289 @Test func aBookIsOnlyShownWhenEveryDeltaAppliedAndTheChecksumMatched() async throws {290 let rig = await Rig()291 try await rig.stream.subscribe([.book("hyperliquid:BTC")])292 let s = try await rig.greet(0)293 let b0 = [L("65000", "1"), L("64999.5", "2")], a0 = [L("65000.5", "1.5"), L("65001", "3")]294 s.serve(subscribed("book|hyperliquid:BTC|20", type: "book", id: "hyperliquid:BTC", snapshot: book(kind: "snapshot", seq: 10, prev: nil, bids: b0, asks: a0, after: (b0, a0)), ageMs: "0", extra: #","depth":20"#))295 try await eventually("the snapshot") { await rig.stream.book("hyperliquid:BTC")?.book.seq == 10 }296297 // a delta: one price resized, one removed (size "0"), one added — then the checksum of the result298 let b1 = [L("65000", "0.4"), L("64999", "7")], a1 = [L("65000.5", "1.5"), L("65001", "3")]299 s.serve(book(kind: "delta", seq: 11, prev: 10, bids: [L("65000", "0.4"), L("64999.5", "0"), L("64999", "7")], asks: [], after: (b1, a1)))300 try await eventually("the delta") { await rig.stream.book("hyperliquid:BTC")?.book.seq == 11 }301 var held = try #require(await rig.stream.book("hyperliquid:BTC"))302 #expect(held.book.bids == b1 && held.book.asks == a1 && held.freshness.state == .live)303304 // a hole (prevSeq 12 after 11): never patched across — the book is withheld and a fresh snapshot is asked for305 s.serve(book(kind: "delta", seq: 13, prev: 12, bids: [L("65000", "9")], asks: [], after: (b1, a1)))306 try await eventually("the resync request") { s.sent.count == 2 }307 #expect(s.sent[1] == ["v": 1, "op": "subscribe", "channels": [["type": "book", "id": "hyperliquid:BTC", "depth": 20]]])308 #expect(await rig.stream.book("hyperliquid:BTC") == nil)309 // deltas that arrive while waiting are not applied310 s.serve(book(kind: "delta", seq: 14, prev: 13, bids: [L("65000", "8")], asks: [], after: (b1, a1)))311 let b2 = [L("65000", "9")], a2 = [L("65000.5", "1")]312 s.serve(subscribed("book|hyperliquid:BTC|20", type: "book", id: "hyperliquid:BTC", snapshot: book(kind: "snapshot", seq: 14, prev: nil, bids: b2, asks: a2, after: (b2, a2)), ageMs: "0", extra: #","depth":20"#))313 try await eventually("the fresh snapshot") { await rig.stream.book("hyperliquid:BTC")?.book.seq == 14 }314 held = try #require(await rig.stream.book("hyperliquid:BTC"))315 #expect(held.book.bids == b2)316317 // a delta in sequence whose checksum does not match the rebuilt book: withheld again318 s.serve(book(kind: "delta", seq: 15, prev: 14, bids: [L("64990", "1")], asks: [], after: (b2, a2), checksum: 12345))319 try await eventually("the second resync request") { s.sent.count == 3 }320 #expect(await rig.stream.book("hyperliquid:BTC") == nil)321 #expect(rig.recorder.events.filter { $0 == .bookResync(key: "book|hyperliquid:BTC|20") }.count == 2)322 await rig.stream.stop()323 }324325 @Test func tradesCandlesErrorsAndDrops() async throws {326 let rig = await Rig()327 try await rig.stream.subscribe([.trades("hyperliquid:BTC"), .candle("spot:BTC"), .quote("hyperliquid:NOPE")])328 let s = try await rig.greet(0)329 let trade = { (ids: [String], snapshot: Bool) in330 #"{"v":1,"type":"trade","id":"hyperliquid:BTC","trades":[\#(ids.map { #"{"id":"\#($0)","price":"65000","size":"0.01","side":"buy","ts":5}"# }.joined(separator: ","))],"seq":1,"recvTs":6,"source":"hyperliquid-ws"\#(snapshot ? #","snapshot":true"# : "")}"#331 }332 s.serve(trade(["t1", "t2"], true)); s.serve(trade(["t2", "t3"], false)); s.serve(trade(["t3"], false))333 s.serve(#"{"v":1,"type":"candle","id":"spot:BTC","interval":"1m","ts":60000,"open":"1","high":"2","low":"0.5","close":"1.5","volume":"10","seq":1,"recvTs":6,"source":"coinbase-ws"}"#)334 s.serve(#"{"v":1,"type":"dropped","channel":"trades","id":"hyperliquid:BTC","count":4,"total":9}"#)335 s.serve(#"{"v":1,"type":"error","code":"unknown_instrument","message":"unknown instrument 'hyperliquid:NOPE'","channel":{"type":"quote","id":"hyperliquid:NOPE"}}"#)336 s.serve(#"{"v":1,"type":"error","code":"rate_limited","message":"at most 20 frames per second"}"#)337 s.serve("this is not json"); s.serve(#"{"v":2,"type":"quote"}"#); s.serve(#"{"v":1,"type":"from_the_future"}"#)338 s.serve(#"{"v":1,"type":"heartbeat","ts":1795000000000,"subscriptions":4}"#)339 try await eventually("the heartbeat after everything") { rig.recorder.has(.heartbeat(subscriptions: 4)) }340 let trades = rig.recorder.events.compactMap { e -> ([String], Bool)? in if case .trades(_, let t, let h) = e { (t.map(\.id), h) } else { nil } }341 #expect(trades.count == 2 && trades[0].0 == ["t1", "t2"] && trades[0].1 && trades[1].0 == ["t3"] && !trades[1].1) // duplicates are dropped342 #expect(rig.recorder.events.contains { if case .candle(let c, _) = $0 { c.close == "1.5" } else { false } })343 #expect(rig.recorder.has(.tradesDropped(id: "hyperliquid:BTC", count: 4, total: 9)))344 #expect(await rig.stream.refusal(of: .quote("hyperliquid:NOPE")) == "unknown_instrument")345 #expect(await rig.stream.refusal(of: .trades("hyperliquid:BTC")) == nil)346 #expect(await rig.stream.state == .live) // malformed frames and unknown types change nothing347348 // a refused channel is not asked again on the next connection349 s.serverCloses(QuoteProtocol.Close.goingAway)350 let s2 = try await rig.greet(1)351 #expect(s2.sent[0]["channels"]?.arrayValue?.compactMap { $0["id"]?.stringValue } == ["*", "hyperliquid:BTC", "spot:BTC"])352 await rig.stream.stop()353 }354355 @Test func heartbeatTimeoutReconnectsResubscribesAndWhatWasHeldIsStaleMeanwhile() async throws {356 let rig = await Rig()357 try await rig.stream.subscribe([.quote("hyperliquid:BTC"), .book("hyperliquid:BTC")])358 let s1 = try await rig.greet(0, heartbeatMs: 60) // the watchdog is 2.5 heartbeat periods: 150 ms359 s1.serve(subscribed("quote|hyperliquid:BTC|", type: "quote", id: "hyperliquid:BTC", snapshot: quote("hyperliquid:BTC", mid: "65000", seq: 1), ageMs: "0"))360 let b0 = [L("65000", "1")], a0 = [L("65001", "1")]361 s1.serve(book(kind: "snapshot", seq: 1, prev: nil, bids: b0, asks: a0, after: (b0, a0)))362 try await eventually("live values") { let q = await rig.stream.quote("hyperliquid:BTC"), b = await rig.stream.book("hyperliquid:BTC"); return q?.freshness.state == .live && b != nil }363364 // …then the server goes silent: no frame for 2.5 periods → the socket is dropped and a new one opened365 let s2 = try await rig.socket(1)366 #expect(s1.closedByClient == 1000)367 #expect(rig.recorder.has(.stale(keys: ["quote|hyperliquid:BTC|", "book|hyperliquid:BTC|20"])))368 #expect(rig.recorder.states.contains { if case .reconnecting(attempt: 1, delayMs: 10) = $0 { true } else { false } }) // 20 ms × (0.5 + 0.5 × random 0)369 // while the stream is down the held quote keeps its timestamp and is NOT live; the book is withheld370 let held = try #require(await rig.stream.quote("hyperliquid:BTC"))371 #expect(held.quote.quote.mid == "65000" && held.freshness.state != .live && !held.freshness.isLive)372 #expect(await rig.stream.book("hyperliquid:BTC") == nil)373 #expect(await rig.stream.serverLimits() == nil)374375 // the new connection subscribes to everything again, by itself376 s2.serve(hello())377 try await eventually("the resubscription") { !s2.sent.isEmpty }378 #expect(s2.sent == [["v": 1, "op": "subscribe", "channels": [["type": "status", "id": "*"], ["type": "quote", "id": "hyperliquid:BTC"], ["type": "book", "id": "hyperliquid:BTC", "depth": 20]]]])379 // a delta before the fresh snapshot is not applied to the old book380 s2.serve(book(kind: "delta", seq: 2, prev: 1, bids: [L("65000", "5")], asks: [], after: ([L("65000", "5")], a0)))381 s2.serve(quote("hyperliquid:BTC", mid: "65010", seq: 9))382 try await eventually("fresh quote") { await rig.stream.quote("hyperliquid:BTC")?.quote.quote.mid == "65010" }383 #expect(await rig.stream.quote("hyperliquid:BTC")?.freshness.state == .live)384 #expect(await rig.stream.book("hyperliquid:BTC") == nil)385 #expect(await rig.stream.state == .live)386 await rig.stream.stop()387 }388389 @Test func backoffGrowsAndIsCappedAndResetsAfterAHello() async throws {390 let rig = await Rig(random: 1)391 rig.connector.refuseNext(.handshake(status: 503)); rig.connector.refuseNext(.transport("offline")); rig.connector.refuseNext(.handshake(status: 429)); rig.connector.refuseNext(.transport("offline"))392 try await rig.stream.subscribe([.quote("hyperliquid:BTC")])393 let s = try await rig.greet(0)394 let delays = { rig.recorder.states.compactMap { st -> Int? in if case .reconnecting(_, let d) = st { d } else { nil } } }395 #expect(delays() == [20, 40, 80, 80]) // min · 2^attempt, capped at max (random = 1)396 #expect(rig.connector.requests.count == 5)397 s.serverCloses(QuoteProtocol.Close.goingAway) // after a hello the next delay starts from the minimum again398 _ = try await rig.greet(1)399 #expect(delays().last == 20 && rig.recorder.has(.closed(code: 1001)))400 await rig.stream.stop()401 }402403 @Test func theSessionEndedCloseCodeEndsTheStreamWithAnEventAndNoReconnection() async throws {404 let rig = await Rig()405 try await rig.stream.subscribe([.quote("hyperliquid:BTC")])406 let s = try await rig.greet(0)407 s.serve(quote("hyperliquid:BTC", mid: "65000", seq: 1))408 try await eventually("a live quote") { await rig.stream.quote("hyperliquid:BTC")?.freshness.isLive == true }409 s.serverCloses(QuoteProtocol.Close.unauthorized)410 try await eventually("ended") { await rig.stream.state == .ended(.unauthorized) }411 try await eventually("events") { rig.recorder.states.last == .ended(.unauthorized) }412 #expect(rig.recorder.has(.closed(code: 4001)) && rig.recorder.has(.stale(keys: ["quote|hyperliquid:BTC|"])))413 #expect(await rig.stream.quote("hyperliquid:BTC")?.freshness.state == .stale) // what is left on screen is stale at once414 try await Task.sleep(for: .milliseconds(200)) // several backoff periods415 #expect(rig.connector.requests.count == 1)416 // subscribing does not knock again with the dead credential…417 try await rig.stream.subscribe([.quote("hyperliquid:ETH")])418 try await Task.sleep(for: .milliseconds(50))419 #expect(rig.connector.requests.count == 1)420 // …an explicit start, after the owner signed in again, does — and everything is subscribed again421 await rig.stream.start()422 let s2 = try await rig.greet(1)423 #expect(s2.sent[0]["channels"]?.arrayValue?.count == 3)424 await rig.stream.stop()425 }426427 @Test func aRefusedHandshakeIsNotRetriedWhenARetryCannotHelp() async throws {428 let a = await Rig()429 a.connector.refuseNext(.handshake(status: 401))430 try await a.stream.subscribe([.quote("hyperliquid:BTC")])431 try await eventually("ended 401") { await a.stream.state == .ended(.unauthorized) }432 let b = await Rig()433 b.connector.refuseNext(.handshake(status: 403)) // origin_refused434 try await b.stream.subscribe([.quote("hyperliquid:BTC")])435 try await eventually("ended 403") { await b.stream.state == .ended(.refused(status: 403)) }436 // the refusal may also only surface on the first receive (URLSessionWebSocketTask)437 let c = await Rig()438 try await c.stream.subscribe([.quote("hyperliquid:BTC")])439 try await c.socket(0).fail(.handshake(status: 401))440 try await eventually("ended 401 on receive") { await c.stream.state == .ended(.unauthorized) }441 try await Task.sleep(for: .milliseconds(150))442 #expect(a.connector.requests.count == 1 && b.connector.requests.count == 1 && c.connector.requests.count == 1)443 }444445 @Test func signedOutNothingIsSentAndASessionThatEndsElsewhereClosesTheSocket() async throws {446 let out = await Rig(token: nil)447 try await out.stream.subscribe([.quote("hyperliquid:BTC")])448 try await eventually("ended signed out") { await out.stream.state == .ended(.signedOut) }449 #expect(out.connector.requests.isEmpty)450451 // the API client learns that the session ended (lock, or a 401 on any call): the socket is closed, no reconnection452 let rig = await Rig()453 try await rig.stream.subscribe([.quote("hyperliquid:BTC")])454 let s = try await rig.greet(0)455 try await Task.sleep(for: .milliseconds(30)) // the session listener is attached456 await rig.client.forgetSession()457 try await eventually("ended by the session") { await rig.stream.state == .ended(.unauthorized) }458 #expect(s.closedByClient == 1000)459 try await Task.sleep(for: .milliseconds(150))460 #expect(rig.connector.requests.count == 1)461 }462463 @Test func stopClosesCleanlyKeepsSubscriptionsAndNothingHeldStaysLive() async throws {464 let rig = await Rig()465 try await rig.stream.subscribe([.quote("hyperliquid:BTC")])466 let s = try await rig.greet(0)467 s.serve(quote("hyperliquid:BTC", mid: "65000", seq: 1))468 try await eventually("a live quote") { await rig.stream.quote("hyperliquid:BTC")?.freshness.isLive == true }469 await rig.stream.stop()470 #expect(s.closedByClient == 1000)471 #expect(await rig.stream.state == .idle)472 #expect(await rig.stream.quote("hyperliquid:BTC")?.freshness.state == .stale)473 try await Task.sleep(for: .milliseconds(150))474 #expect(rig.connector.requests.count == 1) // no reconnection after a stop475 await rig.stream.stop() // idempotent476 await rig.stream.start()477 let s2 = try await rig.greet(1)478 #expect(s2.sent[0]["channels"]?.arrayValue?.count == 2)479 await rig.stream.stop()480 }481482 @Test func idleCloseWithNothingSubscribedDoesNotReconnect() async throws {483 let rig = await Rig()484 await rig.stream.start()485 let s = try await rig.greet(0)486 #expect(s.sent == [["v": 1, "op": "subscribe", "channels": [["type": "status", "id": "*"]]]])487 s.serverCloses(QuoteProtocol.Close.idle)488 try await eventually("idle") { await rig.stream.state == .idle }489 try await Task.sleep(for: .milliseconds(150))490 #expect(rig.connector.requests.count == 1)491 try await rig.stream.subscribe([.quote("hyperliquid:BTC")]) // the next subscription opens it again492 _ = try await rig.greet(1)493 await rig.stream.stop()494 }495496 @Test func limitsAreEnforcedBeforeTheServerHasTo() async throws {497 var o = Rig.fastOptions(); o.maxSubscriptions = 4; o.channelsPerFrame = 2498 let rig = await Rig(options: o)499 await #expect(throws: QuoteStreamError.invalidChannel("book|hyperliquid:BTC|7")) { try await rig.stream.subscribe([.book("hyperliquid:BTC", depth: 7)]) }500 try await rig.stream.subscribe([.quote("a:1"), .quote("a:2"), .quote("a:3")]) // 3 + the venue statuses = 4501 await #expect(throws: QuoteStreamError.tooManySubscriptions(limit: 4)) { try await rig.stream.subscribe([.quote("a:4")]) }502 let s = try await rig.socket(0)503 s.serve(hello(maxSubscriptions: 3)) // the server's own limit replaces the assumed one504 try await eventually("two frames of two channels") { s.sent.count == 2 }505 #expect(s.sent.map { $0["channels"]?.arrayValue?.count } == [2, 2])506 await rig.stream.unsubscribe([.quote("a:3")])507 await #expect(throws: QuoteStreamError.tooManySubscriptions(limit: 3)) { try await rig.stream.subscribe([.quote("a:5")]) }508 await rig.stream.stop()509 }510}511