1use crate::error::BaseError;
8use crate::http::request::RequestBuilder;
9use reqwest::{Client, Method};
10use std::sync::{Arc, RwLock};
11use std::time::Duration;
12
13const DEFAULT_MAX_RESPONSE_BYTES: usize = 10 * 1024 * 1024;
15
16#[derive(Debug, Clone, Copy, PartialEq, Eq)]
26#[non_exhaustive]
27pub enum HttpRedirectPolicy {
28 None,
30 Limited(usize),
35}
36
37impl Default for HttpRedirectPolicy {
38 fn default() -> Self {
39 Self::Limited(10)
41 }
42}
43
44impl HttpRedirectPolicy {
45 fn to_reqwest(self) -> reqwest::redirect::Policy {
47 match self {
48 Self::None => reqwest::redirect::Policy::none(),
49 Self::Limited(max) => reqwest::redirect::Policy::limited(max),
50 }
51 }
52}
53
54#[derive(Debug, Clone)]
72#[non_exhaustive]
73pub struct HttpClientConfig {
74 pub timeout_secs: u64,
76
77 pub pool_max_idle_per_host: usize,
79
80 pub pool_idle_timeout_secs: u64,
82
83 pub user_agent: Option<String>,
85
86 pub accept_invalid_certs: bool,
88
89 pub proxy_url: Option<String>,
91
92 pub circuit_breaker: Option<crate::http::CircuitBreakerConfig>,
95
96 pub max_response_bytes: usize,
101
102 pub redirect: HttpRedirectPolicy,
109}
110
111impl Default for HttpClientConfig {
112 fn default() -> Self {
113 Self {
114 timeout_secs: 30,
115 pool_max_idle_per_host: 10,
116 pool_idle_timeout_secs: 90,
117 user_agent: None,
118 accept_invalid_certs: false,
119 proxy_url: None,
120 circuit_breaker: None,
121 max_response_bytes: DEFAULT_MAX_RESPONSE_BYTES,
122 redirect: HttpRedirectPolicy::default(),
123 }
124 }
125}
126
127impl HttpClientConfig {
128 pub fn validate(&self) -> Result<(), BaseError> {
132 if self.timeout_secs == 0 {
133 return Err(BaseError::ParamInvalid(
134 "http.timeout_secs".to_string(),
135 "HTTP 请求超时时间必须大于 0 秒".to_string(),
136 ));
137 }
138 if self.pool_max_idle_per_host == 0 {
139 return Err(BaseError::ParamInvalid(
140 "http.pool_max_idle_per_host".to_string(),
141 "每个主机最大空闲连接数必须大于 0".to_string(),
142 ));
143 }
144 if self.pool_idle_timeout_secs == 0 {
145 return Err(BaseError::ParamInvalid(
146 "http.pool_idle_timeout_secs".to_string(),
147 "连接池空闲超时时间必须大于 0 秒".to_string(),
148 ));
149 }
150 if self.max_response_bytes == 0 {
151 return Err(BaseError::ParamInvalid(
152 "http.max_response_bytes".to_string(),
153 "HTTP 响应体上限必须大于 0 字节".to_string(),
154 ));
155 }
156 if let Some(circuit_breaker) = &self.circuit_breaker {
157 circuit_breaker.validate()?;
158 }
159
160 Ok(())
161 }
162}
163
164#[cfg(test)]
165mod config_tests {
166 use super::*;
167
168 #[test]
169 fn test_http_client_config_validate_rejects_zero_values() {
170 let invalid_configs = [
171 HttpClientConfig {
172 timeout_secs: 0,
173 ..HttpClientConfig::default()
174 },
175 HttpClientConfig {
176 pool_max_idle_per_host: 0,
177 ..HttpClientConfig::default()
178 },
179 HttpClientConfig {
180 pool_idle_timeout_secs: 0,
181 ..HttpClientConfig::default()
182 },
183 HttpClientConfig {
184 max_response_bytes: 0,
185 ..HttpClientConfig::default()
186 },
187 ];
188
189 for config in invalid_configs {
190 let err = config.validate().expect_err("HTTP 客户端零值配置应被拒绝");
191
192 assert!(matches!(err, BaseError::ParamInvalid(_, _)));
193 }
194 }
195
196 #[test]
197 fn test_with_config_rejects_invalid_config_before_building_client() {
198 let config = HttpClientConfig {
199 timeout_secs: 0,
200 ..HttpClientConfig::default()
201 };
202
203 let err = HttpClient::with_config(config)
204 .expect_err("无效 HTTP 配置应在构建 reqwest client 前被拒绝");
205
206 assert!(matches!(err, BaseError::ParamInvalid(field, _) if field == "http.timeout_secs"));
207 }
208
209 #[test]
210 fn test_http_client_config_validate_rejects_invalid_circuit_breaker_config() {
211 let config = HttpClientConfig {
212 circuit_breaker: Some(crate::http::CircuitBreakerConfig {
213 failure_threshold: 0,
214 ..crate::http::CircuitBreakerConfig::default()
215 }),
216 ..HttpClientConfig::default()
217 };
218
219 let err = config
220 .validate()
221 .expect_err("HTTP 客户端应拒绝非法熔断器配置");
222
223 assert!(matches!(
224 err,
225 BaseError::ParamInvalid(field, _) if field == "http.circuit_breaker.failure_threshold"
226 ));
227 }
228
229 #[test]
230 fn test_default_redirect_policy_stays_backward_compatible_and_validates() {
231 assert_eq!(
234 HttpClientConfig::default().redirect,
235 HttpRedirectPolicy::Limited(10)
236 );
237 assert_eq!(
238 HttpRedirectPolicy::default(),
239 HttpRedirectPolicy::Limited(10)
240 );
241 assert!(HttpClientConfig::default().validate().is_ok());
242 assert!(HttpClientConfig {
243 redirect: HttpRedirectPolicy::None,
244 ..HttpClientConfig::default()
245 }
246 .validate()
247 .is_ok());
248 assert!(HttpClientConfig {
249 redirect: HttpRedirectPolicy::Limited(0),
250 ..HttpClientConfig::default()
251 }
252 .validate()
253 .is_ok());
254 }
255}
256
257#[cfg(test)]
258mod redirect_policy_tests {
259 use super::*;
260 use tokio::io::{AsyncReadExt, AsyncWriteExt};
261
262 async fn serve_once(response: Vec<u8>) -> std::net::SocketAddr {
264 let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
265 .await
266 .expect("本地监听端口应可绑定");
267 let addr = listener.local_addr().expect("应能取得监听地址");
268
269 tokio::spawn(async move {
270 let Ok((mut stream, _)) = listener.accept().await else {
271 return;
272 };
273 let mut buf = [0u8; 4096];
275 let _ = stream.read(&mut buf).await;
276 let _ = stream.write_all(&response).await;
277 let _ = stream.shutdown().await;
278 });
279
280 addr
281 }
282
283 fn found_response(location: &str) -> Vec<u8> {
284 format!(
285 "HTTP/1.1 302 Found\r\nLocation: {location}\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
286 )
287 .into_bytes()
288 }
289
290 fn ok_response(body: &str) -> Vec<u8> {
291 format!(
292 "HTTP/1.1 200 OK\r\nContent-Type: text/plain\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
293 body.len()
294 )
295 .into_bytes()
296 }
297
298 #[tokio::test]
301 async fn test_default_redirect_policy_follows_302_as_before() {
302 let target = serve_once(ok_response("ok")).await;
303 let target_url = format!("http://{target}/final");
304 let origin = serve_once(found_response(&target_url)).await;
305
306 let client = HttpClient::new(5).expect("默认客户端应可创建");
307 let response = client
308 .get(&format!("http://{origin}/start"))
309 .send()
310 .await
311 .expect("默认策略下请求应成功");
312
313 assert_eq!(response.status(), 200, "默认策略应跟随 302");
314 assert_eq!(
315 response.url(),
316 target_url,
317 "Response::url() 应返回跟随重定向后的最终 URL"
318 );
319 assert_eq!(
320 response.text().await.expect("应读到最终响应体"),
321 "ok",
322 "默认策略应落到重定向目标"
323 );
324 }
325
326 #[tokio::test]
329 async fn test_redirect_policy_none_returns_3xx_without_following() {
330 let target = serve_once(ok_response("must-not-be-read")).await;
331 let target_url = format!("http://{target}/final");
332 let origin = serve_once(found_response(&target_url)).await;
333
334 let client = HttpClient::with_config(HttpClientConfig {
335 redirect: HttpRedirectPolicy::None,
336 ..HttpClientConfig::default()
337 })
338 .expect("合法配置应创建客户端");
339
340 let response = client
341 .get(&format!("http://{origin}/start"))
342 .send()
343 .await
344 .expect("None 策略下 3xx 应作为成功响应返回");
345
346 assert_eq!(response.status(), 302, "None 应原样返回 3xx");
347 let location = response
348 .headers()
349 .get(reqwest::header::LOCATION)
350 .and_then(|value| value.to_str().ok())
351 .map(str::to_string);
352 assert_eq!(
353 location.as_deref(),
354 Some(target_url.as_str()),
355 "Location 必须保留给调用方做逐跳校验"
356 );
357 }
358
359 #[tokio::test]
362 async fn test_redirect_policy_limited_stops_after_configured_hops() {
363 let final_server = serve_once(ok_response("too-far")).await;
364 let second_url = format!("http://{final_server}/second");
365 let second = serve_once(found_response(&second_url)).await;
366 let first_url = format!("http://{second}/first");
367 let origin = serve_once(found_response(&first_url)).await;
368
369 let client = HttpClient::with_config(HttpClientConfig {
370 redirect: HttpRedirectPolicy::Limited(1),
371 ..HttpClientConfig::default()
372 })
373 .expect("合法配置应创建客户端");
374
375 let err = match client.get(&format!("http://{origin}/start")).send().await {
377 Ok(_) => panic!("超过跳数上限应返回请求错误"),
378 Err(err) => err,
379 };
380
381 assert!(
382 matches!(&err, BaseError::HttpRequestFailed(_)),
383 "跳数超限应映射为 HttpRequestFailed,实际: {err:?}"
384 );
385 }
386}
387
388#[derive(Clone, Debug)]
411pub struct HttpClient {
412 client: Client,
414
415 default_timeout: Duration,
417
418 max_response_bytes: usize,
420
421 default_token: Arc<RwLock<Option<String>>>,
423
424 circuit_breaker: Option<crate::http::CircuitBreaker>,
426}
427
428impl HttpClient {
429 pub fn with_config(cfg: HttpClientConfig) -> Result<Self, BaseError> {
453 cfg.validate()?;
454
455 let _ = rustls::crypto::ring::default_provider().install_default();
467
468 let mut builder = Client::builder()
470 .timeout(Duration::from_secs(cfg.timeout_secs))
471 .pool_max_idle_per_host(cfg.pool_max_idle_per_host)
472 .pool_idle_timeout(Duration::from_secs(cfg.pool_idle_timeout_secs))
473 .danger_accept_invalid_certs(cfg.accept_invalid_certs);
474
475 builder = builder.redirect(cfg.redirect.to_reqwest());
478
479 if let Some(ua) = cfg.user_agent {
481 builder = builder.user_agent(ua);
482 }
483
484 if let Some(proxy_url) = cfg.proxy_url {
486 let proxy =
487 reqwest::Proxy::all(&proxy_url).map_err(BaseError::HttpClientCreateFailed)?;
488 builder = builder.proxy(proxy);
489 }
490
491 let client = builder.build().map_err(BaseError::HttpClientCreateFailed)?;
492
493 let circuit_breaker = cfg
494 .circuit_breaker
495 .map(crate::http::CircuitBreaker::new)
496 .transpose()?;
497
498 Ok(Self {
499 client,
500 default_timeout: Duration::from_secs(cfg.timeout_secs),
501 max_response_bytes: cfg.max_response_bytes,
502 default_token: Arc::new(RwLock::new(None)),
503 circuit_breaker,
504 })
505 }
506
507 pub fn new(timeout_secs: u64) -> Result<Self, BaseError> {
526 Self::with_config(HttpClientConfig {
528 timeout_secs,
529 ..Default::default()
530 })
531 }
532
533 pub fn set_default_token(&self, token: String) {
546 let mut default_token = self
548 .default_token
549 .write()
550 .unwrap_or_else(|p| p.into_inner());
551 *default_token = Some(token);
552 log::debug!("已设置默认 Token");
553 }
554
555 fn get_default_token(&self) -> Option<String> {
557 let default_token = self.default_token.read().unwrap_or_else(|p| p.into_inner());
559 default_token.clone()
560 }
561
562 pub fn request(&self, method: Method, url: &str) -> RequestBuilder {
587 RequestBuilder::new(
589 self.client.clone(),
590 method,
591 url.to_string(),
592 self.default_timeout,
593 self.max_response_bytes,
594 self.get_default_token(),
595 self.circuit_breaker.clone(),
596 )
597 }
598
599 pub fn get(&self, url: &str) -> RequestBuilder {
618 self.request(Method::GET, url)
619 }
620
621 pub fn post(&self, url: &str) -> RequestBuilder {
641 self.request(Method::POST, url)
642 }
643
644 pub fn put(&self, url: &str) -> RequestBuilder {
664 self.request(Method::PUT, url)
665 }
666
667 pub fn delete(&self, url: &str) -> RequestBuilder {
686 self.request(Method::DELETE, url)
687 }
688
689 pub fn patch(&self, url: &str) -> RequestBuilder {
709 self.request(Method::PATCH, url)
710 }
711}