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 keeps it disjoint from the `&mut Exchange` borrow, so
16//! the drive loop can read the next frame and call `handle_message` without
17//! aliasing. The registry has ONE owner thread: every other task hands it a
18//! job over a channel and waits for the reply, so no client field is shared and
19//! no lock is taken at a use site.
20
21#![allow(dead_code)]
22
23use std::collections::{HashMap, HashSet, VecDeque};
24use std::sync::Arc;
25
26use futures::{SinkExt, StreamExt};
27use std::sync::LazyLock;
28use tokio::sync::{mpsc, watch};
29use tokio_tungstenite::tungstenite::Message;
30
31use crate::Value;
32
33/// Handle to one per-connection state. The state itself lives on the client
34/// store's owner thread; a handle carries only the key (`url`) and the wakeup
35/// channel its waiters await.
36pub struct ClientState {
37    pub url: String,
38    /// Bumped by the owner on every observable state change.
39    gen_rx: watch::Receiver<u64>,
40}
41
42/// Per-connection state. Created, mutated and dropped only on the client
43/// store's owner thread, so nothing here is behind a lock.
44struct ClientCore {
45    handle: Arc<ClientState>,
46    /// Frames queued for the writer task → socket.
47    outgoing: mpsc::UnboundedSender<Message>,
48    /// Receiver half handed to the writer task when the socket connects (a slot
49    /// is pre-registered before connecting so `client.subscriptions` writes
50    /// persist — upbit builds its subscribe frame before the socket is up).
51    pending_rx: Option<mpsc::UnboundedReceiver<Message>>,
52    /// Set while one caller is inside `ensure_client`'s dial for this url; the
53    /// store decides the winner, so concurrent callers never open two sockets.
54    connecting: bool,
55    /// Parsed inbound messages awaiting dispatch to `handle_message`.
56    incoming: VecDeque<Value>,
57    /// messageHash → resolved value (set by `handle_message` via `resolve`).
58    resolved: HashMap<String, Value>,
59    /// messageHash → error (set by `reject`; delivered before/instead of value).
60    rejections: HashMap<String, Value>,
61    /// subscribeHash → subscription object (TS `client.subscriptions[hash]`).
62    /// A subscribe frame is sent only the first time a hash is inserted.
63    subscriptions: HashMap<String, Value>,
64    /// messageHashes some `watch` call is currently waiting on. Mirrors TS
65    /// `client.futures` (read by a few venues' `handle_message`).
66    futures: HashSet<String>,
67    /// In-flight single-flight slots keyed by messageHash — the registry behind
68    /// TS's `client.future ()` / `client.reusableFuture ()` leader election
69    /// (binance/bybit/kucoin/... `authenticate`). Separate from `resolved`
70    /// because a flight has *many* waiters (all of whom must observe the
71    /// settled value, not consume it) and because settling one must also clear
72    /// its `futures` entry so the NEXT cycle can elect a fresh leader.
73    flights: HashMap<String, FlightSlot>,
74    connected: bool,
75    closed: bool,
76    last_pong_ms: i64,
77    /// Static-WS-test mock transport. When `mock` is set, `send_text` records the
78    /// (JSON-parsed) outgoing frame into `mock_sent` instead of relying on a
79    /// socket, and no real connection is ever opened. `ws_test_completed` is the
80    /// watch side's done-flag the frame injector's rejection loop polls.
81    mock: bool,
82    mock_sent: Vec<Value>,
83    ws_test_completed: bool,
84    /// Wakeup channel for this client's waiters (`next_message`,
85    /// `ws_await_flight`, `ensure_client` joiners).
86    gen_tx: watch::Sender<u64>,
87}
88
89/// One single-flight slot. `settled` stays populated after the flight closes so
90/// waiters that poll late still observe the result, and so a caller that
91/// re-awaits a hash nobody is working on any more gets the last value instead
92/// of blocking (TS's already-resolved Future). `open` is what a concurrent
93/// caller joins.
94#[derive(Clone)]
95struct FlightSlot {
96    open: bool,
97    settled: Option<Result<Value, Value>>,
98}
99
100/// All live clients, owned by one thread. Every other task hands this store a
101/// job over a channel, so no core is ever shared and there is no lock to nest,
102/// poison, or hold across an await. A job sees the whole store, so a decision
103/// (who dials, who leads a flight, who takes a settled value) is atomic by
104/// construction: the owner runs one job at a time.
105#[derive(Default)]
106struct WsClientStore {
107    clients: HashMap<String, ClientCore>,
108}
109
110type ClientJob = Box<dyn FnOnce(&mut WsClientStore) + Send + 'static>;
111
112// Marks the owner thread while a job runs: a job that calls back into the
113// store would wait on its own reply forever, so `client_op` panics instead.
114thread_local! {
115    static IN_CLIENT_JOB: std::cell::Cell<bool> = std::cell::Cell::new(false);
116}
117
118struct InClientJob;
119
120impl InClientJob {
121    fn enter() -> Self {
122        IN_CLIENT_JOB.with(|f| f.set(true));
123        InClientJob
124    }
125}
126
127impl Drop for InClientJob {
128    fn drop(&mut self) { IN_CLIENT_JOB.with(|f| f.set(false)); }
129}
130
131/// Who dials a slot's socket: the store elects exactly one caller.
132enum ConnectClaim {
133    Connected,
134    Wait,
135    Claimed,
136}
137
138/// Wake this client's waiters. The generation is what `watch::Receiver::changed`
139/// compares, so a waiter that armed before the change still sees it.
140fn bump(c: &mut ClientCore) {
141    let next = *c.gen_tx.borrow() + 1;
142    let _ = c.gen_tx.send(next);
143}
144
145/// Settle an open single-flight and clear its `futures` entry, so the next
146/// cycle elects a fresh leader. False when `hash` names no open flight.
147fn core_flight_settle(c: &mut ClientCore, hash: &str, res: Result<Value, Value>) -> bool {
148    match c.flights.get_mut(hash) {
149        Some(slot) if slot.open => {
150            slot.open = false;
151            slot.settled = Some(res);
152        }
153        _ => return false,
154    }
155    c.futures.remove(hash);
156    true
157}
158
159/// Hand `f` to the store's owner thread and return its result.
160fn client_op<R, F>(f: F) -> R
161where
162    R: Send + 'static,
163    F: FnOnce(&mut WsClientStore) -> R + Send + 'static,
164{
165    if IN_CLIENT_JOB.with(|flag| flag.get()) {
166        panic!("ccxt: ws client job called back into the client store (would deadlock)");
167    }
168    let (tx, rx) = std::sync::mpsc::sync_channel::<Result<R, Box<dyn std::any::Any + Send>>>(1);
169    let job: ClientJob = Box::new(move |store: &mut WsClientStore| {
170        let _ = tx.send(std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| f(store))));
171    });
172    if WS_CLIENTS_TX.send(job).is_err() {
173        panic!("ccxt: ws client owner is gone");
174    }
175    match rx.recv() {
176        Ok(Ok(v)) => v,
177        Ok(Err(payload)) => std::panic::resume_unwind(payload),
178        Err(_) => panic!("ccxt: ws client owner dropped the reply"),
179    }
180}
181
182static WS_CLIENTS_TX: LazyLock<mpsc::UnboundedSender<ClientJob>> = LazyLock::new(|| {
183    let (tx, mut rx) = mpsc::unbounded_channel::<ClientJob>();
184    std::thread::Builder::new()
185        .name("ccxt-ws-clients".to_string())
186        .spawn(move || {
187            let mut store = WsClientStore::default();
188            while let Some(job) = rx.blocking_recv() {
189                let _in_job = InClientJob::enter();
190                job(&mut store);
191            }
192        })
193        .expect("ccxt: cannot start the ws client owner");
194    tx
195});
196
197/// Monotonic-ish wall clock in ms. `SystemTime` is fine here (keep-alive only).
198fn now_ms() -> i64 {
199    std::time::SystemTime::now()
200        .duration_since(std::time::UNIX_EPOCH)
201        .map(|d| d.as_millis() as i64)
202        .unwrap_or(0)
203}
204
205/// Decode a text frame into a `Value` — JSON when it parses, else a raw string
206/// (some venues send bare `"pong"` etc. that `handle_message` matches on).
207fn parse_text(t: &str) -> Value {
208    match serde_json::from_str::<serde_json::Value>(t) {
209        Ok(j) => Value::from_json(&j),
210        Err(_) => Value::Str(t.to_string().into()),
211    }
212}
213
214/// Decode a binary frame: try raw-inflate then gzip (the two schemes venues
215/// use), fall back to the bytes as UTF-8. Then parse as text.
216fn parse_binary(b: &[u8]) -> Value {
217    use std::io::Read;
218    // gzip
219    {
220        let mut d = flate2::read::GzDecoder::new(b);
221        let mut s = String::new();
222        if d.read_to_string(&mut s).is_ok() && !s.is_empty() {
223            return parse_text(&s);
224        }
225    }
226    // raw deflate (no zlib header)
227    {
228        let mut d = flate2::read::DeflateDecoder::new(b);
229        let mut s = String::new();
230        if d.read_to_string(&mut s).is_ok() && !s.is_empty() {
231            return parse_text(&s);
232        }
233    }
234    // Uncompressed and valid UTF-8 → parse as text/JSON (covers venues that
235    // send plain-JSON frames over the binary opcode).
236    if let Ok(s) = std::str::from_utf8(b) {
237        return parse_text(s);
238    }
239    // Genuine binary payload (e.g. mexc protobuf): carry the raw bytes through
240    // as the port's byte-array form so `isBinaryMessage`/`decodeProtoMsg` see them.
241    crate::exchange_stubs::bytes_to_value(b)
242}
243
244/// Decode a binary frame for a client with `decompressBinary` off (mexc
245/// protobuf, paradex SBE): JSON is still read as text, as some venues send it
246/// over the binary opcode, everything else is carried through as raw bytes.
247/// No utf-8 fallback here: a binary payload can pass for utf-8 text.
248fn parse_raw_binary(b: &[u8]) -> Value {
249    match serde_json::from_slice::<serde_json::Value>(b) {
250        Ok(j) => Value::from_json(&j),
251        Err(_) => crate::exchange_stubs::bytes_to_value(b),
252    }
253}
254
255impl ClientState {
256    /// Read this client's core on the owner thread. The caller is the observer,
257    /// so this does not wake waiters.
258    fn with<R, F>(&self, f: F) -> R
259    where
260        R: Send + 'static,
261        F: FnOnce(&mut ClientCore) -> R + Send + 'static,
262    {
263        let url = self.url.clone();
264        client_op(move |s| match s.clients.get_mut(&url) {
265            Some(c) => f(c),
266            None => panic!("ccxt: no ws client state for {url}"),
267        })
268    }
269
270    /// Mutate this client's core and wake everyone waiting on it.
271    fn with_mut<R, F>(&self, f: F) -> R
272    where
273        R: Send + 'static,
274        F: FnOnce(&mut ClientCore) -> R + Send + 'static,
275    {
276        let url = self.url.clone();
277        client_op(move |s| {
278            let c = match s.clients.get_mut(&url) {
279                Some(c) => c,
280                None => panic!("ccxt: no ws client state for {url}"),
281            };
282            let r = f(c);
283            bump(c);
284            r
285        })
286    }
287
288    /// A receiver armed at the current generation: await `changed ()` on it and
289    /// no change published after this call can be missed.
290    fn waiter(&self) -> watch::Receiver<u64> {
291        let mut rx = self.gen_rx.clone();
292        rx.borrow_and_update();
293        rx
294    }
295
296    fn push_incoming(&self, v: Value) {
297        self.with_mut(move |c| c.incoming.push_back(v));
298    }
299
300    /// Await the next inbound message. `None` once the socket is closed and
301    /// the backlog is drained. The waiter is armed before the queue is read, so
302    /// a resolve/push racing the await is never lost.
303    pub async fn next_message(&self) -> Option<Value> {
304        let mock = self.with(|c| c.mock);
305        let mut rx = self.waiter();
306        loop {
307            let next = self.with(|c| c.incoming.pop_front());
308            if next.is_some() {
309                return next;
310            }
311            if self.with(|c| c.closed) {
312                return None;
313            }
314            if mock {
315                // Static WS test: the mock queue is fed by the frame injector.
316                // If nothing arrives within a short window the fixture is
317                // finished (or under-feeds this watch) — stop instead of
318                // blocking the drive loop forever, so the test completes.
319                if tokio::time::timeout(std::time::Duration::from_millis(1500), rx.changed()).await.is_err() {
320                    return None;
321                }
322            } else if rx.changed().await.is_err() {
323                return None;
324            }
325        }
326    }
327
328    /// Store a resolved value for `hash` (TS `client.resolve`). Also settles an
329    /// open single-flight on the same hash: TS's `client.resolve ()` settles
330    /// the future AND removes it from `client.futures`, which is what lets the
331    /// next cycle elect a fresh leader. Both paths run — a hash can in
332    /// principle be someone's flight and someone else's `watch`, and only the
333    /// waiter that exists will read its side.
334    pub fn resolve(&self, hash: &str, value: Value) {
335        let h = hash.to_string();
336        self.with_mut(move |c| {
337            core_flight_settle(c, &h, Ok(value.clone()));
338            c.resolved.insert(h.clone(), value);
339        });
340    }
341
342    /// Store an error for `hash` (TS `client.reject`), settling an open
343    /// single-flight on the same hash — see `resolve`.
344    pub fn reject(&self, hash: &str, err: Value) {
345        let h = hash.to_string();
346        self.with_mut(move |c| {
347            core_flight_settle(c, &h, Err(err.clone()));
348            c.rejections.insert(h.clone(), err);
349        });
350    }
351
352    /// If any of `hashes` has a resolved value or rejection, remove and return
353    /// it (`Ok` for value, `Err` for rejection). Rejections take priority.
354    pub fn take_settled(&self, hashes: &[String]) -> Option<Result<Value, Value>> {
355        let hs = hashes.to_vec();
356        self.with(move |c| {
357            for h in &hs {
358                if let Some(e) = c.rejections.remove(h) {
359                    return Some(Err(e));
360                }
361            }
362            for h in &hs {
363                if let Some(v) = c.resolved.remove(h) {
364                    return Some(Ok(v));
365                }
366            }
367            None
368        })
369    }
370
371    /// Register interest in `hashes` (TS `client.future`). Returns true if the
372    /// subscribe frame still needs sending for `subscribe_hash`.
373    pub fn note_futures(&self, hashes: &[String]) {
374        let hs = hashes.to_vec();
375        self.with(move |c| {
376            for h in hs {
377                c.futures.insert(h);
378            }
379        });
380    }
381
382    /// Open a single-flight for `hash`, or join one already in progress. `true`
383    /// means this caller is the leader and must do the work; `false` means a
384    /// flight is already open and the caller should wait on it.
385    ///
386    /// The insert into `futures` is what makes the transpiled
387    /// `if (messageHash in client.futures)` follower test observable, and it
388    /// happens in the same store job as the check — TS's documented
389    /// "atomic check-and-insert".
390    pub fn flight_begin(&self, hash: &str) -> bool {
391        let h = hash.to_string();
392        self.with(move |c| match c.flights.get_mut(&h) {
393            // Open flight — join it as a follower.
394            Some(slot) if slot.open => false,
395            // Closed: re-open, keeping the last value for anyone who re-awaits
396            // without new work being done.
397            Some(slot) => {
398                slot.open = true;
399                c.futures.insert(h.clone());
400                true
401            }
402            None => {
403                c.flights.insert(h.clone(), FlightSlot { open: true, settled: None });
404                c.futures.insert(h);
405                true
406            }
407        })
408    }
409
410    /// The flight's last outcome, if it has one. Does NOT consume it: every
411    /// waiter must be able to observe the same result.
412    pub fn flight_peek(&self, hash: &str) -> Option<Result<Value, Value>> {
413        let h = hash.to_string();
414        self.with(move |c| c.flights.get(&h).and_then(|s| s.settled.clone()))
415    }
416
417    /// Whether a flight for `hash` exists and is still open.
418    pub fn flight_is_open(&self, hash: &str) -> bool {
419        let h = hash.to_string();
420        self.with(move |c| c.flights.get(&h).map(|s| s.open).unwrap_or(false))
421    }
422
423    /// Settle an open flight and wake its waiters. Returns false (and does
424    /// nothing) when `hash` names no open flight, so `resolve`/`reject` can
425    /// fall through to their normal watch-hash behaviour.
426    pub fn flight_settle(&self, hash: &str, res: Result<Value, Value>) -> bool {
427        let h = hash.to_string();
428        self.with_mut(move |c| core_flight_settle(c, &h, res))
429    }
430
431    /// Record `subscribe_hash` → `subscription`; returns true the first time
432    /// (so the caller sends the subscribe frame exactly once). Mirrors TS
433    /// `client.subscriptions[subscribeHash] = subscription || true`.
434    pub fn subscribe_once(&self, subscribe_hash: &str, subscription: Value) -> bool {
435        let sh = subscribe_hash.to_string();
436        self.with(move |c| {
437            if c.subscriptions.contains_key(&sh) {
438                return false;
439            }
440            let stored = if matches!(subscription, Value::Null) {
441                Value::Bool(true)
442            } else {
443                subscription
444            };
445            c.subscriptions.insert(sh, stored);
446            true
447        })
448    }
449
450    /// Directly set a subscription entry (TS `client.subscriptions[h] = x`
451    /// written from `handle_message`).
452    pub fn set_subscription(&self, subscribe_hash: &str, subscription: Value) {
453        let sh = subscribe_hash.to_string();
454        self.with(move |c| {
455            c.subscriptions.insert(sh, subscription);
456        });
457    }
458
459    pub fn is_subscribed(&self, subscribe_hash: &str) -> bool {
460        let sh = subscribe_hash.to_string();
461        self.with(move |c| c.subscriptions.contains_key(&sh))
462    }
463
464    pub fn send_text(&self, s: String) -> bool {
465        if std::env::var("CCXT_WS_DEBUG").is_ok() { eprintln!("[wssend] {}", s.chars().take(200).collect::<String>()); }
466        // Static-WS-test mock transport: record the frame (JSON-parsed, like the
467        // TS `client.connection.send` stub) instead of hitting a socket.
468        self.with(move |c| {
469            if c.mock {
470                c.mock_sent.push(parse_text(&s));
471                return true;
472            }
473            c.outgoing.send(Message::Text(s)).is_ok()
474        })
475    }
476
477    /// Keep-alive frame straight onto the writer queue (false once it is gone).
478    fn send_ping(&self) -> bool {
479        self.with(|c| c.outgoing.send(Message::Ping(Vec::new())).is_ok())
480    }
481
482    /// Enable the mock transport: mark connected (so `ensure_client` never opens
483    /// a socket) and route `send_text` to the capture buffer.
484    pub fn mock_enable(&self) {
485        self.with_mut(|c| {
486            c.mock = true;
487            c.connected = true;
488        });
489    }
490    /// Injected inbound frame → the same queue the socket reader feeds.
491    pub fn mock_inject(&self, msg: Value) {
492        self.with_mut(move |c| c.incoming.push_back(msg));
493    }
494    pub fn is_mock(&self) -> bool { self.with(|c| c.mock) }
495    /// The captured outgoing frames as a `Value::List`.
496    pub fn mock_sent_value(&self) -> Value {
497        self.with(|c| Value::Array(c.mock_sent.clone()))
498    }
499    pub fn has_pending_futures(&self) -> bool {
500        self.with(|c| !c.futures.is_empty())
501    }
502    /// Whether the mock inbound queue still holds un-consumed frames.
503    pub fn has_queued_messages(&self) -> bool {
504        self.with(|c| !c.incoming.is_empty())
505    }
506    /// Pop the oldest un-consumed inbound frame (static-WS harness: replay the
507    /// acks an unWatch* fixture holds beyond the one that resolved the call).
508    pub fn pop_queued_message(&self) -> Option<Value> {
509        self.with(|c| c.incoming.pop_front())
510    }
511    pub fn mark_ws_test_completed(&self) { self.with(|c| c.ws_test_completed = true); }
512    pub fn is_ws_test_completed(&self) -> bool { self.with(|c| c.ws_test_completed) }
513    /// Reject every pending future so a fixture whose frames don't resolve the
514    /// watch fails (with a message) rather than hanging the drive loop.
515    pub fn reject_pending_futures(&self, err: Value) {
516        self.with_mut(move |c| {
517            let hashes: Vec<String> = c.futures.iter().cloned().collect();
518            for h in hashes {
519                core_flight_settle(c, &h, Err(err.clone()));
520                c.rejections.insert(h, err.clone());
521            }
522        });
523    }
524
525    pub fn is_closed(&self) -> bool {
526        self.with(|c| c.closed)
527    }
528
529    pub fn is_connected(&self) -> bool {
530        self.with(|c| c.connected)
531    }
532
533    pub fn on_pong(&self) {
534        self.with(|c| c.last_pong_ms = now_ms());
535    }
536
537    /// Drop resolved/rejected/subscription/future state,
538    /// e.g. after a reconnect so stale hashes don't resolve new waiters.
539    /// Internal wipe only — the transpiled `client.reset(error)` goes through
540    /// `reset_with_error` below, which delivers the error first.
541    pub fn reset(&self) {
542        self.with(|c| {
543            c.resolved.clear();
544            c.rejections.clear();
545            c.subscriptions.clear();
546            c.futures.clear();
547            c.flights.clear();
548        });
549    }
550
551    /// TS `client.reset(error)` — reject every pending future/flight with the
552    /// error so waiters fail fast instead of hanging, then drop the pending
553    /// future state. Mirrors the js/php/c#/go/java/python clients: rejections
554    /// are kept (they carry the error to the waiters), delivered-but-not-taken
555    /// `resolved` values are kept (in TS an already-resolved future is settled
556    /// — `reject` on it is a no-op — so its waiter still gets the value), and
557    /// subscriptions are left to the caller — the TS `Client.reset` does not
558    /// clear them either.
559    pub fn reset_with_error(&self, error: Value) {
560        self.with_mut(move |c| {
561            let hashes: Vec<String> = c.futures.iter().cloned().collect();
562            for h in &hashes {
563                if c.resolved.contains_key(h) {
564                    continue;
565                }
566                core_flight_settle(c, h, Err(error.clone()));
567                c.rejections.insert(h.clone(), error.clone());
568            }
569            c.futures.clear();
570        });
571    }
572
573    /// Snapshot of `subscriptions` as a `Value::Map { hash: subscription }` —
574    /// the shape the transpiled `get_value(&client, "subscriptions")` reads.
575    /// Tagged with `__ws_subs_url` so that writes performed on the snapshot
576    /// (`client.subscriptions[chanId] = …`, common in bitfinex/chan-id venues)
577    /// route back to this live `ClientState` instead of a discarded clone.
578    pub fn subscriptions_value(&self) -> Value {
579        let url = self.url.clone();
580        self.with(move |c| {
581            let mut m = indexmap::IndexMap::new();
582            m.insert("__ws_subs_url".to_string(), Value::Str(url.clone().into()));
583            for (h, sub) in c.subscriptions.iter() {
584                // Tag each subscription DICT with a back-reference so a field write
585                // on it (`subscription['receivedSnapshot'] = true`) persists to this
586                // live client — venues mutate a subscription retrieved from
587                // client.subscriptions and rely on JS object identity.
588                let tagged = match sub {
589                    Value::Dict(d) => {
590                        let mut inner = (**d).clone();
591                        inner.insert("__ws_sub_ref".to_string(),
592                            Value::Str(format!("{}\u{1}{}", url, h).into()));
593                        Value::Dict(std::sync::Arc::new(inner))
594                    }
595                    other => other.clone(),
596                };
597                m.insert(h.clone(), tagged);
598            }
599            Value::Map(m)
600        })
601    }
602
603    /// Set a field on a stored subscription dict (`client.subscriptions[hash]
604    /// [key] = val`). Creates the entry if missing.
605    pub fn set_subscription_field(&self, hash: &str, key: &str, val: Value) {
606        let h = hash.to_string();
607        let k = key.to_string();
608        self.with(move |c| {
609            if matches!(c.subscriptions.get(&h), Some(Value::Dict(_))) {
610                if let Some(Value::Dict(d)) = c.subscriptions.get_mut(&h) {
611                    std::sync::Arc::make_mut(d).insert(k, val);
612                }
613            } else {
614                let mut inner = indexmap::IndexMap::new();
615                inner.insert(k, val);
616                c.subscriptions.insert(h, Value::Dict(std::sync::Arc::new(inner)));
617            }
618        });
619    }
620
621    /// Snapshot of `futures` as a `Value::Map { hash: true }`.
622    pub fn futures_value(&self) -> Value {
623        let url = self.url.clone();
624        self.with(move |c| {
625            let mut m = indexmap::IndexMap::new();
626            for h in c.futures.iter() {
627                // Each entry is a future *handle* carrying the url + its own hash, so
628                // transpiled `client.futures[hash].resolve(x)` (bitget/cryptocom auth)
629                // routes back to this client — see value_resolve/value_reject.
630                let mut fh = indexmap::IndexMap::new();
631                fh.insert("url".to_string(), Value::Str(url.clone().into()));
632                fh.insert("__ws_future_hash".to_string(), Value::Str(h.clone().into()));
633                m.insert(h.clone(), Value::Map(fh));
634            }
635            Value::Map(m)
636        })
637    }
638}
639
640/// Get the existing client for `url`, or `None` if not yet connected.
641pub fn get_client(url: &str) -> Option<Arc<ClientState>> {
642    let u = url.to_string();
643    client_op(move |s| {
644        s.clients.get(&u).filter(|c| !c.closed).map(|c| c.handle.clone())
645    })
646}
647
648/// `client.subscriptions[key] = val` written on a tagged snapshot — persist it
649/// to the live client so subsequent `handle_message` snapshots see it.
650pub fn value_subs_insert(url: &str, key: &str, val: Value) {
651    if let Some(c) = get_client(url) { c.set_subscription(key, val); }
652}
653
654/// `delete client.subscriptions[key]` on a tagged snapshot.
655pub fn value_subs_remove(url: &str, key: &str) {
656    let k = key.to_string();
657    if let Some(c) = get_client(url) { c.with(move |core| { core.subscriptions.remove(&k); }); }
658}
659
660/// `client.subscriptions[hash][key] = val` written on a tagged subscription
661/// dict (carrying `__ws_sub_ref` = "url\u{1}hash").
662pub fn value_sub_field_write(subref: &str, key: &str, val: Value) {
663    if let Some((url, hash)) = subref.split_once('\u{1}') {
664        if let Some(c) = get_client(url) { c.set_subscription_field(hash, key, val); }
665    }
666}
667
668/// Ensure a live connection to `url`, connecting (and spawning the reader /
669/// writer / keep-alive tasks) if needed. Idempotent per URL.
670/// Open an HTTP CONNECT tunnel to `proxy` and hand the raw stream to
671/// tungstenite. `connect_async` has no proxy support of its own, so a venue
672/// reached through `wsProxy` / `wssProxy` has to be dialed this way.
673fn upgrade_request(
674    url: &str,
675    headers: &[(String, String)],
676) -> Result<tokio_tungstenite::tungstenite::handshake::client::Request, String> {
677    use tokio_tungstenite::tungstenite::client::IntoClientRequest;
678    use tokio_tungstenite::tungstenite::http::{HeaderName, HeaderValue};
679    let mut request = url
680        .into_client_request()
681        .map_err(|e| format!("[NetworkError] ws url {url}: {e}"))?;
682    for (key, value) in headers {
683        let name = HeaderName::from_bytes(key.as_bytes())
684            .map_err(|e| format!("[BadRequest] ws header {key}: {e}"))?;
685        let value = HeaderValue::from_str(value)
686            .map_err(|e| format!("[BadRequest] ws header {key}: {e}"))?;
687        request.headers_mut().insert(name, value);
688    }
689    Ok(request)
690}
691
692async fn connect_via_proxy(
693    url: &str,
694    headers: &[(String, String)],
695    proxy: &str,
696) -> Result<tokio_tungstenite::WebSocketStream<
697        tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>>, String> {
698    use tokio::io::{AsyncReadExt, AsyncWriteExt};
699    let target = url::Url::parse(url).map_err(|e| format!("[NetworkError] ws url {url}: {e}"))?;
700    let host = target.host_str().ok_or_else(|| format!("[NetworkError] ws url {url} has no host"))?;
701    let port = target.port_or_known_default().unwrap_or(443);
702    let p = url::Url::parse(proxy).map_err(|e| format!("[NetworkError] ws proxy {proxy}: {e}"))?;
703    let p_host = p.host_str().ok_or_else(|| format!("[NetworkError] ws proxy {proxy} has no host"))?;
704    let p_port = p.port_or_known_default().unwrap_or(8080);
705    let mut stream = tokio::net::TcpStream::connect((p_host, p_port))
706        .await
707        .map_err(|e| format!("[NetworkError] ws proxy connect {proxy}: {e}"))?;
708    let connect = format!(
709        "CONNECT {host}:{port} HTTP/1.1\r\nHost: {host}:{port}\r\nProxy-Connection: Keep-Alive\r\n\r\n"
710    );
711    stream
712        .write_all(connect.as_bytes())
713        .await
714        .map_err(|e| format!("[NetworkError] ws proxy CONNECT {proxy}: {e}"))?;
715    let mut head = Vec::new();
716    let mut byte = [0u8; 1];
717    while !head.ends_with(b"\r\n\r\n") {
718        let n = stream
719            .read(&mut byte)
720            .await
721            .map_err(|e| format!("[NetworkError] ws proxy CONNECT {proxy}: {e}"))?;
722        if n == 0 {
723            return Err(format!("[NetworkError] ws proxy {proxy} closed during CONNECT"));
724        }
725        head.push(byte[0]);
726        if head.len() > 8192 {
727            return Err(format!("[NetworkError] ws proxy {proxy} sent an oversized CONNECT reply"));
728        }
729    }
730    let status = String::from_utf8_lossy(&head);
731    let first = status.lines().next().unwrap_or_default();
732    if !first.contains(" 200") {
733        return Err(format!("[NetworkError] ws proxy {proxy} refused CONNECT: {first}"));
734    }
735    let (ws, _resp) = tokio_tungstenite::client_async_tls(upgrade_request(url, headers)?, stream)
736        .await
737        .map_err(|e| format!("[NetworkError] ws connect {url} via {proxy}: {e}"))?;
738    Ok(ws)
739}
740
741pub async fn ensure_client(url: &str, proxy: Option<String>, decompress_binary: bool) -> Result<Arc<ClientState>, String> {
742    ensure_client_with_headers(url, &[], proxy, decompress_binary).await
743}
744
745/// `ensure_client` with extra upgrade-request headers (TS `options.ws.options.headers`).
746pub async fn ensure_client_with_headers(
747    url: &str,
748    headers: &[(String, String)],
749    proxy: Option<String>,
750    decompress_binary: bool,
751) -> Result<Arc<ClientState>, String> {
752    let state = ensure_slot(url);
753    // The store elects exactly one dialer per slot; a caller that loses the
754    // election waits for that dial and then takes the claim itself, so two
755    // callers never open two sockets.
756    loop {
757        let mut rx = state.waiter();
758        match state.with(|c| {
759            if c.connected {
760                ConnectClaim::Connected
761            } else if c.connecting {
762                ConnectClaim::Wait
763            } else {
764                c.connecting = true;
765                ConnectClaim::Claimed
766            }
767        }) {
768            ConnectClaim::Connected => return Ok(state),
769            ConnectClaim::Claimed => break,
770            ConnectClaim::Wait => {
771                if rx.changed().await.is_err() {
772                    return Err(format!("[NetworkError] ws {url} client owner is gone"));
773                }
774            }
775        }
776    }
777    let dialled = match proxy.as_deref().filter(|p| !p.is_empty()) {
778        Some(p) => connect_via_proxy(url, headers, p).await,
779        None => match upgrade_request(url, headers) {
780            Ok(req) => tokio_tungstenite::connect_async(req)
781                .await
782                .map(|(ws, _resp)| ws)
783                .map_err(|e| format!("[NetworkError] ws connect {url}: {e}")),
784            Err(e) => Err(e),
785        },
786    };
787    let ws = match dialled {
788        Ok(ws) => ws,
789        Err(e) => {
790            state.with_mut(|c| c.connecting = false);
791            return Err(e);
792        }
793    };
794    let (mut write, mut read) = ws.split();
795    let maybe_rx = state.with(|c| c.pending_rx.take());
796    let mut rx = match maybe_rx {
797        Some(rx) => rx,
798        None => {
799            let e = format!("[NetworkError] ws {url} slot has no writer channel");
800            state.with_mut(|c| c.connecting = false);
801            return Err(e);
802        }
803    };
804    state.with_mut(|c| c.last_pong_ms = now_ms());
805
806    // Writer task: drain the outgoing queue to the socket.
807    tokio::spawn(async move {
808        while let Some(msg) = rx.recv().await {
809            if write.send(msg).await.is_err() {
810                break;
811            }
812        }
813        let _ = write.close().await;
814    });
815
816    // Reader task: decode frames → incoming queue.
817    let st = state.clone();
818    tokio::spawn(async move {
819        while let Some(frame) = read.next().await {
820            match frame {
821                Ok(Message::Text(t)) => st.push_incoming(parse_text(&t)),
822                Ok(Message::Binary(b)) => st.push_incoming(if decompress_binary { parse_binary(&b) } else { parse_raw_binary(&b) }),
823                Ok(Message::Pong(_)) => st.on_pong(),
824                // tungstenite answers Ping frames with Pong automatically.
825                Ok(Message::Ping(_)) => {}
826                Ok(Message::Close(_)) | Err(_) => break,
827                _ => {}
828            }
829        }
830        st.with_mut(|c| {
831            c.connected = false;
832            c.closed = true;
833        });
834    });
835
836    // Keep-alive: an unsolicited Ping every 30s; the peer's Pong updates
837    // last_pong. (Full miss-count RequestTimeout handling is a later refinement.)
838    let st2 = state.clone();
839    tokio::spawn(async move {
840        let mut iv = tokio::time::interval(std::time::Duration::from_secs(30));
841        iv.tick().await; // first tick fires immediately; skip it
842        loop {
843            iv.tick().await;
844            if st2.is_closed() {
845                break;
846            }
847            if !st2.send_ping() {
848                break;
849            }
850        }
851    });
852
853    state.with_mut(|c| {
854        c.connected = true;
855        c.connecting = false;
856    });
857    Ok(state)
858}
859
860/// Live read of a client handle's `subscriptions` / `futures` field, straight
861/// from the registry so a read after a write (upbit builds its subscribe frame
862/// from subscriptions it just set) is coherent, not a stale embedded snapshot.
863pub fn client_field_live(url: &str, field: &str) -> Value {
864    match get_client(url) {
865        Some(c) if field == "futures" => c.futures_value(),
866        Some(c) => c.subscriptions_value(),
867        None => Value::Map(indexmap::IndexMap::new()),
868    }
869}
870
871/// Get-or-create the registry slot for `url` WITHOUT connecting the socket, so
872/// `client.subscriptions` written before `watch()` connects still persist.
873fn ensure_slot(url: &str) -> Arc<ClientState> {
874    let u = url.to_string();
875    client_op(move |s| {
876        if let Some(c) = s.clients.get(&u) {
877            if !c.closed {
878                return c.handle.clone();
879            }
880        }
881        let (out_tx, out_rx) = mpsc::unbounded_channel::<Message>();
882        let (gen_tx, gen_rx) = watch::channel(0u64);
883        let handle = Arc::new(ClientState { url: u.clone(), gen_rx });
884        s.clients.insert(u.clone(), ClientCore {
885            handle: handle.clone(),
886            outgoing: out_tx,
887            pending_rx: Some(out_rx),
888            connecting: false,
889            incoming: VecDeque::new(),
890            resolved: HashMap::new(),
891            rejections: HashMap::new(),
892            subscriptions: HashMap::new(),
893            futures: HashSet::new(),
894            flights: HashMap::new(),
895            connected: false,
896            closed: false,
897            last_pong_ms: now_ms(),
898            mock: false,
899            mock_sent: Vec::new(),
900            ws_test_completed: false,
901            gen_tx,
902        });
903        handle
904    })
905}
906
907/// Remove (and thereby disconnect) the client for `url`. The core stays owned by
908/// the store so a handle still in flight keeps addressing its own state, but it
909/// is marked closed and no longer handed out.
910pub fn drop_client(url: &str) {
911    let u = url.to_string();
912    client_op(move |s| {
913        if let Some(c) = s.clients.get_mut(&u) {
914            c.closed = true;
915            c.connected = false;
916            bump(c);
917        }
918    });
919}
920
921// ── `Value`-handle bridge ────────────────────────────────────────────────────
922//
923// The transpiled `handle_message(&mut self, client: Value, message: Value)`
924// receives a *client* as a `Value`. We model it as `Value::Map { "url": <url>,
925// "subscriptions": <snapshot>, "futures": <snapshot> }`. The `Value` methods
926// `resolve`/`reject`/`send`/… (in value.rs) extract `url` and route here.
927
928// ── Static-WS-test mock transport (url-keyed façade over ClientState) ────────
929
930/// `setupWsMockTransport(url)` — register a connected, socket-less client whose
931/// sends are captured. Clears any prior state so each fixture starts fresh.
932pub fn mock_setup(url: &str) {
933    let c = ensure_slot(url);
934    c.with_mut(|core| {
935        core.resolved.clear();
936        core.rejections.clear();
937        core.subscriptions.clear();
938        core.futures.clear();
939        core.flights.clear();
940        core.mock = true;
941        core.connected = true;
942        core.mock_sent.clear();
943        // Discard any messages left unconsumed by a prior test on the same URL
944        // (e.g. a heartbeat a watchTrades drive loop returned past before
945        // reading) so they don't leak an extra handler dispatch / sent frame.
946        core.incoming.clear();
947        core.ws_test_completed = false;
948    });
949}
950pub fn mock_inject(url: &str, msg: Value) {
951    if let Some(c) = get_client(url) { c.mock_inject(msg); }
952}
953pub fn mock_sent_messages(url: &str) -> Value {
954    match get_client(url) { Some(c) => c.mock_sent_value(), None => Value::Array(vec![]) }
955}
956pub fn mock_has_pending_futures(url: &str) -> bool {
957    get_client(url).map(|c| c.has_pending_futures()).unwrap_or(false)
958}
959pub fn mock_has_queued_messages(url: &str) -> bool {
960    get_client(url).map(|c| c.has_queued_messages()).unwrap_or(false)
961}
962pub fn mock_pop_message(url: &str) -> Option<Value> {
963    get_client(url).and_then(|c| c.pop_queued_message())
964}
965pub fn mock_mark_completed(url: &str) {
966    if let Some(c) = get_client(url) { c.mark_ws_test_completed(); }
967}
968pub fn mock_is_completed(url: &str) -> bool {
969    get_client(url).map(|c| c.is_ws_test_completed()).unwrap_or(true)
970}
971pub fn mock_reject_futures(url: &str) {
972    if let Some(c) = get_client(url) {
973        c.reject_pending_futures(Value::Str(
974            "[ExchangeError] static ws test: the injected messages did not resolve the watch future".to_string().into()));
975    }
976}
977
978/// Build the client-handle `Value` passed to `handle_message`: the URL plus
979/// live snapshots of `subscriptions` / `futures` (the fields venues read via
980/// `get_value(&client, "subscriptions")`).
981pub fn client_value(url: &str) -> Value {
982    // Pre-register the slot so subscriptions written on this handle (before the
983    // socket connects) persist and read back — upbit-style subscribe building.
984    let c = ensure_slot(url);
985    let mut m = indexmap::IndexMap::new();
986    m.insert("url".to_string(), Value::Str(url.to_string().into()));
987    m.insert("subscriptions".to_string(), c.subscriptions_value());
988    m.insert("futures".to_string(), c.futures_value());
989    Value::Map(m)
990}
991
992/// Typed client handle for the ws drive loop.
993///
994/// The loop owns one per frame and hands it to the venue's `handle_message`;
995/// venues read the four fields it exposes instead of `get_value` on a box.
996/// Writes to `subscriptions`/`futures` reach the live client by tag.
997#[allow(dead_code)]
998#[derive(Clone)]
999pub struct ClientHandle {
1000    /// `client.url` — `Value::Str` when the handle names a url, else `Null`.
1001    pub url: Value,
1002    /// `client.subscriptions`, exactly what `get_value` used to read.
1003    pub subscriptions: Value,
1004    /// `client.futures` (open single-flights on this client).
1005    pub futures: Value,
1006    /// `client.rejections`.
1007    pub rejections: Value,
1008    value: Value,
1009}
1010
1011#[allow(dead_code)]
1012impl ClientHandle {
1013    pub fn from_value(value: Value) -> ClientHandle {
1014        let read = |k: &str| crate::get_value(&value, &Value::Str(k.to_string().into()));
1015        ClientHandle {
1016            url: read("url"),
1017            subscriptions: read("subscriptions"),
1018            futures: read("futures"),
1019            rejections: read("rejections"),
1020            value,
1021        }
1022    }
1023
1024    pub fn url(&self) -> Option<String> {
1025        match &self.url { Value::Str(s) => Some(s.to_string()), _ => None }
1026    }
1027
1028    /// The `Value` handle the untyped generated handlers take.
1029    pub fn as_value(&self) -> Value { self.value.clone() }
1030
1031    pub fn resolve(&self, args: &[Value]) -> Value { value_resolve(&self.value, args) }
1032    pub fn reject(&self, args: &[Value]) -> Value { value_reject(&self.value, args) }
1033    pub fn send(&self, args: &[Value]) -> Value { value_send(&self.value, args) }
1034    pub fn reset(&self, error: Value) -> Value { value_reset(&self.value, error) }
1035    pub fn on_pong(&self) -> Value { value_on_pong(&self.value) }
1036    pub fn as_map(&self) -> Option<&indexmap::IndexMap<String, Value>> {
1037        self.value.as_map()
1038    }
1039
1040    /// `delete client.subscriptions[key]`: drops the live client's entry and
1041    /// the handle's snapshot entry (what `remove(&mut subscriptions, key)` did).
1042    pub fn remove_subscription(&mut self, key: &Value) {
1043        if let (Value::Dict(m), Value::Str(k)) = (&mut self.subscriptions, key) {
1044            crate::value::try_ws_subs_remove(m, k);
1045            Arc::make_mut(m).shift_remove(k.as_ref());
1046        }
1047    }
1048
1049    /// `client.subscriptions[key] = val`: writes the live client and the
1050    /// handle's snapshot (what `add_element_to_object(&mut subscriptions, ..)` did).
1051    pub fn add_subscription(&mut self, key: &Value, val: Value) {
1052        match (&mut self.subscriptions, key) {
1053            (Value::Dict(m), Value::Str(k)) => {
1054                crate::value::try_ws_subs_write(m, k, &val);
1055                Arc::make_mut(m).insert(k.to_string(), val);
1056            }
1057            (other, _) => crate::runtime::add_element_to_object(other, key, val),
1058        }
1059    }
1060    /// `key in client.subscriptions`, read from the handle's snapshot.
1061    pub fn has_subscription(&self, key: &Value) -> bool { crate::runtime::in_op(&self.subscriptions, key) }
1062    /// `client.subscriptions[key]` (Null when absent).
1063    pub fn get_subscription(&self, key: &Value) -> Value { crate::get_value(&self.subscriptions, key) }
1064    /// `Object.keys(client.subscriptions)` (internal tags filtered).
1065    pub fn subscription_keys(&self) -> Vec<Value> {
1066        crate::runtime::object_keys(&self.subscriptions).as_array().cloned().unwrap_or_default()
1067    }
1068    /// `key in client.futures`, read from the handle's snapshot.
1069    pub fn has_future(&self, key: &Value) -> bool { crate::runtime::in_op(&self.futures, key) }
1070    /// `client.futures[key]` (Null when absent).
1071    pub fn get_future(&self, key: &Value) -> Value { crate::get_value(&self.futures, key) }
1072    /// `Object.keys(client.futures)`.
1073    pub fn future_keys(&self) -> Vec<Value> {
1074        crate::runtime::object_keys(&self.futures).as_array().cloned().unwrap_or_default()
1075    }
1076    pub fn future(&self, args: &[Value]) -> Value {
1077        self.value.future(args)
1078    }
1079    pub fn reusable_future(&self, msg_hash: Value) -> Value {
1080        self.value.reusable_future(msg_hash)
1081    }
1082}
1083
1084/// Open-or-join the single-flight for `hash` on `url`, creating the registry
1085/// slot if the client has not been dialed yet (venue `authenticate` parks its
1086/// flights on a never-dialed pseudo-url, because the real user-data url embeds
1087/// the credential the flight is fetching).
1088pub fn begin_flight(url: &str, hash: &str) -> bool {
1089    ensure_slot(url).flight_begin(hash)
1090}
1091
1092
1093/// The `Value` a `client.future ()` / `client.reusableFuture ()` call hands
1094/// back: enough to find the flight again (its client's url + the hash). TS
1095/// returns a real Future object; a `Value` can't hold one, so the port returns
1096/// a handle and `ws_await_flight` does the awaiting.
1097pub fn flight_handle(url: &str, hash: &str, led: bool) -> Value {
1098    let mut m = indexmap::IndexMap::new();
1099    m.insert("url".to_string(), Value::Str(url.to_string().into()));
1100    m.insert("__ws_flight_hash".to_string(), Value::Str(hash.to_string().into()));
1101    // Whether the call that produced this handle opened the flight. A leader
1102    // settles its own flight (and TS's `await future` resolves the instant it
1103    // does), so it must never block on itself — including when the venue
1104    // decides, after taking the lead, that there is no work to do because it
1105    // is already subscribed (bitget's `authenticate`).
1106    m.insert("__ws_flight_led".to_string(), Value::Bool(led));
1107    Value::Map(m)
1108}
1109
1110/// The hash a flight handle refers to. Accepts the `futures_value ()` handle
1111/// shape too, so `client.futures[hash]` entries can be awaited as well.
1112fn flight_hash_of(handle: &Value) -> Option<String> {
1113    for key in ["__ws_flight_hash", "__ws_future_hash"] {
1114        if let Value::Str(h) = crate::get_value(handle, &Value::Str(key.to_string().into())) {
1115            return Some(h.to_string());
1116        }
1117    }
1118    None
1119}
1120
1121/// Await a flight handle — the port of TS's `await client.future (hash)` and
1122/// of the trailing `await future` a single-flight leader runs after settling.
1123///
1124/// Returns the resolved value; a rejected flight panics with the error, which
1125/// is how the port rethrows (the drive loop does the same with `take_settled`).
1126/// A handle that names no flight returns `Value::Null` rather than hanging.
1127pub async fn ws_await_flight(handle: &Value) -> Value {
1128    let (url, hash) = match (url_of(handle), flight_hash_of(handle)) {
1129        (Some(u), Some(h)) => (u, h),
1130        _ => return Value::Null,
1131    };
1132    let client = match get_client(&url) {
1133        Some(c) => c,
1134        None => return Value::Null,
1135    };
1136    let settled = client.flight_peek(&hash);
1137    // The leader: its own `client.resolve ()` has already run by the time it
1138    // reaches its trailing await, so take the value and go. Waiting here would
1139    // deadlock the (common) case where the venue took the lead and then found
1140    // it had nothing to do.
1141    let led = matches!(
1142        crate::get_value(handle, &Value::Str("__ws_flight_led".into())),
1143        Value::Bool(true)
1144    );
1145    if led || !client.flight_is_open(&hash) {
1146        return match settled {
1147            Some(Ok(v)) => v,
1148            Some(Err(e)) => panic!(
1149                "{}",
1150                match &e {
1151                    Value::Str(s) => s.clone(),
1152                    v => crate::runtime::stringify_param(v).into(),
1153                }
1154            ),
1155            // A flight that never opened is not an error — the value it would
1156            // have carried is already in the venue's own cache, which is what
1157            // the caller reads next.
1158            None => Value::Null,
1159        };
1160    }
1161    let budget = if client.is_mock() {
1162        std::time::Duration::from_millis(1500)
1163    } else {
1164        std::time::Duration::from_secs(60)
1165    };
1166    let deadline = tokio::time::Instant::now() + budget;
1167    loop {
1168        // Arm the wakeup before peeking, so a settle racing this loop is never
1169        // missed (same pattern as `next_message`).
1170        let mut rx = client.waiter();
1171        if let Some(res) = client.flight_peek(&hash) {
1172            return match res {
1173                Ok(v) => v,
1174                Err(e) => panic!(
1175                    "{}",
1176                    match &e {
1177                        Value::Str(s) => s.clone(),
1178                        v => crate::runtime::stringify_param(v).into(),
1179                    }
1180                ),
1181            };
1182        }
1183        if !client.flight_is_open(&hash) {
1184            // Closed without a value (reset between fixture cases).
1185            return Value::Null;
1186        }
1187        if tokio::time::timeout_at(deadline, rx.changed()).await.is_err() {
1188            panic!(
1189                "[NetworkError] timed out waiting for the in-flight '{}' on {}",
1190                hash, url
1191            );
1192        }
1193    }
1194}
1195
1196/// Extract the `url` from a client-handle `Value` (`Map{"url": ...}`).
1197pub fn url_of(client: &Value) -> Option<String> {
1198    match crate::get_value(client, &Value::Str("url".into())) {
1199        Value::Str(s) => Some(s.to_string()),
1200        _ => None,
1201    }
1202}
1203
1204fn hash_str(v: &Value) -> Option<String> {
1205    match v {
1206        Value::Str(s) => Some(s.to_string()),
1207        _ => None,
1208    }
1209}
1210
1211/// `client.resolve(value, messageHash)` routed by URL. Returns `value`.
1212pub fn value_resolve(client: &Value, args: &[Value]) -> Value {
1213    let value = args.get(0).cloned().unwrap_or(Value::Null);
1214    // `client.futures[hash].resolve(value)` — the future handle carries its own
1215    // hash, so there is no second arg. Resolve that hash.
1216    if let Some(hash) = future_hash_of(client) {
1217        if let Some(url) = url_of(client) {
1218            if let Some(c) = get_client(&url) { c.resolve(&hash, value.clone()); }
1219        }
1220        return value;
1221    }
1222    if let (Some(url), Some(hash)) = (url_of(client), args.get(1).and_then(hash_str)) {
1223        if let Some(c) = get_client(&url) {
1224            c.resolve(&hash, value.clone());
1225        }
1226    }
1227    value
1228}
1229
1230/// Extract the hash a future handle (`client.futures[hash]`) resolves/rejects.
1231fn future_hash_of(client: &Value) -> Option<String> {
1232    match crate::get_value(client, &Value::Str("__ws_future_hash".into())) {
1233        Value::Str(s) => Some(s.to_string()),
1234        _ => None,
1235    }
1236}
1237
1238/// `client.reject(error, messageHash)` routed by URL.
1239pub fn value_reject(client: &Value, args: &[Value]) -> Value {
1240    let err = args.get(0).cloned().unwrap_or(Value::Null);
1241    // `client.futures[hash].reject(error)` — future handle carries its own hash.
1242    if let Some(hash) = future_hash_of(client) {
1243        if let Some(url) = url_of(client) {
1244            if let Some(c) = get_client(&url) { c.reject(&hash, err.clone()); }
1245        }
1246        return err;
1247    }
1248    if let Some(url) = url_of(client) {
1249        if let Some(c) = get_client(&url) {
1250            match args.get(1).and_then(hash_str) {
1251                Some(hash) => c.reject(&hash, err.clone()),
1252                // reject with no hash → reject every pending future.
1253                None => c.reject_pending_futures(err.clone()),
1254            }
1255        }
1256    }
1257    err
1258}
1259
1260/// `client.send(message)` routed by URL. Serialises non-string payloads to JSON.
1261pub fn value_send(client: &Value, args: &[Value]) -> Value {
1262    if let Some(url) = url_of(client) {
1263        if let Some(c) = get_client(&url) {
1264            let payload = match args.get(0) {
1265                Some(Value::Str(s)) => s.to_string(),
1266                Some(v) => v.to_json().to_string(),
1267                None => String::new().into(),
1268            };
1269            c.send_text(payload);
1270        }
1271    }
1272    Value::Null
1273}
1274
1275/// `client.reset(...)` routed by URL. An arg-less `client.reset()` reaches
1276/// here with `Value::Null` — there is no error to deliver, so fall back to
1277/// the internal wipe rather than rejecting every waiter with a null error.
1278pub fn value_reset(client: &Value, error: Value) -> Value {
1279    if let Some(url) = url_of(client) {
1280        if let Some(c) = get_client(&url) {
1281            if matches!(error, Value::Null) {
1282                c.reset();
1283            } else {
1284                c.reset_with_error(error);
1285            }
1286        }
1287    }
1288    Value::Null
1289}
1290
1291/// `client.on_pong(...)` routed by URL.
1292pub fn value_on_pong(client: &Value) -> Value {
1293    if let Some(url) = url_of(client) {
1294        if let Some(c) = get_client(&url) {
1295            c.on_pong();
1296        }
1297    }
1298    Value::Null
1299}
1300
1301#[cfg(test)]
1302mod tests {
1303    use super::*;
1304    use tokio_tungstenite::tungstenite::Message as WsMessage;
1305
1306    // A minimal mock exchange WS server: accepts one connection, waits for a
1307    // subscribe frame, then streams a few JSON "ticker" messages. Proves the
1308    // full connect → send(subscribe) → receive → parse → resolve round-trip
1309    // without touching a live venue.
1310    async fn spawn_mock_server() -> String {
1311        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
1312        let addr = listener.local_addr().unwrap();
1313        tokio::spawn(async move {
1314            if let Ok((stream, _)) = listener.accept().await {
1315                let mut ws = tokio_tungstenite::accept_async(stream).await.unwrap();
1316                // Wait for the client's subscribe frame.
1317                if let Some(Ok(WsMessage::Text(sub))) = ws.next().await {
1318                    assert!(sub.contains("subscribe"), "expected subscribe, got {sub}");
1319                }
1320                // Stream three ticker updates.
1321                for px in ["100.5", "101.0", "101.5"] {
1322                    let msg = format!("{{\"channel\":\"ticker\",\"symbol\":\"BTC/USDT\",\"last\":\"{px}\"}}");
1323                    ws.send(WsMessage::Text(msg)).await.unwrap();
1324                }
1325                // Give the client time to drain before closing.
1326                tokio::time::sleep(std::time::Duration::from_millis(50)).await;
1327                let _ = ws.close(None).await;
1328            }
1329        });
1330        format!("ws://{addr}")
1331    }
1332
1333    // The transpiled `client.reset(error)` path (`value_reset` →
1334    // `reset_with_error`): a pending watch hash must observe the error (not
1335    // hang), a delivered-but-not-taken value must survive the reset, and an
1336    // arg-less `client.reset()` (error = `Value::Null`) must fall back to the
1337    // silent wipe instead of rejecting waiters with a null error.
1338    #[test]
1339    fn value_reset_rejects_pending_futures() {
1340        let url = "ws://reset-with-error.test";
1341        mock_setup(url);
1342        let client = get_client(url).expect("mock client");
1343        client.note_futures(&["pending".to_string(), "delivered".to_string()]);
1344        client.resolve("delivered", Value::Str("payload".into()));
1345
1346        let handle = client_value(url);
1347        let error = Value::Str("[InvalidNonce] gap detected".into());
1348        value_reset(&handle, error.clone());
1349
1350        // The pending waiter fails fast with the reset error…
1351        assert_eq!(
1352            client.take_settled(&["pending".to_string()]),
1353            Some(Err(error))
1354        );
1355        // …while the already-delivered value still reaches its waiter.
1356        assert_eq!(
1357            client.take_settled(&["delivered".to_string()]),
1358            Some(Ok(Value::Str("payload".into())))
1359        );
1360        assert!(!client.has_pending_futures());
1361
1362        // Arg-less reset: silent wipe, nothing settled with a null error.
1363        client.note_futures(&["pending2".to_string()]);
1364        value_reset(&handle, Value::Null);
1365        assert_eq!(client.take_settled(&["pending2".to_string()]), None);
1366        assert!(!client.has_pending_futures());
1367
1368        drop_client(url);
1369    }
1370
1371    #[tokio::test]
1372    async fn upgrade_request_carries_option_headers() {
1373        use tokio_tungstenite::tungstenite::handshake::server::{Request, Response};
1374        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
1375        let addr = listener.local_addr().unwrap();
1376        let (tx, rx) = tokio::sync::oneshot::channel::<Option<String>>();
1377        tokio::spawn(async move {
1378            if let Ok((stream, _)) = listener.accept().await {
1379                let mut seen = None;
1380                let callback = |req: &Request, resp: Response| {
1381                    seen = req.headers().get("X-Gate-Size-Decimal").map(|v| v.to_str().unwrap().to_string());
1382                    Ok(resp)
1383                };
1384                let ws = tokio_tungstenite::accept_hdr_async(stream, callback).await.unwrap();
1385                let _ = tx.send(seen);
1386                drop(ws);
1387            }
1388        });
1389        let url = format!("ws://{addr}");
1390        let headers = vec![("X-Gate-Size-Decimal".to_string(), "1".to_string())];
1391        ensure_client_with_headers(&url, &headers, None, true).await.expect("connect");
1392        assert_eq!(rx.await.unwrap().as_deref(), Some("1"));
1393        drop_client(&url);
1394    }
1395
1396    #[tokio::test]
1397    async fn transport_roundtrip() {
1398        let url = spawn_mock_server().await;
1399        let client = ensure_client(&url, None, true).await.expect("connect");
1400
1401        // Send a subscribe frame once (idempotent per hash).
1402        assert!(client.subscribe_once("ticker:BTC/USDT", Value::Null));
1403        assert!(!client.subscribe_once("ticker:BTC/USDT", Value::Null));
1404        assert!(client.send_text("{\"op\":\"subscribe\",\"channel\":\"ticker\"}".to_string()));
1405
1406        // Drive: pull each inbound message, mimic handle_message resolving the
1407        // "ticker" hash, and collect the resolved values.
1408        let mut lasts = Vec::new();
1409        while lasts.len() < 3 {
1410            let msg = client.next_message().await.expect("message before close");
1411            let last = crate::get_value(&msg, &Value::Str("last".into()));
1412            if let Value::Str(s) = &last {
1413                client.resolve("ticker", Value::Str(s.clone()));
1414            }
1415            if let Some(Ok(Value::Str(v))) = client.take_settled(&["ticker".to_string()]) {
1416                lasts.push(v);
1417            }
1418        }
1419        assert_eq!(lasts, vec!["100.5", "101.0", "101.5"]);
1420
1421        // Field snapshots the transpiled code reads off the client handle.
1422        let subs = client.subscriptions_value();
1423        assert!(crate::runtime::is_true(&crate::get_value(
1424            &subs,
1425            &Value::Str("ticker:BTC/USDT".into())
1426        )));
1427
1428        drop_client(&url);
1429    }
1430
1431    // A minimal Core whose `handle_message` resolves the "ticker" hash with the
1432    // inbound message's `last` field — exactly what a real venue's
1433    // handle_message does. Lets us drive the *actual* `watch()` runtime end to
1434    // end (connect → subscribe → frame → dispatch_to_derived("handle_message")
1435    // → resolve → return) against the mock server, independent of venue quirks.
1436    struct TestWsCore {
1437        exchange: crate::exchange::Exchange,
1438    }
1439    impl std::ops::Deref for TestWsCore {
1440        type Target = crate::exchange::Exchange;
1441        fn deref(&self) -> &Self::Target {
1442            &self.exchange
1443        }
1444    }
1445    impl std::ops::DerefMut for TestWsCore {
1446        fn deref_mut(&mut self) -> &mut Self::Target {
1447            &mut self.exchange
1448        }
1449    }
1450    impl crate::exchange::DerivedExchange for TestWsCore {}
1451    impl crate::exchange_generated::ExchangeBase for TestWsCore {
1452        fn call_dynamic<'a>(
1453            &'a mut self,
1454            method: &'a str,
1455            args: Vec<Value>,
1456        ) -> std::pin::Pin<Box<dyn std::future::Future<Output = Value> + Send + 'a>> {
1457            Box::pin(async move {
1458                match method {
1459                    "handle_message" => {
1460                        let client = args.get(0).cloned().unwrap_or(Value::Null);
1461                        let message = args.get(1).cloned().unwrap_or(Value::Null);
1462                        let last = crate::get_value(&message, &Value::Str("last".into()));
1463                        // `client.resolve(value, messageHash)` — routes to the registry.
1464                        client.resolve(&[last, Value::Str("ticker".into())]);
1465                        Value::Null
1466                    }
1467                    _ => self.call_dynamic_base(method, args).await,
1468                }
1469            })
1470        }
1471    }
1472
1473    #[tokio::test]
1474    async fn watch_drive_loop_end_to_end() {
1475        use crate::exchange::ExchangeRuntime;
1476        let url = spawn_mock_server().await;
1477        let mut core = TestWsCore {
1478            exchange: crate::exchange::Exchange::new(None),
1479        };
1480        // Drive the real base `watch()`: connect, send subscribe, read frames,
1481        // dispatch each to handle_message, return once "ticker" resolves.
1482        let result = ExchangeRuntime::watch(
1483            &mut core,
1484            Value::Str(url.clone().into()),
1485            Value::Str("ticker".into()),
1486            &[
1487                Value::Str("{\"op\":\"subscribe\",\"channel\":\"ticker\"}".into()),
1488                Value::Str("ticker".into()),
1489                Value::Null,
1490            ],
1491        )
1492        .await;
1493        // First streamed ticker.
1494        assert_eq!(result, Value::Str("100.5".into()));
1495        drop_client(&url);
1496    }
1497
1498    // ── single-flight (client.future / client.reusableFuture) ───────────────
1499    //
1500    // The venue `authenticate` idiom: the first caller leads and fetches the
1501    // credential, concurrent callers join the flight and wake when it settles.
1502    // Regression cover for the port's original no-op `future()` stub, where
1503    // every caller led and nobody waited.
1504
1505    #[tokio::test]
1506    async fn flight_elects_one_leader_and_registers_it() {
1507        let url = "flight-test-election";
1508        let c = ensure_slot(url);
1509        assert!(c.flight_begin("authenticate:future"), "first caller leads");
1510        assert!(!c.flight_begin("authenticate:future"), "second caller follows");
1511        // The follower's `messageHash in client.futures` test must see it.
1512        assert!(in_op_futures(&c, "authenticate:future"));
1513        drop_client(url);
1514    }
1515
1516    #[tokio::test]
1517    async fn flight_settle_wakes_waiters_and_reopens() {
1518        let url = "flight-test-settle";
1519        let c = ensure_slot(url);
1520        assert!(c.flight_begin("auth"));
1521        // Every waiter observes the value — settling must not consume it.
1522        c.resolve("auth", Value::Str("listen-key".into()));
1523        assert_eq!(
1524            ws_await_flight(&flight_handle(url, "auth", false)).await,
1525            Value::Str("listen-key".into())
1526        );
1527        assert_eq!(
1528            ws_await_flight(&flight_handle(url, "auth", false)).await,
1529            Value::Str("listen-key".into())
1530        );
1531        // Settled ⇒ cleared from `futures`, so the next cycle re-leads rather
1532        // than parking every caller on the follower branch forever.
1533        assert!(!in_op_futures(&c, "auth"));
1534        assert!(c.flight_begin("auth"), "a settled flight re-elects");
1535        drop_client(url);
1536    }
1537
1538    #[tokio::test]
1539    async fn flight_follower_waits_for_the_leader() {
1540        let url = "flight-test-wait";
1541        let c = ensure_slot(url);
1542        assert!(c.flight_begin("auth"));
1543        let settler = {
1544            let c = c.clone();
1545            tokio::spawn(async move {
1546                tokio::time::sleep(std::time::Duration::from_millis(60)).await;
1547                c.resolve("auth", Value::Str("late".into()));
1548            })
1549        };
1550        let started = std::time::Instant::now();
1551        let got = ws_await_flight(&flight_handle(url, "auth", false)).await;
1552        assert_eq!(got, Value::Str("late".into()));
1553        assert!(started.elapsed() >= std::time::Duration::from_millis(50), "waited for the leader");
1554        settler.await.unwrap();
1555        drop_client(url);
1556    }
1557
1558    #[tokio::test]
1559    async fn a_leader_never_blocks_on_its_own_flight() {
1560        // A venue can take the lead and then find it has nothing to do — bitget
1561        // re-`authenticate`s on an already-subscribed client. Its trailing
1562        // `await future` must return, not wait for a settle that never comes.
1563        let url = "flight-test-leader";
1564        let c = ensure_slot(url);
1565        let led = c.flight_begin("authenticated");
1566        assert!(led);
1567        let started = std::time::Instant::now();
1568        assert_eq!(
1569            ws_await_flight(&flight_handle(url, "authenticated", led)).await,
1570            Value::Null
1571        );
1572        assert!(started.elapsed() < std::time::Duration::from_millis(200), "returned at once");
1573        // Having led once and settled, the value is still there for a re-await.
1574        c.resolve("authenticated", Value::Bool(true));
1575        let led2 = c.flight_begin("authenticated");
1576        assert_eq!(
1577            ws_await_flight(&flight_handle(url, "authenticated", led2)).await,
1578            Value::Bool(true),
1579            "a re-lead with no new work reports the last value"
1580        );
1581        drop_client(url);
1582    }
1583
1584    #[tokio::test]
1585    async fn flight_handle_without_a_flight_returns_null() {
1586        // Never-opened flight: return rather than hang, the value the caller
1587        // wanted is already in the venue's own cache.
1588        let url = "flight-test-missing";
1589        ensure_slot(url);
1590        assert_eq!(ws_await_flight(&flight_handle(url, "nope", false)).await, Value::Null);
1591        drop_client(url);
1592    }
1593
1594    /// The transpiled follower test, `messageHash in client.futures`.
1595    fn in_op_futures(c: &Arc<ClientState>, hash: &str) -> bool {
1596        !matches!(
1597            crate::get_value(&c.futures_value(), &Value::Str(hash.to_string().into())),
1598            Value::Null
1599        )
1600    }
1601
1602    #[tokio::test]
1603    async fn parse_helpers() {
1604        // JSON text → dict; non-JSON → Value::Str.
1605        assert!(matches!(parse_text("{\"a\":1}"), Value::Dict(_)));
1606        assert_eq!(parse_text("pong"), Value::Str("pong".into()));
1607        // gzip binary → parsed JSON.
1608        use std::io::Write;
1609        let mut e = flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::default());
1610        e.write_all(b"{\"x\":true}").unwrap();
1611        let gz = e.finish().unwrap();
1612        assert!(matches!(parse_binary(&gz), Value::Dict(_)));
1613    }
1614
1615    #[test]
1616    fn raw_binary_frames_stay_bytes() {
1617        // an SBE heartbeat header is all small integers, so the frame is valid
1618        // utf-8, it must still reach the exchange as bytes with decompressBinary off
1619        let frame: Vec<u8> = vec![0x10, 0x00, 0x28, 0x00, 0x01, 0x00, 0x02, 0x00, 0x41, 0x42, 0x43, 0x01];
1620        assert!(std::str::from_utf8(&frame).is_ok());
1621        assert_eq!(parse_raw_binary(&frame), crate::exchange_stubs::bytes_to_value(&frame));
1622        // json over the binary opcode is still parsed
1623        assert!(matches!(parse_raw_binary(b"{\"x\":true}"), Value::Dict(_)));
1624    }
1625}