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.
490fn upgrade_request(
491    url: &str,
492    headers: &[(String, String)],
493) -> Result<tokio_tungstenite::tungstenite::handshake::client::Request, String> {
494    use tokio_tungstenite::tungstenite::client::IntoClientRequest;
495    use tokio_tungstenite::tungstenite::http::{HeaderName, HeaderValue};
496    let mut request = url
497        .into_client_request()
498        .map_err(|e| format!("[NetworkError] ws url {url}: {e}"))?;
499    for (key, value) in headers {
500        let name = HeaderName::from_bytes(key.as_bytes())
501            .map_err(|e| format!("[BadRequest] ws header {key}: {e}"))?;
502        let value = HeaderValue::from_str(value)
503            .map_err(|e| format!("[BadRequest] ws header {key}: {e}"))?;
504        request.headers_mut().insert(name, value);
505    }
506    Ok(request)
507}
508
509async fn connect_via_proxy(
510    url: &str,
511    headers: &[(String, String)],
512    proxy: &str,
513) -> Result<tokio_tungstenite::WebSocketStream<
514        tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>>, String> {
515    use tokio::io::{AsyncReadExt, AsyncWriteExt};
516    let target = url::Url::parse(url).map_err(|e| format!("[NetworkError] ws url {url}: {e}"))?;
517    let host = target.host_str().ok_or_else(|| format!("[NetworkError] ws url {url} has no host"))?;
518    let port = target.port_or_known_default().unwrap_or(443);
519    let p = url::Url::parse(proxy).map_err(|e| format!("[NetworkError] ws proxy {proxy}: {e}"))?;
520    let p_host = p.host_str().ok_or_else(|| format!("[NetworkError] ws proxy {proxy} has no host"))?;
521    let p_port = p.port_or_known_default().unwrap_or(8080);
522    let mut stream = tokio::net::TcpStream::connect((p_host, p_port))
523        .await
524        .map_err(|e| format!("[NetworkError] ws proxy connect {proxy}: {e}"))?;
525    let connect = format!(
526        "CONNECT {host}:{port} HTTP/1.1\r\nHost: {host}:{port}\r\nProxy-Connection: Keep-Alive\r\n\r\n"
527    );
528    stream
529        .write_all(connect.as_bytes())
530        .await
531        .map_err(|e| format!("[NetworkError] ws proxy CONNECT {proxy}: {e}"))?;
532    let mut head = Vec::new();
533    let mut byte = [0u8; 1];
534    while !head.ends_with(b"\r\n\r\n") {
535        let n = stream
536            .read(&mut byte)
537            .await
538            .map_err(|e| format!("[NetworkError] ws proxy CONNECT {proxy}: {e}"))?;
539        if n == 0 {
540            return Err(format!("[NetworkError] ws proxy {proxy} closed during CONNECT"));
541        }
542        head.push(byte[0]);
543        if head.len() > 8192 {
544            return Err(format!("[NetworkError] ws proxy {proxy} sent an oversized CONNECT reply"));
545        }
546    }
547    let status = String::from_utf8_lossy(&head);
548    let first = status.lines().next().unwrap_or_default();
549    if !first.contains(" 200") {
550        return Err(format!("[NetworkError] ws proxy {proxy} refused CONNECT: {first}"));
551    }
552    let (ws, _resp) = tokio_tungstenite::client_async_tls(upgrade_request(url, headers)?, stream)
553        .await
554        .map_err(|e| format!("[NetworkError] ws connect {url} via {proxy}: {e}"))?;
555    Ok(ws)
556}
557
558pub async fn ensure_client(url: &str, proxy: Option<String>, decompress_binary: bool) -> Result<Arc<ClientState>, String> {
559    ensure_client_with_headers(url, &[], proxy, decompress_binary).await
560}
561
562/// `ensure_client` with extra upgrade-request headers (TS `options.ws.options.headers`).
563pub async fn ensure_client_with_headers(
564    url: &str,
565    headers: &[(String, String)],
566    proxy: Option<String>,
567    decompress_binary: bool,
568) -> Result<Arc<ClientState>, String> {
569    let state = ensure_slot(url);
570    if *state.connected.lock().unwrap() {
571        return Ok(state);
572    }
573    // Serialize connect; re-check under the gate (another task may have just
574    // connected this slot). Lock via a cloned Arc so `state` stays movable.
575    let gate_holder = state.clone();
576    let _gate = gate_holder.connect_gate.lock().await;
577    if *state.connected.lock().unwrap() {
578        return Ok(state);
579    }
580    let ws = match proxy.as_deref().filter(|p| !p.is_empty()) {
581        Some(p) => connect_via_proxy(url, headers, p).await?,
582        None => {
583            let (ws, _resp) = tokio_tungstenite::connect_async(upgrade_request(url, headers)?)
584                .await
585                .map_err(|e| format!("[NetworkError] ws connect {url}: {e}"))?;
586            ws
587        }
588    };
589    let (mut write, mut read) = ws.split();
590    let mut rx = state.pending_rx.lock().unwrap().take()
591        .ok_or_else(|| format!("[NetworkError] ws {url} slot has no writer channel"))?;
592    *state.last_pong_ms.lock().unwrap() = now_ms();
593
594    // Writer task: drain the outgoing queue to the socket.
595    tokio::spawn(async move {
596        while let Some(msg) = rx.recv().await {
597            if write.send(msg).await.is_err() {
598                break;
599            }
600        }
601        let _ = write.close().await;
602    });
603
604    // Reader task: decode frames → incoming queue.
605    let st = state.clone();
606    tokio::spawn(async move {
607        while let Some(frame) = read.next().await {
608            match frame {
609                Ok(Message::Text(t)) => st.push_incoming(parse_text(&t)),
610                Ok(Message::Binary(b)) => st.push_incoming(if decompress_binary { parse_binary(&b) } else { parse_raw_binary(&b) }),
611                Ok(Message::Pong(_)) => st.on_pong(),
612                // tungstenite answers Ping frames with Pong automatically.
613                Ok(Message::Ping(_)) => {}
614                Ok(Message::Close(_)) | Err(_) => break,
615                _ => {}
616            }
617        }
618        *st.connected.lock().unwrap() = false;
619        *st.closed.lock().unwrap() = true;
620        st.notify.notify_waiters();
621    });
622
623    // Keep-alive: an unsolicited Ping every 30s; the peer's Pong updates
624    // last_pong. (Full miss-count RequestTimeout handling is a later refinement.)
625    let st2 = state.clone();
626    tokio::spawn(async move {
627        let mut iv = tokio::time::interval(std::time::Duration::from_secs(30));
628        iv.tick().await; // first tick fires immediately; skip it
629        loop {
630            iv.tick().await;
631            if st2.is_closed() {
632                break;
633            }
634            if st2.outgoing.send(Message::Ping(Vec::new())).is_err() {
635                break;
636            }
637        }
638    });
639
640    *state.connected.lock().unwrap() = true;
641    Ok(state)
642}
643
644/// Live read of a client handle's `subscriptions` / `futures` field, straight
645/// from the registry so a read after a write (upbit builds its subscribe frame
646/// from subscriptions it just set) is coherent, not a stale embedded snapshot.
647pub fn client_field_live(url: &str, field: &str) -> Value {
648    match get_client(url) {
649        Some(c) if field == "futures" => c.futures_value(),
650        Some(c) => c.subscriptions_value(),
651        None => Value::Map(indexmap::IndexMap::new()),
652    }
653}
654
655/// Get-or-create the registry slot for `url` WITHOUT connecting the socket, so
656/// `client.subscriptions` written before `watch()` connects still persist.
657fn ensure_slot(url: &str) -> Arc<ClientState> {
658    let mut reg = REGISTRY.lock().unwrap();
659    if let Some(c) = reg.get(url) {
660        if !c.is_closed() {
661            return c.clone();
662        }
663    }
664    let (tx, rx) = mpsc::unbounded_channel::<Message>();
665    let state = Arc::new(ClientState {
666        url: url.to_string(),
667        outgoing: tx,
668        pending_rx: Mutex::new(Some(rx)),
669        connect_gate: tokio::sync::Mutex::new(()),
670        incoming: Mutex::new(VecDeque::new()),
671        notify: Notify::new(),
672        resolved: Mutex::new(HashMap::new()),
673        rejections: Mutex::new(HashMap::new()),
674        subscriptions: Mutex::new(HashMap::new()),
675        futures: Mutex::new(HashSet::new()),
676        flights: Mutex::new(HashMap::new()),
677        connected: Mutex::new(false),
678        closed: Mutex::new(false),
679        last_pong_ms: Mutex::new(now_ms()),
680        mock: Mutex::new(false),
681        mock_sent: Mutex::new(Vec::new()),
682        ws_test_completed: Mutex::new(false),
683    });
684    reg.insert(url.to_string(), state.clone());
685    state
686}
687
688/// Remove (and thereby drop / disconnect) the client for `url`.
689pub fn drop_client(url: &str) {
690    REGISTRY.lock().unwrap().remove(url);
691}
692
693// ── `Value`-handle bridge ────────────────────────────────────────────────────
694//
695// The transpiled `handle_message(&mut self, client: Value, message: Value)`
696// receives a *client* as a `Value`. We model it as `Value::Map { "url": <url>,
697// "subscriptions": <snapshot>, "futures": <snapshot> }`. The `Value` methods
698// `resolve`/`reject`/`send`/… (in value.rs) extract `url` and route here.
699
700// ── Static-WS-test mock transport (url-keyed façade over ClientState) ────────
701
702/// `setupWsMockTransport(url)` — register a connected, socket-less client whose
703/// sends are captured. Clears any prior state so each fixture starts fresh.
704pub fn mock_setup(url: &str) {
705    let c = ensure_slot(url);
706    c.reset();
707    c.mock_enable();
708    c.mock_sent.lock().unwrap().clear();
709    // Discard any messages left unconsumed by a prior test on the same URL (e.g.
710    // a heartbeat a watchTrades drive loop returned past before reading) so they
711    // don't leak an extra handler dispatch / sent frame into the next test.
712    c.incoming.lock().unwrap().clear();
713    *c.ws_test_completed.lock().unwrap() = false;
714}
715pub fn mock_inject(url: &str, msg: Value) {
716    if let Some(c) = get_client(url) { c.mock_inject(msg); }
717}
718pub fn mock_sent_messages(url: &str) -> Value {
719    match get_client(url) { Some(c) => c.mock_sent_value(), None => Value::Array(vec![]) }
720}
721pub fn mock_has_pending_futures(url: &str) -> bool {
722    get_client(url).map(|c| c.has_pending_futures()).unwrap_or(false)
723}
724pub fn mock_has_queued_messages(url: &str) -> bool {
725    get_client(url).map(|c| c.has_queued_messages()).unwrap_or(false)
726}
727pub fn mock_mark_completed(url: &str) {
728    if let Some(c) = get_client(url) { c.mark_ws_test_completed(); }
729}
730pub fn mock_is_completed(url: &str) -> bool {
731    get_client(url).map(|c| c.is_ws_test_completed()).unwrap_or(true)
732}
733pub fn mock_reject_futures(url: &str) {
734    if let Some(c) = get_client(url) {
735        c.reject_pending_futures(Value::Str(
736            "[ExchangeError] static ws test: the injected messages did not resolve the watch future".to_string().into()));
737    }
738}
739
740/// Build the client-handle `Value` passed to `handle_message`: the URL plus
741/// live snapshots of `subscriptions` / `futures` (the fields venues read via
742/// `get_value(&client, "subscriptions")`).
743pub fn client_value(url: &str) -> Value {
744    // Pre-register the slot so subscriptions written on this handle (before the
745    // socket connects) persist and read back — upbit-style subscribe building.
746    let c = ensure_slot(url);
747    let mut m = indexmap::IndexMap::new();
748    m.insert("url".to_string(), Value::Str(url.to_string().into()));
749    m.insert("subscriptions".to_string(), c.subscriptions_value());
750    m.insert("futures".to_string(), c.futures_value());
751    Value::Map(m)
752}
753
754/// Open-or-join the single-flight for `hash` on `url`, creating the registry
755/// slot if the client has not been dialed yet (venue `authenticate` parks its
756/// flights on a never-dialed pseudo-url, because the real user-data url embeds
757/// the credential the flight is fetching).
758pub fn begin_flight(url: &str, hash: &str) -> bool {
759    ensure_slot(url).flight_begin(hash)
760}
761
762
763/// The `Value` a `client.future ()` / `client.reusableFuture ()` call hands
764/// back: enough to find the flight again (its client's url + the hash). TS
765/// returns a real Future object; a `Value` can't hold one, so the port returns
766/// a handle and `ws_await_flight` does the awaiting.
767pub fn flight_handle(url: &str, hash: &str, led: bool) -> Value {
768    let mut m = indexmap::IndexMap::new();
769    m.insert("url".to_string(), Value::Str(url.to_string().into()));
770    m.insert("__ws_flight_hash".to_string(), Value::Str(hash.to_string().into()));
771    // Whether the call that produced this handle opened the flight. A leader
772    // settles its own flight (and TS's `await future` resolves the instant it
773    // does), so it must never block on itself — including when the venue
774    // decides, after taking the lead, that there is no work to do because it
775    // is already subscribed (bitget's `authenticate`).
776    m.insert("__ws_flight_led".to_string(), Value::Bool(led));
777    Value::Map(m)
778}
779
780/// The hash a flight handle refers to. Accepts the `futures_value ()` handle
781/// shape too, so `client.futures[hash]` entries can be awaited as well.
782fn flight_hash_of(handle: &Value) -> Option<String> {
783    for key in ["__ws_flight_hash", "__ws_future_hash"] {
784        if let Value::Str(h) = crate::get_value(handle, &Value::Str(key.to_string().into())) {
785            return Some(h.to_string());
786        }
787    }
788    None
789}
790
791/// Await a flight handle — the port of TS's `await client.future (hash)` and
792/// of the trailing `await future` a single-flight leader runs after settling.
793///
794/// Returns the resolved value; a rejected flight panics with the error, which
795/// is how the port rethrows (the drive loop does the same with `take_settled`).
796/// A handle that names no flight returns `Value::Null` rather than hanging.
797pub async fn ws_await_flight(handle: &Value) -> Value {
798    let (url, hash) = match (url_of(handle), flight_hash_of(handle)) {
799        (Some(u), Some(h)) => (u, h),
800        _ => return Value::Null,
801    };
802    let client = match get_client(&url) {
803        Some(c) => c,
804        None => return Value::Null,
805    };
806    let settled = client.flight_peek(&hash);
807    // The leader: its own `client.resolve ()` has already run by the time it
808    // reaches its trailing await, so take the value and go. Waiting here would
809    // deadlock the (common) case where the venue took the lead and then found
810    // it had nothing to do.
811    let led = matches!(
812        crate::get_value(handle, &Value::Str("__ws_flight_led".into())),
813        Value::Bool(true)
814    );
815    if led || !client.flight_is_open(&hash) {
816        return match settled {
817            Some(Ok(v)) => v,
818            Some(Err(e)) => panic!(
819                "{}",
820                match &e {
821                    Value::Str(s) => s.clone(),
822                    v => crate::runtime::stringify_param(v).into(),
823                }
824            ),
825            // A flight that never opened is not an error — the value it would
826            // have carried is already in the venue's own cache, which is what
827            // the caller reads next.
828            None => Value::Null,
829        };
830    }
831    let budget = if client.is_mock() {
832        std::time::Duration::from_millis(1500)
833    } else {
834        std::time::Duration::from_secs(60)
835    };
836    let deadline = tokio::time::Instant::now() + budget;
837    loop {
838        // Create the wakeup before peeking, so a settle racing this loop is
839        // never missed (same pattern as `next_message`).
840        let notified = client.notify.notified();
841        if let Some(res) = client.flight_peek(&hash) {
842            return match res {
843                Ok(v) => v,
844                Err(e) => panic!(
845                    "{}",
846                    match &e {
847                        Value::Str(s) => s.clone(),
848                        v => crate::runtime::stringify_param(v).into(),
849                    }
850                ),
851            };
852        }
853        if !client.flight_is_open(&hash) {
854            // Closed without a value (reset between fixture cases).
855            return Value::Null;
856        }
857        if tokio::time::timeout_at(deadline, notified).await.is_err() {
858            panic!(
859                "[NetworkError] timed out waiting for the in-flight '{}' on {}",
860                hash, url
861            );
862        }
863    }
864}
865
866/// Extract the `url` from a client-handle `Value` (`Map{"url": ...}`).
867pub fn url_of(client: &Value) -> Option<String> {
868    match crate::get_value(client, &Value::Str("url".into())) {
869        Value::Str(s) => Some(s.to_string()),
870        _ => None,
871    }
872}
873
874fn hash_str(v: &Value) -> Option<String> {
875    match v {
876        Value::Str(s) => Some(s.to_string()),
877        _ => None,
878    }
879}
880
881/// `client.resolve(value, messageHash)` routed by URL. Returns `value`.
882pub fn value_resolve(client: &Value, args: &[Value]) -> Value {
883    let value = args.get(0).cloned().unwrap_or(Value::Null);
884    // `client.futures[hash].resolve(value)` — the future handle carries its own
885    // hash, so there is no second arg. Resolve that hash.
886    if let Some(hash) = future_hash_of(client) {
887        if let Some(url) = url_of(client) {
888            if let Some(c) = get_client(&url) { c.resolve(&hash, value.clone()); }
889        }
890        return value;
891    }
892    if let (Some(url), Some(hash)) = (url_of(client), args.get(1).and_then(hash_str)) {
893        if let Some(c) = get_client(&url) {
894            c.resolve(&hash, value.clone());
895        }
896    }
897    value
898}
899
900/// Extract the hash a future handle (`client.futures[hash]`) resolves/rejects.
901fn future_hash_of(client: &Value) -> Option<String> {
902    match crate::get_value(client, &Value::Str("__ws_future_hash".into())) {
903        Value::Str(s) => Some(s.to_string()),
904        _ => None,
905    }
906}
907
908/// `client.reject(error, messageHash)` routed by URL.
909pub fn value_reject(client: &Value, args: &[Value]) -> Value {
910    let err = args.get(0).cloned().unwrap_or(Value::Null);
911    // `client.futures[hash].reject(error)` — future handle carries its own hash.
912    if let Some(hash) = future_hash_of(client) {
913        if let Some(url) = url_of(client) {
914            if let Some(c) = get_client(&url) { c.reject(&hash, err.clone()); }
915        }
916        return err;
917    }
918    if let Some(url) = url_of(client) {
919        if let Some(c) = get_client(&url) {
920            match args.get(1).and_then(hash_str) {
921                Some(hash) => c.reject(&hash, err.clone()),
922                // reject with no hash → reject every pending future.
923                None => {
924                    let hashes: Vec<String> = c.futures.lock().unwrap().iter().cloned().collect();
925                    for h in hashes {
926                        c.reject(&h, err.clone());
927                    }
928                }
929            }
930        }
931    }
932    err
933}
934
935/// `client.send(message)` routed by URL. Serialises non-string payloads to JSON.
936pub fn value_send(client: &Value, args: &[Value]) -> Value {
937    if let Some(url) = url_of(client) {
938        if let Some(c) = get_client(&url) {
939            let payload = match args.get(0) {
940                Some(Value::Str(s)) => s.to_string(),
941                Some(v) => v.to_json().to_string(),
942                None => String::new().into(),
943            };
944            c.send_text(payload);
945        }
946    }
947    Value::Null
948}
949
950/// `client.reset(...)` routed by URL. An arg-less `client.reset()` reaches
951/// here with `Value::Null` — there is no error to deliver, so fall back to
952/// the internal wipe rather than rejecting every waiter with a null error.
953pub fn value_reset(client: &Value, error: Value) -> Value {
954    if let Some(url) = url_of(client) {
955        if let Some(c) = get_client(&url) {
956            if matches!(error, Value::Null) {
957                c.reset();
958            } else {
959                c.reset_with_error(error);
960            }
961        }
962    }
963    Value::Null
964}
965
966/// `client.on_pong(...)` routed by URL.
967pub fn value_on_pong(client: &Value) -> Value {
968    if let Some(url) = url_of(client) {
969        if let Some(c) = get_client(&url) {
970            c.on_pong();
971        }
972    }
973    Value::Null
974}
975
976#[cfg(test)]
977mod tests {
978    use super::*;
979    use tokio_tungstenite::tungstenite::Message as WsMessage;
980
981    // A minimal mock exchange WS server: accepts one connection, waits for a
982    // subscribe frame, then streams a few JSON "ticker" messages. Proves the
983    // full connect → send(subscribe) → receive → parse → resolve round-trip
984    // without touching a live venue.
985    async fn spawn_mock_server() -> String {
986        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
987        let addr = listener.local_addr().unwrap();
988        tokio::spawn(async move {
989            if let Ok((stream, _)) = listener.accept().await {
990                let mut ws = tokio_tungstenite::accept_async(stream).await.unwrap();
991                // Wait for the client's subscribe frame.
992                if let Some(Ok(WsMessage::Text(sub))) = ws.next().await {
993                    assert!(sub.contains("subscribe"), "expected subscribe, got {sub}");
994                }
995                // Stream three ticker updates.
996                for px in ["100.5", "101.0", "101.5"] {
997                    let msg = format!("{{\"channel\":\"ticker\",\"symbol\":\"BTC/USDT\",\"last\":\"{px}\"}}");
998                    ws.send(WsMessage::Text(msg)).await.unwrap();
999                }
1000                // Give the client time to drain before closing.
1001                tokio::time::sleep(std::time::Duration::from_millis(50)).await;
1002                let _ = ws.close(None).await;
1003            }
1004        });
1005        format!("ws://{addr}")
1006    }
1007
1008    // The transpiled `client.reset(error)` path (`value_reset` →
1009    // `reset_with_error`): a pending watch hash must observe the error (not
1010    // hang), a delivered-but-not-taken value must survive the reset, and an
1011    // arg-less `client.reset()` (error = `Value::Null`) must fall back to the
1012    // silent wipe instead of rejecting waiters with a null error.
1013    #[test]
1014    fn value_reset_rejects_pending_futures() {
1015        let url = "ws://reset-with-error.test";
1016        mock_setup(url);
1017        let client = get_client(url).expect("mock client");
1018        client.note_futures(&["pending".to_string(), "delivered".to_string()]);
1019        client.resolve("delivered", Value::Str("payload".into()));
1020
1021        let handle = client_value(url);
1022        let error = Value::Str("[InvalidNonce] gap detected".into());
1023        value_reset(&handle, error.clone());
1024
1025        // The pending waiter fails fast with the reset error…
1026        assert_eq!(
1027            client.take_settled(&["pending".to_string()]),
1028            Some(Err(error))
1029        );
1030        // …while the already-delivered value still reaches its waiter.
1031        assert_eq!(
1032            client.take_settled(&["delivered".to_string()]),
1033            Some(Ok(Value::Str("payload".into())))
1034        );
1035        assert!(!client.has_pending_futures());
1036
1037        // Arg-less reset: silent wipe, nothing settled with a null error.
1038        client.note_futures(&["pending2".to_string()]);
1039        value_reset(&handle, Value::Null);
1040        assert_eq!(client.take_settled(&["pending2".to_string()]), None);
1041        assert!(!client.has_pending_futures());
1042
1043        drop_client(url);
1044    }
1045
1046    #[tokio::test]
1047    async fn upgrade_request_carries_option_headers() {
1048        use tokio_tungstenite::tungstenite::handshake::server::{Request, Response};
1049        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
1050        let addr = listener.local_addr().unwrap();
1051        let (tx, rx) = tokio::sync::oneshot::channel::<Option<String>>();
1052        tokio::spawn(async move {
1053            if let Ok((stream, _)) = listener.accept().await {
1054                let mut seen = None;
1055                let callback = |req: &Request, resp: Response| {
1056                    seen = req.headers().get("X-Gate-Size-Decimal").map(|v| v.to_str().unwrap().to_string());
1057                    Ok(resp)
1058                };
1059                let ws = tokio_tungstenite::accept_hdr_async(stream, callback).await.unwrap();
1060                let _ = tx.send(seen);
1061                drop(ws);
1062            }
1063        });
1064        let url = format!("ws://{addr}");
1065        let headers = vec![("X-Gate-Size-Decimal".to_string(), "1".to_string())];
1066        ensure_client_with_headers(&url, &headers, None, true).await.expect("connect");
1067        assert_eq!(rx.await.unwrap().as_deref(), Some("1"));
1068        drop_client(&url);
1069    }
1070
1071    #[tokio::test]
1072    async fn transport_roundtrip() {
1073        let url = spawn_mock_server().await;
1074        let client = ensure_client(&url, None, true).await.expect("connect");
1075
1076        // Send a subscribe frame once (idempotent per hash).
1077        assert!(client.subscribe_once("ticker:BTC/USDT", Value::Null));
1078        assert!(!client.subscribe_once("ticker:BTC/USDT", Value::Null));
1079        assert!(client.send_text("{\"op\":\"subscribe\",\"channel\":\"ticker\"}".to_string()));
1080
1081        // Drive: pull each inbound message, mimic handle_message resolving the
1082        // "ticker" hash, and collect the resolved values.
1083        let mut lasts = Vec::new();
1084        while lasts.len() < 3 {
1085            let msg = client.next_message().await.expect("message before close");
1086            let last = crate::get_value(&msg, &Value::Str("last".into()));
1087            if let Value::Str(s) = &last {
1088                client.resolve("ticker", Value::Str(s.clone()));
1089            }
1090            if let Some(Ok(Value::Str(v))) = client.take_settled(&["ticker".to_string()]) {
1091                lasts.push(v);
1092            }
1093        }
1094        assert_eq!(lasts, vec!["100.5", "101.0", "101.5"]);
1095
1096        // Field snapshots the transpiled code reads off the client handle.
1097        let subs = client.subscriptions_value();
1098        assert!(crate::runtime::is_true(&crate::get_value(
1099            &subs,
1100            &Value::Str("ticker:BTC/USDT".into())
1101        )));
1102
1103        drop_client(&url);
1104    }
1105
1106    // A minimal Core whose `handle_message` resolves the "ticker" hash with the
1107    // inbound message's `last` field — exactly what a real venue's
1108    // handle_message does. Lets us drive the *actual* `watch()` runtime end to
1109    // end (connect → subscribe → frame → dispatch_to_derived("handle_message")
1110    // → resolve → return) against the mock server, independent of venue quirks.
1111    struct TestWsCore {
1112        exchange: crate::exchange::Exchange,
1113    }
1114    impl std::ops::Deref for TestWsCore {
1115        type Target = crate::exchange::Exchange;
1116        fn deref(&self) -> &Self::Target {
1117            &self.exchange
1118        }
1119    }
1120    impl std::ops::DerefMut for TestWsCore {
1121        fn deref_mut(&mut self) -> &mut Self::Target {
1122            &mut self.exchange
1123        }
1124    }
1125    impl crate::exchange::DerivedExchange for TestWsCore {}
1126    impl crate::exchange_generated::ExchangeBase for TestWsCore {
1127        fn call_dynamic<'a>(
1128            &'a mut self,
1129            method: &'a str,
1130            args: Vec<Value>,
1131        ) -> std::pin::Pin<Box<dyn std::future::Future<Output = Value> + Send + 'a>> {
1132            Box::pin(async move {
1133                match method {
1134                    "handle_message" => {
1135                        let client = args.get(0).cloned().unwrap_or(Value::Null);
1136                        let message = args.get(1).cloned().unwrap_or(Value::Null);
1137                        let last = crate::get_value(&message, &Value::Str("last".into()));
1138                        // `client.resolve(value, messageHash)` — routes to the registry.
1139                        client.resolve(&[last, Value::Str("ticker".into())]);
1140                        Value::Null
1141                    }
1142                    _ => self.call_dynamic_base(method, args).await,
1143                }
1144            })
1145        }
1146    }
1147
1148    #[tokio::test]
1149    async fn watch_drive_loop_end_to_end() {
1150        use crate::exchange::ExchangeRuntime;
1151        let url = spawn_mock_server().await;
1152        let mut core = TestWsCore {
1153            exchange: crate::exchange::Exchange::new(None),
1154        };
1155        // Drive the real base `watch()`: connect, send subscribe, read frames,
1156        // dispatch each to handle_message, return once "ticker" resolves.
1157        let result = ExchangeRuntime::watch(
1158            &mut core,
1159            Value::Str(url.clone().into()),
1160            Value::Str("ticker".into()),
1161            &[
1162                Value::Str("{\"op\":\"subscribe\",\"channel\":\"ticker\"}".into()),
1163                Value::Str("ticker".into()),
1164                Value::Null,
1165            ],
1166        )
1167        .await;
1168        // First streamed ticker.
1169        assert_eq!(result, Value::Str("100.5".into()));
1170        drop_client(&url);
1171    }
1172
1173    // ── single-flight (client.future / client.reusableFuture) ───────────────
1174    //
1175    // The venue `authenticate` idiom: the first caller leads and fetches the
1176    // credential, concurrent callers join the flight and wake when it settles.
1177    // Regression cover for the port's original no-op `future()` stub, where
1178    // every caller led and nobody waited.
1179
1180    #[tokio::test]
1181    async fn flight_elects_one_leader_and_registers_it() {
1182        let url = "flight-test-election";
1183        let c = ensure_slot(url);
1184        assert!(c.flight_begin("authenticate:future"), "first caller leads");
1185        assert!(!c.flight_begin("authenticate:future"), "second caller follows");
1186        // The follower's `messageHash in client.futures` test must see it.
1187        assert!(in_op_futures(&c, "authenticate:future"));
1188        drop_client(url);
1189    }
1190
1191    #[tokio::test]
1192    async fn flight_settle_wakes_waiters_and_reopens() {
1193        let url = "flight-test-settle";
1194        let c = ensure_slot(url);
1195        assert!(c.flight_begin("auth"));
1196        // Every waiter observes the value — settling must not consume it.
1197        c.resolve("auth", Value::Str("listen-key".into()));
1198        assert_eq!(
1199            ws_await_flight(&flight_handle(url, "auth", false)).await,
1200            Value::Str("listen-key".into())
1201        );
1202        assert_eq!(
1203            ws_await_flight(&flight_handle(url, "auth", false)).await,
1204            Value::Str("listen-key".into())
1205        );
1206        // Settled ⇒ cleared from `futures`, so the next cycle re-leads rather
1207        // than parking every caller on the follower branch forever.
1208        assert!(!in_op_futures(&c, "auth"));
1209        assert!(c.flight_begin("auth"), "a settled flight re-elects");
1210        drop_client(url);
1211    }
1212
1213    #[tokio::test]
1214    async fn flight_follower_waits_for_the_leader() {
1215        let url = "flight-test-wait";
1216        let c = ensure_slot(url);
1217        assert!(c.flight_begin("auth"));
1218        let settler = {
1219            let c = c.clone();
1220            tokio::spawn(async move {
1221                tokio::time::sleep(std::time::Duration::from_millis(60)).await;
1222                c.resolve("auth", Value::Str("late".into()));
1223            })
1224        };
1225        let started = std::time::Instant::now();
1226        let got = ws_await_flight(&flight_handle(url, "auth", false)).await;
1227        assert_eq!(got, Value::Str("late".into()));
1228        assert!(started.elapsed() >= std::time::Duration::from_millis(50), "waited for the leader");
1229        settler.await.unwrap();
1230        drop_client(url);
1231    }
1232
1233    #[tokio::test]
1234    async fn a_leader_never_blocks_on_its_own_flight() {
1235        // A venue can take the lead and then find it has nothing to do — bitget
1236        // re-`authenticate`s on an already-subscribed client. Its trailing
1237        // `await future` must return, not wait for a settle that never comes.
1238        let url = "flight-test-leader";
1239        let c = ensure_slot(url);
1240        let led = c.flight_begin("authenticated");
1241        assert!(led);
1242        let started = std::time::Instant::now();
1243        assert_eq!(
1244            ws_await_flight(&flight_handle(url, "authenticated", led)).await,
1245            Value::Null
1246        );
1247        assert!(started.elapsed() < std::time::Duration::from_millis(200), "returned at once");
1248        // Having led once and settled, the value is still there for a re-await.
1249        c.resolve("authenticated", Value::Bool(true));
1250        let led2 = c.flight_begin("authenticated");
1251        assert_eq!(
1252            ws_await_flight(&flight_handle(url, "authenticated", led2)).await,
1253            Value::Bool(true),
1254            "a re-lead with no new work reports the last value"
1255        );
1256        drop_client(url);
1257    }
1258
1259    #[tokio::test]
1260    async fn flight_handle_without_a_flight_returns_null() {
1261        // Never-opened flight: return rather than hang, the value the caller
1262        // wanted is already in the venue's own cache.
1263        let url = "flight-test-missing";
1264        ensure_slot(url);
1265        assert_eq!(ws_await_flight(&flight_handle(url, "nope", false)).await, Value::Null);
1266        drop_client(url);
1267    }
1268
1269    /// The transpiled follower test, `messageHash in client.futures`.
1270    fn in_op_futures(c: &Arc<ClientState>, hash: &str) -> bool {
1271        !matches!(
1272            crate::get_value(&c.futures_value(), &Value::Str(hash.to_string().into())),
1273            Value::Null
1274        )
1275    }
1276
1277    #[tokio::test]
1278    async fn parse_helpers() {
1279        // JSON text → dict; non-JSON → Value::Str.
1280        assert!(matches!(parse_text("{\"a\":1}"), Value::Dict(_)));
1281        assert_eq!(parse_text("pong"), Value::Str("pong".into()));
1282        // gzip binary → parsed JSON.
1283        use std::io::Write;
1284        let mut e = flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::default());
1285        e.write_all(b"{\"x\":true}").unwrap();
1286        let gz = e.finish().unwrap();
1287        assert!(matches!(parse_binary(&gz), Value::Dict(_)));
1288    }
1289
1290    #[test]
1291    fn raw_binary_frames_stay_bytes() {
1292        // an SBE heartbeat header is all small integers, so the frame is valid
1293        // utf-8, it must still reach the exchange as bytes with decompressBinary off
1294        let frame: Vec<u8> = vec![0x10, 0x00, 0x28, 0x00, 0x01, 0x00, 0x02, 0x00, 0x41, 0x42, 0x43, 0x01];
1295        assert!(std::str::from_utf8(&frame).is_ok());
1296        assert_eq!(parse_raw_binary(&frame), crate::exchange_stubs::bytes_to_value(&frame));
1297        // json over the binary opcode is still parsed
1298        assert!(matches!(parse_raw_binary(b"{\"x\":true}"), Value::Dict(_)));
1299    }
1300}