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