Skip to main content

ccxt_common/pro/
ws_client.rs

1//! WebSocket transport for the pro (`watch*`) API.
2//!
3//! This is the Rust port of the runtime side of `ts/src/base/ws/{Client,WsClient}.ts`.
4//! The transpiled `pro/<id>.rs` exchanges call — via the base `watch()` /
5//! `watch_multiple()` — into a *client* object keyed by URL that:
6//!   * owns the live `tokio-tungstenite` connection (one per URL),
7//!   * exposes `resolve` / `reject` / `future` / `send` so the venue's
8//!     `handle_message` can push parsed data back to the awaiting `watch`,
9//!   * tracks `subscriptions` (so a subscribe frame is sent once per hash),
10//!   * runs ping/pong keep-alive.
11//!
12//! Ownership model (why this is a global registry, not a field on `Exchange`):
13//! the base `watch()` borrows `&mut self` to drive `handle_message`, which
14//! itself needs the client. Keeping the connection + futures in a process-wide
15//! registry keyed by URL (behind its own locks) keeps it disjoint from the
16//! `&mut Exchange` borrow, so the drive loop can read the next frame and call
17//! `handle_message(self, client, msg)` without aliasing.
18
19#![allow(dead_code)]
20
21use std::collections::{HashMap, HashSet, VecDeque};
22use std::sync::{Arc, Mutex};
23
24use futures::{SinkExt, StreamExt};
25use once_cell::sync::Lazy;
26use tokio::sync::{mpsc, Notify};
27use tokio_tungstenite::tungstenite::Message;
28
29use crate::Value;
30
31/// Per-connection state. Lives in [`REGISTRY`] behind an `Arc`, so both the
32/// background reader/writer tasks and the `watch` drive loop share it.
33pub struct ClientState {
34    pub url: String,
35    /// Frames queued for the writer task → socket.
36    outgoing: mpsc::UnboundedSender<Message>,
37    /// Receiver half held until the socket connects (a slot is pre-registered
38    /// before connecting so `client.subscriptions` writes persist — upbit builds
39    /// its subscribe frame from subscriptions set before the socket is up). The
40    /// writer task takes this on connect.
41    pending_rx: Mutex<Option<mpsc::UnboundedReceiver<Message>>>,
42    /// Serializes the (async) connect so concurrent `ensure_client`s for a
43    /// pre-registered slot don't open two sockets.
44    connect_gate: tokio::sync::Mutex<()>,
45    /// Parsed inbound messages awaiting dispatch to `handle_message`.
46    incoming: Mutex<VecDeque<Value>>,
47    /// Woken on: new inbound message, a resolve/reject, or close.
48    notify: Notify,
49    /// messageHash → resolved value (set by `handle_message` via `resolve`).
50    resolved: Mutex<HashMap<String, Value>>,
51    /// messageHash → error (set by `reject`; delivered before/instead of value).
52    rejections: Mutex<HashMap<String, Value>>,
53    /// subscribeHash → subscription object (TS `client.subscriptions[hash]`).
54    /// A subscribe frame is sent only the first time a hash is inserted.
55    subscriptions: Mutex<HashMap<String, Value>>,
56    /// messageHashes some `watch` call is currently waiting on. Mirrors TS
57    /// `client.futures` (read by a few venues' `handle_message`).
58    futures: Mutex<HashSet<String>>,
59    /// In-flight single-flight slots keyed by messageHash — the registry behind
60    /// TS's `client.future ()` / `client.reusableFuture ()` leader election
61    /// (binance/bybit/kucoin/... `authenticate`). Separate from `resolved`
62    /// because a flight has *many* waiters (all of whom must observe the
63    /// settled value, not consume it) and because settling one must also clear
64    /// its `futures` entry so the NEXT cycle can elect a fresh leader.
65    flights: Mutex<HashMap<String, FlightSlot>>,
66    connected: Mutex<bool>,
67    closed: Mutex<bool>,
68    last_pong_ms: Mutex<i64>,
69    /// Static-WS-test mock transport. When `mock` is set, `send_text` records the
70    /// (JSON-parsed) outgoing frame into `mock_sent` instead of relying on a
71    /// socket, and no real connection is ever opened. `ws_test_completed` is the
72    /// watch side's done-flag the frame injector's rejection loop polls.
73    mock: Mutex<bool>,
74    mock_sent: Mutex<Vec<Value>>,
75    ws_test_completed: Mutex<bool>,
76}
77
78/// One single-flight slot. `settled` stays populated after the flight closes so
79/// waiters that poll late still observe the result, and so a caller that
80/// re-awaits a hash nobody is working on any more gets the last value instead
81/// of blocking (TS's already-resolved Future). `open` is what a concurrent
82/// caller joins.
83#[derive(Clone)]
84struct FlightSlot {
85    open: bool,
86    settled: Option<Result<Value, Value>>,
87}
88
89static REGISTRY: Lazy<Mutex<HashMap<String, Arc<ClientState>>>> =
90    Lazy::new(|| Mutex::new(HashMap::new()));
91
92/// Monotonic-ish wall clock in ms. `SystemTime` is fine here (keep-alive only).
93fn now_ms() -> i64 {
94    std::time::SystemTime::now()
95        .duration_since(std::time::UNIX_EPOCH)
96        .map(|d| d.as_millis() as i64)
97        .unwrap_or(0)
98}
99
100/// Decode a text frame into a `Value` — JSON when it parses, else a raw string
101/// (some venues send bare `"pong"` etc. that `handle_message` matches on).
102fn parse_text(t: &str) -> Value {
103    match serde_json::from_str::<serde_json::Value>(t) {
104        Ok(j) => Value::from_json(&j),
105        Err(_) => Value::Str(t.to_string().into()),
106    }
107}
108
109/// Decode a binary frame: try raw-inflate then gzip (the two schemes venues
110/// use), fall back to the bytes as UTF-8. Then parse as text.
111fn parse_binary(b: &[u8]) -> Value {
112    use std::io::Read;
113    // gzip
114    {
115        let mut d = flate2::read::GzDecoder::new(b);
116        let mut s = String::new();
117        if d.read_to_string(&mut s).is_ok() && !s.is_empty() {
118            return parse_text(&s);
119        }
120    }
121    // raw deflate (no zlib header)
122    {
123        let mut d = flate2::read::DeflateDecoder::new(b);
124        let mut s = String::new();
125        if d.read_to_string(&mut s).is_ok() && !s.is_empty() {
126            return parse_text(&s);
127        }
128    }
129    // Uncompressed and valid UTF-8 → parse as text/JSON (covers venues that
130    // send plain-JSON frames over the binary opcode).
131    if let Ok(s) = std::str::from_utf8(b) {
132        return parse_text(s);
133    }
134    // Genuine binary payload (e.g. mexc protobuf): carry the raw bytes through
135    // as the port's byte-array form so `isBinaryMessage`/`decodeProtoMsg` see them.
136    crate::exchange_stubs::bytes_to_value(b)
137}
138
139/// Decode a binary frame for a client with `decompressBinary` off (mexc
140/// protobuf, paradex SBE): JSON is still read as text, as some venues send it
141/// over the binary opcode, everything else is carried through as raw bytes.
142/// No utf-8 fallback here: a binary payload can pass for utf-8 text.
143fn parse_raw_binary(b: &[u8]) -> Value {
144    match serde_json::from_slice::<serde_json::Value>(b) {
145        Ok(j) => Value::from_json(&j),
146        Err(_) => crate::exchange_stubs::bytes_to_value(b),
147    }
148}
149
150impl ClientState {
151    fn push_incoming(&self, v: Value) {
152        self.incoming.lock().unwrap().push_back(v);
153        self.notify.notify_waiters();
154    }
155
156    /// Await the next inbound message. `None` once the socket is closed and
157    /// the backlog is drained. Uses the create-future-before-check pattern so
158    /// a resolve/push racing the await is never lost.
159    pub async fn next_message(&self) -> Option<Value> {
160        let mock = *self.mock.lock().unwrap();
161        loop {
162            let notified = self.notify.notified();
163            if let Some(v) = self.incoming.lock().unwrap().pop_front() {
164                return Some(v);
165            }
166            if *self.closed.lock().unwrap() {
167                return None;
168            }
169            if mock {
170                // Static WS test: the mock queue is fed by the frame injector.
171                // If nothing arrives within a short window the fixture is
172                // finished (or under-feeds this watch) — stop instead of
173                // blocking the drive loop forever, so the test completes.
174                if tokio::time::timeout(std::time::Duration::from_millis(1500), notified).await.is_err() {
175                    return None;
176                }
177            } else {
178                notified.await;
179            }
180        }
181    }
182
183    /// Store a resolved value for `hash` (TS `client.resolve`). Also settles an
184    /// open single-flight on the same hash: TS's `client.resolve ()` settles
185    /// the future AND removes it from `client.futures`, which is what lets the
186    /// next cycle elect a fresh leader. Both paths run — a hash can in
187    /// principle be someone's flight and someone else's `watch`, and only the
188    /// waiter that exists will read its side.
189    pub fn resolve(&self, hash: &str, value: Value) {
190        self.flight_settle(hash, Ok(value.clone()));
191        self.resolved.lock().unwrap().insert(hash.to_string(), value);
192        self.notify.notify_waiters();
193    }
194
195    /// Store an error for `hash` (TS `client.reject`), settling an open
196    /// single-flight on the same hash — see `resolve`.
197    pub fn reject(&self, hash: &str, err: Value) {
198        self.flight_settle(hash, Err(err.clone()));
199        self.rejections.lock().unwrap().insert(hash.to_string(), err);
200        self.notify.notify_waiters();
201    }
202
203    /// If any of `hashes` has a resolved value or rejection, remove and return
204    /// it (`Ok` for value, `Err` for rejection). Rejections take priority.
205    pub fn take_settled(&self, hashes: &[String]) -> Option<Result<Value, Value>> {
206        {
207            let mut rj = self.rejections.lock().unwrap();
208            for h in hashes {
209                if let Some(e) = rj.remove(h) {
210                    return Some(Err(e));
211                }
212            }
213        }
214        let mut r = self.resolved.lock().unwrap();
215        for h in hashes {
216            if let Some(v) = r.remove(h) {
217                return Some(Ok(v));
218            }
219        }
220        None
221    }
222
223    /// Register interest in `hashes` (TS `client.future`). Returns true if the
224    /// subscribe frame still needs sending for `subscribe_hash`.
225    pub fn note_futures(&self, hashes: &[String]) {
226        let mut f = self.futures.lock().unwrap();
227        for h in hashes {
228            f.insert(h.clone());
229        }
230    }
231
232    /// Open a single-flight for `hash`, or join one already in progress. `true`
233    /// means this caller is the leader and must do the work; `false` means a
234    /// flight is already open and the caller should wait on it.
235    ///
236    /// The insert into `futures` is what makes the transpiled
237    /// `if (messageHash in client.futures)` follower test observable, and it
238    /// happens under the same lock as the check — this is TS's documented
239    /// "atomic check-and-insert".
240    pub fn flight_begin(&self, hash: &str) -> bool {
241        let mut fl = self.flights.lock().unwrap();
242        match fl.get_mut(hash) {
243            // Open flight — join it as a follower.
244            Some(slot) if slot.open => false,
245            // Closed: re-open, keeping the last value for anyone who re-awaits
246            // without new work being done.
247            Some(slot) => {
248                slot.open = true;
249                self.futures.lock().unwrap().insert(hash.to_string());
250                true
251            }
252            None => {
253                fl.insert(hash.to_string(), FlightSlot { open: true, settled: None });
254                self.futures.lock().unwrap().insert(hash.to_string());
255                true
256            }
257        }
258    }
259
260    /// The flight's last outcome, if it has one. Does NOT consume it: every
261    /// waiter must be able to observe the same result.
262    pub fn flight_peek(&self, hash: &str) -> Option<Result<Value, Value>> {
263        self.flights.lock().unwrap().get(hash).and_then(|s| s.settled.clone())
264    }
265
266    /// Whether a flight for `hash` exists and is still open.
267    pub fn flight_is_open(&self, hash: &str) -> bool {
268        self.flights.lock().unwrap().get(hash).map(|s| s.open).unwrap_or(false)
269    }
270
271    /// Settle an open flight and wake its waiters. Returns false (and does
272    /// nothing) when `hash` names no open flight, so `resolve`/`reject` can
273    /// fall through to their normal watch-hash behaviour.
274    pub fn flight_settle(&self, hash: &str, res: Result<Value, Value>) -> bool {
275        {
276            let mut fl = self.flights.lock().unwrap();
277            match fl.get_mut(hash) {
278                Some(slot) if slot.open => {
279                    slot.open = false;
280                    slot.settled = Some(res);
281                }
282                _ => return false,
283            }
284        }
285        // Clear the `futures` entry as part of settling, mirroring TS: the
286        // flight is over, so the next cycle must elect a fresh leader.
287        self.futures.lock().unwrap().remove(hash);
288        self.notify.notify_waiters();
289        true
290    }
291
292    /// Record `subscribe_hash` → `subscription`; returns true the first time
293    /// (so the caller sends the subscribe frame exactly once). Mirrors TS
294    /// `client.subscriptions[subscribeHash] = subscription || true`.
295    pub fn subscribe_once(&self, subscribe_hash: &str, subscription: Value) -> bool {
296        let mut subs = self.subscriptions.lock().unwrap();
297        if subs.contains_key(subscribe_hash) {
298            return false;
299        }
300        let stored = if matches!(subscription, Value::Null) {
301            Value::Bool(true)
302        } else {
303            subscription
304        };
305        subs.insert(subscribe_hash.to_string(), stored);
306        true
307    }
308
309    /// Directly set a subscription entry (TS `client.subscriptions[h] = x`
310    /// written from `handle_message`).
311    pub fn set_subscription(&self, subscribe_hash: &str, subscription: Value) {
312        self.subscriptions.lock().unwrap().insert(subscribe_hash.to_string(), subscription);
313    }
314
315    pub fn is_subscribed(&self, subscribe_hash: &str) -> bool {
316        self.subscriptions.lock().unwrap().contains_key(subscribe_hash)
317    }
318
319    pub fn send_text(&self, s: String) -> bool {
320        if std::env::var("CCXT_WS_DEBUG").is_ok() { eprintln!("[wssend] {}", s.chars().take(200).collect::<String>()); }
321        // Static-WS-test mock transport: record the frame (JSON-parsed, like the
322        // TS `client.connection.send` stub) instead of hitting a socket.
323        if *self.mock.lock().unwrap() {
324            self.mock_sent.lock().unwrap().push(parse_text(&s));
325            return true;
326        }
327        self.outgoing.send(Message::Text(s)).is_ok()
328    }
329
330    /// Enable the mock transport: mark connected (so `ensure_client` never opens
331    /// a socket) and route `send_text` to the capture buffer.
332    pub fn mock_enable(&self) {
333        *self.mock.lock().unwrap() = true;
334        *self.connected.lock().unwrap() = true;
335    }
336    /// Injected inbound frame → the same queue the socket reader feeds.
337    pub fn mock_inject(&self, msg: Value) {
338        self.incoming.lock().unwrap().push_back(msg);
339        self.notify.notify_one();
340    }
341    pub fn is_mock(&self) -> bool { *self.mock.lock().unwrap() }
342    /// The captured outgoing frames as a `Value::List`.
343    pub fn mock_sent_value(&self) -> Value {
344        Value::Array(self.mock_sent.lock().unwrap().clone())
345    }
346    pub fn has_pending_futures(&self) -> bool {
347        !self.futures.lock().unwrap().is_empty()
348    }
349    /// Whether the mock inbound queue still holds un-consumed frames.
350    pub fn has_queued_messages(&self) -> bool {
351        !self.incoming.lock().unwrap().is_empty()
352    }
353    pub fn mark_ws_test_completed(&self) { *self.ws_test_completed.lock().unwrap() = true; }
354    pub fn is_ws_test_completed(&self) -> bool { *self.ws_test_completed.lock().unwrap() }
355    /// Reject every pending future so a fixture whose frames don't resolve the
356    /// watch fails (with a message) rather than hanging the drive loop.
357    pub fn reject_pending_futures(&self, err: Value) {
358        let hashes: Vec<String> = self.futures.lock().unwrap().iter().cloned().collect();
359        for h in hashes { self.reject(&h, err.clone()); }
360    }
361
362    pub fn is_closed(&self) -> bool {
363        *self.closed.lock().unwrap()
364    }
365
366    pub fn on_pong(&self) {
367        *self.last_pong_ms.lock().unwrap() = now_ms();
368    }
369
370    /// Drop resolved/rejected/subscription/future state,
371    /// e.g. after a reconnect so stale hashes don't resolve new waiters.
372    /// Internal wipe only — the transpiled `client.reset(error)` goes through
373    /// `reset_with_error` below, which delivers the error first.
374    pub fn reset(&self) {
375        self.resolved.lock().unwrap().clear();
376        self.rejections.lock().unwrap().clear();
377        self.subscriptions.lock().unwrap().clear();
378        self.futures.lock().unwrap().clear();
379        self.flights.lock().unwrap().clear();
380    }
381
382    /// TS `client.reset(error)` — reject every pending future/flight with the
383    /// error so waiters fail fast instead of hanging, then drop the pending
384    /// future state. Mirrors the js/php/c#/go/java/python clients: rejections
385    /// are kept (they carry the error to the waiters), delivered-but-not-taken
386    /// `resolved` values are kept (in TS an already-resolved future is settled
387    /// — `reject` on it is a no-op — so its waiter still gets the value), and
388    /// subscriptions are left to the caller — the TS `Client.reset` does not
389    /// clear them either.
390    pub fn reset_with_error(&self, error: Value) {
391        let hashes: Vec<String> = self.futures.lock().unwrap().iter().cloned().collect();
392        for h in &hashes {
393            if self.resolved.lock().unwrap().contains_key(h) {
394                continue;
395            }
396            self.reject(h, error.clone());
397        }
398        self.futures.lock().unwrap().clear();
399    }
400
401    /// Snapshot of `subscriptions` as a `Value::Map { hash: subscription }` —
402    /// the shape the transpiled `get_value(&client, "subscriptions")` reads.
403    /// Tagged with `__ws_subs_url` so that writes performed on the snapshot
404    /// (`client.subscriptions[chanId] = …`, common in bitfinex/chan-id venues)
405    /// route back to this live `ClientState` instead of a discarded clone.
406    pub fn subscriptions_value(&self) -> Value {
407        let subs = self.subscriptions.lock().unwrap();
408        let mut m = indexmap::IndexMap::new();
409        m.insert("__ws_subs_url".to_string(), Value::Str(self.url.clone().into()));
410        for (h, sub) in subs.iter() {
411            // Tag each subscription DICT with a back-reference so a field write
412            // on it (`subscription['receivedSnapshot'] = true`) persists to this
413            // live client — venues mutate a subscription retrieved from
414            // client.subscriptions and rely on JS object identity.
415            let tagged = match sub {
416                Value::Dict(d) => {
417                    let mut inner = (**d).clone();
418                    inner.insert("__ws_sub_ref".to_string(),
419                        Value::Str(format!("{}\u{1}{}", self.url, h).into()));
420                    Value::Dict(std::sync::Arc::new(inner))
421                }
422                other => other.clone(),
423            };
424            m.insert(h.clone(), tagged);
425        }
426        Value::Map(m)
427    }
428
429    /// Set a field on a stored subscription dict (`client.subscriptions[hash]
430    /// [key] = val`). Creates the entry if missing.
431    pub fn set_subscription_field(&self, hash: &str, key: &str, val: Value) {
432        let mut subs = self.subscriptions.lock().unwrap();
433        match subs.get_mut(hash) {
434            Some(Value::Dict(d)) => { std::sync::Arc::make_mut(d).insert(key.to_string(), val); }
435            _ => {
436                let mut inner = indexmap::IndexMap::new();
437                inner.insert(key.to_string(), val);
438                subs.insert(hash.to_string(), Value::Dict(std::sync::Arc::new(inner)));
439            }
440        }
441    }
442
443    /// Snapshot of `futures` as a `Value::Map { hash: true }`.
444    pub fn futures_value(&self) -> Value {
445        let f = self.futures.lock().unwrap();
446        let mut m = indexmap::IndexMap::new();
447        for h in f.iter() {
448            // Each entry is a future *handle* carrying the url + its own hash, so
449            // transpiled `client.futures[hash].resolve(x)` (bitget/cryptocom auth)
450            // routes back to this ClientState — see value_resolve/value_reject.
451            let mut fh = indexmap::IndexMap::new();
452            fh.insert("url".to_string(), Value::Str(self.url.clone().into()));
453            fh.insert("__ws_future_hash".to_string(), Value::Str(h.clone().into()));
454            m.insert(h.clone(), Value::Map(fh));
455        }
456        Value::Map(m)
457    }
458}
459
460/// Get the existing client for `url`, or `None` if not yet connected.
461pub fn get_client(url: &str) -> Option<Arc<ClientState>> {
462    let reg = REGISTRY.lock().unwrap();
463    reg.get(url).filter(|c| !c.is_closed()).cloned()
464}
465
466/// `client.subscriptions[key] = val` written on a tagged snapshot — persist it
467/// to the live client so subsequent `handle_message` snapshots see it.
468pub fn value_subs_insert(url: &str, key: &str, val: Value) {
469    if let Some(c) = get_client(url) { c.set_subscription(key, val); }
470}
471
472/// `delete client.subscriptions[key]` on a tagged snapshot.
473pub fn value_subs_remove(url: &str, key: &str) {
474    if let Some(c) = get_client(url) { c.subscriptions.lock().unwrap().remove(key); }
475}
476
477/// `client.subscriptions[hash][key] = val` written on a tagged subscription
478/// dict (carrying `__ws_sub_ref` = "url\u{1}hash").
479pub fn value_sub_field_write(subref: &str, key: &str, val: Value) {
480    if let Some((url, hash)) = subref.split_once('\u{1}') {
481        if let Some(c) = get_client(url) { c.set_subscription_field(hash, key, val); }
482    }
483}
484
485/// Ensure a live connection to `url`, connecting (and spawning the reader /
486/// writer / keep-alive tasks) if needed. Idempotent per URL.
487/// Open an HTTP CONNECT tunnel to `proxy` and hand the raw stream to
488/// tungstenite. `connect_async` has no proxy support of its own, so a venue
489/// reached through `wsProxy` / `wssProxy` has to be dialed this way.
490async fn connect_via_proxy(
491    url: &str,
492    proxy: &str,
493) -> Result<tokio_tungstenite::WebSocketStream<
494        tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>>, String> {
495    use tokio::io::{AsyncReadExt, AsyncWriteExt};
496    let target = url::Url::parse(url).map_err(|e| format!("[NetworkError] ws url {url}: {e}"))?;
497    let host = target.host_str().ok_or_else(|| format!("[NetworkError] ws url {url} has no host"))?;
498    let port = target.port_or_known_default().unwrap_or(443);
499    let p = url::Url::parse(proxy).map_err(|e| format!("[NetworkError] ws proxy {proxy}: {e}"))?;
500    let p_host = p.host_str().ok_or_else(|| format!("[NetworkError] ws proxy {proxy} has no host"))?;
501    let p_port = p.port_or_known_default().unwrap_or(8080);
502    let mut stream = tokio::net::TcpStream::connect((p_host, p_port))
503        .await
504        .map_err(|e| format!("[NetworkError] ws proxy connect {proxy}: {e}"))?;
505    let connect = format!(
506        "CONNECT {host}:{port} HTTP/1.1\r\nHost: {host}:{port}\r\nProxy-Connection: Keep-Alive\r\n\r\n"
507    );
508    stream
509        .write_all(connect.as_bytes())
510        .await
511        .map_err(|e| format!("[NetworkError] ws proxy CONNECT {proxy}: {e}"))?;
512    let mut head = Vec::new();
513    let mut byte = [0u8; 1];
514    while !head.ends_with(b"\r\n\r\n") {
515        let n = stream
516            .read(&mut byte)
517            .await
518            .map_err(|e| format!("[NetworkError] ws proxy CONNECT {proxy}: {e}"))?;
519        if n == 0 {
520            return Err(format!("[NetworkError] ws proxy {proxy} closed during CONNECT"));
521        }
522        head.push(byte[0]);
523        if head.len() > 8192 {
524            return Err(format!("[NetworkError] ws proxy {proxy} sent an oversized CONNECT reply"));
525        }
526    }
527    let status = String::from_utf8_lossy(&head);
528    let first = status.lines().next().unwrap_or_default();
529    if !first.contains(" 200") {
530        return Err(format!("[NetworkError] ws proxy {proxy} refused CONNECT: {first}"));
531    }
532    let (ws, _resp) = tokio_tungstenite::client_async_tls(url, stream)
533        .await
534        .map_err(|e| format!("[NetworkError] ws connect {url} via {proxy}: {e}"))?;
535    Ok(ws)
536}
537
538pub async fn ensure_client(url: &str, proxy: Option<String>, decompress_binary: bool) -> Result<Arc<ClientState>, String> {
539    let state = ensure_slot(url);
540    if *state.connected.lock().unwrap() {
541        return Ok(state);
542    }
543    // Serialize connect; re-check under the gate (another task may have just
544    // connected this slot). Lock via a cloned Arc so `state` stays movable.
545    let gate_holder = state.clone();
546    let _gate = gate_holder.connect_gate.lock().await;
547    if *state.connected.lock().unwrap() {
548        return Ok(state);
549    }
550    let ws = match proxy.as_deref().filter(|p| !p.is_empty()) {
551        Some(p) => connect_via_proxy(url, p).await?,
552        None => {
553            let (ws, _resp) = tokio_tungstenite::connect_async(url)
554                .await
555                .map_err(|e| format!("[NetworkError] ws connect {url}: {e}"))?;
556            ws
557        }
558    };
559    let (mut write, mut read) = ws.split();
560    let mut rx = state.pending_rx.lock().unwrap().take()
561        .ok_or_else(|| format!("[NetworkError] ws {url} slot has no writer channel"))?;
562    *state.last_pong_ms.lock().unwrap() = now_ms();
563
564    // Writer task: drain the outgoing queue to the socket.
565    tokio::spawn(async move {
566        while let Some(msg) = rx.recv().await {
567            if write.send(msg).await.is_err() {
568                break;
569            }
570        }
571        let _ = write.close().await;
572    });
573
574    // Reader task: decode frames → incoming queue.
575    let st = state.clone();
576    tokio::spawn(async move {
577        while let Some(frame) = read.next().await {
578            match frame {
579                Ok(Message::Text(t)) => st.push_incoming(parse_text(&t)),
580                Ok(Message::Binary(b)) => st.push_incoming(if decompress_binary { parse_binary(&b) } else { parse_raw_binary(&b) }),
581                Ok(Message::Pong(_)) => st.on_pong(),
582                // tungstenite answers Ping frames with Pong automatically.
583                Ok(Message::Ping(_)) => {}
584                Ok(Message::Close(_)) | Err(_) => break,
585                _ => {}
586            }
587        }
588        *st.connected.lock().unwrap() = false;
589        *st.closed.lock().unwrap() = true;
590        st.notify.notify_waiters();
591    });
592
593    // Keep-alive: an unsolicited Ping every 30s; the peer's Pong updates
594    // last_pong. (Full miss-count RequestTimeout handling is a later refinement.)
595    let st2 = state.clone();
596    tokio::spawn(async move {
597        let mut iv = tokio::time::interval(std::time::Duration::from_secs(30));
598        iv.tick().await; // first tick fires immediately; skip it
599        loop {
600            iv.tick().await;
601            if st2.is_closed() {
602                break;
603            }
604            if st2.outgoing.send(Message::Ping(Vec::new())).is_err() {
605                break;
606            }
607        }
608    });
609
610    *state.connected.lock().unwrap() = true;
611    Ok(state)
612}
613
614/// Live read of a client handle's `subscriptions` / `futures` field, straight
615/// from the registry so a read after a write (upbit builds its subscribe frame
616/// from subscriptions it just set) is coherent, not a stale embedded snapshot.
617pub fn client_field_live(url: &str, field: &str) -> Value {
618    match get_client(url) {
619        Some(c) if field == "futures" => c.futures_value(),
620        Some(c) => c.subscriptions_value(),
621        None => Value::Map(indexmap::IndexMap::new()),
622    }
623}
624
625/// Get-or-create the registry slot for `url` WITHOUT connecting the socket, so
626/// `client.subscriptions` written before `watch()` connects still persist.
627fn ensure_slot(url: &str) -> Arc<ClientState> {
628    let mut reg = REGISTRY.lock().unwrap();
629    if let Some(c) = reg.get(url) {
630        if !c.is_closed() {
631            return c.clone();
632        }
633    }
634    let (tx, rx) = mpsc::unbounded_channel::<Message>();
635    let state = Arc::new(ClientState {
636        url: url.to_string(),
637        outgoing: tx,
638        pending_rx: Mutex::new(Some(rx)),
639        connect_gate: tokio::sync::Mutex::new(()),
640        incoming: Mutex::new(VecDeque::new()),
641        notify: Notify::new(),
642        resolved: Mutex::new(HashMap::new()),
643        rejections: Mutex::new(HashMap::new()),
644        subscriptions: Mutex::new(HashMap::new()),
645        futures: Mutex::new(HashSet::new()),
646        flights: Mutex::new(HashMap::new()),
647        connected: Mutex::new(false),
648        closed: Mutex::new(false),
649        last_pong_ms: Mutex::new(now_ms()),
650        mock: Mutex::new(false),
651        mock_sent: Mutex::new(Vec::new()),
652        ws_test_completed: Mutex::new(false),
653    });
654    reg.insert(url.to_string(), state.clone());
655    state
656}
657
658/// Remove (and thereby drop / disconnect) the client for `url`.
659pub fn drop_client(url: &str) {
660    REGISTRY.lock().unwrap().remove(url);
661}
662
663// ── `Value`-handle bridge ────────────────────────────────────────────────────
664//
665// The transpiled `handle_message(&mut self, client: Value, message: Value)`
666// receives a *client* as a `Value`. We model it as `Value::Map { "url": <url>,
667// "subscriptions": <snapshot>, "futures": <snapshot> }`. The `Value` methods
668// `resolve`/`reject`/`send`/… (in value.rs) extract `url` and route here.
669
670// ── Static-WS-test mock transport (url-keyed façade over ClientState) ────────
671
672/// `setupWsMockTransport(url)` — register a connected, socket-less client whose
673/// sends are captured. Clears any prior state so each fixture starts fresh.
674pub fn mock_setup(url: &str) {
675    let c = ensure_slot(url);
676    c.reset();
677    c.mock_enable();
678    c.mock_sent.lock().unwrap().clear();
679    // Discard any messages left unconsumed by a prior test on the same URL (e.g.
680    // a heartbeat a watchTrades drive loop returned past before reading) so they
681    // don't leak an extra handler dispatch / sent frame into the next test.
682    c.incoming.lock().unwrap().clear();
683    *c.ws_test_completed.lock().unwrap() = false;
684}
685pub fn mock_inject(url: &str, msg: Value) {
686    if let Some(c) = get_client(url) { c.mock_inject(msg); }
687}
688pub fn mock_sent_messages(url: &str) -> Value {
689    match get_client(url) { Some(c) => c.mock_sent_value(), None => Value::Array(vec![]) }
690}
691pub fn mock_has_pending_futures(url: &str) -> bool {
692    get_client(url).map(|c| c.has_pending_futures()).unwrap_or(false)
693}
694pub fn mock_has_queued_messages(url: &str) -> bool {
695    get_client(url).map(|c| c.has_queued_messages()).unwrap_or(false)
696}
697pub fn mock_mark_completed(url: &str) {
698    if let Some(c) = get_client(url) { c.mark_ws_test_completed(); }
699}
700pub fn mock_is_completed(url: &str) -> bool {
701    get_client(url).map(|c| c.is_ws_test_completed()).unwrap_or(true)
702}
703pub fn mock_reject_futures(url: &str) {
704    if let Some(c) = get_client(url) {
705        c.reject_pending_futures(Value::Str(
706            "[ExchangeError] static ws test: the injected messages did not resolve the watch future".to_string().into()));
707    }
708}
709
710/// Build the client-handle `Value` passed to `handle_message`: the URL plus
711/// live snapshots of `subscriptions` / `futures` (the fields venues read via
712/// `get_value(&client, "subscriptions")`).
713pub fn client_value(url: &str) -> Value {
714    // Pre-register the slot so subscriptions written on this handle (before the
715    // socket connects) persist and read back — upbit-style subscribe building.
716    let c = ensure_slot(url);
717    let mut m = indexmap::IndexMap::new();
718    m.insert("url".to_string(), Value::Str(url.to_string().into()));
719    m.insert("subscriptions".to_string(), c.subscriptions_value());
720    m.insert("futures".to_string(), c.futures_value());
721    Value::Map(m)
722}
723
724/// Open-or-join the single-flight for `hash` on `url`, creating the registry
725/// slot if the client has not been dialed yet (venue `authenticate` parks its
726/// flights on a never-dialed pseudo-url, because the real user-data url embeds
727/// the credential the flight is fetching).
728pub fn begin_flight(url: &str, hash: &str) -> bool {
729    ensure_slot(url).flight_begin(hash)
730}
731
732
733/// The `Value` a `client.future ()` / `client.reusableFuture ()` call hands
734/// back: enough to find the flight again (its client's url + the hash). TS
735/// returns a real Future object; a `Value` can't hold one, so the port returns
736/// a handle and `ws_await_flight` does the awaiting.
737pub fn flight_handle(url: &str, hash: &str, led: bool) -> Value {
738    let mut m = indexmap::IndexMap::new();
739    m.insert("url".to_string(), Value::Str(url.to_string().into()));
740    m.insert("__ws_flight_hash".to_string(), Value::Str(hash.to_string().into()));
741    // Whether the call that produced this handle opened the flight. A leader
742    // settles its own flight (and TS's `await future` resolves the instant it
743    // does), so it must never block on itself — including when the venue
744    // decides, after taking the lead, that there is no work to do because it
745    // is already subscribed (bitget's `authenticate`).
746    m.insert("__ws_flight_led".to_string(), Value::Bool(led));
747    Value::Map(m)
748}
749
750/// The hash a flight handle refers to. Accepts the `futures_value ()` handle
751/// shape too, so `client.futures[hash]` entries can be awaited as well.
752fn flight_hash_of(handle: &Value) -> Option<String> {
753    for key in ["__ws_flight_hash", "__ws_future_hash"] {
754        if let Value::Str(h) = crate::get_value(handle, &Value::Str(key.to_string().into())) {
755            return Some(h.to_string());
756        }
757    }
758    None
759}
760
761/// Await a flight handle — the port of TS's `await client.future (hash)` and
762/// of the trailing `await future` a single-flight leader runs after settling.
763///
764/// Returns the resolved value; a rejected flight panics with the error, which
765/// is how the port rethrows (the drive loop does the same with `take_settled`).
766/// A handle that names no flight returns `Value::Null` rather than hanging.
767pub async fn ws_await_flight(handle: &Value) -> Value {
768    let (url, hash) = match (url_of(handle), flight_hash_of(handle)) {
769        (Some(u), Some(h)) => (u, h),
770        _ => return Value::Null,
771    };
772    let client = match get_client(&url) {
773        Some(c) => c,
774        None => return Value::Null,
775    };
776    let settled = client.flight_peek(&hash);
777    // The leader: its own `client.resolve ()` has already run by the time it
778    // reaches its trailing await, so take the value and go. Waiting here would
779    // deadlock the (common) case where the venue took the lead and then found
780    // it had nothing to do.
781    let led = matches!(
782        crate::get_value(handle, &Value::Str("__ws_flight_led".into())),
783        Value::Bool(true)
784    );
785    if led || !client.flight_is_open(&hash) {
786        return match settled {
787            Some(Ok(v)) => v,
788            Some(Err(e)) => panic!(
789                "{}",
790                match &e {
791                    Value::Str(s) => s.clone(),
792                    v => crate::runtime::stringify_param(v).into(),
793                }
794            ),
795            // A flight that never opened is not an error — the value it would
796            // have carried is already in the venue's own cache, which is what
797            // the caller reads next.
798            None => Value::Null,
799        };
800    }
801    let budget = if client.is_mock() {
802        std::time::Duration::from_millis(1500)
803    } else {
804        std::time::Duration::from_secs(60)
805    };
806    let deadline = tokio::time::Instant::now() + budget;
807    loop {
808        // Create the wakeup before peeking, so a settle racing this loop is
809        // never missed (same pattern as `next_message`).
810        let notified = client.notify.notified();
811        if let Some(res) = client.flight_peek(&hash) {
812            return match res {
813                Ok(v) => v,
814                Err(e) => panic!(
815                    "{}",
816                    match &e {
817                        Value::Str(s) => s.clone(),
818                        v => crate::runtime::stringify_param(v).into(),
819                    }
820                ),
821            };
822        }
823        if !client.flight_is_open(&hash) {
824            // Closed without a value (reset between fixture cases).
825            return Value::Null;
826        }
827        if tokio::time::timeout_at(deadline, notified).await.is_err() {
828            panic!(
829                "[NetworkError] timed out waiting for the in-flight '{}' on {}",
830                hash, url
831            );
832        }
833    }
834}
835
836/// Extract the `url` from a client-handle `Value` (`Map{"url": ...}`).
837pub fn url_of(client: &Value) -> Option<String> {
838    match crate::get_value(client, &Value::Str("url".into())) {
839        Value::Str(s) => Some(s.to_string()),
840        _ => None,
841    }
842}
843
844fn hash_str(v: &Value) -> Option<String> {
845    match v {
846        Value::Str(s) => Some(s.to_string()),
847        _ => None,
848    }
849}
850
851/// `client.resolve(value, messageHash)` routed by URL. Returns `value`.
852pub fn value_resolve(client: &Value, args: &[Value]) -> Value {
853    let value = args.get(0).cloned().unwrap_or(Value::Null);
854    // `client.futures[hash].resolve(value)` — the future handle carries its own
855    // hash, so there is no second arg. Resolve that hash.
856    if let Some(hash) = future_hash_of(client) {
857        if let Some(url) = url_of(client) {
858            if let Some(c) = get_client(&url) { c.resolve(&hash, value.clone()); }
859        }
860        return value;
861    }
862    if let (Some(url), Some(hash)) = (url_of(client), args.get(1).and_then(hash_str)) {
863        if let Some(c) = get_client(&url) {
864            c.resolve(&hash, value.clone());
865        }
866    }
867    value
868}
869
870/// Extract the hash a future handle (`client.futures[hash]`) resolves/rejects.
871fn future_hash_of(client: &Value) -> Option<String> {
872    match crate::get_value(client, &Value::Str("__ws_future_hash".into())) {
873        Value::Str(s) => Some(s.to_string()),
874        _ => None,
875    }
876}
877
878/// `client.reject(error, messageHash)` routed by URL.
879pub fn value_reject(client: &Value, args: &[Value]) -> Value {
880    let err = args.get(0).cloned().unwrap_or(Value::Null);
881    // `client.futures[hash].reject(error)` — future handle carries its own hash.
882    if let Some(hash) = future_hash_of(client) {
883        if let Some(url) = url_of(client) {
884            if let Some(c) = get_client(&url) { c.reject(&hash, err.clone()); }
885        }
886        return err;
887    }
888    if let Some(url) = url_of(client) {
889        if let Some(c) = get_client(&url) {
890            match args.get(1).and_then(hash_str) {
891                Some(hash) => c.reject(&hash, err.clone()),
892                // reject with no hash → reject every pending future.
893                None => {
894                    let hashes: Vec<String> = c.futures.lock().unwrap().iter().cloned().collect();
895                    for h in hashes {
896                        c.reject(&h, err.clone());
897                    }
898                }
899            }
900        }
901    }
902    err
903}
904
905/// `client.send(message)` routed by URL. Serialises non-string payloads to JSON.
906pub fn value_send(client: &Value, args: &[Value]) -> Value {
907    if let Some(url) = url_of(client) {
908        if let Some(c) = get_client(&url) {
909            let payload = match args.get(0) {
910                Some(Value::Str(s)) => s.to_string(),
911                Some(v) => v.to_json().to_string(),
912                None => String::new().into(),
913            };
914            c.send_text(payload);
915        }
916    }
917    Value::Null
918}
919
920/// `client.reset(...)` routed by URL. An arg-less `client.reset()` reaches
921/// here with `Value::Null` — there is no error to deliver, so fall back to
922/// the internal wipe rather than rejecting every waiter with a null error.
923pub fn value_reset(client: &Value, error: Value) -> Value {
924    if let Some(url) = url_of(client) {
925        if let Some(c) = get_client(&url) {
926            if matches!(error, Value::Null) {
927                c.reset();
928            } else {
929                c.reset_with_error(error);
930            }
931        }
932    }
933    Value::Null
934}
935
936/// `client.on_pong(...)` routed by URL.
937pub fn value_on_pong(client: &Value) -> Value {
938    if let Some(url) = url_of(client) {
939        if let Some(c) = get_client(&url) {
940            c.on_pong();
941        }
942    }
943    Value::Null
944}
945
946#[cfg(test)]
947mod tests {
948    use super::*;
949    use tokio_tungstenite::tungstenite::Message as WsMessage;
950
951    // A minimal mock exchange WS server: accepts one connection, waits for a
952    // subscribe frame, then streams a few JSON "ticker" messages. Proves the
953    // full connect → send(subscribe) → receive → parse → resolve round-trip
954    // without touching a live venue.
955    async fn spawn_mock_server() -> String {
956        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
957        let addr = listener.local_addr().unwrap();
958        tokio::spawn(async move {
959            if let Ok((stream, _)) = listener.accept().await {
960                let mut ws = tokio_tungstenite::accept_async(stream).await.unwrap();
961                // Wait for the client's subscribe frame.
962                if let Some(Ok(WsMessage::Text(sub))) = ws.next().await {
963                    assert!(sub.contains("subscribe"), "expected subscribe, got {sub}");
964                }
965                // Stream three ticker updates.
966                for px in ["100.5", "101.0", "101.5"] {
967                    let msg = format!("{{\"channel\":\"ticker\",\"symbol\":\"BTC/USDT\",\"last\":\"{px}\"}}");
968                    ws.send(WsMessage::Text(msg)).await.unwrap();
969                }
970                // Give the client time to drain before closing.
971                tokio::time::sleep(std::time::Duration::from_millis(50)).await;
972                let _ = ws.close(None).await;
973            }
974        });
975        format!("ws://{addr}")
976    }
977
978    // The transpiled `client.reset(error)` path (`value_reset` →
979    // `reset_with_error`): a pending watch hash must observe the error (not
980    // hang), a delivered-but-not-taken value must survive the reset, and an
981    // arg-less `client.reset()` (error = `Value::Null`) must fall back to the
982    // silent wipe instead of rejecting waiters with a null error.
983    #[test]
984    fn value_reset_rejects_pending_futures() {
985        let url = "ws://reset-with-error.test";
986        mock_setup(url);
987        let client = get_client(url).expect("mock client");
988        client.note_futures(&["pending".to_string(), "delivered".to_string()]);
989        client.resolve("delivered", Value::Str("payload".into()));
990
991        let handle = client_value(url);
992        let error = Value::Str("[InvalidNonce] gap detected".into());
993        value_reset(&handle, error.clone());
994
995        // The pending waiter fails fast with the reset error…
996        assert_eq!(
997            client.take_settled(&["pending".to_string()]),
998            Some(Err(error))
999        );
1000        // …while the already-delivered value still reaches its waiter.
1001        assert_eq!(
1002            client.take_settled(&["delivered".to_string()]),
1003            Some(Ok(Value::Str("payload".into())))
1004        );
1005        assert!(!client.has_pending_futures());
1006
1007        // Arg-less reset: silent wipe, nothing settled with a null error.
1008        client.note_futures(&["pending2".to_string()]);
1009        value_reset(&handle, Value::Null);
1010        assert_eq!(client.take_settled(&["pending2".to_string()]), None);
1011        assert!(!client.has_pending_futures());
1012
1013        drop_client(url);
1014    }
1015
1016    #[tokio::test]
1017    async fn transport_roundtrip() {
1018        let url = spawn_mock_server().await;
1019        let client = ensure_client(&url, None, true).await.expect("connect");
1020
1021        // Send a subscribe frame once (idempotent per hash).
1022        assert!(client.subscribe_once("ticker:BTC/USDT", Value::Null));
1023        assert!(!client.subscribe_once("ticker:BTC/USDT", Value::Null));
1024        assert!(client.send_text("{\"op\":\"subscribe\",\"channel\":\"ticker\"}".to_string()));
1025
1026        // Drive: pull each inbound message, mimic handle_message resolving the
1027        // "ticker" hash, and collect the resolved values.
1028        let mut lasts = Vec::new();
1029        while lasts.len() < 3 {
1030            let msg = client.next_message().await.expect("message before close");
1031            let last = crate::get_value(&msg, &Value::Str("last".into()));
1032            if let Value::Str(s) = &last {
1033                client.resolve("ticker", Value::Str(s.clone()));
1034            }
1035            if let Some(Ok(Value::Str(v))) = client.take_settled(&["ticker".to_string()]) {
1036                lasts.push(v);
1037            }
1038        }
1039        assert_eq!(lasts, vec!["100.5", "101.0", "101.5"]);
1040
1041        // Field snapshots the transpiled code reads off the client handle.
1042        let subs = client.subscriptions_value();
1043        assert!(crate::runtime::is_true(&crate::get_value(
1044            &subs,
1045            &Value::Str("ticker:BTC/USDT".into())
1046        )));
1047
1048        drop_client(&url);
1049    }
1050
1051    // A minimal Core whose `handle_message` resolves the "ticker" hash with the
1052    // inbound message's `last` field — exactly what a real venue's
1053    // handle_message does. Lets us drive the *actual* `watch()` runtime end to
1054    // end (connect → subscribe → frame → dispatch_to_derived("handle_message")
1055    // → resolve → return) against the mock server, independent of venue quirks.
1056    struct TestWsCore {
1057        exchange: crate::exchange::Exchange,
1058    }
1059    impl std::ops::Deref for TestWsCore {
1060        type Target = crate::exchange::Exchange;
1061        fn deref(&self) -> &Self::Target {
1062            &self.exchange
1063        }
1064    }
1065    impl std::ops::DerefMut for TestWsCore {
1066        fn deref_mut(&mut self) -> &mut Self::Target {
1067            &mut self.exchange
1068        }
1069    }
1070    impl crate::exchange::DerivedExchange for TestWsCore {}
1071    impl crate::exchange_generated::ExchangeBase for TestWsCore {
1072        fn call_dynamic<'a>(
1073            &'a mut self,
1074            method: &'a str,
1075            args: Vec<Value>,
1076        ) -> std::pin::Pin<Box<dyn std::future::Future<Output = Value> + Send + 'a>> {
1077            Box::pin(async move {
1078                match method {
1079                    "handle_message" => {
1080                        let client = args.get(0).cloned().unwrap_or(Value::Null);
1081                        let message = args.get(1).cloned().unwrap_or(Value::Null);
1082                        let last = crate::get_value(&message, &Value::Str("last".into()));
1083                        // `client.resolve(value, messageHash)` — routes to the registry.
1084                        client.resolve(&[last, Value::Str("ticker".into())]);
1085                        Value::Null
1086                    }
1087                    _ => self.call_dynamic_base(method, args).await,
1088                }
1089            })
1090        }
1091    }
1092
1093    #[tokio::test]
1094    async fn watch_drive_loop_end_to_end() {
1095        use crate::exchange::ExchangeRuntime;
1096        let url = spawn_mock_server().await;
1097        let mut core = TestWsCore {
1098            exchange: crate::exchange::Exchange::new(None),
1099        };
1100        // Drive the real base `watch()`: connect, send subscribe, read frames,
1101        // dispatch each to handle_message, return once "ticker" resolves.
1102        let result = ExchangeRuntime::watch(
1103            &mut core,
1104            Value::Str(url.clone().into()),
1105            Value::Str("ticker".into()),
1106            &[
1107                Value::Str("{\"op\":\"subscribe\",\"channel\":\"ticker\"}".into()),
1108                Value::Str("ticker".into()),
1109                Value::Null,
1110            ],
1111        )
1112        .await;
1113        // First streamed ticker.
1114        assert_eq!(result, Value::Str("100.5".into()));
1115        drop_client(&url);
1116    }
1117
1118    // ── single-flight (client.future / client.reusableFuture) ───────────────
1119    //
1120    // The venue `authenticate` idiom: the first caller leads and fetches the
1121    // credential, concurrent callers join the flight and wake when it settles.
1122    // Regression cover for the port's original no-op `future()` stub, where
1123    // every caller led and nobody waited.
1124
1125    #[tokio::test]
1126    async fn flight_elects_one_leader_and_registers_it() {
1127        let url = "flight-test-election";
1128        let c = ensure_slot(url);
1129        assert!(c.flight_begin("authenticate:future"), "first caller leads");
1130        assert!(!c.flight_begin("authenticate:future"), "second caller follows");
1131        // The follower's `messageHash in client.futures` test must see it.
1132        assert!(in_op_futures(&c, "authenticate:future"));
1133        drop_client(url);
1134    }
1135
1136    #[tokio::test]
1137    async fn flight_settle_wakes_waiters_and_reopens() {
1138        let url = "flight-test-settle";
1139        let c = ensure_slot(url);
1140        assert!(c.flight_begin("auth"));
1141        // Every waiter observes the value — settling must not consume it.
1142        c.resolve("auth", Value::Str("listen-key".into()));
1143        assert_eq!(
1144            ws_await_flight(&flight_handle(url, "auth", false)).await,
1145            Value::Str("listen-key".into())
1146        );
1147        assert_eq!(
1148            ws_await_flight(&flight_handle(url, "auth", false)).await,
1149            Value::Str("listen-key".into())
1150        );
1151        // Settled ⇒ cleared from `futures`, so the next cycle re-leads rather
1152        // than parking every caller on the follower branch forever.
1153        assert!(!in_op_futures(&c, "auth"));
1154        assert!(c.flight_begin("auth"), "a settled flight re-elects");
1155        drop_client(url);
1156    }
1157
1158    #[tokio::test]
1159    async fn flight_follower_waits_for_the_leader() {
1160        let url = "flight-test-wait";
1161        let c = ensure_slot(url);
1162        assert!(c.flight_begin("auth"));
1163        let settler = {
1164            let c = c.clone();
1165            tokio::spawn(async move {
1166                tokio::time::sleep(std::time::Duration::from_millis(60)).await;
1167                c.resolve("auth", Value::Str("late".into()));
1168            })
1169        };
1170        let started = std::time::Instant::now();
1171        let got = ws_await_flight(&flight_handle(url, "auth", false)).await;
1172        assert_eq!(got, Value::Str("late".into()));
1173        assert!(started.elapsed() >= std::time::Duration::from_millis(50), "waited for the leader");
1174        settler.await.unwrap();
1175        drop_client(url);
1176    }
1177
1178    #[tokio::test]
1179    async fn a_leader_never_blocks_on_its_own_flight() {
1180        // A venue can take the lead and then find it has nothing to do — bitget
1181        // re-`authenticate`s on an already-subscribed client. Its trailing
1182        // `await future` must return, not wait for a settle that never comes.
1183        let url = "flight-test-leader";
1184        let c = ensure_slot(url);
1185        let led = c.flight_begin("authenticated");
1186        assert!(led);
1187        let started = std::time::Instant::now();
1188        assert_eq!(
1189            ws_await_flight(&flight_handle(url, "authenticated", led)).await,
1190            Value::Null
1191        );
1192        assert!(started.elapsed() < std::time::Duration::from_millis(200), "returned at once");
1193        // Having led once and settled, the value is still there for a re-await.
1194        c.resolve("authenticated", Value::Bool(true));
1195        let led2 = c.flight_begin("authenticated");
1196        assert_eq!(
1197            ws_await_flight(&flight_handle(url, "authenticated", led2)).await,
1198            Value::Bool(true),
1199            "a re-lead with no new work reports the last value"
1200        );
1201        drop_client(url);
1202    }
1203
1204    #[tokio::test]
1205    async fn flight_handle_without_a_flight_returns_null() {
1206        // Never-opened flight: return rather than hang, the value the caller
1207        // wanted is already in the venue's own cache.
1208        let url = "flight-test-missing";
1209        ensure_slot(url);
1210        assert_eq!(ws_await_flight(&flight_handle(url, "nope", false)).await, Value::Null);
1211        drop_client(url);
1212    }
1213
1214    /// The transpiled follower test, `messageHash in client.futures`.
1215    fn in_op_futures(c: &Arc<ClientState>, hash: &str) -> bool {
1216        !matches!(
1217            crate::get_value(&c.futures_value(), &Value::Str(hash.to_string().into())),
1218            Value::Null
1219        )
1220    }
1221
1222    #[tokio::test]
1223    async fn parse_helpers() {
1224        // JSON text → dict; non-JSON → Value::Str.
1225        assert!(matches!(parse_text("{\"a\":1}"), Value::Dict(_)));
1226        assert_eq!(parse_text("pong"), Value::Str("pong".into()));
1227        // gzip binary → parsed JSON.
1228        use std::io::Write;
1229        let mut e = flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::default());
1230        e.write_all(b"{\"x\":true}").unwrap();
1231        let gz = e.finish().unwrap();
1232        assert!(matches!(parse_binary(&gz), Value::Dict(_)));
1233    }
1234
1235    #[test]
1236    fn raw_binary_frames_stay_bytes() {
1237        // an SBE heartbeat header is all small integers, so the frame is valid
1238        // utf-8, it must still reach the exchange as bytes with decompressBinary off
1239        let frame: Vec<u8> = vec![0x10, 0x00, 0x28, 0x00, 0x01, 0x00, 0x02, 0x00, 0x41, 0x42, 0x43, 0x01];
1240        assert!(std::str::from_utf8(&frame).is_ok());
1241        assert_eq!(parse_raw_binary(&frame), crate::exchange_stubs::bytes_to_value(&frame));
1242        // json over the binary opcode is still parsed
1243        assert!(matches!(parse_raw_binary(b"{\"x\":true}"), Value::Dict(_)));
1244    }
1245}