use crate::error::BaseError;
use crate::http::response::Response;
use reqwest::header::{HeaderMap, HeaderName, HeaderValue};
use reqwest::{Client, Method};
use serde::Serialize;
use std::time::Duration;
fn redact_url_for_log(url: &str) -> String {
let Ok(mut parsed_url) = reqwest::Url::parse(url) else {
return "<invalid-url>".to_string();
};
parsed_url.set_query(None);
if !parsed_url.username().is_empty() {
let _ = parsed_url.set_username("***");
}
if parsed_url.password().is_some() {
let _ = parsed_url.set_password(Some("***"));
}
parsed_url.to_string()
}
#[derive(Debug, Clone)]
pub struct RetryConfig {
pub max_retries: u32,
pub retry_on: Vec<u16>,
pub backoff_ms: u64,
}
impl Default for RetryConfig {
fn default() -> Self {
Self {
max_retries: 3,
retry_on: vec![502, 503, 504],
backoff_ms: 100,
}
}
}
impl RetryConfig {
const MAX_RETRIES: u32 = 10;
const MAX_BACKOFF_MS: u64 = 60_000;
pub fn validate(&self) -> Result<(), BaseError> {
if self.max_retries > Self::MAX_RETRIES {
return Err(BaseError::ParamInvalid(
"http.retry.max_retries".to_string(),
format!("最大重试次数不能超过 {}", Self::MAX_RETRIES),
));
}
if self.max_retries == 0 {
return Ok(());
}
if self.retry_on.is_empty() {
return Err(BaseError::ParamInvalid(
"http.retry.retry_on".to_string(),
"启用重试时 retry_on 不能为空".to_string(),
));
}
if let Some(status) = self
.retry_on
.iter()
.copied()
.find(|status| !(100..=599).contains(status))
{
return Err(BaseError::ParamInvalid(
"http.retry.retry_on".to_string(),
format!("非法 HTTP 状态码: {status}"),
));
}
if self.backoff_ms == 0 {
return Err(BaseError::ParamInvalid(
"http.retry.backoff_ms".to_string(),
"启用重试时初始退避时间必须大于 0 毫秒".to_string(),
));
}
if self.backoff_ms > Self::MAX_BACKOFF_MS {
return Err(BaseError::ParamInvalid(
"http.retry.backoff_ms".to_string(),
format!("初始退避时间不能超过 {} 毫秒", Self::MAX_BACKOFF_MS),
));
}
Ok(())
}
}
pub struct RequestBuilder {
client: Client,
method: Method,
url: String,
headers: HeaderMap,
header_errors: Vec<String>,
query_params: Vec<(String, String)>,
body: Option<Vec<u8>>,
timeout: Duration,
token: Option<String>,
retry: Option<RetryConfig>,
circuit_breaker: Option<crate::http::CircuitBreaker>,
}
impl RequestBuilder {
pub(crate) fn new(
client: Client,
method: Method,
url: String,
timeout: Duration,
token: Option<String>,
circuit_breaker: Option<crate::http::CircuitBreaker>,
) -> Self {
Self {
client,
method,
url,
headers: HeaderMap::new(),
header_errors: Vec::new(),
query_params: Vec::new(),
body: None,
timeout,
token,
retry: None,
circuit_breaker,
}
}
pub fn header(mut self, name: &str, value: &str) -> Self {
let header_name = match HeaderName::from_bytes(name.as_bytes()) {
Ok(n) => n,
Err(e) => {
self.header_errors
.push(format!("非法 header 名称 '{}': {}", name, e));
return self;
}
};
let header_value = match HeaderValue::from_str(value) {
Ok(v) => v,
Err(e) => {
self.header_errors
.push(format!("非法 header 值 '{}': {}", value, e));
return self;
}
};
self.headers.insert(header_name, header_value);
self
}
pub fn headers(mut self, headers: Vec<(&str, &str)>) -> Self {
for (name, value) in headers {
let header_name = match HeaderName::from_bytes(name.as_bytes()) {
Ok(n) => n,
Err(e) => {
self.header_errors
.push(format!("非法 header 名称 '{}': {}", name, e));
continue;
}
};
let header_value = match HeaderValue::from_str(value) {
Ok(v) => v,
Err(e) => {
self.header_errors
.push(format!("非法 header 值 '{}': {}", value, e));
continue;
}
};
self.headers.insert(header_name, header_value);
}
self
}
pub fn content_type(self, content_type: &str) -> Self {
self.header("Content-Type", content_type)
}
pub fn bearer_token(mut self, token: &str) -> Self {
self.token = Some(token.to_string());
self
}
pub fn user_agent(self, user_agent: &str) -> Self {
self.header("User-Agent", user_agent)
}
pub fn query(mut self, key: &str, value: &str) -> Self {
self.query_params.push((key.to_string(), value.to_string()));
self
}
pub fn queries(mut self, params: Vec<(&str, &str)>) -> Self {
for (key, value) in params {
self.query_params.push((key.to_string(), value.to_string()));
}
self
}
pub fn json<T: Serialize>(mut self, json: &T) -> Result<Self, BaseError> {
let json_bytes =
serde_json::to_vec(json).map_err(|e| BaseError::JsonSerializeFailed(e.to_string()))?;
self.body = Some(json_bytes);
self = self.content_type("application/json");
Ok(self)
}
pub fn form(mut self, form: Vec<(&str, &str)>) -> Self {
match serde_urlencoded::to_string(&form) {
Ok(encoded) => {
self.body = Some(encoded.into_bytes());
self = self.content_type("application/x-www-form-urlencoded");
}
Err(e) => {
self.header_errors.push(format!("表单数据编码失败: {}", e));
}
}
self
}
pub fn body(mut self, body: Vec<u8>) -> Self {
self.body = Some(body);
self
}
pub fn text(mut self, text: &str) -> Self {
self.body = Some(text.as_bytes().to_vec());
self = self.content_type("text/plain");
self
}
pub fn timeout(mut self, timeout_secs: u64) -> Self {
self.timeout = Duration::from_secs(timeout_secs);
self
}
pub fn retry(mut self, config: RetryConfig) -> Self {
self.retry = Some(config);
self
}
pub async fn send(self) -> Result<Response, BaseError> {
if !self.header_errors.is_empty() {
return Err(BaseError::ParamInvalid(
"header".to_string(),
self.header_errors.join("; "),
));
}
if self
.query_params
.iter()
.any(|(key, _)| key.trim().is_empty())
{
return Err(BaseError::ParamInvalid(
"query".to_string(),
"query 参数名称不能为空".to_string(),
));
}
let parsed_url = reqwest::Url::parse(&self.url).map_err(|err| {
BaseError::ParamInvalid("url".to_string(), format!("非法 HTTP URL: {}", err))
})?;
if !matches!(parsed_url.scheme(), "http" | "https") {
return Err(BaseError::ParamInvalid(
"url".to_string(),
"HTTP 客户端仅支持 http 和 https URL".to_string(),
));
}
if let Some(token) = &self.token {
let auth_value = format!("Bearer {}", token);
if let Err(err) = HeaderValue::from_str(&auth_value) {
return Err(BaseError::ParamInvalid(
"authorization".to_string(),
format!("非法 bearer token,无法构造 Authorization 头: {}", err),
));
}
}
if self.timeout.is_zero() {
return Err(BaseError::ParamInvalid(
"http.timeout_secs".to_string(),
"HTTP 请求超时时间必须大于 0 秒".to_string(),
));
}
if let Some(retry) = &self.retry {
retry.validate()?;
}
let retry = self.retry.clone();
let host = self
.circuit_breaker
.as_ref()
.and_then(|_| parsed_url.host_str().map(|h| h.to_string()));
let Some(retry) = retry else {
return self.send_guarded(host.as_deref()).await;
};
let mut attempt: u32 = 0;
loop {
let result = self.send_guarded(host.as_deref()).await;
let should_retry = match &result {
Ok(resp) => retry.retry_on.contains(&resp.status()),
Err(BaseError::HttpRequestFailed(_)) => true,
Err(_) => false,
};
if !should_retry || attempt >= retry.max_retries {
return result;
}
let backoff = retry.backoff_ms.saturating_mul(1u64 << attempt.min(20));
if backoff > 0 {
tokio::time::sleep(Duration::from_millis(backoff)).await;
}
attempt += 1;
}
}
async fn send_guarded(&self, host: Option<&str>) -> Result<Response, BaseError> {
let breaker = self.circuit_breaker.as_ref();
if let (Some(breaker), Some(host)) = (breaker, host) {
if !breaker.allow(host) {
return Err(BaseError::HttpCircuitBreakerOpen(host.to_string()));
}
}
let result = self.send_once().await;
if let (Some(breaker), Some(host)) = (breaker, host) {
match &result {
Ok(resp) if resp.status() >= 500 => breaker.on_failure(host),
Ok(_) => breaker.on_success(host),
Err(_) => breaker.on_failure(host),
}
}
result
}
async fn send_once(&self) -> Result<Response, BaseError> {
let mut request = self
.client
.request(self.method.clone(), &self.url)
.timeout(self.timeout);
request = request.headers(self.headers.clone());
if let Some(token) = &self.token {
request = request.bearer_auth(token);
}
if !self.query_params.is_empty() {
request = request.query(&self.query_params);
}
if let Some(body) = &self.body {
request = request.body(body.clone());
}
let start = std::time::Instant::now();
let result = request.send().await;
let elapsed_ms = start.elapsed().as_millis();
let log_url = redact_url_for_log(&self.url);
match &result {
Ok(resp) => {
tracing::debug!(
target: "yang_base::http",
method = %self.method,
url = %log_url,
status = resp.status().as_u16(),
elapsed_ms = elapsed_ms as u64,
"HTTP 出站请求完成"
);
}
Err(e) => {
tracing::warn!(
target: "yang_base::http",
method = %self.method,
url = %log_url,
elapsed_ms = elapsed_ms as u64,
error = %e,
"HTTP 出站请求失败"
);
}
}
let response = result.map_err(BaseError::HttpRequestFailed)?;
Ok(Response::new(response))
}
}
#[cfg(test)]
mod retry_config_tests {
use super::*;
#[test]
fn test_redact_url_for_log_removes_query_and_userinfo() {
let redacted = redact_url_for_log("https://user:secret@example.com/path?token=secret&x=1");
assert_eq!(redacted, "https://***:***@example.com/path");
assert!(!redacted.contains("token"));
assert!(!redacted.contains("secret"));
assert!(!redacted.contains("user"));
}
#[test]
fn test_retry_config_validate_rejects_unsafe_values() {
let invalid_configs = [
RetryConfig {
max_retries: 11,
..RetryConfig::default()
},
RetryConfig {
max_retries: 1,
retry_on: Vec::new(),
..RetryConfig::default()
},
RetryConfig {
max_retries: 1,
backoff_ms: 0,
..RetryConfig::default()
},
RetryConfig {
max_retries: 1,
backoff_ms: 60_001,
..RetryConfig::default()
},
RetryConfig {
max_retries: 1,
retry_on: vec![99],
..RetryConfig::default()
},
RetryConfig {
max_retries: 1,
retry_on: vec![600],
..RetryConfig::default()
},
];
for config in invalid_configs {
assert!(matches!(
config.validate(),
Err(BaseError::ParamInvalid(_, _))
));
}
}
#[tokio::test]
async fn test_send_rejects_invalid_retry_config_before_network() {
let builder = RequestBuilder::new(
Client::new(),
Method::GET,
"http://127.0.0.1:1".to_string(),
Duration::from_secs(30),
None,
None,
)
.retry(RetryConfig {
max_retries: 11,
..RetryConfig::default()
});
let err = match builder.send().await {
Ok(_) => panic!("无效 retry 配置应在网络请求前被拒绝"),
Err(err) => err,
};
assert!(
matches!(err, BaseError::ParamInvalid(field, _) if field == "http.retry.max_retries")
);
}
#[tokio::test]
async fn test_send_rejects_zero_request_timeout_before_network() {
let builder = RequestBuilder::new(
Client::new(),
Method::GET,
"http://127.0.0.1:1".to_string(),
Duration::from_secs(30),
None,
None,
)
.timeout(0);
let err = match builder.send().await {
Ok(_) => panic!("0 秒请求超时应在网络请求前被拒绝"),
Err(err) => err,
};
assert!(matches!(err, BaseError::ParamInvalid(field, _) if field == "http.timeout_secs"));
}
#[tokio::test]
async fn test_send_rejects_blank_query_key_before_network() {
let client = crate::http::HttpClient::new(30).expect("HTTP client should be valid");
let result = client
.get("https://api.example.com/users")
.query(" ", "value")
.send()
.await;
let err = match result {
Err(err) => err,
Ok(_) => panic!("空白 query key 应在发送前被拒绝"),
};
assert!(matches!(
err,
crate::error::BaseError::ParamInvalid(field, _) if field == "query"
));
}
#[tokio::test]
async fn test_send_rejects_invalid_bearer_token_before_network() {
let builder = RequestBuilder::new(
Client::new(),
Method::GET,
"http://127.0.0.1:1".to_string(),
Duration::from_secs(30),
Some("bad\r\ntoken".to_string()),
None,
);
let err = match builder.send().await {
Ok(_) => panic!("非法 bearer token 应在网络请求前被拒绝"),
Err(err) => err,
};
assert!(matches!(err, BaseError::ParamInvalid(field, _) if field == "authorization"));
}
#[tokio::test]
async fn test_send_rejects_invalid_url_before_network() {
let invalid_urls = ["not a url", "ftp://example.com/file"];
for url in invalid_urls {
let builder = RequestBuilder::new(
Client::new(),
Method::GET,
url.to_string(),
Duration::from_secs(30),
None,
None,
);
let err = match builder.send().await {
Ok(_) => panic!("非法 URL 应在网络请求前被拒绝"),
Err(err) => err,
};
assert!(matches!(err, BaseError::ParamInvalid(field, _) if field == "url"));
}
}
}