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_or_default(|v| v.to_string());
531                        log::debug!("User data stream subscribed: id={subscription_id}");
532                        self.emit(BinanceSpotWsTradingMessage::UserDataSubscribed {
533                            subscription_id,
534                        });
535                    }
536                    _ => {
537                        // Order operation responses come as SBE binary, not JSON text.
538                        // If we get a JSON success for an order operation, log it.
539                        log::debug!("Unexpected JSON success for request {id_str}");
540                    }
541                }
542                return;
543            }
544
545            // Error response without matching pending request
546            if let Some(code) = json.get("code").and_then(|v| v.as_i64()) {
547                let msg = json
548                    .get("msg")
549                    .and_then(|v| v.as_str())
550                    .unwrap_or("Unknown error");
551                log::warn!(
552                    "Received error response without matching request ID: code={code} msg={msg}"
553                );
554            }
555            return;
556        }
557
558        // Stream termination event
559        if json.get("eventStreamTerminated").is_some() {
560            log::warn!("User data stream terminated, resubscribe needed");
561            return;
562        }
563
564        log::debug!("Unhandled text message: {} bytes", text.len());
565    }
566
567    fn handle_user_data_event(&self, event: &serde_json::Value) {
568        if let Some(msg) = classify_user_data_event(event) {
569            self.emit(msg);
570        }
571    }
572
573    fn decode_ws_api_response(
574        &mut self,
575        data: &[u8],
576    ) -> Result<BinanceSpotWsTradingMessage, BinanceWsApiError> {
577        // Check template ID before parsing
578        if data.len() >= message_header_codec::ENCODED_LENGTH {
579            let buf = ReadBuf::new(data);
580            let template_id = buf.get_u16_at(2);
581
582            // User data stream events arrive as SBE with their own template IDs
583            // (not wrapped in WebSocketResponse template 50).
584            match template_id {
585                601 => {
586                    log::debug!("Received SBE BalanceUpdateEvent ({} bytes)", data.len());
587                    match super::decode_sbe::decode_balance_update(data) {
588                        Ok(msg) => {
589                            log::debug!(
590                                "SBE balance update: asset={}, delta={}",
591                                msg.asset,
592                                msg.delta
593                            );
594                            return Ok(BinanceSpotWsTradingMessage::BalanceUpdate(msg));
595                        }
596                        Err(e) => {
597                            log::error!("Failed to decode SBE BalanceUpdateEvent: {e}");
598                            return Ok(BinanceSpotWsTradingMessage::Error(format!(
599                                "SBE BalanceUpdateEvent decode failed: {e}"
600                            )));
601                        }
602                    }
603                }
604                603 => {
605                    log::debug!("Received SBE ExecutionReportEvent ({} bytes)", data.len());
606                    match super::decode_sbe::decode_execution_report(data) {
607                        Ok(report) => {
608                            log::debug!(
609                                "SBE execution report: symbol={}, order_id={}, exec={:?}, status={:?}",
610                                report.symbol,
611                                report.order_id,
612                                report.execution_type,
613                                report.order_status
614                            );
615                            return Ok(BinanceSpotWsTradingMessage::ExecutionReport(Box::new(
616                                report,
617                            )));
618                        }
619                        Err(e) => {
620                            log::error!("Failed to decode SBE ExecutionReportEvent: {e}");
621                            return Ok(BinanceSpotWsTradingMessage::Error(format!(
622                                "SBE ExecutionReportEvent decode failed: {e}"
623                            )));
624                        }
625                    }
626                }
627                606 => {
628                    return Ok(match super::decode_sbe::decode_list_status(data) {
629                        Ok(status) => BinanceSpotWsTradingMessage::ListStatus(status),
630                        Err(e) => BinanceSpotWsTradingMessage::Error(format!(
631                            "SBE ListStatusEvent decode failed: {e}"
632                        )),
633                    });
634                }
635                607 => {
636                    log::debug!(
637                        "Received SBE OutboundAccountPositionEvent ({} bytes)",
638                        data.len()
639                    );
640
641                    match super::decode_sbe::decode_account_position(data) {
642                        Ok(msg) => {
643                            log::debug!("SBE account position: {} balance(s)", msg.balances.len());
644                            return Ok(BinanceSpotWsTradingMessage::AccountPosition(msg));
645                        }
646                        Err(e) => {
647                            log::error!("Failed to decode SBE OutboundAccountPositionEvent: {e}");
648                            return Ok(BinanceSpotWsTradingMessage::Error(format!(
649                                "SBE OutboundAccountPositionEvent decode failed: {e}"
650                            )));
651                        }
652                    }
653                }
654                610 => {
655                    let event_time = parse_server_shutdown_event_time_ms(data);
656                    return Ok(BinanceSpotWsTradingMessage::ServerShutdown { event_time });
657                }
658                _ => {} // Fall through to WebSocketResponse parsing
659            }
660        }
661
662        // Standard WebSocketResponse envelope (template 50)
663        let (request_id, status, result_data) = self.parse_envelope(data)?;
664
665        // Look up the pending request by ID
666        let meta = self.pending_requests.remove(&request_id).ok_or_else(|| {
667            BinanceWsApiError::UnknownRequestId(format!("No pending request for ID: {request_id}"))
668        })?;
669
670        // Check for error status (non-200)
671        if status != 200 {
672            return Ok(match Self::try_decode_sbe_error(&result_data) {
673                Some((code, msg)) => self.create_rejection(request_id, status, code, msg, meta),
674                // An undecodable error payload carries no definitive command evidence
675                None => BinanceSpotWsTradingMessage::RequestFailed {
676                    request_id,
677                    msg: format!("Request failed with status {status}; error payload undecodable"),
678                },
679            });
680        }
681
682        // Decode the inner payload based on request type
683        match meta {
684            BinanceSpotWsTradingRequestMeta::PlaceOrder => {
685                let response = parse::decode_new_order_full(&result_data)?;
686                Ok(BinanceSpotWsTradingMessage::OrderAccepted {
687                    request_id,
688                    response,
689                })
690            }
691            BinanceSpotWsTradingRequestMeta::CancelOrder => {
692                Self::decode_cancel_order(request_id, &result_data)
693            }
694            BinanceSpotWsTradingRequestMeta::CancelReplaceOrder => {
695                let (cancel_response, new_order_response) =
696                    parse::decode_cancel_replace_orders(&result_data)?;
697                Ok(BinanceSpotWsTradingMessage::CancelReplaceAccepted {
698                    request_id,
699                    cancel_response,
700                    new_order_response,
701                })
702            }
703            BinanceSpotWsTradingRequestMeta::CancelAllOrders => {
704                let responses = parse::decode_cancel_open_orders(&result_data)?;
705                Ok(BinanceSpotWsTradingMessage::AllOrdersCanceled {
706                    request_id,
707                    responses,
708                })
709            }
710            BinanceSpotWsTradingRequestMeta::SessionLogon => {
711                log::debug!("Session authenticated (SBE response)");
712                Ok(BinanceSpotWsTradingMessage::Authenticated)
713            }
714            BinanceSpotWsTradingRequestMeta::SubscribeUserData => {
715                log::debug!("User data stream subscribed (SBE response)");
716                Ok(BinanceSpotWsTradingMessage::UserDataSubscribed {
717                    subscription_id: request_id,
718                })
719            }
720        }
721    }
722
723    fn decode_cancel_order(
724        request_id: String,
725        result_data: &[u8],
726    ) -> Result<BinanceSpotWsTradingMessage, BinanceWsApiError> {
727        match parse::decode_cancel_order_or_list(result_data)? {
728            BinanceCancelOpenOrdersResponse::Order(response) => {
729                Ok(BinanceSpotWsTradingMessage::OrderCanceled {
730                    request_id,
731                    response,
732                })
733            }
734            response @ BinanceCancelOpenOrdersResponse::OrderList(_) => {
735                Ok(BinanceSpotWsTradingMessage::AllOrdersCanceled {
736                    request_id,
737                    responses: vec![response],
738                })
739            }
740        }
741    }
742
743    /// Parses the WebSocketResponse SBE envelope.
744    ///
745    /// Returns (request_id, status, result_payload).
746    fn parse_envelope(&self, data: &[u8]) -> Result<(String, u16, Vec<u8>), BinanceWsApiError> {
747        if data.len() < message_header_codec::ENCODED_LENGTH {
748            return Err(BinanceWsApiError::DecodeError(
749                crate::spot::sbe::error::SbeDecodeError::BufferTooShort {
750                    expected: message_header_codec::ENCODED_LENGTH,
751                    actual: data.len(),
752                },
753            ));
754        }
755
756        let buf = ReadBuf::new(data);
757
758        // Parse message header
759        let block_length = buf.get_u16_at(0);
760        let template_id = buf.get_u16_at(2);
761
762        if template_id != SBE_TEMPLATE_ID {
763            return Err(BinanceWsApiError::DecodeError(
764                crate::spot::sbe::error::SbeDecodeError::UnknownTemplateId(template_id),
765            ));
766        }
767
768        let version = buf.get_u16_at(6);
769
770        // Create decoder at offset after message header
771        let decoder = WebSocketResponseDecoder::default().wrap(
772            buf,
773            message_header_codec::ENCODED_LENGTH,
774            block_length,
775            version,
776        );
777
778        // Read status from fixed block (offset 1 within block)
779        let status = decoder.status();
780
781        // Skip rate_limits group
782        let mut rate_limits = decoder.rate_limits_decoder();
783        while rate_limits.advance().unwrap_or(None).is_some() {}
784        let mut decoder = rate_limits.parent().map_err(|e| {
785            BinanceWsApiError::ClientError(format!("Failed to get parent from rate_limits: {e}"))
786        })?;
787
788        // Extract request ID
789        let id_coords = decoder.id_decoder();
790        let id_bytes = decoder.id_slice(id_coords);
791        let request_id = String::from_utf8_lossy(id_bytes).to_string();
792
793        // Extract result payload - copy to owned Vec to avoid lifetime issues
794        let result_coords = decoder.result_decoder();
795        let result_data = decoder.result_slice(result_coords).to_vec();
796
797        Ok((request_id, status, result_data))
798    }
799
800    fn create_rejection(
801        &self,
802        request_id: String,
803        status: u16,
804        code: i32,
805        msg: String,
806        meta: BinanceSpotWsTradingRequestMeta,
807    ) -> BinanceSpotWsTradingMessage {
808        match meta {
809            BinanceSpotWsTradingRequestMeta::PlaceOrder => {
810                BinanceSpotWsTradingMessage::OrderRejected {
811                    request_id,
812                    status,
813                    code,
814                    msg,
815                }
816            }
817            BinanceSpotWsTradingRequestMeta::CancelOrder => {
818                BinanceSpotWsTradingMessage::CancelRejected {
819                    request_id,
820                    status,
821                    code,
822                    msg,
823                }
824            }
825            BinanceSpotWsTradingRequestMeta::CancelReplaceOrder => {
826                BinanceSpotWsTradingMessage::CancelReplaceRejected {
827                    request_id,
828                    status,
829                    code,
830                    msg,
831                }
832            }
833            BinanceSpotWsTradingRequestMeta::CancelAllOrders => {
834                BinanceSpotWsTradingMessage::CancelRejected {
835                    request_id,
836                    status,
837                    code,
838                    msg,
839                }
840            }
841            BinanceSpotWsTradingRequestMeta::SessionLogon => {
842                BinanceSpotWsTradingMessage::AuthenticationRejected(format!("code={code}: {msg}"))
843            }
844            BinanceSpotWsTradingRequestMeta::SubscribeUserData => {
845                BinanceSpotWsTradingMessage::UserDataSubscriptionRejected(format!(
846                    "code={code}: {msg}"
847                ))
848            }
849        }
850    }
851
852    // Decodes the SBE error response to extract the Binance error code and message
853    fn try_decode_sbe_error(data: &[u8]) -> Option<(i32, String)> {
854        const HEADER_LEN: usize = 8;
855
856        if data.len()
857            < HEADER_LEN + crate::spot::sbe::spot::error_response_codec::SBE_BLOCK_LENGTH as usize
858        {
859            return None;
860        }
861
862        let buf = ReadBuf::new(data);
863        let header = message_header_codec::MessageHeaderDecoder::default().wrap(buf, 0);
864        if header.template_id() != crate::spot::sbe::spot::error_response_codec::SBE_TEMPLATE_ID {
865            return None;
866        }
867
868        let mut decoder = ErrorResponseDecoder::default().header(header, 0);
869        let code = i32::from(decoder.code());
870        let msg_coords = decoder.msg_decoder();
871        let msg_bytes = decoder.msg_slice(msg_coords);
872        let msg = String::from_utf8_lossy(msg_bytes).into_owned();
873
874        Some((code, msg))
875    }
876}
877
878/// Classifies a JSON user-data event into a trading message, if any.
879///
880/// Returns `None` when the event type is unknown or the payload fails to
881/// deserialize; in that case the caller logs and drops the event.
882pub(crate) fn classify_user_data_event(
883    event: &serde_json::Value,
884) -> Option<BinanceSpotWsTradingMessage> {
885    let event_type = event
886        .get("e")
887        .and_then(|v| serde_json::from_value::<BinanceSpotUserDataEventType>(v.clone()).ok())
888        .unwrap_or(BinanceSpotUserDataEventType::Unknown);
889
890    match event_type {
891        BinanceSpotUserDataEventType::ExecutionReport => {
892            match serde_json::from_value::<super::user_data::BinanceSpotExecutionReport>(
893                event.clone(),
894            ) {
895                Ok(report) => {
896                    log::debug!(
897                        "Execution report: symbol={}, order_id={}, exec={:?}, status={:?}",
898                        report.symbol,
899                        report.order_id,
900                        report.execution_type,
901                        report.order_status
902                    );
903                    Some(BinanceSpotWsTradingMessage::ExecutionReport(Box::new(
904                        report,
905                    )))
906                }
907                Err(e) => {
908                    log::warn!("Failed to parse execution report: {e}");
909                    None
910                }
911            }
912        }
913        BinanceSpotUserDataEventType::OutboundAccountPosition => {
914            match serde_json::from_value::<super::user_data::BinanceSpotAccountPositionMsg>(
915                event.clone(),
916            ) {
917                Ok(msg) => {
918                    log::debug!("Account position update: {} balance(s)", msg.balances.len());
919                    Some(BinanceSpotWsTradingMessage::AccountPosition(msg))
920                }
921                Err(e) => {
922                    log::warn!("Failed to parse account position: {e}");
923                    None
924                }
925            }
926        }
927        BinanceSpotUserDataEventType::BalanceUpdate => {
928            match serde_json::from_value::<super::user_data::BinanceSpotBalanceUpdateMsg>(
929                event.clone(),
930            ) {
931                Ok(msg) => {
932                    log::debug!("Balance update: asset={}, delta={}", msg.asset, msg.delta);
933                    Some(BinanceSpotWsTradingMessage::BalanceUpdate(msg))
934                }
935                Err(e) => {
936                    log::warn!("Failed to parse balance update: {e}");
937                    None
938                }
939            }
940        }
941        BinanceSpotUserDataEventType::ServerShutdown => {
942            let event_time = event.get("E").and_then(|v| v.as_i64()).unwrap_or_default();
943            Some(BinanceSpotWsTradingMessage::ServerShutdown { event_time })
944        }
945        BinanceSpotUserDataEventType::ListenKeyExpired
946        | BinanceSpotUserDataEventType::ExternalLockUpdate
947        | BinanceSpotUserDataEventType::EventStreamTerminated
948        | BinanceSpotUserDataEventType::Unknown => {
949            log::debug!("Unhandled user data event type: {event_type:?}");
950            None
951        }
952    }
953}
954
955/// Parses the `event_time` from an SBE `ServerShutdownEvent` (template 610) frame.
956///
957/// The SBE field is microseconds; the trading message variant documents
958/// milliseconds (matching the JSON dispatch), so this divides by 1_000.
959/// Returns `0` when the buffer is too short to contain the field.
960pub(crate) fn parse_server_shutdown_event_time_ms(data: &[u8]) -> i64 {
961    if data.len() < message_header_codec::ENCODED_LENGTH + 8 {
962        return 0;
963    }
964    let buf = ReadBuf::new(data);
965    buf.get_i64_at(message_header_codec::ENCODED_LENGTH) / 1_000
966}
967
968#[cfg(test)]
969mod tests {
970    use std::time::Duration;
971
972    use futures_util::StreamExt;
973    use nautilus_common::testing::wait_until_async;
974    use nautilus_network::{
975        error::SendError,
976        websocket::{AuthTracker, WebSocketConfig},
977    };
978    use rstest::rstest;
979
980    use super::*;
981    use crate::spot::sbe::spot::{
982        cancel_order_response_codec::CancelOrderResponseDecoder,
983        new_order_full_response_codec::NewOrderFullResponseDecoder,
984        self_trade_prevention_mode::SelfTradePreventionMode,
985    };
986
987    #[tokio::test]
988    async fn test_authentication_with_full_replay_buffer() {
989        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
990        let address = listener.local_addr().unwrap();
991        let (replayed_tx, replayed_rx) = tokio::sync::oneshot::channel();
992
993        let server = tokio::spawn(async move {
994            let (first, _) = listener.accept().await.unwrap();
995            let _first = tokio_tungstenite::accept_async(first).await.unwrap();
996            let (replacement, _) = listener.accept().await.unwrap();
997            let mut replacement = tokio_tungstenite::accept_async(replacement).await.unwrap();
998            let auth = replacement.next().await.unwrap().unwrap();
999            let auth: serde_json::Value = serde_json::from_str(auth.to_text().unwrap()).unwrap();
1000            assert_eq!(auth["method"], method::SESSION_LOGON);
1001            assert_eq!(auth["id"], "ws-1000");
1002            assert_eq!(auth["params"]["apiKey"], "api-key");
1003            let subscribe = replacement.next().await.unwrap().unwrap();
1004            let subscribe: serde_json::Value =
1005                serde_json::from_str(subscribe.to_text().unwrap()).unwrap();
1006            assert_eq!(subscribe["method"], "userDataStream.subscribe");
1007            assert_eq!(subscribe["id"], "ws-1001");
1008            assert_eq!(subscribe["params"], serde_json::json!({}));
1009            assert_eq!(
1010                replacement.next().await.unwrap().unwrap(),
1011                Message::text("held")
1012            );
1013            replayed_tx.send(()).unwrap();
1014            std::future::pending::<()>().await;
1015        });
1016
1017        let tracker = AuthTracker::new();
1018        let (_cmd_tx, cmd_rx) = tokio::sync::mpsc::unbounded_channel();
1019        let (_raw_tx, raw_rx) = tokio::sync::mpsc::unbounded_channel();
1020        let (out_tx, _out_rx) = tokio::sync::mpsc::unbounded_channel();
1021
1022        let mut handler = BinanceSpotWsTradingHandler::new(
1023            Arc::new(AtomicBool::new(false)),
1024            cmd_rx,
1025            raw_rx,
1026            out_tx,
1027            Arc::new(SigningCredential::new(
1028                "api-key".to_string(),
1029                "secret".to_string(),
1030            )),
1031        );
1032        let config = WebSocketConfig::builder()
1033            .url(format!("ws://{address}"))
1034            .writer_capacity(1)
1035            .reconnect_delay_initial_ms(1)
1036            .reconnect_delay_max_ms(1)
1037            .reconnect_jitter_ms(0)
1038            .build()
1039            .unwrap();
1040        let client = WebSocketClient::builder()
1041            .config(config)
1042            .message_handler(Arc::new(|_| {}))
1043            .connect()
1044            .await
1045            .unwrap();
1046        client.set_auth_tracker(tracker.clone(), true);
1047
1048        // Enqueue and request reconnect without yielding so the writer retains this message
1049        client.send_text("held".to_string(), None).await.unwrap();
1050        assert!(client.request_reconnect());
1051        wait_until_async(
1052            || async { client.is_active() && client.connection_epoch() == 1 },
1053            Duration::from_secs(5),
1054        )
1055        .await;
1056        assert!(matches!(
1057            client.send_text("overflow".to_string(), None).await,
1058            Err(SendError::BufferFull)
1059        ));
1060        handler.inner = Some(client);
1061        tokio::time::timeout(Duration::from_secs(5), handler.handle_session_logon())
1062            .await
1063            .unwrap()
1064            .unwrap();
1065        tokio::time::timeout(Duration::from_secs(5), handler.handle_subscribe_user_data())
1066            .await
1067            .unwrap()
1068            .unwrap();
1069        tracker.succeed();
1070        tokio::time::timeout(Duration::from_secs(5), replayed_rx)
1071            .await
1072            .unwrap()
1073            .unwrap();
1074        handler.inner.as_ref().unwrap().disconnect().await;
1075        server.abort();
1076    }
1077
1078    #[rstest]
1079    #[case::valid(false)]
1080    #[case::malformed(true)]
1081    fn test_list_status_routes_typed_message_or_controlled_error(#[case] malformed: bool) {
1082        let (_cmd_tx, cmd_rx) = tokio::sync::mpsc::unbounded_channel();
1083        let (_raw_tx, raw_rx) = tokio::sync::mpsc::unbounded_channel();
1084        let (out_tx, _out_rx) = tokio::sync::mpsc::unbounded_channel();
1085
1086        let mut handler = BinanceSpotWsTradingHandler::new(
1087            Arc::new(AtomicBool::new(false)),
1088            cmd_rx,
1089            raw_rx,
1090            out_tx,
1091            Arc::new(SigningCredential::new(
1092                "api-key".to_owned(),
1093                "secret".to_owned(),
1094            )),
1095        );
1096        let mut data = crate::common::testing::load_fixture_bytes(
1097            "spot/user_data_sbe/list_status_executing.sbe",
1098        );
1099
1100        if malformed {
1101            data.pop();
1102        }
1103
1104        let message = handler.decode_ws_api_response(&data).unwrap();
1105        if malformed {
1106            let BinanceSpotWsTradingMessage::Error(reason) = message else {
1107                panic!("Expected controlled error");
1108            };
1109
1110            assert!(reason.starts_with("SBE ListStatusEvent decode failed:"));
1111        } else {
1112            let BinanceSpotWsTradingMessage::ListStatus(status) = message else {
1113                panic!("Expected typed list status");
1114            };
1115
1116            assert_eq!(
1117                status,
1118                super::super::decode_sbe::decode_list_status(&data).unwrap()
1119            );
1120        }
1121    }
1122
1123    #[rstest]
1124    fn test_cancel_replace_response_decodes_both_orders() {
1125        let (_cmd_tx, cmd_rx) = tokio::sync::mpsc::unbounded_channel();
1126        let (_raw_tx, raw_rx) = tokio::sync::mpsc::unbounded_channel();
1127        let (out_tx, _out_rx) = tokio::sync::mpsc::unbounded_channel();
1128        let mut handler = BinanceSpotWsTradingHandler::new(
1129            Arc::new(AtomicBool::new(false)),
1130            cmd_rx,
1131            raw_rx,
1132            out_tx,
1133            Arc::new(SigningCredential::new(
1134                "api-key".to_string(),
1135                "secret".to_string(),
1136            )),
1137        );
1138        let placed = include_bytes!(
1139            "../../../../test_data/spot/user_data_sbe/mainnet/web_socket_response_1.sbe"
1140        );
1141        let canceled = include_bytes!(
1142            "../../../../test_data/spot/user_data_sbe/mainnet/web_socket_response_2.sbe"
1143        );
1144        let (request_id, _, replacement) = handler.parse_envelope(placed).unwrap();
1145        let (_, _, cancellation) = handler.parse_envelope(canceled).unwrap();
1146        let expected_new = parse::decode_new_order_full(&replacement).unwrap();
1147        let expected_cancel = parse::decode_cancel_order(&cancellation).unwrap();
1148        let mut payload = Vec::new();
1149
1150        for field in [
1151            2_u16,
1152            crate::spot::sbe::spot::cancel_replace_order_response_codec::SBE_TEMPLATE_ID,
1153            crate::spot::sbe::spot::SBE_SCHEMA_ID,
1154            crate::spot::sbe::spot::SBE_SCHEMA_VERSION,
1155        ] {
1156            payload.extend_from_slice(&field.to_le_bytes());
1157        }
1158        let success =
1159            crate::spot::sbe::spot::cancel_replace_status::CancelReplaceStatus::Success as u8;
1160        payload.extend_from_slice(&[success, success]);
1161        payload.extend_from_slice(&(cancellation.len() as u16).to_le_bytes());
1162        payload.extend_from_slice(&cancellation);
1163        payload.extend_from_slice(&(replacement.len() as u32).to_le_bytes());
1164        payload.extend_from_slice(&replacement);
1165        let mut response = placed[..placed.len() - replacement.len() - 4].to_vec();
1166        response.extend_from_slice(&(payload.len() as u32).to_le_bytes());
1167        response.extend_from_slice(&payload);
1168        handler.pending_requests.insert(
1169            request_id.clone(),
1170            BinanceSpotWsTradingRequestMeta::CancelReplaceOrder,
1171        );
1172
1173        let decoded = handler.decode_ws_api_response(&response).unwrap();
1174
1175        let BinanceSpotWsTradingMessage::CancelReplaceAccepted {
1176            request_id: actual_id,
1177            cancel_response,
1178            new_order_response,
1179        } = decoded
1180        else {
1181            panic!("Expected cancel-replace acceptance");
1182        };
1183        assert_eq!(actual_id, request_id);
1184        assert_eq!(cancel_response, expected_cancel);
1185        assert_eq!(new_order_response, expected_new);
1186        assert!(handler.pending_requests.is_empty());
1187    }
1188
1189    #[rstest]
1190    fn test_mainnet_order_responses_match_generated_decoders() {
1191        let (_cmd_tx, cmd_rx) = tokio::sync::mpsc::unbounded_channel();
1192        let (_raw_tx, raw_rx) = tokio::sync::mpsc::unbounded_channel();
1193        let (out_tx, _out_rx) = tokio::sync::mpsc::unbounded_channel();
1194        let handler = BinanceSpotWsTradingHandler::new(
1195            Arc::new(AtomicBool::new(false)),
1196            cmd_rx,
1197            raw_rx,
1198            out_tx,
1199            Arc::new(SigningCredential::new(
1200                "api-key".to_string(),
1201                "secret".to_string(),
1202            )),
1203        );
1204        let placed = include_bytes!(
1205            "../../../../test_data/spot/user_data_sbe/mainnet/web_socket_response_1.sbe"
1206        );
1207        let canceled = include_bytes!(
1208            "../../../../test_data/spot/user_data_sbe/mainnet/web_socket_response_2.sbe"
1209        );
1210        let (_, _, replacement) = handler.parse_envelope(placed).unwrap();
1211        let (_, _, cancellation) = handler.parse_envelope(canceled).unwrap();
1212        let placed_header = message_header_codec::MessageHeaderDecoder::default()
1213            .wrap(ReadBuf::new(&replacement), 0);
1214        let placed_decoder = NewOrderFullResponseDecoder::default().header(placed_header, 0);
1215        let canceled_header = message_header_codec::MessageHeaderDecoder::default()
1216            .wrap(ReadBuf::new(&cancellation), 0);
1217        let canceled_decoder = CancelOrderResponseDecoder::default().header(canceled_header, 0);
1218
1219        let new_order = parse::decode_new_order_full(&replacement).unwrap();
1220        let cancel = parse::decode_cancel_order(&cancellation).unwrap();
1221
1222        assert_eq!(
1223            new_order.self_trade_prevention_mode,
1224            placed_decoder.self_trade_prevention_mode()
1225        );
1226        assert_eq!(new_order.working_time, placed_decoder.working_time());
1227        assert_eq!(new_order.stop_price_mantissa, placed_decoder.stop_price());
1228        assert_eq!(
1229            cancel.self_trade_prevention_mode,
1230            canceled_decoder.self_trade_prevention_mode()
1231        );
1232        assert_eq!(
1233            cancel.self_trade_prevention_mode,
1234            SelfTradePreventionMode::ExpireMaker
1235        );
1236    }
1237
1238    #[rstest]
1239    #[case::missing(None)]
1240    #[case::overflow(Some(i64::MAX))]
1241    fn test_json_error_without_valid_code_is_ambiguous(#[case] code: Option<i64>) {
1242        let (_cmd_tx, cmd_rx) = tokio::sync::mpsc::unbounded_channel();
1243        let (_raw_tx, raw_rx) = tokio::sync::mpsc::unbounded_channel();
1244        let (out_tx, mut out_rx) = tokio::sync::mpsc::unbounded_channel();
1245        let mut handler = BinanceSpotWsTradingHandler::new(
1246            Arc::new(AtomicBool::new(false)),
1247            cmd_rx,
1248            raw_rx,
1249            out_tx,
1250            Arc::new(SigningCredential::new(
1251                "test-key".to_string(),
1252                "test-secret".to_string(),
1253            )),
1254        );
1255        handler.pending_requests.insert(
1256            "order-1".to_string(),
1257            BinanceSpotWsTradingRequestMeta::PlaceOrder,
1258        );
1259        let response = serde_json::json!({"id": "order-1", "status": 400, "error": {"code": code, "msg": "invalid request"}});
1260
1261        handler.handle_text_response(&response.to_string());
1262
1263        let BinanceSpotWsTradingMessage::RequestFailed { request_id, msg } =
1264            out_rx.try_recv().unwrap()
1265        else {
1266            panic!("expected ambiguous request failure");
1267        };
1268        assert_eq!(request_id, "order-1");
1269        assert_eq!(msg, "Missing or invalid venue error code: invalid request");
1270        assert!(handler.pending_requests.is_empty());
1271        assert!(out_rx.try_recv().is_err());
1272    }
1273
1274    #[rstest]
1275    #[case::microseconds_converted_to_ms(1_700_000_000_000_000_i64, 1_700_000_000_000_i64)]
1276    #[case::zero(0_i64, 0_i64)]
1277    #[case::negative(-1_000_i64, -1_i64)]
1278    fn test_parse_server_shutdown_event_time_ms(
1279        #[case] event_time_us: i64,
1280        #[case] expected_ms: i64,
1281    ) {
1282        let mut buf = vec![0u8; message_header_codec::ENCODED_LENGTH];
1283        buf.extend_from_slice(&event_time_us.to_le_bytes());
1284        assert_eq!(parse_server_shutdown_event_time_ms(&buf), expected_ms);
1285    }
1286
1287    #[rstest]
1288    fn test_parse_server_shutdown_event_time_ms_short_buffer_returns_zero() {
1289        let buf = vec![0u8; message_header_codec::ENCODED_LENGTH + 4];
1290        assert_eq!(parse_server_shutdown_event_time_ms(&buf), 0);
1291    }
1292
1293    #[rstest]
1294    fn test_classify_user_data_event_server_shutdown_emits_variant() {
1295        let event = serde_json::json!({"e": "serverShutdown", "E": 1_700_000_000_000_i64});
1296        let msg = classify_user_data_event(&event).expect("expected ServerShutdown");
1297        match msg {
1298            BinanceSpotWsTradingMessage::ServerShutdown { event_time } => {
1299                assert_eq!(event_time, 1_700_000_000_000);
1300            }
1301            other => panic!("expected ServerShutdown variant, was {other:?}"),
1302        }
1303    }
1304
1305    #[rstest]
1306    fn test_classify_user_data_event_server_shutdown_missing_event_time_defaults_to_zero() {
1307        let event = serde_json::json!({"e": "serverShutdown"});
1308        let msg = classify_user_data_event(&event).expect("expected ServerShutdown");
1309        match msg {
1310            BinanceSpotWsTradingMessage::ServerShutdown { event_time } => {
1311                assert_eq!(event_time, 0);
1312            }
1313            other => panic!("expected ServerShutdown variant, was {other:?}"),
1314        }
1315    }
1316
1317    #[rstest]
1318    fn test_classify_user_data_event_unknown_returns_none() {
1319        let event = serde_json::json!({"e": "somethingElse"});
1320        assert!(classify_user_data_event(&event).is_none());
1321    }
1322
1323    #[rstest]
1324    fn test_sign_params_includes_recv_window_in_signature() {
1325        let (_cmd_tx, cmd_rx) = tokio::sync::mpsc::unbounded_channel();
1326        let (_raw_tx, raw_rx) = tokio::sync::mpsc::unbounded_channel();
1327        let (out_tx, _out_rx) = tokio::sync::mpsc::unbounded_channel();
1328        let credential = Arc::new(SigningCredential::new(
1329            "api-key".to_string(),
1330            "hmac-secret".to_string(),
1331        ));
1332        let handler = BinanceSpotWsTradingHandler::new(
1333            Arc::new(AtomicBool::new(false)),
1334            cmd_rx,
1335            raw_rx,
1336            out_tx,
1337            credential.clone(),
1338        )
1339        .with_recv_window(Some(45_000));
1340
1341        let signed = handler
1342            .sign_params(serde_json::json!({"symbol": "BTCUSDT"}))
1343            .unwrap();
1344        let mut unsigned = signed.clone();
1345        let signature = unsigned
1346            .as_object_mut()
1347            .unwrap()
1348            .remove("signature")
1349            .unwrap();
1350        let query = canonical_ws_query_string(
1351            unsigned
1352                .as_object()
1353                .unwrap()
1354                .iter()
1355                .map(|(key, value)| (key.as_str(), value)),
1356        )
1357        .unwrap();
1358
1359        assert_eq!(signed["recvWindow"], 45_000);
1360        assert_eq!(signature, credential.sign(&query));
1361    }
1362}