1use 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
63pub 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 #[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 #[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 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 self.fail_pending_requests();
213
214 self.emit(BinanceSpotWsTradingMessage::Reconnected);
215 continue;
216 }
217
218 self.handle_message(msg);
219 }
220 else => {
221 return false;
223 }
224 }
225 }
226 }
227
228 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 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(¶ms)
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(¶ms)
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(¶ms)
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 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 if let Some(event) = json.get("event") {
457 self.handle_user_data_event(event);
458 return;
459 }
460
461 if json.get("e").is_some() {
463 self.handle_user_data_event(&json);
464 return;
465 }
466
467 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 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 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 log::debug!("Unexpected JSON success for request {id_str}");
540 }
541 }
542 return;
543 }
544
545 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 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 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 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 _ => {} }
660 }
661
662 let (request_id, status, result_data) = self.parse_envelope(data)?;
664
665 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 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 None => BinanceSpotWsTradingMessage::RequestFailed {
676 request_id,
677 msg: format!("Request failed with status {status}; error payload undecodable"),
678 },
679 });
680 }
681
682 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 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 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 let decoder = WebSocketResponseDecoder::default().wrap(
772 buf,
773 message_header_codec::ENCODED_LENGTH,
774 block_length,
775 version,
776 );
777
778 let status = decoder.status();
780
781 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 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 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 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
878pub(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
955pub(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 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}