Skip to main content

nautilus_binance/spot/websocket/trading/
handler.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Binance Spot WebSocket API message handler.
17//!
18//! The handler runs in a dedicated Tokio task as the I/O boundary between the client
19//! orchestrator and the network layer. It exclusively owns the `WebSocketClient` and
20//! processes commands from the client via an unbounded channel.
21//!
22//! ## Responsibilities
23//!
24//! - Command processing: Receives `BinanceSpotWsTradingCommand` from client, serializes to JSON requests.
25//! - Response decoding: Parses SBE binary responses using schema 3 decoders.
26//! - Request correlation: Matches responses to pending requests by ID.
27//! - Message transformation: Emits `BinanceSpotWsTradingMessage` events to client via channel.
28
29use std::{
30    fmt::Debug,
31    sync::{
32        Arc,
33        atomic::{AtomicBool, AtomicU64, Ordering},
34    },
35};
36
37use ahash::AHashMap;
38use nautilus_network::{RECONNECTED, websocket::WebSocketClient};
39use tokio_tungstenite::tungstenite::Message;
40
41use super::{
42    client::BINANCE_WS_RATE_LIMIT_KEY_ORDER,
43    error::{BinanceWsApiError, BinanceWsApiResult},
44    messages::{
45        BinanceSpotWsTradingCommand, BinanceSpotWsTradingMessage, BinanceSpotWsTradingRequest,
46        BinanceSpotWsTradingRequestMeta, method,
47    },
48};
49use crate::{
50    common::credential::{SigningCredential, canonical_ws_query_string},
51    spot::{
52        enums::BinanceSpotUserDataEventType,
53        http::{models::BinanceCancelOpenOrdersResponse, parse},
54        sbe::spot::{
55            ReadBuf,
56            error_response_codec::ErrorResponseDecoder,
57            message_header_codec,
58            web_socket_response_codec::{SBE_TEMPLATE_ID, WebSocketResponseDecoder},
59        },
60    },
61};
62
63/// Binance Spot WebSocket API handler.
64///
65/// Runs in a dedicated Tokio task, processing commands from the client
66/// and transforming raw WebSocket messages into Nautilus domain events.
67/// Messages are sent to the client via the output channel.
68pub struct BinanceSpotWsTradingHandler {
69    signal: Arc<AtomicBool>,
70    inner: Option<WebSocketClient>,
71    cmd_rx: tokio::sync::mpsc::UnboundedReceiver<BinanceSpotWsTradingCommand>,
72    raw_rx: tokio::sync::mpsc::UnboundedReceiver<Message>,
73    out_tx: tokio::sync::mpsc::UnboundedSender<BinanceSpotWsTradingMessage>,
74    credential: Arc<SigningCredential>,
75    pending_requests: AHashMap<String, BinanceSpotWsTradingRequestMeta>,
76    request_id_counter: AtomicU64,
77    recv_window_ms: Option<u64>,
78}
79
80impl Debug for BinanceSpotWsTradingHandler {
81    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
82        f.debug_struct(stringify!(BinanceSpotWsTradingHandler))
83            .field("inner", &self.inner.as_ref().map(|_| "<client>"))
84            .field(
85                "pending_requests",
86                &format!("{} pending", self.pending_requests.len()),
87            )
88            .finish_non_exhaustive()
89    }
90}
91
92impl BinanceSpotWsTradingHandler {
93    /// Creates a new handler instance.
94    #[must_use]
95    pub fn new(
96        signal: Arc<AtomicBool>,
97        cmd_rx: tokio::sync::mpsc::UnboundedReceiver<BinanceSpotWsTradingCommand>,
98        raw_rx: tokio::sync::mpsc::UnboundedReceiver<Message>,
99        out_tx: tokio::sync::mpsc::UnboundedSender<BinanceSpotWsTradingMessage>,
100        credential: Arc<SigningCredential>,
101    ) -> Self {
102        Self {
103            signal,
104            inner: None,
105            cmd_rx,
106            raw_rx,
107            out_tx,
108            credential,
109            pending_requests: AHashMap::new(),
110            request_id_counter: AtomicU64::new(1000),
111            recv_window_ms: None,
112        }
113    }
114
115    /// Configures the receive window added before request signing.
116    #[must_use]
117    pub const fn with_recv_window(mut self, recv_window_ms: Option<u64>) -> Self {
118        self.recv_window_ms = recv_window_ms;
119        self
120    }
121
122    /// Runs the main event loop for commands and raw messages.
123    ///
124    /// Sends output messages via `out_tx` channel. Returns `false` when disconnected
125    /// or the signal is set, indicating the handler should exit.
126    pub async fn run(&mut self) -> bool {
127        loop {
128            if self.signal.load(Ordering::Relaxed) {
129                return false;
130            }
131
132            tokio::select! {
133                Some(cmd) = self.cmd_rx.recv() => {
134                    match cmd {
135                        BinanceSpotWsTradingCommand::SetClient(client) => {
136                            log::debug!("Handler received WebSocket client");
137                            self.inner = Some(client);
138                            self.emit(BinanceSpotWsTradingMessage::Connected);
139                        }
140                        BinanceSpotWsTradingCommand::Disconnect => {
141                            log::debug!("Handler disconnecting WebSocket client");
142                            self.inner = None;
143                            return false;
144                        }
145                        BinanceSpotWsTradingCommand::PlaceOrder { id, params } => {
146                            if let Err(e) = self.handle_place_order(id.clone(), params).await {
147                                log::debug!("Failed to handle place order command: {e}");
148                                self.pending_requests.remove(&id);
149                                self.emit(BinanceSpotWsTradingMessage::RequestFailed {
150                                    request_id: id,
151                                    msg: e.to_string(),
152                                });
153                            }
154                        }
155                        BinanceSpotWsTradingCommand::CancelOrder { id, params } => {
156                            if let Err(e) = self.handle_cancel_order(id.clone(), params).await {
157                                log::debug!("Failed to handle cancel order command: {e}");
158                                self.pending_requests.remove(&id);
159                                self.emit(BinanceSpotWsTradingMessage::RequestFailed {
160                                    request_id: id,
161                                    msg: e.to_string(),
162                                });
163                            }
164                        }
165                        BinanceSpotWsTradingCommand::CancelReplaceOrder { id, params } => {
166                            if let Err(e) = self.handle_cancel_replace_order(id.clone(), params).await {
167                                log::debug!("Failed to handle cancel replace command: {e}");
168                                self.pending_requests.remove(&id);
169                                self.emit(BinanceSpotWsTradingMessage::RequestFailed {
170                                    request_id: id,
171                                    msg: e.to_string(),
172                                });
173                            }
174                        }
175                        BinanceSpotWsTradingCommand::CancelAllOrders { id, symbol } => {
176                            if let Err(e) = self.handle_cancel_all_orders(id.clone(), symbol).await {
177                                log::debug!("Failed to handle cancel all command: {e}");
178                                self.pending_requests.remove(&id);
179                                self.emit(BinanceSpotWsTradingMessage::RequestFailed {
180                                    request_id: id,
181                                    msg: e.to_string(),
182                                });
183                            }
184                        }
185                        BinanceSpotWsTradingCommand::SessionLogon => {
186                            if let Err(e) = self.handle_session_logon().await {
187                                log::error!("Session logon failed: {e}");
188                                self.emit(BinanceSpotWsTradingMessage::AuthenticationRejected(
189                                    format!("Session logon failed: {e}"),
190                                ));
191                            }
192                        }
193                        BinanceSpotWsTradingCommand::SubscribeUserData => {
194                            if let Err(e) = self.handle_subscribe_user_data().await {
195                                log::error!("User data subscribe failed: {e}");
196                                self.emit(
197                                    BinanceSpotWsTradingMessage::UserDataSubscriptionRejected(
198                                        format!("User data subscribe failed: {e}"),
199                                    ),
200                                );
201                            }
202                        }
203                    }
204                }
205                Some(msg) = self.raw_rx.recv() => {
206                    if let Message::Text(ref text) = msg
207                        && text.as_str() == RECONNECTED
208                    {
209                        log::debug!("Handler received reconnection signal");
210
211                        // Fail any pending requests - they won't get responses on new connection
212                        self.fail_pending_requests();
213
214                        self.emit(BinanceSpotWsTradingMessage::Reconnected);
215                        continue;
216                    }
217
218                    self.handle_message(msg);
219                }
220                else => {
221                    // Both channels closed
222                    return false;
223                }
224            }
225        }
226    }
227
228    /// Sends a message to the output channel.
229    fn emit(&self, msg: BinanceSpotWsTradingMessage) {
230        if let Err(e) = self.out_tx.send(msg) {
231            log::error!("Failed to send message to output channel: {e}");
232        }
233    }
234
235    /// Fails all pending requests after a reconnection.
236    fn fail_pending_requests(&mut self) {
237        if self.pending_requests.is_empty() {
238            return;
239        }
240
241        let count = self.pending_requests.len();
242        log::warn!("Failing {count} pending requests after reconnection");
243
244        let pending = std::mem::take(&mut self.pending_requests);
245        for (request_id, _meta) in pending {
246            self.emit(BinanceSpotWsTradingMessage::RequestFailed {
247                request_id,
248                msg: "Connection lost before response received".to_string(),
249            });
250        }
251    }
252
253    async fn handle_place_order(
254        &mut self,
255        id: String,
256        params: crate::spot::http::query::NewOrderParams,
257    ) -> BinanceWsApiResult<()> {
258        let params_json = serde_json::to_value(&params)
259            .map_err(|e| BinanceWsApiError::ClientError(e.to_string()))?;
260        let signed_params = self.sign_params(params_json)?;
261
262        let request = BinanceSpotWsTradingRequest::new(&id, method::ORDER_PLACE, signed_params);
263        self.pending_requests
264            .insert(id.clone(), BinanceSpotWsTradingRequestMeta::PlaceOrder);
265        self.send_request(request).await
266    }
267
268    async fn handle_cancel_order(
269        &mut self,
270        id: String,
271        params: crate::spot::http::query::CancelOrderParams,
272    ) -> BinanceWsApiResult<()> {
273        let params_json = serde_json::to_value(&params)
274            .map_err(|e| BinanceWsApiError::ClientError(e.to_string()))?;
275        let signed_params = self.sign_params(params_json)?;
276
277        let request = BinanceSpotWsTradingRequest::new(&id, method::ORDER_CANCEL, signed_params);
278        self.pending_requests
279            .insert(id.clone(), BinanceSpotWsTradingRequestMeta::CancelOrder);
280        self.send_request(request).await
281    }
282
283    async fn handle_cancel_replace_order(
284        &mut self,
285        id: String,
286        params: crate::spot::http::query::CancelReplaceOrderParams,
287    ) -> BinanceWsApiResult<()> {
288        let params_json = serde_json::to_value(&params)
289            .map_err(|e| BinanceWsApiError::ClientError(e.to_string()))?;
290        let signed_params = self.sign_params(params_json)?;
291
292        let request =
293            BinanceSpotWsTradingRequest::new(&id, method::ORDER_CANCEL_REPLACE, signed_params);
294        self.pending_requests.insert(
295            id.clone(),
296            BinanceSpotWsTradingRequestMeta::CancelReplaceOrder,
297        );
298        self.send_request(request).await
299    }
300
301    async fn handle_cancel_all_orders(
302        &mut self,
303        id: String,
304        symbol: String,
305    ) -> BinanceWsApiResult<()> {
306        let params_json = serde_json::json!({ "symbol": symbol });
307        let signed_params = self.sign_params(params_json)?;
308
309        let request =
310            BinanceSpotWsTradingRequest::new(&id, method::OPEN_ORDERS_CANCEL_ALL, signed_params);
311        self.pending_requests
312            .insert(id.clone(), BinanceSpotWsTradingRequestMeta::CancelAllOrders);
313        self.send_request(request).await
314    }
315
316    async fn handle_session_logon(&mut self) -> BinanceWsApiResult<()> {
317        let id = self.next_request_id();
318        let params_json = serde_json::json!({});
319        let signed_params = self.sign_params(params_json)?;
320
321        let request = BinanceSpotWsTradingRequest::new(&id, method::SESSION_LOGON, signed_params);
322        self.pending_requests
323            .insert(id, BinanceSpotWsTradingRequestMeta::SessionLogon);
324        self.send_request(request).await
325    }
326
327    async fn handle_subscribe_user_data(&mut self) -> BinanceWsApiResult<()> {
328        let id = self.next_request_id();
329        let request = BinanceSpotWsTradingRequest::new(
330            &id,
331            "userDataStream.subscribe",
332            serde_json::json!({}),
333        );
334        self.pending_requests
335            .insert(id, BinanceSpotWsTradingRequestMeta::SubscribeUserData);
336        self.send_request(request).await
337    }
338
339    fn next_request_id(&self) -> String {
340        let id = self.request_id_counter.fetch_add(1, Ordering::Relaxed);
341        format!("ws-{id}")
342    }
343
344    fn sign_params(&self, mut params: serde_json::Value) -> BinanceWsApiResult<serde_json::Value> {
345        let timestamp = std::time::SystemTime::now()
346            .duration_since(std::time::UNIX_EPOCH)
347            .map_err(|e| BinanceWsApiError::ClientError(e.to_string()))?
348            .as_millis() as i64;
349
350        if let Some(obj) = params.as_object_mut() {
351            obj.insert("timestamp".to_string(), serde_json::json!(timestamp));
352            obj.insert(
353                "apiKey".to_string(),
354                serde_json::json!(self.credential.api_key()),
355            );
356
357            if let Some(recv_window_ms) = self.recv_window_ms {
358                obj.insert("recvWindow".to_string(), serde_json::json!(recv_window_ms));
359            }
360        }
361
362        // Sign over a key-sorted query string: Binance's WS API verifies the
363        // signature against the parameters sorted by key, which must not depend
364        // on serde_json's Map iteration order (issue #4410).
365        let query_string = canonical_ws_query_string(
366            params
367                .as_object()
368                .into_iter()
369                .flatten()
370                .map(|(k, v)| (k.as_str(), v)),
371        )
372        .map_err(|e| BinanceWsApiError::ClientError(e.to_string()))?;
373        let signature = self.credential.sign(&query_string);
374
375        if let Some(obj) = params.as_object_mut() {
376            obj.insert("signature".to_string(), serde_json::json!(signature));
377        }
378
379        Ok(params)
380    }
381
382    async fn send_request(
383        &mut self,
384        request: BinanceSpotWsTradingRequest,
385    ) -> BinanceWsApiResult<()> {
386        let client = self.inner.as_mut().ok_or_else(|| {
387            BinanceWsApiError::ConnectionError("WebSocket not connected".to_string())
388        })?;
389
390        let json = serde_json::to_string(&request)
391            .map_err(|e| BinanceWsApiError::ClientError(e.to_string()))?;
392
393        log::debug!(
394            "Sending WebSocket API request id={} method={}",
395            request.id,
396            request.method
397        );
398
399        let keys = Some(BINANCE_WS_RATE_LIMIT_KEY_ORDER.as_slice());
400
401        let is_session_setup = matches!(
402            self.pending_requests.get(&request.id),
403            Some(
404                BinanceSpotWsTradingRequestMeta::SessionLogon
405                    | BinanceSpotWsTradingRequestMeta::SubscribeUserData
406            )
407        );
408
409        let result = if is_session_setup {
410            client
411                .send_text_on_connection(json, keys, client.connection_epoch())
412                .await
413        } else {
414            client.send_text(json, keys).await
415        };
416
417        result.map_err(|e| {
418            BinanceWsApiError::ConnectionError(format!("Failed to send request: {e}"))
419        })?;
420
421        Ok(())
422    }
423
424    fn handle_message(&mut self, msg: Message) {
425        match msg {
426            Message::Binary(data) => self.handle_binary_response(&data),
427            Message::Text(text) => self.handle_text_response(&text),
428            Message::Ping(_) | Message::Pong(_) => {}
429            Message::Close(frame) => {
430                log::debug!("WebSocket closed: {frame:?}");
431            }
432            Message::Frame(_) => {}
433        }
434    }
435
436    fn handle_binary_response(&mut self, data: &[u8]) {
437        match self.decode_ws_api_response(data) {
438            Ok(response) => self.emit(response),
439            Err(e) => {
440                log::error!("Failed to decode WebSocket API response: {e}");
441                self.emit(BinanceSpotWsTradingMessage::Error(e.to_string()));
442            }
443        }
444    }
445
446    fn handle_text_response(&mut self, text: &str) {
447        let json: serde_json::Value = match serde_json::from_str(text) {
448            Ok(j) => j,
449            Err(e) => {
450                log::warn!("Failed to parse text response as JSON: {e}");
451                return;
452            }
453        };
454
455        // User data events arrive wrapped: {"subscriptionId": N, "event": {...}}
456        if let Some(event) = json.get("event") {
457            self.handle_user_data_event(event);
458            return;
459        }
460
461        // Legacy listen-key streams, including Binance US, send the event directly.
462        if json.get("e").is_some() {
463            self.handle_user_data_event(&json);
464            return;
465        }
466
467        // WS API responses have an "id" field for request correlation
468        if let Some(id) = json.get("id") {
469            let id_str = match id {
470                serde_json::Value::String(s) => s.clone(),
471                serde_json::Value::Number(n) => n.to_string(),
472                _ => return,
473            };
474
475            if let Some(meta) = self.pending_requests.remove(&id_str) {
476                // Check for error: nested {"error": {"code": N, "msg": "..."}}
477                // or top-level {"code": N, "msg": "..."}
478                let error_info = json
479                    .get("error")
480                    .map(|e| {
481                        (
482                            e.get("code")
483                                .and_then(|v| v.as_i64())
484                                .and_then(|code| i32::try_from(code).ok()),
485                            e.get("msg")
486                                .and_then(|v| v.as_str())
487                                .unwrap_or("Unknown error")
488                                .to_string(),
489                        )
490                    })
491                    .or_else(|| {
492                        json.get("code").and_then(|c| c.as_i64()).map(|code| {
493                            let msg = json
494                                .get("msg")
495                                .and_then(|v| v.as_str())
496                                .unwrap_or("Unknown error")
497                                .to_string();
498                            (i32::try_from(code).ok(), msg)
499                        })
500                    });
501
502                if let Some((code, msg)) = error_info {
503                    let status = json
504                        .get("status")
505                        .and_then(|v| v.as_u64())
506                        .map(|s| s as u16);
507                    let rejection = match code {
508                        Some(code) => {
509                            self.create_rejection(id_str, status.unwrap_or(0), code, msg, meta)
510                        }
511                        None => BinanceSpotWsTradingMessage::RequestFailed {
512                            request_id: id_str,
513                            msg: format!("Missing or invalid venue error code: {msg}"),
514                        },
515                    };
516                    self.emit(rejection);
517                    return;
518                }
519
520                // Success response
521                match meta {
522                    BinanceSpotWsTradingRequestMeta::SessionLogon => {
523                        log::debug!("Session authenticated");
524                        self.emit(BinanceSpotWsTradingMessage::Authenticated);
525                    }
526                    BinanceSpotWsTradingRequestMeta::SubscribeUserData => {
527                        let subscription_id = json
528                            .get("result")
529                            .and_then(|r| r.get("subscriptionId"))
530                            .map(|v| v.to_string())
531                            .unwrap_or_default();
532                        log::debug!("User data stream subscribed: id={subscription_id}");
533                        self.emit(BinanceSpotWsTradingMessage::UserDataSubscribed {
534                            subscription_id,
535                        });
536                    }
537                    _ => {
538                        // Order operation responses come as SBE binary, not JSON text.
539                        // If we get a JSON success for an order operation, log it.
540                        log::debug!("Unexpected JSON success for request {id_str}");
541                    }
542                }
543                return;
544            }
545
546            // Error response without matching pending request
547            if let Some(code) = json.get("code").and_then(|v| v.as_i64()) {
548                let msg = json
549                    .get("msg")
550                    .and_then(|v| v.as_str())
551                    .unwrap_or("Unknown error");
552                log::warn!(
553                    "Received error response without matching request ID: code={code} msg={msg}"
554                );
555            }
556            return;
557        }
558
559        // Stream termination event
560        if json.get("eventStreamTerminated").is_some() {
561            log::warn!("User data stream terminated, resubscribe needed");
562            return;
563        }
564
565        log::debug!("Unhandled text message: {} bytes", text.len());
566    }
567
568    fn handle_user_data_event(&self, event: &serde_json::Value) {
569        if let Some(msg) = classify_user_data_event(event) {
570            self.emit(msg);
571        }
572    }
573
574    fn decode_ws_api_response(
575        &mut self,
576        data: &[u8],
577    ) -> Result<BinanceSpotWsTradingMessage, BinanceWsApiError> {
578        // Check template ID before parsing
579        if data.len() >= message_header_codec::ENCODED_LENGTH {
580            let buf = ReadBuf::new(data);
581            let template_id = buf.get_u16_at(2);
582
583            // User data stream events arrive as SBE with their own template IDs
584            // (not wrapped in WebSocketResponse template 50).
585            match template_id {
586                601 => {
587                    log::debug!("Received SBE BalanceUpdateEvent ({} bytes)", data.len());
588                    match super::decode_sbe::decode_balance_update(data) {
589                        Ok(msg) => {
590                            log::debug!(
591                                "SBE balance update: asset={}, delta={}",
592                                msg.asset,
593                                msg.delta
594                            );
595                            return Ok(BinanceSpotWsTradingMessage::BalanceUpdate(msg));
596                        }
597                        Err(e) => {
598                            log::error!("Failed to decode SBE BalanceUpdateEvent: {e}");
599                            return Ok(BinanceSpotWsTradingMessage::Error(format!(
600                                "SBE BalanceUpdateEvent decode failed: {e}"
601                            )));
602                        }
603                    }
604                }
605                603 => {
606                    log::debug!("Received SBE ExecutionReportEvent ({} bytes)", data.len());
607                    match super::decode_sbe::decode_execution_report(data) {
608                        Ok(report) => {
609                            log::debug!(
610                                "SBE execution report: symbol={}, order_id={}, exec={:?}, status={:?}",
611                                report.symbol,
612                                report.order_id,
613                                report.execution_type,
614                                report.order_status
615                            );
616                            return Ok(BinanceSpotWsTradingMessage::ExecutionReport(Box::new(
617                                report,
618                            )));
619                        }
620                        Err(e) => {
621                            log::error!("Failed to decode SBE ExecutionReportEvent: {e}");
622                            return Ok(BinanceSpotWsTradingMessage::Error(format!(
623                                "SBE ExecutionReportEvent decode failed: {e}"
624                            )));
625                        }
626                    }
627                }
628                606 => {
629                    return Ok(match super::decode_sbe::decode_list_status(data) {
630                        Ok(status) => BinanceSpotWsTradingMessage::ListStatus(status),
631                        Err(e) => BinanceSpotWsTradingMessage::Error(format!(
632                            "SBE ListStatusEvent decode failed: {e}"
633                        )),
634                    });
635                }
636                607 => {
637                    log::debug!(
638                        "Received SBE OutboundAccountPositionEvent ({} bytes)",
639                        data.len()
640                    );
641
642                    match super::decode_sbe::decode_account_position(data) {
643                        Ok(msg) => {
644                            log::debug!("SBE account position: {} balance(s)", msg.balances.len());
645                            return Ok(BinanceSpotWsTradingMessage::AccountPosition(msg));
646                        }
647                        Err(e) => {
648                            log::error!("Failed to decode SBE OutboundAccountPositionEvent: {e}");
649                            return Ok(BinanceSpotWsTradingMessage::Error(format!(
650                                "SBE OutboundAccountPositionEvent decode failed: {e}"
651                            )));
652                        }
653                    }
654                }
655                610 => {
656                    let event_time = parse_server_shutdown_event_time_ms(data);
657                    return Ok(BinanceSpotWsTradingMessage::ServerShutdown { event_time });
658                }
659                _ => {} // Fall through to WebSocketResponse parsing
660            }
661        }
662
663        // Standard WebSocketResponse envelope (template 50)
664        let (request_id, status, result_data) = self.parse_envelope(data)?;
665
666        // Look up the pending request by ID
667        let meta = self.pending_requests.remove(&request_id).ok_or_else(|| {
668            BinanceWsApiError::UnknownRequestId(format!("No pending request for ID: {request_id}"))
669        })?;
670
671        // Check for error status (non-200)
672        if status != 200 {
673            return Ok(match Self::try_decode_sbe_error(&result_data) {
674                Some((code, msg)) => self.create_rejection(request_id, status, code, msg, meta),
675                // An undecodable error payload carries no definitive command evidence
676                None => BinanceSpotWsTradingMessage::RequestFailed {
677                    request_id,
678                    msg: format!("Request failed with status {status}; error payload undecodable"),
679                },
680            });
681        }
682
683        // Decode the inner payload based on request type
684        match meta {
685            BinanceSpotWsTradingRequestMeta::PlaceOrder => {
686                let response = parse::decode_new_order_full(&result_data)?;
687                Ok(BinanceSpotWsTradingMessage::OrderAccepted {
688                    request_id,
689                    response,
690                })
691            }
692            BinanceSpotWsTradingRequestMeta::CancelOrder => {
693                Self::decode_cancel_order(request_id, &result_data)
694            }
695            BinanceSpotWsTradingRequestMeta::CancelReplaceOrder => {
696                let (cancel_response, new_order_response) =
697                    parse::decode_cancel_replace_orders(&result_data)?;
698                Ok(BinanceSpotWsTradingMessage::CancelReplaceAccepted {
699                    request_id,
700                    cancel_response,
701                    new_order_response,
702                })
703            }
704            BinanceSpotWsTradingRequestMeta::CancelAllOrders => {
705                let responses = parse::decode_cancel_open_orders(&result_data)?;
706                Ok(BinanceSpotWsTradingMessage::AllOrdersCanceled {
707                    request_id,
708                    responses,
709                })
710            }
711            BinanceSpotWsTradingRequestMeta::SessionLogon => {
712                log::debug!("Session authenticated (SBE response)");
713                Ok(BinanceSpotWsTradingMessage::Authenticated)
714            }
715            BinanceSpotWsTradingRequestMeta::SubscribeUserData => {
716                log::debug!("User data stream subscribed (SBE response)");
717                Ok(BinanceSpotWsTradingMessage::UserDataSubscribed {
718                    subscription_id: request_id,
719                })
720            }
721        }
722    }
723
724    fn decode_cancel_order(
725        request_id: String,
726        result_data: &[u8],
727    ) -> Result<BinanceSpotWsTradingMessage, BinanceWsApiError> {
728        match parse::decode_cancel_order_or_list(result_data)? {
729            BinanceCancelOpenOrdersResponse::Order(response) => {
730                Ok(BinanceSpotWsTradingMessage::OrderCanceled {
731                    request_id,
732                    response,
733                })
734            }
735            response @ BinanceCancelOpenOrdersResponse::OrderList(_) => {
736                Ok(BinanceSpotWsTradingMessage::AllOrdersCanceled {
737                    request_id,
738                    responses: vec![response],
739                })
740            }
741        }
742    }
743
744    /// Parses the WebSocketResponse SBE envelope.
745    ///
746    /// Returns (request_id, status, result_payload).
747    fn parse_envelope(&self, data: &[u8]) -> Result<(String, u16, Vec<u8>), BinanceWsApiError> {
748        if data.len() < message_header_codec::ENCODED_LENGTH {
749            return Err(BinanceWsApiError::DecodeError(
750                crate::spot::sbe::error::SbeDecodeError::BufferTooShort {
751                    expected: message_header_codec::ENCODED_LENGTH,
752                    actual: data.len(),
753                },
754            ));
755        }
756
757        let buf = ReadBuf::new(data);
758
759        // Parse message header
760        let block_length = buf.get_u16_at(0);
761        let template_id = buf.get_u16_at(2);
762
763        if template_id != SBE_TEMPLATE_ID {
764            return Err(BinanceWsApiError::DecodeError(
765                crate::spot::sbe::error::SbeDecodeError::UnknownTemplateId(template_id),
766            ));
767        }
768
769        let version = buf.get_u16_at(6);
770
771        // Create decoder at offset after message header
772        let decoder = WebSocketResponseDecoder::default().wrap(
773            buf,
774            message_header_codec::ENCODED_LENGTH,
775            block_length,
776            version,
777        );
778
779        // Read status from fixed block (offset 1 within block)
780        let status = decoder.status();
781
782        // Skip rate_limits group
783        let mut rate_limits = decoder.rate_limits_decoder();
784        while rate_limits.advance().unwrap_or(None).is_some() {}
785        let mut decoder = rate_limits.parent().map_err(|e| {
786            BinanceWsApiError::ClientError(format!("Failed to get parent from rate_limits: {e}"))
787        })?;
788
789        // Extract request ID
790        let id_coords = decoder.id_decoder();
791        let id_bytes = decoder.id_slice(id_coords);
792        let request_id = String::from_utf8_lossy(id_bytes).to_string();
793
794        // Extract result payload - copy to owned Vec to avoid lifetime issues
795        let result_coords = decoder.result_decoder();
796        let result_data = decoder.result_slice(result_coords).to_vec();
797
798        Ok((request_id, status, result_data))
799    }
800
801    fn create_rejection(
802        &self,
803        request_id: String,
804        status: u16,
805        code: i32,
806        msg: String,
807        meta: BinanceSpotWsTradingRequestMeta,
808    ) -> BinanceSpotWsTradingMessage {
809        match meta {
810            BinanceSpotWsTradingRequestMeta::PlaceOrder => {
811                BinanceSpotWsTradingMessage::OrderRejected {
812                    request_id,
813                    status,
814                    code,
815                    msg,
816                }
817            }
818            BinanceSpotWsTradingRequestMeta::CancelOrder => {
819                BinanceSpotWsTradingMessage::CancelRejected {
820                    request_id,
821                    status,
822                    code,
823                    msg,
824                }
825            }
826            BinanceSpotWsTradingRequestMeta::CancelReplaceOrder => {
827                BinanceSpotWsTradingMessage::CancelReplaceRejected {
828                    request_id,
829                    status,
830                    code,
831                    msg,
832                }
833            }
834            BinanceSpotWsTradingRequestMeta::CancelAllOrders => {
835                BinanceSpotWsTradingMessage::CancelRejected {
836                    request_id,
837                    status,
838                    code,
839                    msg,
840                }
841            }
842            BinanceSpotWsTradingRequestMeta::SessionLogon => {
843                BinanceSpotWsTradingMessage::AuthenticationRejected(format!("code={code}: {msg}"))
844            }
845            BinanceSpotWsTradingRequestMeta::SubscribeUserData => {
846                BinanceSpotWsTradingMessage::UserDataSubscriptionRejected(format!(
847                    "code={code}: {msg}"
848                ))
849            }
850        }
851    }
852
853    // Decodes the SBE error response to extract the Binance error code and message
854    fn try_decode_sbe_error(data: &[u8]) -> Option<(i32, String)> {
855        const HEADER_LEN: usize = 8;
856
857        if data.len()
858            < HEADER_LEN + crate::spot::sbe::spot::error_response_codec::SBE_BLOCK_LENGTH as usize
859        {
860            return None;
861        }
862
863        let buf = ReadBuf::new(data);
864        let header = message_header_codec::MessageHeaderDecoder::default().wrap(buf, 0);
865        if header.template_id() != crate::spot::sbe::spot::error_response_codec::SBE_TEMPLATE_ID {
866            return None;
867        }
868
869        let mut decoder = ErrorResponseDecoder::default().header(header, 0);
870        let code = i32::from(decoder.code());
871        let msg_coords = decoder.msg_decoder();
872        let msg_bytes = decoder.msg_slice(msg_coords);
873        let msg = String::from_utf8_lossy(msg_bytes).into_owned();
874
875        Some((code, msg))
876    }
877}
878
879/// Classifies a JSON user-data event into a trading message, if any.
880///
881/// Returns `None` when the event type is unknown or the payload fails to
882/// deserialize; in that case the caller logs and drops the event.
883pub(crate) fn classify_user_data_event(
884    event: &serde_json::Value,
885) -> Option<BinanceSpotWsTradingMessage> {
886    let event_type = event
887        .get("e")
888        .and_then(|v| serde_json::from_value::<BinanceSpotUserDataEventType>(v.clone()).ok())
889        .unwrap_or(BinanceSpotUserDataEventType::Unknown);
890
891    match event_type {
892        BinanceSpotUserDataEventType::ExecutionReport => {
893            match serde_json::from_value::<super::user_data::BinanceSpotExecutionReport>(
894                event.clone(),
895            ) {
896                Ok(report) => {
897                    log::debug!(
898                        "Execution report: symbol={}, order_id={}, exec={:?}, status={:?}",
899                        report.symbol,
900                        report.order_id,
901                        report.execution_type,
902                        report.order_status
903                    );
904                    Some(BinanceSpotWsTradingMessage::ExecutionReport(Box::new(
905                        report,
906                    )))
907                }
908                Err(e) => {
909                    log::warn!("Failed to parse execution report: {e}");
910                    None
911                }
912            }
913        }
914        BinanceSpotUserDataEventType::OutboundAccountPosition => {
915            match serde_json::from_value::<super::user_data::BinanceSpotAccountPositionMsg>(
916                event.clone(),
917            ) {
918                Ok(msg) => {
919                    log::debug!("Account position update: {} balance(s)", msg.balances.len());
920                    Some(BinanceSpotWsTradingMessage::AccountPosition(msg))
921                }
922                Err(e) => {
923                    log::warn!("Failed to parse account position: {e}");
924                    None
925                }
926            }
927        }
928        BinanceSpotUserDataEventType::BalanceUpdate => {
929            match serde_json::from_value::<super::user_data::BinanceSpotBalanceUpdateMsg>(
930                event.clone(),
931            ) {
932                Ok(msg) => {
933                    log::debug!("Balance update: asset={}, delta={}", msg.asset, msg.delta);
934                    Some(BinanceSpotWsTradingMessage::BalanceUpdate(msg))
935                }
936                Err(e) => {
937                    log::warn!("Failed to parse balance update: {e}");
938                    None
939                }
940            }
941        }
942        BinanceSpotUserDataEventType::ServerShutdown => {
943            let event_time = event.get("E").and_then(|v| v.as_i64()).unwrap_or_default();
944            Some(BinanceSpotWsTradingMessage::ServerShutdown { event_time })
945        }
946        BinanceSpotUserDataEventType::ListenKeyExpired
947        | BinanceSpotUserDataEventType::ExternalLockUpdate
948        | BinanceSpotUserDataEventType::EventStreamTerminated
949        | BinanceSpotUserDataEventType::Unknown => {
950            log::debug!("Unhandled user data event type: {event_type:?}");
951            None
952        }
953    }
954}
955
956/// Parses the `event_time` from an SBE `ServerShutdownEvent` (template 610) frame.
957///
958/// The SBE field is microseconds; the trading message variant documents
959/// milliseconds (matching the JSON dispatch), so this divides by 1_000.
960/// Returns `0` when the buffer is too short to contain the field.
961pub(crate) fn parse_server_shutdown_event_time_ms(data: &[u8]) -> i64 {
962    if data.len() < message_header_codec::ENCODED_LENGTH + 8 {
963        return 0;
964    }
965    let buf = ReadBuf::new(data);
966    buf.get_i64_at(message_header_codec::ENCODED_LENGTH) / 1_000
967}
968
969#[cfg(test)]
970mod tests {
971    use std::time::Duration;
972
973    use futures_util::StreamExt;
974    use nautilus_common::testing::wait_until_async;
975    use nautilus_network::{
976        error::SendError,
977        websocket::{AuthTracker, WebSocketConfig},
978    };
979    use rstest::rstest;
980
981    use super::*;
982    use crate::spot::sbe::spot::{
983        cancel_order_response_codec::CancelOrderResponseDecoder,
984        new_order_full_response_codec::NewOrderFullResponseDecoder,
985        self_trade_prevention_mode::SelfTradePreventionMode,
986    };
987
988    #[tokio::test]
989    async fn test_authentication_with_full_replay_buffer() {
990        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
991        let address = listener.local_addr().unwrap();
992        let (replayed_tx, replayed_rx) = tokio::sync::oneshot::channel();
993
994        let server = tokio::spawn(async move {
995            let (first, _) = listener.accept().await.unwrap();
996            let _first = tokio_tungstenite::accept_async(first).await.unwrap();
997            let (replacement, _) = listener.accept().await.unwrap();
998            let mut replacement = tokio_tungstenite::accept_async(replacement).await.unwrap();
999            let auth = replacement.next().await.unwrap().unwrap();
1000            let auth: serde_json::Value = serde_json::from_str(auth.to_text().unwrap()).unwrap();
1001            assert_eq!(auth["method"], method::SESSION_LOGON);
1002            assert_eq!(auth["id"], "ws-1000");
1003            assert_eq!(auth["params"]["apiKey"], "api-key");
1004            let subscribe = replacement.next().await.unwrap().unwrap();
1005            let subscribe: serde_json::Value =
1006                serde_json::from_str(subscribe.to_text().unwrap()).unwrap();
1007            assert_eq!(subscribe["method"], "userDataStream.subscribe");
1008            assert_eq!(subscribe["id"], "ws-1001");
1009            assert_eq!(subscribe["params"], serde_json::json!({}));
1010            assert_eq!(
1011                replacement.next().await.unwrap().unwrap(),
1012                Message::text("held")
1013            );
1014            replayed_tx.send(()).unwrap();
1015            std::future::pending::<()>().await;
1016        });
1017
1018        let tracker = AuthTracker::new();
1019        let (_cmd_tx, cmd_rx) = tokio::sync::mpsc::unbounded_channel();
1020        let (_raw_tx, raw_rx) = tokio::sync::mpsc::unbounded_channel();
1021        let (out_tx, _out_rx) = tokio::sync::mpsc::unbounded_channel();
1022
1023        let mut handler = BinanceSpotWsTradingHandler::new(
1024            Arc::new(AtomicBool::new(false)),
1025            cmd_rx,
1026            raw_rx,
1027            out_tx,
1028            Arc::new(SigningCredential::new(
1029                "api-key".to_string(),
1030                "secret".to_string(),
1031            )),
1032        );
1033        let config = WebSocketConfig::builder()
1034            .url(format!("ws://{address}"))
1035            .writer_capacity(1)
1036            .reconnect_delay_initial_ms(1)
1037            .reconnect_delay_max_ms(1)
1038            .reconnect_jitter_ms(0)
1039            .build()
1040            .unwrap();
1041        let client = WebSocketClient::builder()
1042            .config(config)
1043            .message_handler(Arc::new(|_| {}))
1044            .connect()
1045            .await
1046            .unwrap();
1047        client.set_auth_tracker(tracker.clone(), true);
1048
1049        // Enqueue and request reconnect without yielding so the writer retains this message
1050        client.send_text("held".to_string(), None).await.unwrap();
1051        assert!(client.request_reconnect());
1052        wait_until_async(
1053            || async { client.is_active() && client.connection_epoch() == 1 },
1054            Duration::from_secs(5),
1055        )
1056        .await;
1057        assert!(matches!(
1058            client.send_text("overflow".to_string(), None).await,
1059            Err(SendError::BufferFull)
1060        ));
1061        handler.inner = Some(client);
1062        tokio::time::timeout(Duration::from_secs(5), handler.handle_session_logon())
1063            .await
1064            .unwrap()
1065            .unwrap();
1066        tokio::time::timeout(Duration::from_secs(5), handler.handle_subscribe_user_data())
1067            .await
1068            .unwrap()
1069            .unwrap();
1070        tracker.succeed();
1071        tokio::time::timeout(Duration::from_secs(5), replayed_rx)
1072            .await
1073            .unwrap()
1074            .unwrap();
1075        handler.inner.as_ref().unwrap().disconnect().await;
1076        server.abort();
1077    }
1078
1079    #[rstest]
1080    #[case::valid(false)]
1081    #[case::malformed(true)]
1082    fn test_list_status_routes_typed_message_or_controlled_error(#[case] malformed: bool) {
1083        let (_cmd_tx, cmd_rx) = tokio::sync::mpsc::unbounded_channel();
1084        let (_raw_tx, raw_rx) = tokio::sync::mpsc::unbounded_channel();
1085        let (out_tx, _out_rx) = tokio::sync::mpsc::unbounded_channel();
1086
1087        let mut handler = BinanceSpotWsTradingHandler::new(
1088            Arc::new(AtomicBool::new(false)),
1089            cmd_rx,
1090            raw_rx,
1091            out_tx,
1092            Arc::new(SigningCredential::new(
1093                "api-key".to_owned(),
1094                "secret".to_owned(),
1095            )),
1096        );
1097        let mut data = crate::common::testing::load_fixture_bytes(
1098            "spot/user_data_sbe/list_status_executing.sbe",
1099        );
1100
1101        if malformed {
1102            data.pop();
1103        }
1104
1105        let message = handler.decode_ws_api_response(&data).unwrap();
1106        if malformed {
1107            let BinanceSpotWsTradingMessage::Error(reason) = message else {
1108                panic!("Expected controlled error");
1109            };
1110
1111            assert!(reason.starts_with("SBE ListStatusEvent decode failed:"));
1112        } else {
1113            let BinanceSpotWsTradingMessage::ListStatus(status) = message else {
1114                panic!("Expected typed list status");
1115            };
1116
1117            assert_eq!(
1118                status,
1119                super::super::decode_sbe::decode_list_status(&data).unwrap()
1120            );
1121        }
1122    }
1123
1124    #[rstest]
1125    fn test_cancel_replace_response_decodes_both_orders() {
1126        let (_cmd_tx, cmd_rx) = tokio::sync::mpsc::unbounded_channel();
1127        let (_raw_tx, raw_rx) = tokio::sync::mpsc::unbounded_channel();
1128        let (out_tx, _out_rx) = tokio::sync::mpsc::unbounded_channel();
1129        let mut handler = BinanceSpotWsTradingHandler::new(
1130            Arc::new(AtomicBool::new(false)),
1131            cmd_rx,
1132            raw_rx,
1133            out_tx,
1134            Arc::new(SigningCredential::new(
1135                "api-key".to_string(),
1136                "secret".to_string(),
1137            )),
1138        );
1139        let placed = include_bytes!(
1140            "../../../../test_data/spot/user_data_sbe/mainnet/web_socket_response_1.sbe"
1141        );
1142        let canceled = include_bytes!(
1143            "../../../../test_data/spot/user_data_sbe/mainnet/web_socket_response_2.sbe"
1144        );
1145        let (request_id, _, replacement) = handler.parse_envelope(placed).unwrap();
1146        let (_, _, cancellation) = handler.parse_envelope(canceled).unwrap();
1147        let expected_new = parse::decode_new_order_full(&replacement).unwrap();
1148        let expected_cancel = parse::decode_cancel_order(&cancellation).unwrap();
1149        let mut payload = Vec::new();
1150
1151        for field in [
1152            2_u16,
1153            crate::spot::sbe::spot::cancel_replace_order_response_codec::SBE_TEMPLATE_ID,
1154            crate::spot::sbe::spot::SBE_SCHEMA_ID,
1155            crate::spot::sbe::spot::SBE_SCHEMA_VERSION,
1156        ] {
1157            payload.extend_from_slice(&field.to_le_bytes());
1158        }
1159        let success =
1160            crate::spot::sbe::spot::cancel_replace_status::CancelReplaceStatus::Success as u8;
1161        payload.extend_from_slice(&[success, success]);
1162        payload.extend_from_slice(&(cancellation.len() as u16).to_le_bytes());
1163        payload.extend_from_slice(&cancellation);
1164        payload.extend_from_slice(&(replacement.len() as u32).to_le_bytes());
1165        payload.extend_from_slice(&replacement);
1166        let mut response = placed[..placed.len() - replacement.len() - 4].to_vec();
1167        response.extend_from_slice(&(payload.len() as u32).to_le_bytes());
1168        response.extend_from_slice(&payload);
1169        handler.pending_requests.insert(
1170            request_id.clone(),
1171            BinanceSpotWsTradingRequestMeta::CancelReplaceOrder,
1172        );
1173
1174        let decoded = handler.decode_ws_api_response(&response).unwrap();
1175
1176        let BinanceSpotWsTradingMessage::CancelReplaceAccepted {
1177            request_id: actual_id,
1178            cancel_response,
1179            new_order_response,
1180        } = decoded
1181        else {
1182            panic!("Expected cancel-replace acceptance");
1183        };
1184        assert_eq!(actual_id, request_id);
1185        assert_eq!(cancel_response, expected_cancel);
1186        assert_eq!(new_order_response, expected_new);
1187        assert!(handler.pending_requests.is_empty());
1188    }
1189
1190    #[rstest]
1191    fn test_mainnet_order_responses_match_generated_decoders() {
1192        let (_cmd_tx, cmd_rx) = tokio::sync::mpsc::unbounded_channel();
1193        let (_raw_tx, raw_rx) = tokio::sync::mpsc::unbounded_channel();
1194        let (out_tx, _out_rx) = tokio::sync::mpsc::unbounded_channel();
1195        let handler = BinanceSpotWsTradingHandler::new(
1196            Arc::new(AtomicBool::new(false)),
1197            cmd_rx,
1198            raw_rx,
1199            out_tx,
1200            Arc::new(SigningCredential::new(
1201                "api-key".to_string(),
1202                "secret".to_string(),
1203            )),
1204        );
1205        let placed = include_bytes!(
1206            "../../../../test_data/spot/user_data_sbe/mainnet/web_socket_response_1.sbe"
1207        );
1208        let canceled = include_bytes!(
1209            "../../../../test_data/spot/user_data_sbe/mainnet/web_socket_response_2.sbe"
1210        );
1211        let (_, _, replacement) = handler.parse_envelope(placed).unwrap();
1212        let (_, _, cancellation) = handler.parse_envelope(canceled).unwrap();
1213        let placed_header = message_header_codec::MessageHeaderDecoder::default()
1214            .wrap(ReadBuf::new(&replacement), 0);
1215        let placed_decoder = NewOrderFullResponseDecoder::default().header(placed_header, 0);
1216        let canceled_header = message_header_codec::MessageHeaderDecoder::default()
1217            .wrap(ReadBuf::new(&cancellation), 0);
1218        let canceled_decoder = CancelOrderResponseDecoder::default().header(canceled_header, 0);
1219
1220        let new_order = parse::decode_new_order_full(&replacement).unwrap();
1221        let cancel = parse::decode_cancel_order(&cancellation).unwrap();
1222
1223        assert_eq!(
1224            new_order.self_trade_prevention_mode,
1225            placed_decoder.self_trade_prevention_mode()
1226        );
1227        assert_eq!(new_order.working_time, placed_decoder.working_time());
1228        assert_eq!(new_order.stop_price_mantissa, placed_decoder.stop_price());
1229        assert_eq!(
1230            cancel.self_trade_prevention_mode,
1231            canceled_decoder.self_trade_prevention_mode()
1232        );
1233        assert_eq!(
1234            cancel.self_trade_prevention_mode,
1235            SelfTradePreventionMode::ExpireMaker
1236        );
1237    }
1238
1239    #[rstest]
1240    #[case::missing(None)]
1241    #[case::overflow(Some(i64::MAX))]
1242    fn test_json_error_without_valid_code_is_ambiguous(#[case] code: Option<i64>) {
1243        let (_cmd_tx, cmd_rx) = tokio::sync::mpsc::unbounded_channel();
1244        let (_raw_tx, raw_rx) = tokio::sync::mpsc::unbounded_channel();
1245        let (out_tx, mut out_rx) = tokio::sync::mpsc::unbounded_channel();
1246        let mut handler = BinanceSpotWsTradingHandler::new(
1247            Arc::new(AtomicBool::new(false)),
1248            cmd_rx,
1249            raw_rx,
1250            out_tx,
1251            Arc::new(SigningCredential::new(
1252                "test-key".to_string(),
1253                "test-secret".to_string(),
1254            )),
1255        );
1256        handler.pending_requests.insert(
1257            "order-1".to_string(),
1258            BinanceSpotWsTradingRequestMeta::PlaceOrder,
1259        );
1260        let response = serde_json::json!({"id": "order-1", "status": 400, "error": {"code": code, "msg": "invalid request"}});
1261
1262        handler.handle_text_response(&response.to_string());
1263
1264        let BinanceSpotWsTradingMessage::RequestFailed { request_id, msg } =
1265            out_rx.try_recv().unwrap()
1266        else {
1267            panic!("expected ambiguous request failure");
1268        };
1269        assert_eq!(request_id, "order-1");
1270        assert_eq!(msg, "Missing or invalid venue error code: invalid request");
1271        assert!(handler.pending_requests.is_empty());
1272        assert!(out_rx.try_recv().is_err());
1273    }
1274
1275    #[rstest]
1276    #[case::microseconds_converted_to_ms(1_700_000_000_000_000_i64, 1_700_000_000_000_i64)]
1277    #[case::zero(0_i64, 0_i64)]
1278    #[case::negative(-1_000_i64, -1_i64)]
1279    fn test_parse_server_shutdown_event_time_ms(
1280        #[case] event_time_us: i64,
1281        #[case] expected_ms: i64,
1282    ) {
1283        let mut buf = vec![0u8; message_header_codec::ENCODED_LENGTH];
1284        buf.extend_from_slice(&event_time_us.to_le_bytes());
1285        assert_eq!(parse_server_shutdown_event_time_ms(&buf), expected_ms);
1286    }
1287
1288    #[rstest]
1289    fn test_parse_server_shutdown_event_time_ms_short_buffer_returns_zero() {
1290        let buf = vec![0u8; message_header_codec::ENCODED_LENGTH + 4];
1291        assert_eq!(parse_server_shutdown_event_time_ms(&buf), 0);
1292    }
1293
1294    #[rstest]
1295    fn test_classify_user_data_event_server_shutdown_emits_variant() {
1296        let event = serde_json::json!({"e": "serverShutdown", "E": 1_700_000_000_000_i64});
1297        let msg = classify_user_data_event(&event).expect("expected ServerShutdown");
1298        match msg {
1299            BinanceSpotWsTradingMessage::ServerShutdown { event_time } => {
1300                assert_eq!(event_time, 1_700_000_000_000);
1301            }
1302            other => panic!("expected ServerShutdown variant, was {other:?}"),
1303        }
1304    }
1305
1306    #[rstest]
1307    fn test_classify_user_data_event_server_shutdown_missing_event_time_defaults_to_zero() {
1308        let event = serde_json::json!({"e": "serverShutdown"});
1309        let msg = classify_user_data_event(&event).expect("expected ServerShutdown");
1310        match msg {
1311            BinanceSpotWsTradingMessage::ServerShutdown { event_time } => {
1312                assert_eq!(event_time, 0);
1313            }
1314            other => panic!("expected ServerShutdown variant, was {other:?}"),
1315        }
1316    }
1317
1318    #[rstest]
1319    fn test_classify_user_data_event_unknown_returns_none() {
1320        let event = serde_json::json!({"e": "somethingElse"});
1321        assert!(classify_user_data_event(&event).is_none());
1322    }
1323
1324    #[rstest]
1325    fn test_sign_params_includes_recv_window_in_signature() {
1326        let (_cmd_tx, cmd_rx) = tokio::sync::mpsc::unbounded_channel();
1327        let (_raw_tx, raw_rx) = tokio::sync::mpsc::unbounded_channel();
1328        let (out_tx, _out_rx) = tokio::sync::mpsc::unbounded_channel();
1329        let credential = Arc::new(SigningCredential::new(
1330            "api-key".to_string(),
1331            "hmac-secret".to_string(),
1332        ));
1333        let handler = BinanceSpotWsTradingHandler::new(
1334            Arc::new(AtomicBool::new(false)),
1335            cmd_rx,
1336            raw_rx,
1337            out_tx,
1338            credential.clone(),
1339        )
1340        .with_recv_window(Some(45_000));
1341
1342        let signed = handler
1343            .sign_params(serde_json::json!({"symbol": "BTCUSDT"}))
1344            .unwrap();
1345        let mut unsigned = signed.clone();
1346        let signature = unsigned
1347            .as_object_mut()
1348            .unwrap()
1349            .remove("signature")
1350            .unwrap();
1351        let query = canonical_ws_query_string(
1352            unsigned
1353                .as_object()
1354                .unwrap()
1355                .iter()
1356                .map(|(key, value)| (key.as_str(), value)),
1357        )
1358        .unwrap();
1359
1360        assert_eq!(signed["recvWindow"], 45_000);
1361        assert_eq!(signature, credential.sign(&query));
1362    }
1363}