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