Skip to main content

nautilus_betfair/http/
client.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//! Betfair HTTP client implementation.
17
18use std::{
19    collections::HashMap,
20    num::NonZeroU32,
21    sync::{
22        Arc,
23        atomic::{AtomicBool, AtomicU64, Ordering},
24    },
25};
26
27use http::HeaderValue;
28use nautilus_core::string::{secret::SecretString, urlencoding};
29use nautilus_network::{
30    http::{HttpClient, HttpRedirectPolicy, Method, create_standard_nautilus_headers},
31    ratelimiter::quota::Quota,
32    retry::{RetryConfig, RetryError, RetryManager},
33};
34use serde::{Deserialize, Serialize, de::DeserializeOwned};
35use tokio_util::sync::CancellationToken;
36use zeroize::Zeroizing;
37
38use super::{
39    error::BetfairHttpError,
40    models::{CertLoginResponse, LoginResponse, LoginStatus},
41};
42use crate::common::{
43    consts::{
44        BETFAIR_ACCOUNTS_URL, BETFAIR_BETTING_URL, BETFAIR_CERT_LOGIN_URL,
45        BETFAIR_IDENTITY_LOGIN_URL, BETFAIR_KEEP_ALIVE_URL, BETFAIR_NAVIGATION_URL,
46        BETFAIR_RATE_LIMIT_DEFAULT, BETFAIR_RATE_LIMIT_ORDERS, HEADER_X_APPLICATION,
47        HEADER_X_AUTHENTICATION,
48    },
49    credential::BetfairCredential,
50    enums::CertLoginStatus,
51};
52
53// Keep the final dispatch 15 seconds inside Betfair's 60-second customerRef window
54const ORDER_RETRY_MAX_ELAPSED_MS: u64 = 45_000;
55
56/// Betfair JSON-RPC request envelope.
57#[derive(Debug, Serialize)]
58struct JsonRpcRequest<P: Serialize> {
59    jsonrpc: &'static str,
60    method: String,
61    params: P,
62    id: u64,
63}
64
65/// Betfair JSON-RPC response envelope.
66#[derive(Debug, Deserialize)]
67struct JsonRpcResponse<T> {
68    result: Option<T>,
69    error: Option<JsonRpcError>,
70}
71
72/// JSON-RPC error object.
73#[derive(Debug, Deserialize)]
74struct JsonRpcError {
75    code: i64,
76    message: String,
77    data: Option<serde_json::Value>,
78}
79
80#[derive(Debug, Deserialize)]
81#[serde(rename_all = "camelCase")]
82struct JsonRpcApiException {
83    error_code: String,
84    error_details: Option<String>,
85}
86
87impl JsonRpcError {
88    fn api_exception(&self) -> Option<JsonRpcApiException> {
89        let data = self.data.as_ref()?;
90        let exception_name = data.get("exceptionname")?.as_str()?;
91        serde_json::from_value(data.get(exception_name)?.clone()).ok()
92    }
93}
94
95/// Betfair HTTP client for raw API operations.
96///
97/// Handles session-token authentication, JSON-RPC protocol, form-encoded
98/// identity requests, REST navigation, rate limiting, and retry logic.
99#[derive(Debug)]
100pub struct BetfairHttpClient {
101    client: HttpClient,
102    credential: BetfairCredential,
103    session_token: Arc<tokio::sync::RwLock<Option<SecretString>>>,
104    retry_manager: RetryManager<BetfairHttpError>,
105    order_retry_manager: RetryManager<BetfairHttpError>,
106    cancellation_token: parking_lot::Mutex<CancellationToken>,
107    connect_lock: tokio::sync::Mutex<()>,
108    request_id: AtomicU64,
109    url_identity_login: String,
110    url_keep_alive: String,
111    url_betting: String,
112    url_accounts: String,
113    url_navigation: String,
114    url_cert_login: String,
115}
116
117impl BetfairHttpClient {
118    /// Creates a new [`BetfairHttpClient`].
119    ///
120    /// # Errors
121    ///
122    /// Returns an error if the HTTP client cannot be created.
123    pub fn new(
124        credential: BetfairCredential,
125        timeout_secs: Option<u64>,
126        max_retries: Option<u32>,
127        retry_delay_ms: Option<u64>,
128        proxy_url: Option<String>,
129        request_rate_per_second: Option<u32>,
130        order_request_rate_per_second: Option<u32>,
131    ) -> Result<Self, BetfairHttpError> {
132        let retry_config = RetryConfig {
133            max_retries: max_retries.unwrap_or(3),
134            initial_delay_ms: retry_delay_ms.unwrap_or(1000),
135            max_delay_ms: 10_000,
136            backoff_factor: 2.0,
137            jitter_ms: 500,
138            operation_timeout_ms: Some(30_000),
139            immediate_first: false,
140            max_elapsed_ms: Some(120_000),
141        };
142        let order_retry_config = RetryConfig {
143            max_elapsed_ms: Some(ORDER_RETRY_MAX_ELAPSED_MS),
144            ..retry_config
145        };
146
147        Ok(Self {
148            client: HttpClient::builder()
149                .redirect_policy(HttpRedirectPolicy::Reject)
150                .headers(create_standard_nautilus_headers().into_iter().collect())
151                .keyed_quotas(Self::rate_limiter_quotas(
152                    request_rate_per_second.unwrap_or(5),
153                    order_request_rate_per_second.unwrap_or(20),
154                )?)
155                .maybe_default_quota(Self::default_quota(request_rate_per_second.unwrap_or(5))?)
156                .maybe_timeout_secs(timeout_secs)
157                .maybe_proxy_url(proxy_url)
158                .maybe_certs_dir(credential.certs_dir().map(str::to_owned))
159                .build()
160                .map_err(|e| anyhow::anyhow!("Failed to create HTTP client: {e}"))?,
161            credential,
162            session_token: Arc::new(tokio::sync::RwLock::new(None)),
163            retry_manager: RetryManager::new(retry_config),
164            order_retry_manager: RetryManager::new(order_retry_config),
165            cancellation_token: parking_lot::Mutex::new(CancellationToken::new()),
166            connect_lock: tokio::sync::Mutex::new(()),
167            request_id: AtomicU64::new(1),
168            url_identity_login: BETFAIR_IDENTITY_LOGIN_URL.to_string(),
169            url_keep_alive: BETFAIR_KEEP_ALIVE_URL.to_string(),
170            url_betting: BETFAIR_BETTING_URL.to_string(),
171            url_accounts: BETFAIR_ACCOUNTS_URL.to_string(),
172            url_navigation: BETFAIR_NAVIGATION_URL.to_string(),
173            url_cert_login: BETFAIR_CERT_LOGIN_URL.to_string(),
174        })
175    }
176
177    /// Overrides the API base URLs (for testing with mock servers).
178    ///
179    /// The certificate login and keep-alive URLs use the same base as `identity_login`,
180    /// with the final path segment replaced by `certlogin` and `keepAlive`.
181    #[must_use]
182    pub fn with_urls(
183        mut self,
184        identity_login: String,
185        betting: String,
186        accounts: String,
187        navigation: String,
188    ) -> Self {
189        // Derive identity URLs from the same base for mock servers
190        if let Some(base) = identity_login.rfind('/') {
191            self.url_keep_alive = format!("{}/keepAlive", &identity_login[..base]);
192            self.url_cert_login = format!("{}/certlogin", &identity_login[..base]);
193        }
194        self.url_identity_login = identity_login;
195        self.url_betting = betting;
196        self.url_accounts = accounts;
197        self.url_navigation = navigation;
198        self
199    }
200
201    /// Returns a clone of the current cancellation token for this client.
202    ///
203    /// `disconnect()` cancels and replaces the token, so callers should fetch
204    /// a fresh clone for each operation rather than holding one long-term.
205    pub fn cancellation_token(&self) -> CancellationToken {
206        self.cancellation_token.lock().clone()
207    }
208
209    /// Returns the current session token, if authenticated.
210    pub async fn session_token(&self) -> Option<SecretString> {
211        self.session_token.read().await.clone()
212    }
213
214    /// Runs a synchronous token publication while session mutation is serialized.
215    pub(crate) async fn with_session_token<T>(
216        &self,
217        publish: impl FnOnce(&SecretString) -> T,
218    ) -> Option<T> {
219        let _guard = self.connect_lock.lock().await;
220        self.session_token.read().await.as_ref().map(publish)
221    }
222
223    /// Returns whether the client has an active session.
224    pub async fn is_connected(&self) -> bool {
225        self.session_token.read().await.is_some()
226    }
227
228    /// Returns the application key.
229    #[must_use]
230    pub fn app_key(&self) -> &str {
231        self.credential.app_key()
232    }
233
234    /// Authenticates with Betfair using certificate login when a certificate directory is set.
235    /// Uses interactive login otherwise.
236    ///
237    /// Sends credentials to the Identity API and stores the returned
238    /// session token for subsequent requests.
239    ///
240    /// # Errors
241    ///
242    /// Returns an error if the login request fails or authentication
243    /// is rejected.
244    pub async fn connect(&self) -> Result<(), BetfairHttpError> {
245        // Serialize session mutations so an older keep-alive response cannot overwrite a newer
246        // full login. This matches Python's per-instance asyncio.Lock around the same path.
247        let _guard = self.connect_lock.lock().await;
248
249        if self.session_token.read().await.is_some() {
250            log::debug!("Session token exists (already connected), skipping");
251            return Ok(());
252        }
253
254        let token = self.login().await?;
255        *self.session_token.write().await = Some(token);
256        Ok(())
257    }
258
259    /// Resets the session and re-authenticates.
260    ///
261    /// # Errors
262    ///
263    /// Returns an error if re-authentication fails.
264    pub async fn reconnect(&self) -> Result<(), BetfairHttpError> {
265        self.reconnect_with_token().await.map(drop)
266    }
267
268    /// Resets the session, re-authenticates, and returns the replacement token.
269    ///
270    /// # Errors
271    ///
272    /// Returns an error if re-authentication fails.
273    pub(crate) async fn reconnect_with_token(&self) -> Result<SecretString, BetfairHttpError> {
274        let _guard = self.connect_lock.lock().await;
275        log::info!("Betfair reconnecting...");
276        *self.session_token.write().await = None;
277        let token = self.login().await?;
278        *self.session_token.write().await = Some(token.clone());
279        Ok(token)
280    }
281
282    async fn login(&self) -> Result<SecretString, BetfairHttpError> {
283        let password = Zeroizing::new(urlencoding::encode(self.credential.password()).into_owned());
284        let form_body = SecretString::from(format!(
285            "username={}&password={}",
286            urlencoding::encode(self.credential.username()),
287            password.as_str(),
288        ));
289
290        if self.credential.certs_dir().is_some() {
291            let resp_bytes = self.send_identity(&self.url_cert_login, form_body).await?;
292            let mut resp: CertLoginResponse = serde_json::from_slice(&resp_bytes)?;
293            if resp.login_status != CertLoginStatus::Success {
294                let response: serde_json::Value = serde_json::from_slice(&resp_bytes)?;
295                let status = response["loginStatus"]
296                    .as_str()
297                    .unwrap_or(resp.login_status.as_ref())
298                    .to_string();
299                return Err(BetfairHttpError::LoginFailed { status });
300            }
301
302            return resp
303                .session_token
304                .take()
305                .filter(|token| {
306                    let value = token.expose_secret();
307                    !value.trim().is_empty() && value.parse::<HeaderValue>().is_ok()
308                })
309                .ok_or_else(|| BetfairHttpError::LoginFailed {
310                    status: "SUCCESS without a valid session token".to_string(),
311                });
312        }
313
314        let resp_bytes = self
315            .send_identity(&self.url_identity_login, form_body)
316            .await?;
317
318        let mut resp: LoginResponse = serde_json::from_slice(&resp_bytes)?;
319
320        if resp.status == LoginStatus::Success {
321            log::debug!("Betfair login successful");
322            Ok(std::mem::take(&mut resp.token))
323        } else {
324            Err(BetfairHttpError::LoginFailed {
325                status: resp
326                    .error
327                    .take()
328                    .unwrap_or_else(|| format!("{:?}", resp.status)),
329            })
330        }
331    }
332
333    /// Clears the session token, cancels any in-flight retries, and primes a
334    /// fresh cancellation token for the next session.
335    pub async fn disconnect(&self) {
336        log::info!("Betfair disconnecting...");
337        let _guard = self.connect_lock.lock().await;
338        {
339            let mut guard = self.cancellation_token.lock();
340            guard.cancel();
341            *guard = CancellationToken::new();
342        }
343        *self.session_token.write().await = None;
344    }
345
346    /// Sends a keep-alive request to renew the session.
347    ///
348    /// # Errors
349    ///
350    /// Returns an error if the keep-alive request fails.
351    pub async fn keep_alive(&self) -> Result<(), BetfairHttpError> {
352        self.keep_alive_with_token().await.map(drop)
353    }
354
355    /// Renews the session and returns the current token.
356    ///
357    /// # Errors
358    ///
359    /// Returns an error if the keep-alive request fails.
360    pub(crate) async fn keep_alive_with_token(&self) -> Result<SecretString, BetfairHttpError> {
361        let _guard = self.connect_lock.lock().await;
362        let resp_bytes = self
363            .send_identity(&self.url_keep_alive, SecretString::default())
364            .await?;
365
366        let mut resp: LoginResponse = serde_json::from_slice(&resp_bytes)?;
367
368        if resp.status == LoginStatus::Success {
369            let token = std::mem::take(&mut resp.token);
370            *self.session_token.write().await = Some(token.clone());
371            Ok(token)
372        } else {
373            Err(BetfairHttpError::LoginFailed {
374                status: resp
375                    .error
376                    .take()
377                    .unwrap_or_else(|| format!("{:?}", resp.status)),
378            })
379        }
380    }
381
382    /// Sends a JSON-RPC request to the Betting API.
383    ///
384    /// # Errors
385    ///
386    /// Returns an error if the request fails, authentication is missing,
387    /// or the response contains a JSON-RPC error.
388    pub async fn send_betting<T, P>(&self, method: &str, params: P) -> Result<T, BetfairHttpError>
389    where
390        T: DeserializeOwned,
391        P: Serialize,
392    {
393        self.send_jsonrpc(&self.url_betting, method, params, false)
394            .await
395    }
396
397    /// Sends a JSON-RPC request to the Betting API with order rate limiting.
398    /// Ambiguous failures are retried only when the params include a request-level `customerRef`.
399    ///
400    /// # Errors
401    ///
402    /// Returns an error if the request fails, authentication is missing,
403    /// or the response contains a JSON-RPC error.
404    pub async fn send_betting_order<T, P>(
405        &self,
406        method: &str,
407        params: P,
408    ) -> Result<T, BetfairHttpError>
409    where
410        T: DeserializeOwned,
411        P: Serialize,
412    {
413        self.send_jsonrpc(&self.url_betting, method, params, true)
414            .await
415    }
416
417    /// Sends a JSON-RPC request to the Accounts API.
418    ///
419    /// # Errors
420    ///
421    /// Returns an error if the request fails, authentication is missing,
422    /// or the response contains a JSON-RPC error.
423    pub async fn send_accounts<T, P>(&self, method: &str, params: P) -> Result<T, BetfairHttpError>
424    where
425        T: DeserializeOwned,
426        P: Serialize,
427    {
428        self.send_jsonrpc(&self.url_accounts, method, params, false)
429            .await
430    }
431
432    /// Sends a GET request to the Navigation API.
433    ///
434    /// # Errors
435    ///
436    /// Returns an error if the request fails or the response cannot be parsed.
437    pub async fn send_navigation<T>(&self) -> Result<T, BetfairHttpError>
438    where
439        T: DeserializeOwned,
440    {
441        let headers = self.build_headers("application/json").await?;
442
443        let resp = self
444            .client
445            .request(
446                Method::GET,
447                self.url_navigation.clone(),
448                None,
449                Some(headers),
450                None,
451                None,
452                Some(vec![BETFAIR_RATE_LIMIT_DEFAULT.to_string()]),
453            )
454            .await
455            .map_err(|e| BetfairHttpError::NetworkError(e.to_string()))?;
456
457        if resp.status.as_u16() != 200 {
458            let body = String::from_utf8_lossy(&resp.body);
459            return Err(BetfairHttpError::UnexpectedStatus {
460                status: resp.status.as_u16(),
461                body: body.to_string(),
462            });
463        }
464
465        serde_json::from_slice(&resp.body).map_err(BetfairHttpError::from)
466    }
467
468    fn make_quota(requests_per_second: u32, label: &str) -> Result<Quota, BetfairHttpError> {
469        let rate = NonZeroU32::new(requests_per_second).ok_or_else(|| {
470            BetfairHttpError::InvalidConfiguration(format!("{label} must be greater than zero"))
471        })?;
472
473        Quota::per_second(rate).ok_or_else(|| {
474            BetfairHttpError::InvalidConfiguration(format!("Invalid {label} quota configuration"))
475        })
476    }
477
478    fn rate_limiter_quotas(
479        request_rate_per_second: u32,
480        order_request_rate_per_second: u32,
481    ) -> Result<Vec<(String, Quota)>, BetfairHttpError> {
482        Ok(vec![
483            (
484                BETFAIR_RATE_LIMIT_DEFAULT.to_string(),
485                Self::make_quota(request_rate_per_second, "request_rate_per_second")?,
486            ),
487            (
488                BETFAIR_RATE_LIMIT_ORDERS.to_string(),
489                Self::make_quota(
490                    order_request_rate_per_second,
491                    "order_request_rate_per_second",
492                )?,
493            ),
494        ])
495    }
496
497    fn default_quota(request_rate_per_second: u32) -> Result<Option<Quota>, BetfairHttpError> {
498        Ok(Some(Self::make_quota(
499            request_rate_per_second,
500            "request_rate_per_second",
501        )?))
502    }
503
504    async fn build_headers(
505        &self,
506        content_type: &str,
507    ) -> Result<HashMap<String, String>, BetfairHttpError> {
508        let token = self
509            .session_token
510            .read()
511            .await
512            .as_ref()
513            .map(|token| token.expose_secret().to_owned())
514            .ok_or(BetfairHttpError::MissingCredentials)?;
515
516        let mut headers = HashMap::new();
517        headers.insert(HEADER_X_AUTHENTICATION.to_string(), token);
518        headers.insert(
519            HEADER_X_APPLICATION.to_string(),
520            self.credential.app_key().to_string(),
521        );
522        headers.insert("Accept".to_string(), "application/json".to_string());
523        headers.insert("Content-Type".to_string(), content_type.to_string());
524        Ok(headers)
525    }
526
527    async fn send_identity(
528        &self,
529        url: &str,
530        body: SecretString,
531    ) -> Result<Vec<u8>, BetfairHttpError> {
532        let mut headers = HashMap::new();
533        headers.insert("Accept".to_string(), "application/json".to_string());
534        headers.insert(
535            "Content-Type".to_string(),
536            "application/x-www-form-urlencoded".to_string(),
537        );
538        headers.insert(
539            HEADER_X_APPLICATION.to_string(),
540            self.credential.app_key().to_string(),
541        );
542
543        // Add session token if we have one (for keep-alive)
544        if let Some(token) = self.session_token.read().await.as_ref() {
545            headers.insert(
546                HEADER_X_AUTHENTICATION.to_string(),
547                token.expose_secret().to_owned(),
548            );
549        }
550
551        let resp = self
552            .client
553            .request_with_secret_body(
554                Method::POST,
555                url.to_string(),
556                None,
557                Some(headers),
558                body,
559                None,
560                Some(vec![BETFAIR_RATE_LIMIT_DEFAULT.to_string()]),
561            )
562            .await
563            .map_err(|e| BetfairHttpError::NetworkError(e.to_string()))?;
564
565        if resp.status.as_u16() != 200 {
566            let body = String::from_utf8_lossy(&resp.body);
567            return Err(BetfairHttpError::UnexpectedStatus {
568                status: resp.status.as_u16(),
569                body: body.to_string(),
570            });
571        }
572
573        Ok(resp.body.to_vec())
574    }
575
576    async fn send_jsonrpc<T, P>(
577        &self,
578        base_url: &str,
579        method: &str,
580        params: P,
581        is_order: bool,
582    ) -> Result<T, BetfairHttpError>
583    where
584        T: DeserializeOwned,
585        P: Serialize,
586    {
587        let operation_id = format!("{base_url}#{method}");
588        let params_value = serde_json::to_value(&params)?;
589        let has_order_customer_ref = params_value
590            .get("customerRef")
591            .and_then(serde_json::Value::as_str)
592            .is_some_and(|customer_ref| !customer_ref.is_empty());
593        let had_ambiguous_attempt = AtomicBool::new(false);
594
595        let operation = || {
596            let params_value = params_value.clone();
597            let had_ambiguous_attempt = &had_ambiguous_attempt;
598
599            async move {
600                let result = self
601                    .send_jsonrpc_once(base_url, method, params_value, is_order)
602                    .await;
603
604                if is_order && result.as_ref().is_err_and(|e| e.is_order_ambiguous()) {
605                    had_ambiguous_attempt.store(true, Ordering::Relaxed);
606                }
607
608                result
609            }
610        };
611
612        let should_retry = |error: &BetfairHttpError| -> bool {
613            if is_order {
614                error.is_order_retryable()
615                    && (has_order_customer_ref || !error.is_order_ambiguous())
616            } else {
617                error.is_retryable()
618            }
619        };
620
621        let create_error = |error: RetryError| -> BetfairHttpError {
622            map_retry_error(error, is_order, &had_ambiguous_attempt)
623        };
624
625        // Snapshot the current token; `disconnect()` may swap it for a fresh
626        // one mid-flight, but the in-flight retry loop should observe the
627        // pre-disconnect token so a cancel actually unblocks it.
628        let token = self.cancellation_token.lock().clone();
629
630        let retry_manager = if is_order {
631            &self.order_retry_manager
632        } else {
633            &self.retry_manager
634        };
635        let result = retry_manager
636            .invocation(&operation_id, operation, should_retry, create_error)
637            .cancellation_token(&token)
638            .execute()
639            .await;
640
641        let result = match result {
642            Err(e)
643                if is_order
644                    && had_ambiguous_attempt.load(Ordering::Relaxed)
645                    && !e.is_order_ambiguous() =>
646            {
647                Err(BetfairHttpError::OrderRequestAmbiguous(format!(
648                    "an earlier attempt had an unknown outcome; final error: {e}",
649                )))
650            }
651            result => result,
652        };
653
654        if let Err(ref e) = result
655            && should_retry(e)
656        {
657            log::warn!("Request exhausted retries: method={method}, error={e}");
658        }
659
660        result
661    }
662
663    async fn send_jsonrpc_once<T>(
664        &self,
665        base_url: &str,
666        method: &str,
667        params: serde_json::Value,
668        is_order: bool,
669    ) -> Result<T, BetfairHttpError>
670    where
671        T: DeserializeOwned,
672    {
673        let id = self.request_id.fetch_add(1, Ordering::SeqCst);
674        let request = JsonRpcRequest {
675            jsonrpc: "2.0",
676            method: method.to_string(),
677            params,
678            id,
679        };
680
681        let body = serde_json::to_vec(&request)?;
682        let headers = self.build_headers("application/json").await?;
683        let rate_keys = if is_order {
684            vec![BETFAIR_RATE_LIMIT_ORDERS.to_string()]
685        } else {
686            vec![BETFAIR_RATE_LIMIT_DEFAULT.to_string()]
687        };
688
689        let resp = self
690            .client
691            .request(
692                Method::POST,
693                base_url.to_string(),
694                None,
695                Some(headers),
696                Some(body),
697                None,
698                Some(rate_keys),
699            )
700            .await
701            .map_err(|e| BetfairHttpError::NetworkError(e.to_string()))?;
702
703        if !resp.status.is_success() {
704            let error_body = String::from_utf8_lossy(&resp.body);
705            let preview: String = error_body.chars().take(500).collect();
706            log::warn!(
707                "HTTP error response: method={method}, status={}, body={}",
708                resp.status.as_u16(),
709                preview,
710            );
711            return Err(BetfairHttpError::UnexpectedStatus {
712                status: resp.status.as_u16(),
713                body: error_body.to_string(),
714            });
715        }
716
717        let json_value: serde_json::Value = serde_json::from_slice(&resp.body).map_err(|e| {
718            let preview: String = String::from_utf8_lossy(&resp.body)
719                .chars()
720                .take(500)
721                .collect();
722            log::warn!(
723                "Non-JSON response: method={method}, status={}, body={preview}",
724                resp.status.as_u16(),
725            );
726            BetfairHttpError::ResponseError(e.to_string())
727        })?;
728
729        let rpc_resp: JsonRpcResponse<T> = serde_json::from_value(json_value).map_err(|e| {
730            log::warn!("Failed to deserialize JSON-RPC response: method={method}, error={e}",);
731            BetfairHttpError::ResponseError(e.to_string())
732        })?;
733
734        if let Some(result) = rpc_resp.result {
735            Ok(result)
736        } else if let Some(error) = rpc_resp.error {
737            let api_exception = error.api_exception();
738            Err(BetfairHttpError::BetfairError {
739                code: error.code,
740                message: error.message,
741                api_error_code: api_exception
742                    .as_ref()
743                    .map(|exception| exception.error_code.clone()),
744                api_error_details: api_exception.and_then(|exception| exception.error_details),
745            })
746        } else {
747            Err(BetfairHttpError::ResponseError(
748                "Response contains neither result nor error".to_string(),
749            ))
750        }
751    }
752}
753
754fn map_retry_error(
755    error: RetryError,
756    is_order: bool,
757    had_ambiguous_attempt: &AtomicBool,
758) -> BetfairHttpError {
759    if is_order && matches!(&error, RetryError::OperationTimeout { .. }) {
760        had_ambiguous_attempt.store(true, Ordering::Relaxed);
761    }
762
763    match error {
764        RetryError::Canceled => {
765            BetfairHttpError::Canceled("Adapter disconnecting or shutting down".to_string())
766        }
767        error => BetfairHttpError::NetworkError(error.to_string()),
768    }
769}
770
771#[cfg(test)]
772mod tests {
773    use std::time::Duration;
774
775    use nautilus_testkit::http::assert_http_redirect_rejected;
776    use parking_lot::Mutex;
777    use proptest::prelude::*;
778    use rstest::rstest;
779
780    use super::*;
781    use crate::common::consts::{
782        BETFAIR_RATE_LIMIT_DEFAULT, BETFAIR_RATE_LIMIT_ORDERS, METHOD_LIST_MARKET_CATALOGUE,
783    };
784
785    fn json_value_strategy() -> impl Strategy<Value = serde_json::Value> {
786        let leaf = prop_oneof![
787            Just(serde_json::Value::Null),
788            any::<bool>().prop_map(serde_json::Value::Bool),
789            any::<i64>().prop_map(|value| serde_json::Value::Number(value.into())),
790            "[ -~]{0,32}".prop_map(serde_json::Value::String),
791        ];
792
793        leaf.prop_recursive(3, 64, 8, |inner| {
794            prop_oneof![
795                prop::collection::vec(inner.clone(), 0..8).prop_map(serde_json::Value::Array),
796                prop::collection::vec(("[A-Za-z0-9_]{0,16}", inner), 0..8)
797                    .prop_map(|entries| serde_json::Value::Object(entries.into_iter().collect())),
798            ]
799        })
800    }
801
802    #[tokio::test]
803    async fn test_authenticated_client_rejects_redirects() {
804        let client = BetfairHttpClient::new(
805            BetfairCredential::new("user".into(), "password".into(), "app".into()),
806            Some(3),
807            Some(0),
808            None,
809            None,
810            None,
811            None,
812        )
813        .unwrap()
814        .client;
815        assert_http_redirect_rejected(|url| async move {
816            client
817                .get(url, None, None, Some(3), None)
818                .await
819                .unwrap()
820                .status
821                .as_u16()
822        })
823        .await;
824    }
825
826    #[rstest]
827    fn test_rate_limiter_quotas_has_expected_keys() {
828        let quotas = BetfairHttpClient::rate_limiter_quotas(5, 20).unwrap();
829        let keys: Vec<&str> = quotas.iter().map(|(k, _)| k.as_str()).collect();
830        assert!(keys.contains(&BETFAIR_RATE_LIMIT_DEFAULT));
831        assert!(keys.contains(&BETFAIR_RATE_LIMIT_ORDERS));
832    }
833
834    #[rstest]
835    fn test_default_quota_is_some() {
836        assert!(BetfairHttpClient::default_quota(5).unwrap().is_some());
837    }
838
839    #[rstest]
840    fn test_rate_limiter_quotas_reject_zero_rate_limit() {
841        let result = BetfairHttpClient::rate_limiter_quotas(0, 20);
842
843        assert!(result.is_err());
844        assert!(
845            result
846                .err()
847                .unwrap()
848                .to_string()
849                .contains("request_rate_per_second")
850        );
851    }
852
853    #[rstest]
854    fn test_debug_redacts_session_token() {
855        let client = BetfairHttpClient::new(
856            BetfairCredential::new(
857                "username".to_string(),
858                "betfair-password-sentinel".to_string(),
859                "application-key".to_string(),
860            ),
861            None,
862            None,
863            None,
864            None,
865            None,
866            None,
867        )
868        .unwrap();
869        *client.session_token.try_write().unwrap() =
870            Some(SecretString::from("betfair-session-token-sentinel"));
871
872        let debug = format!("{client:?}");
873
874        assert!(debug.contains("session_token"));
875        assert!(!debug.contains("betfair-session-token-sentinel"));
876        assert!(!debug.contains("betfair-password-sentinel"));
877    }
878
879    #[rstest]
880    fn test_json_rpc_request_serialization() {
881        let request = JsonRpcRequest {
882            jsonrpc: "2.0",
883            method: METHOD_LIST_MARKET_CATALOGUE.to_string(),
884            params: serde_json::json!({"filter": {}, "maxResults": 100}),
885            id: 1,
886        };
887
888        let json = serde_json::to_value(&request).unwrap();
889        assert_eq!(json["jsonrpc"], "2.0");
890        assert_eq!(json["method"], "SportsAPING/v1.0/listMarketCatalogue");
891        assert_eq!(json["params"]["maxResults"], 100);
892        assert_eq!(json["id"], 1);
893    }
894
895    #[rstest]
896    fn test_json_rpc_response_success() {
897        let json = include_str!(concat!(
898            env!("CARGO_MANIFEST_DIR"),
899            "/test_data/rest/betting_place_order_success.json"
900        ));
901        let resp: JsonRpcResponse<serde_json::Value> = serde_json::from_str(json).unwrap();
902        assert_eq!(
903            resp.result
904                .as_ref()
905                .and_then(|result| result["status"].as_str()),
906            Some("SUCCESS")
907        );
908        assert!(resp.error.is_none());
909    }
910
911    #[rstest]
912    fn test_json_rpc_response_error() {
913        let json = include_str!(concat!(
914            env!("CARGO_MANIFEST_DIR"),
915            "/test_data/rest/betting_jsonrpc_error_too_much_data_live.json"
916        ));
917        let resp: JsonRpcResponse<serde_json::Value> = serde_json::from_str(json).unwrap();
918        assert!(resp.result.is_none());
919        let error = resp.error.unwrap();
920        assert_eq!(error.code, -32099);
921        assert_eq!(error.message, "ANGX-0001");
922        let api_exception = error.api_exception().unwrap();
923        assert_eq!(api_exception.error_code, "TOO_MUCH_DATA");
924        assert_eq!(
925            api_exception.error_details.as_deref(),
926            Some("MaxResults must be less than or equal to 1000")
927        );
928    }
929
930    #[rstest]
931    fn test_order_operation_timeout_records_ambiguous_attempt() {
932        let had_ambiguous_attempt = AtomicBool::new(false);
933
934        let error = map_retry_error(
935            RetryError::OperationTimeout { timeout_ms: 30_000 },
936            true,
937            &had_ambiguous_attempt,
938        );
939
940        assert!(error.is_order_ambiguous());
941        assert!(had_ambiguous_attempt.load(Ordering::Relaxed));
942    }
943
944    proptest! {
945        #![proptest_config(ProptestConfig::with_cases(256))]
946
947        #[rstest]
948        fn arbitrary_json_rpc_error_data_preserves_outer_error(
949            data in json_value_strategy(),
950        ) {
951            let response: JsonRpcResponse<serde_json::Value> = serde_json::from_value(
952                serde_json::json!({
953                    "jsonrpc": "2.0",
954                    "id": 73,
955                    "error": {
956                        "code": -32099,
957                        "message": "ANGX-PROPERTY",
958                        "data": data,
959                    },
960                }),
961            )
962            .unwrap();
963            let error = response.error.unwrap();
964            let api_exception = error.api_exception();
965            let surfaced = BetfairHttpError::BetfairError {
966                code: error.code,
967                message: error.message.clone(),
968                api_error_code: api_exception
969                    .as_ref()
970                    .map(|exception| exception.error_code.clone()),
971                api_error_details: api_exception
972                    .and_then(|exception| exception.error_details),
973            };
974
975            prop_assert_eq!(error.code, -32099);
976            prop_assert_eq!(error.message, "ANGX-PROPERTY");
977
978            if matches!(
979                &surfaced,
980                BetfairHttpError::BetfairError {
981                    api_error_code: None,
982                    ..
983                }
984            ) {
985                prop_assert!(surfaced.is_order_ambiguous());
986                prop_assert!(!surfaced.is_order_retryable());
987            }
988        }
989
990        #[rstest]
991        fn unknown_api_error_code_is_ambiguous_and_not_retried(
992            api_error_code in "FUTURE_[A-Z0-9_]{1,24}",
993        ) {
994            let exception_name = "FutureAPINGException";
995            let response: JsonRpcResponse<serde_json::Value> = serde_json::from_value(
996                serde_json::json!({
997                    "jsonrpc": "2.0",
998                    "id": 74,
999                    "error": {
1000                        "code": -32099,
1001                        "message": "ANGX-FUTURE",
1002                        "data": {
1003                            "exceptionname": exception_name,
1004                            (exception_name): {
1005                                "errorCode": api_error_code,
1006                                "errorDetails": "future wire shape",
1007                            },
1008                        },
1009                    },
1010                }),
1011            )
1012            .unwrap();
1013            let error = response.error.unwrap();
1014            let api_exception = error.api_exception().unwrap();
1015            let surfaced = BetfairHttpError::BetfairError {
1016                code: error.code,
1017                message: error.message.clone(),
1018                api_error_code: Some(api_exception.error_code.clone()),
1019                api_error_details: api_exception.error_details.clone(),
1020            };
1021
1022            prop_assert_eq!(error.code, -32099);
1023            prop_assert_eq!(error.message, "ANGX-FUTURE");
1024            prop_assert_eq!(api_exception.error_code, api_error_code);
1025            prop_assert_eq!(
1026                api_exception.error_details.as_deref(),
1027                Some("future wire shape"),
1028            );
1029            prop_assert!(surfaced.is_order_ambiguous());
1030            prop_assert!(!surfaced.is_order_retryable());
1031        }
1032    }
1033
1034    #[tokio::test(start_paused = true)]
1035    async fn test_order_retry_budget_prevents_dispatch_at_45_seconds() {
1036        let client = BetfairHttpClient::new(
1037            BetfairCredential::new(
1038                "username".to_string(),
1039                "password".to_string(),
1040                "app-key".to_string(),
1041            ),
1042            None,
1043            Some(100),
1044            Some(10_000),
1045            None,
1046            Some(5),
1047            Some(20),
1048        )
1049        .unwrap();
1050        let started_at = tokio::time::Instant::now();
1051        let attempt_times = Arc::new(Mutex::new(Vec::new()));
1052        let attempt_times_for_operation = Arc::clone(&attempt_times);
1053
1054        let result = client
1055            .order_retry_manager
1056            .invocation(
1057                "placeOrders",
1058                move || {
1059                    let attempt_times = Arc::clone(&attempt_times_for_operation);
1060                    async move {
1061                        attempt_times.lock().push(started_at.elapsed());
1062                        Err::<(), _>(BetfairHttpError::UnexpectedStatus {
1063                            status: 502,
1064                            body: "Bad Gateway".to_string(),
1065                        })
1066                    }
1067                },
1068                BetfairHttpError::is_order_retryable,
1069                |e| BetfairHttpError::NetworkError(e.to_string()),
1070            )
1071            .execute()
1072            .await;
1073
1074        assert!(matches!(result, Err(BetfairHttpError::NetworkError(_))));
1075        assert_eq!(started_at.elapsed(), Duration::from_secs(45));
1076        let attempt_times = attempt_times.lock();
1077        assert!(attempt_times.len() > 1);
1078        assert_eq!(attempt_times[0], Duration::ZERO);
1079        assert!(
1080            attempt_times
1081                .iter()
1082                .all(|elapsed| *elapsed < Duration::from_secs(45)),
1083        );
1084    }
1085}