use std::sync::Arc;
use std::time::Duration;
use serde::de::DeserializeOwned;
use crate::core::error::{DelopayError, Result};
use crate::http::hyper_backend::HyperTransport;
use crate::http::proxy::ProxyMode;
use crate::http::retry::{backoff, parse_retry_after};
use crate::http::transport::{HttpMethod, RawRequest, Transport, TransportErrorKind};
use crate::resources::cards::Cards;
use crate::resources::customers::Customers;
use crate::resources::disputes::Disputes;
use crate::resources::ephemeral_keys::EphemeralKeys;
use crate::resources::events::Events;
use crate::resources::export::Export;
use crate::resources::files::Files;
use crate::resources::forex::Forex;
use crate::resources::mandates::Mandates;
use crate::resources::payment_links::PaymentLinks;
use crate::resources::payment_methods::PaymentMethods;
use crate::resources::payments::Payments;
use crate::resources::payouts::Payouts;
use crate::resources::poll::Poll;
use crate::resources::refunds::Refunds;
use crate::resources::subscriptions::Subscriptions;
use crate::{PRODUCTION_URL, SANDBOX_URL};
const DEFAULT_TIMEOUT: Duration = Duration::from_secs(30);
const DEFAULT_MAX_RETRIES: u32 = 2;
#[derive(Debug, Clone)]
pub struct Delopay {
pub(crate) inner: Arc<Inner>,
}
pub(crate) struct Inner {
transport: Arc<dyn Transport>,
base_url: String,
checkout_base_url: String,
api_key: String,
max_retries: u32,
}
impl std::fmt::Debug for Inner {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Inner")
.field("base_url", &self.base_url)
.field("checkout_base_url", &self.checkout_base_url)
.field("max_retries", &self.max_retries)
.finish_non_exhaustive()
}
}
impl Delopay {
pub fn new(api_key: impl Into<String>) -> Self {
Self::builder(api_key).build()
}
pub fn sandbox(api_key: impl Into<String>) -> Self {
Self::builder(api_key).sandbox(true).build()
}
pub fn builder(api_key: impl Into<String>) -> DelopayBuilder {
DelopayBuilder::new(api_key)
}
pub fn base_url(&self) -> &str {
&self.inner.base_url
}
pub fn payments(&self) -> Payments {
Payments::new(self.inner.clone())
}
pub fn refunds(&self) -> Refunds {
Refunds::new(self.inner.clone())
}
pub fn customers(&self) -> Customers {
Customers::new(self.inner.clone())
}
pub fn payment_methods(&self) -> PaymentMethods {
PaymentMethods::new(self.inner.clone())
}
pub fn payouts(&self) -> Payouts {
Payouts::new(self.inner.clone())
}
pub fn disputes(&self) -> Disputes {
Disputes::new(self.inner.clone())
}
pub fn mandates(&self) -> Mandates {
Mandates::new(self.inner.clone())
}
pub fn events(&self) -> Events {
Events::new(self.inner.clone())
}
pub fn payment_links(&self) -> PaymentLinks {
PaymentLinks::new(self.inner.clone())
}
pub fn ephemeral_keys(&self) -> EphemeralKeys {
EphemeralKeys::new(self.inner.clone())
}
pub fn poll(&self) -> Poll {
Poll::new(self.inner.clone())
}
pub fn subscriptions(&self) -> Subscriptions {
Subscriptions::new(self.inner.clone())
}
pub fn cards(&self) -> Cards {
Cards::new(self.inner.clone())
}
pub fn forex(&self) -> Forex {
Forex::new(self.inner.clone())
}
pub fn files(&self) -> Files {
Files::new(self.inner.clone())
}
pub fn export(&self) -> Export {
Export::new(self.inner.clone())
}
pub fn hosted_checkout_url(&self, merchant_id: &str, payment_id: &str) -> String {
format!(
"{}/pay/{}/{}",
self.inner.checkout_base_url.trim_end_matches('/'),
merchant_id,
payment_id
)
}
}
impl Inner {
pub(crate) fn with_transport(
transport: Arc<dyn Transport>,
base_url: String,
checkout_base_url: String,
api_key: String,
max_retries: u32,
) -> Self {
Self {
transport,
base_url,
checkout_base_url,
api_key,
max_retries,
}
}
pub(crate) async fn send_raw(
&self,
method: HttpMethod,
path: &str,
body: Option<&[u8]>,
query: &[(&str, String)],
idempotency_key: Option<&str>,
extra_headers: &[(&str, &str)],
) -> Result<Vec<u8>> {
let url = format!("{}{}", self.base_url, path);
let is_idempotent = method.is_inherently_idempotent() || idempotency_key.is_some();
let mut attempt: u32 = 0;
loop {
let mut headers: Vec<(&str, &str)> =
vec![("api-key", &self.api_key), ("accept", "application/json")];
if let Some(key) = idempotency_key {
headers.push(("idempotency-key", key));
}
headers.extend_from_slice(extra_headers);
let req = RawRequest {
method,
url: &url,
headers: &headers,
query,
body,
};
match self.transport.execute(req).await {
Ok(resp) => {
if resp.is_success() {
return Ok(resp.body);
}
let too_many = resp.status == 429;
let retriable = too_many || resp.is_server_error();
let may_retry =
attempt < self.max_retries && retriable && (too_many || is_idempotent);
if may_retry {
attempt += 1;
let delay = parse_retry_after(resp.header("retry-after"))
.unwrap_or_else(|| backoff(attempt));
tokio::time::sleep(delay).await;
continue;
}
let request_id = resp.header("x-request-id").map(str::to_owned);
return Err(DelopayError::from_response(
resp.status,
request_id,
&resp.body,
));
}
Err(err) => {
if err.is_retriable() && is_idempotent && attempt < self.max_retries {
attempt += 1;
tokio::time::sleep(backoff(attempt)).await;
continue;
}
if err.kind == TransportErrorKind::Timeout {
return Err(DelopayError::Timeout);
}
return Err(DelopayError::Transport(err.source));
}
}
}
}
pub(crate) async fn request<T: DeserializeOwned>(
&self,
method: HttpMethod,
path: &str,
body: Option<&[u8]>,
query: &[(&str, String)],
idempotency_key: Option<&str>,
) -> Result<T> {
let bytes = self
.send_raw(method, path, body, query, idempotency_key, &[])
.await?;
decode_success(&bytes)
}
pub(crate) async fn request_with_headers<T: DeserializeOwned>(
&self,
method: HttpMethod,
path: &str,
body: Option<&[u8]>,
query: &[(&str, String)],
idempotency_key: Option<&str>,
extra_headers: &[(&str, &str)],
) -> Result<T> {
let bytes = self
.send_raw(method, path, body, query, idempotency_key, extra_headers)
.await?;
decode_success(&bytes)
}
}
fn decode_success<T: DeserializeOwned>(bytes: &[u8]) -> Result<T> {
let slice: &[u8] = if bytes.is_empty() { b"null" } else { bytes };
serde_json::from_slice(slice).map_err(|e| DelopayError::Decode(e.to_string()))
}
#[derive(Clone)]
pub struct DelopayBuilder {
api_key: String,
base_url: Option<String>,
checkout_base_url: Option<String>,
sandbox: bool,
timeout: Duration,
max_retries: u32,
proxy: ProxyMode,
}
impl std::fmt::Debug for DelopayBuilder {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("DelopayBuilder")
.field("base_url", &self.base_url)
.field("checkout_base_url", &self.checkout_base_url)
.field("sandbox", &self.sandbox)
.field("timeout", &self.timeout)
.field("max_retries", &self.max_retries)
.field("proxy", &self.proxy)
.finish_non_exhaustive()
}
}
impl DelopayBuilder {
fn new(api_key: impl Into<String>) -> Self {
Self {
api_key: api_key.into(),
base_url: None,
checkout_base_url: None,
sandbox: false,
timeout: DEFAULT_TIMEOUT,
max_retries: DEFAULT_MAX_RETRIES,
proxy: ProxyMode::Env,
}
}
pub fn sandbox(mut self, sandbox: bool) -> Self {
self.sandbox = sandbox;
self
}
pub fn base_url(mut self, url: impl Into<String>) -> Self {
self.base_url = Some(url.into());
self
}
pub fn checkout_base_url(mut self, url: impl Into<String>) -> Self {
self.checkout_base_url = Some(url.into());
self
}
pub fn timeout(mut self, timeout: Duration) -> Self {
self.timeout = timeout;
self
}
pub fn max_retries(mut self, max_retries: u32) -> Self {
self.max_retries = max_retries;
self
}
pub fn proxy(mut self, url: impl Into<String>) -> Self {
self.proxy = ProxyMode::Explicit(url.into());
self
}
pub fn no_proxy(mut self) -> Self {
self.proxy = ProxyMode::Disabled;
self
}
pub fn build(self) -> Delopay {
let base_url = self.base_url.unwrap_or_else(|| {
if self.sandbox {
SANDBOX_URL
} else {
PRODUCTION_URL
}
.to_string()
});
let checkout_base_url = self
.checkout_base_url
.unwrap_or_else(|| crate::CHECKOUT_URL.to_string());
let proxy = crate::http::proxy::resolve(&self.proxy, &base_url);
let transport = Arc::new(HyperTransport::new(
self.timeout,
concat!("delopay-rust/", env!("CARGO_PKG_VERSION")),
proxy,
));
Delopay {
inner: Arc::new(Inner::with_transport(
transport,
base_url,
checkout_base_url,
self.api_key,
self.max_retries,
)),
}
}
}
#[cfg(test)]
mod tests {
use std::sync::Arc;
use super::*;
use crate::http::mock::{MockTransport, SeenRequest, Step};
use crate::http::transport::TransportErrorKind;
fn client_with(steps: Vec<Step>, max_retries: u32) -> (Delopay, Arc<MockTransport>) {
let mock = Arc::new(MockTransport::new(steps));
let inner = Inner::with_transport(
mock.clone(),
"https://api.test".to_string(),
"https://checkout.test".to_string(),
"prd_test".to_string(),
max_retries,
);
(
Delopay {
inner: Arc::new(inner),
},
mock,
)
}
#[tokio::test]
async fn retries_429_even_for_non_idempotent_post() {
let (client, mock) =
client_with(vec![Step::status(429, ""), Step::ok(r#"{"ok":true}"#)], 2);
let out: serde_json::Value = client
.inner
.request(HttpMethod::Post, "/x", None, &[], None)
.await
.unwrap();
assert_eq!(out["ok"], true);
assert_eq!(mock.call_count(), 2);
}
#[tokio::test]
async fn does_not_retry_5xx_for_post_without_idempotency_key() {
let (client, mock) = client_with(vec![Step::status(500, "")], 2);
let err = client
.inner
.request::<serde_json::Value>(HttpMethod::Post, "/x", None, &[], None)
.await
.unwrap_err();
assert!(matches!(err, DelopayError::Api(_)));
assert_eq!(mock.call_count(), 1, "a bare POST must never be replayed");
}
#[tokio::test]
async fn retries_5xx_for_post_with_idempotency_key() {
let (client, mock) =
client_with(vec![Step::status(500, ""), Step::ok(r#"{"ok":true}"#)], 2);
let out: serde_json::Value = client
.inner
.request(HttpMethod::Post, "/x", None, &[], Some("key-1"))
.await
.unwrap();
assert_eq!(out["ok"], true);
assert_eq!(mock.call_count(), 2);
assert!(
mock.seen
.lock()
.unwrap()
.iter()
.all(SeenRequest::had_idempotency_key)
);
}
#[tokio::test]
async fn retries_5xx_for_get() {
let (client, mock) =
client_with(vec![Step::status(503, ""), Step::ok(r#"{"ok":true}"#)], 2);
let _: serde_json::Value = client
.inner
.request(HttpMethod::Get, "/x", None, &[], None)
.await
.unwrap();
assert_eq!(mock.call_count(), 2);
let seen = mock.seen.lock().unwrap();
for req in seen.iter() {
assert_eq!(req.method, "GET");
assert_eq!(req.url, "https://api.test/x");
}
}
#[tokio::test]
async fn stops_after_max_retries() {
let (client, mock) = client_with(
vec![
Step::status(500, ""),
Step::status(500, ""),
Step::status(500, ""),
],
2,
);
let _ = client
.inner
.request::<serde_json::Value>(HttpMethod::Get, "/x", None, &[], None)
.await
.unwrap_err();
assert_eq!(mock.call_count(), 3, "initial attempt + 2 retries");
}
#[tokio::test]
async fn timeout_maps_to_timeout_variant() {
let (client, _) = client_with(vec![Step::Fail(TransportErrorKind::Timeout)], 0);
let err = client
.inner
.request::<serde_json::Value>(HttpMethod::Get, "/x", None, &[], None)
.await
.unwrap_err();
assert!(matches!(err, DelopayError::Timeout));
}
#[tokio::test]
async fn connect_failure_maps_to_transport_variant() {
let (client, _) = client_with(vec![Step::Fail(TransportErrorKind::Connect)], 0);
let err = client
.inner
.request::<serde_json::Value>(HttpMethod::Get, "/x", None, &[], None)
.await
.unwrap_err();
assert!(matches!(err, DelopayError::Transport(_)));
}
#[tokio::test]
async fn maps_401_to_authentication_error() {
let (client, _) = client_with(
vec![Step::status(
401,
r#"{"error":{"code":"AUTH_01","type":"authentication_error","message":"bad key"}}"#,
)],
0,
);
let err = client
.inner
.request::<serde_json::Value>(HttpMethod::Get, "/x", None, &[], None)
.await
.unwrap_err();
match err {
DelopayError::Authentication(api) => assert_eq!(api.code, "AUTH_01"),
other => panic!("expected Authentication, got {other:?}"),
}
}
#[tokio::test(start_paused = true)]
async fn honors_retry_after_header() {
let (client, mock) = client_with(
vec![
Step::status_with_header(429, "retry-after", "5"),
Step::ok(r#"{"ok":true}"#),
],
2,
);
let started = tokio::time::Instant::now();
let _: serde_json::Value = client
.inner
.request(HttpMethod::Get, "/x", None, &[], None)
.await
.unwrap();
let waited = started.elapsed();
assert_eq!(mock.call_count(), 2);
assert_eq!(
waited,
Duration::from_secs(5),
"must wait exactly the Retry-After value, not the {:?} backoff",
backoff(1)
);
}
#[tokio::test(start_paused = true)]
async fn falls_back_to_backoff_when_retry_after_absent() {
let (client, mock) =
client_with(vec![Step::status(429, ""), Step::ok(r#"{"ok":true}"#)], 2);
let started = tokio::time::Instant::now();
let _: serde_json::Value = client
.inner
.request(HttpMethod::Get, "/x", None, &[], None)
.await
.unwrap();
assert_eq!(mock.call_count(), 2);
assert_eq!(started.elapsed(), backoff(1));
}
#[tokio::test]
async fn post_without_idempotency_key_is_never_replayed_on_network_failure() {
let (client, mock) = client_with(vec![Step::Fail(TransportErrorKind::Timeout)], 2);
let err = client
.inner
.request::<serde_json::Value>(HttpMethod::Post, "/x", None, &[], None)
.await
.unwrap_err();
assert!(matches!(err, DelopayError::Timeout));
assert_eq!(
mock.call_count(),
1,
"a bare POST must never be replayed after a network failure — the \
original attempt may already have taken effect server-side"
);
}
#[tokio::test]
async fn post_with_idempotency_key_is_retried_on_network_failure() {
let (client, mock) = client_with(
vec![
Step::Fail(TransportErrorKind::Timeout),
Step::ok(r#"{"ok":true}"#),
],
2,
);
let out: serde_json::Value = client
.inner
.request(HttpMethod::Post, "/x", None, &[], Some("key-1"))
.await
.unwrap();
assert_eq!(out["ok"], true);
assert_eq!(mock.call_count(), 2);
}
#[tokio::test]
async fn extra_headers_reach_the_transport() {
let (client, mock) = client_with(vec![Step::ok(r#"{"ok":true}"#)], 0);
let _: serde_json::Value = client
.inner
.request_with_headers(
HttpMethod::Post,
"/x",
None,
&[],
None,
&[("x-profile-id", "pro_1")],
)
.await
.unwrap();
let seen = mock.seen.lock().unwrap();
assert_eq!(seen[0].header("x-profile-id"), Some("pro_1"));
assert_eq!(
seen[0].header("api-key"),
Some("prd_test"),
"extra headers must be appended, not replace the built-in set"
);
}
#[tokio::test]
async fn put_without_idempotency_key_is_not_retried_on_5xx() {
let (client, mock) = client_with(vec![Step::status(500, "")], 2);
let err = client
.inner
.request::<serde_json::Value>(HttpMethod::Put, "/x", None, &[], None)
.await
.unwrap_err();
assert!(matches!(err, DelopayError::Api(_)));
assert_eq!(
mock.call_count(),
1,
"a bare PUT must never be replayed — this API uses PUT for \
state transitions, where a blind replay is not provably safe"
);
}
#[test]
fn delopay_builder_debug_redacts_api_key() {
let builder = Delopay::builder("prd_super_secret_key_for_debug_test");
let formatted = format!("{builder:?}");
assert!(
!formatted.contains("prd_super_secret_key_for_debug_test"),
"DelopayBuilder's Debug output must not contain the secret api key: {formatted}"
);
}
#[test]
fn delopay_builder_debug_redacts_proxy_credentials() {
let builder =
Delopay::builder("prd_x").proxy("http://alice:hunter2@corp-egress.internal:3128");
let formatted = format!("{builder:?}");
assert!(
!formatted.contains("hunter2") && !formatted.contains("alice"),
"DelopayBuilder's Debug output must not contain proxy credentials: {formatted}"
);
}
#[test]
fn inner_debug_redacts_api_key() {
let mock = Arc::new(MockTransport::new(vec![]));
let inner = Inner::with_transport(
mock,
"https://api.test".to_string(),
"https://checkout.test".to_string(),
"prd_super_secret_key_for_inner_debug_test".to_string(),
2,
);
let formatted = format!("{inner:?}");
assert!(
!formatted.contains("prd_super_secret_key_for_inner_debug_test"),
"Inner's Debug output must not contain the secret api key: {formatted}"
);
}
#[tokio::test]
async fn body_read_failure_is_not_retried_through_send_raw() {
let (client, mock) = client_with(vec![Step::Fail(TransportErrorKind::Body)], 2);
let err = client
.inner
.request::<serde_json::Value>(HttpMethod::Get, "/x", None, &[], None)
.await
.unwrap_err();
assert!(matches!(err, DelopayError::Transport(_)));
assert_eq!(
mock.call_count(),
1,
"a Body read failure must never be retried"
);
}
}