1use crate::error::BaseError;
6use crate::http::response::Response;
7use reqwest::header::{HeaderMap, HeaderName, HeaderValue};
8use reqwest::{Client, Method};
9use serde::Serialize;
10use std::time::Duration;
11
12fn is_idempotent_method(method: &Method) -> bool {
20 *method == Method::GET
21 || *method == Method::HEAD
22 || *method == Method::OPTIONS
23 || *method == Method::TRACE
24 || *method == Method::PUT
25 || *method == Method::DELETE
26}
27
28fn redact_url_for_log(url: &str) -> String {
29 let Ok(mut parsed_url) = reqwest::Url::parse(url) else {
30 return "<invalid-url>".to_string();
31 };
32
33 parsed_url.set_query(None);
34 parsed_url.set_fragment(None);
35 if !parsed_url.username().is_empty() {
36 let _ = parsed_url.set_username("***");
37 }
38 if parsed_url.password().is_some() {
39 let _ = parsed_url.set_password(Some("***"));
40 }
41
42 parsed_url.to_string()
43}
44
45#[derive(Debug, Clone)]
78pub struct RetryConfig {
79 pub max_retries: u32,
81 pub retry_on: Vec<u16>,
83 pub backoff_ms: u64,
85 pub retry_non_idempotent: bool,
91 pub total_budget_ms: u64,
97 pub jitter_percent: u8,
103}
104
105impl Default for RetryConfig {
106 fn default() -> Self {
107 Self {
108 max_retries: 3,
109 retry_on: vec![502, 503, 504],
110 backoff_ms: 100,
111 retry_non_idempotent: false,
112 total_budget_ms: 30_000,
113 jitter_percent: 25,
114 }
115 }
116}
117
118impl RetryConfig {
119 const MAX_RETRIES: u32 = 10;
120 const MAX_BACKOFF_MS: u64 = 60_000;
121 const MAX_TOTAL_BUDGET_MS: u64 = 300_000;
122
123 pub fn validate(&self) -> Result<(), BaseError> {
127 if self.max_retries > Self::MAX_RETRIES {
128 return Err(BaseError::ParamInvalid(
129 "http.retry.max_retries".to_string(),
130 format!("最大重试次数不能超过 {}", Self::MAX_RETRIES),
131 ));
132 }
133
134 if self.max_retries == 0 {
135 return Ok(());
136 }
137
138 if self.retry_on.is_empty() {
139 return Err(BaseError::ParamInvalid(
140 "http.retry.retry_on".to_string(),
141 "启用重试时 retry_on 不能为空".to_string(),
142 ));
143 }
144
145 if let Some(status) = self
146 .retry_on
147 .iter()
148 .copied()
149 .find(|status| !(100..=599).contains(status))
150 {
151 return Err(BaseError::ParamInvalid(
152 "http.retry.retry_on".to_string(),
153 format!("非法 HTTP 状态码: {status}"),
154 ));
155 }
156
157 if self.backoff_ms == 0 {
158 return Err(BaseError::ParamInvalid(
159 "http.retry.backoff_ms".to_string(),
160 "启用重试时初始退避时间必须大于 0 毫秒".to_string(),
161 ));
162 }
163
164 if self.backoff_ms > Self::MAX_BACKOFF_MS {
165 return Err(BaseError::ParamInvalid(
166 "http.retry.backoff_ms".to_string(),
167 format!("初始退避时间不能超过 {} 毫秒", Self::MAX_BACKOFF_MS),
168 ));
169 }
170
171 if self.total_budget_ms == 0 || self.total_budget_ms > Self::MAX_TOTAL_BUDGET_MS {
172 return Err(BaseError::ParamInvalid(
173 "http.retry.total_budget_ms".to_string(),
174 format!("重试总预算必须在 1..={} 毫秒内", Self::MAX_TOTAL_BUDGET_MS),
175 ));
176 }
177
178 if self.jitter_percent > 100 {
179 return Err(BaseError::ParamInvalid(
180 "http.retry.jitter_percent".to_string(),
181 "退避抖动百分比不能超过 100".to_string(),
182 ));
183 }
184
185 Ok(())
186 }
187}
188
189fn jittered_backoff(base_ms: u64, jitter_percent: u8, attempt: u32) -> u64 {
195 let jp = u64::from(jitter_percent.min(100));
196 if base_ms == 0 || jp == 0 {
197 return base_ms;
198 }
199
200 let span = base_ms / 100 * jp;
201 if span == 0 {
202 return base_ms;
203 }
204
205 let entropy = std::time::SystemTime::now()
206 .duration_since(std::time::UNIX_EPOCH)
207 .map_or(0, |d| u64::from(d.subsec_nanos()))
208 ^ u64::from(std::process::id())
209 ^ u64::from(attempt);
210
211 base_ms
212 .saturating_sub(span)
213 .saturating_add(entropy % span.saturating_mul(2).saturating_add(1))
214}
215
216pub struct RequestBuilder {
240 client: Client,
242
243 method: Method,
245
246 url: String,
248
249 headers: HeaderMap,
251
252 header_errors: Vec<String>,
257
258 query_params: Vec<(String, String)>,
260
261 body: Option<Vec<u8>>,
263
264 timeout: Duration,
266
267 max_response_bytes: usize,
269
270 token: Option<String>,
272
273 retry: Option<RetryConfig>,
275
276 circuit_breaker: Option<crate::http::CircuitBreaker>,
278}
279
280impl RequestBuilder {
281 pub(crate) fn new(
293 client: Client,
294 method: Method,
295 url: String,
296 timeout: Duration,
297 max_response_bytes: usize,
298 token: Option<String>,
299 circuit_breaker: Option<crate::http::CircuitBreaker>,
300 ) -> Self {
301 Self {
302 client,
303 method,
304 url,
305 headers: HeaderMap::new(),
306 header_errors: Vec::new(),
307 query_params: Vec::new(),
308 body: None,
309 timeout,
310 max_response_bytes,
311 token,
312 retry: None,
313 circuit_breaker,
314 }
315 }
316
317 pub fn header(mut self, name: &str, value: &str) -> Self {
337 let header_name = match HeaderName::from_bytes(name.as_bytes()) {
339 Ok(n) => n,
340 Err(e) => {
341 self.header_errors
343 .push(format!("非法 header 名称 '{}': {}", name, e));
344 return self;
345 }
346 };
347
348 let header_value = match HeaderValue::from_str(value) {
350 Ok(v) => v,
351 Err(e) => {
352 self.header_errors
354 .push(format!("非法 header 值 '{}': {}", value, e));
355 return self;
356 }
357 };
358
359 self.headers.insert(header_name, header_value);
360 self
361 }
362
363 pub fn headers(mut self, headers: Vec<(&str, &str)>) -> Self {
385 for (name, value) in headers {
386 let header_name = match HeaderName::from_bytes(name.as_bytes()) {
388 Ok(n) => n,
389 Err(e) => {
390 self.header_errors
392 .push(format!("非法 header 名称 '{}': {}", name, e));
393 continue;
394 }
395 };
396
397 let header_value = match HeaderValue::from_str(value) {
399 Ok(v) => v,
400 Err(e) => {
401 self.header_errors
403 .push(format!("非法 header 值 '{}': {}", value, e));
404 continue;
405 }
406 };
407
408 self.headers.insert(header_name, header_value);
409 }
410 self
411 }
412
413 pub fn content_type(self, content_type: &str) -> Self {
429 self.header("Content-Type", content_type)
430 }
431
432 pub fn bearer_token(mut self, token: &str) -> Self {
448 self.token = Some(token.to_string());
449 self
450 }
451
452 pub fn user_agent(self, user_agent: &str) -> Self {
468 self.header("User-Agent", user_agent)
469 }
470
471 pub fn query(mut self, key: &str, value: &str) -> Self {
489 self.query_params.push((key.to_string(), value.to_string()));
490 self
491 }
492
493 pub fn queries(mut self, params: Vec<(&str, &str)>) -> Self {
509 for (key, value) in params {
510 self.query_params.push((key.to_string(), value.to_string()));
511 }
512 self
513 }
514
515 pub fn json<T: Serialize>(mut self, json: &T) -> Result<Self, BaseError> {
547 let json_bytes =
548 serde_json::to_vec(json).map_err(|e| BaseError::JsonSerializeFailed(e.to_string()))?;
549
550 self.body = Some(json_bytes);
551 self = self.content_type("application/json");
552
553 Ok(self)
554 }
555
556 pub fn form(mut self, form: Vec<(&str, &str)>) -> Self {
575 match serde_urlencoded::to_string(&form) {
577 Ok(encoded) => {
578 self.body = Some(encoded.into_bytes());
579 self = self.content_type("application/x-www-form-urlencoded");
581 }
582 Err(e) => {
583 self.header_errors.push(format!("表单数据编码失败: {}", e));
585 }
586 }
587 self
588 }
589
590 pub fn body(mut self, body: Vec<u8>) -> Self {
606 self.body = Some(body);
607 self
608 }
609
610 pub fn text(mut self, text: &str) -> Self {
626 self.body = Some(text.as_bytes().to_vec());
627 self = self.content_type("text/plain");
628 self
629 }
630
631 pub fn timeout(mut self, timeout_secs: u64) -> Self {
647 self.timeout = Duration::from_secs(timeout_secs);
648 self
649 }
650
651 pub fn max_response_bytes(mut self, bytes: usize) -> Self {
670 self.max_response_bytes = bytes;
671 self
672 }
673
674 pub fn retry(mut self, config: RetryConfig) -> Self {
697 self.retry = Some(config);
698 self
699 }
700
701 pub async fn send(self) -> Result<Response, BaseError> {
721 if !self.header_errors.is_empty() {
723 return Err(BaseError::ParamInvalid(
724 "header".to_string(),
725 self.header_errors.join("; "),
726 ));
727 }
728
729 if self
730 .query_params
731 .iter()
732 .any(|(key, _)| key.trim().is_empty())
733 {
734 return Err(BaseError::ParamInvalid(
735 "query".to_string(),
736 "query 参数名称不能为空".to_string(),
737 ));
738 }
739
740 let parsed_url = reqwest::Url::parse(&self.url).map_err(|err| {
741 BaseError::ParamInvalid("url".to_string(), format!("非法 HTTP URL: {}", err))
742 })?;
743 if !matches!(parsed_url.scheme(), "http" | "https") {
744 return Err(BaseError::ParamInvalid(
745 "url".to_string(),
746 "HTTP 客户端仅支持 http 和 https URL".to_string(),
747 ));
748 }
749
750 if let Some(token) = &self.token {
751 let auth_value = format!("Bearer {}", token);
752 if let Err(err) = HeaderValue::from_str(&auth_value) {
753 return Err(BaseError::ParamInvalid(
754 "authorization".to_string(),
755 format!("非法 bearer token,无法构造 Authorization 头: {}", err),
756 ));
757 }
758 }
759
760 if self.timeout.is_zero() {
761 return Err(BaseError::ParamInvalid(
762 "http.timeout_secs".to_string(),
763 "HTTP 请求超时时间必须大于 0 秒".to_string(),
764 ));
765 }
766
767 if self.max_response_bytes == 0 {
768 return Err(BaseError::ParamInvalid(
769 "http.max_response_bytes".to_string(),
770 "HTTP 响应体上限必须大于 0 字节".to_string(),
771 ));
772 }
773
774 if let Some(retry) = &self.retry {
775 retry.validate()?;
776 }
777
778 let retry = self.retry.clone();
779
780 let host = self
782 .circuit_breaker
783 .as_ref()
784 .and_then(|_| parsed_url.host_str().map(|h| h.to_string()));
785
786 let Some(retry) = retry else {
788 return self.send_guarded(host.as_deref()).await;
789 };
790
791 if !is_idempotent_method(&self.method) && !retry.retry_non_idempotent {
795 return self.send_guarded(host.as_deref()).await;
796 }
797
798 let mut attempt: u32 = 0;
801 let mut remaining_budget_ms = retry.total_budget_ms;
802 loop {
803 let result = self.send_guarded(host.as_deref()).await;
804
805 let should_retry = match &result {
806 Ok(resp) => retry.retry_on.contains(&resp.status()),
808 Err(BaseError::HttpRequestFailed(_)) => true,
810 Err(_) => false,
812 };
813
814 if !should_retry || attempt >= retry.max_retries {
815 return result;
816 }
817
818 let base = retry.backoff_ms.saturating_mul(1u64 << attempt.min(20));
822 let sleep_ms =
823 jittered_backoff(base, retry.jitter_percent, attempt).min(remaining_budget_ms);
824 if sleep_ms == 0 {
825 return result;
826 }
827
828 tokio::time::sleep(Duration::from_millis(sleep_ms)).await;
829 remaining_budget_ms -= sleep_ms;
830 attempt += 1;
831 }
832 }
833
834 async fn send_guarded(&self, host: Option<&str>) -> Result<Response, BaseError> {
842 let breaker = self.circuit_breaker.as_ref();
843
844 if let (Some(breaker), Some(host)) = (breaker, host) {
845 if !breaker.allow(host) {
846 return Err(BaseError::HttpCircuitBreakerOpen(host.to_string()));
847 }
848 }
849
850 let result = self.send_once().await;
851
852 if let (Some(breaker), Some(host)) = (breaker, host) {
853 match &result {
854 Ok(resp) if resp.status() >= 500 => breaker.on_failure(host),
855 Ok(_) => breaker.on_success(host),
856 Err(_) => breaker.on_failure(host),
857 }
858 }
859
860 result
861 }
862
863 async fn send_once(&self) -> Result<Response, BaseError> {
868 let mut request = self
871 .client
872 .request(self.method.clone(), &self.url)
873 .timeout(self.timeout);
874
875 request = request.headers(self.headers.clone());
877
878 if let Some(token) = &self.token {
880 request = request.bearer_auth(token);
881 }
882
883 if !self.query_params.is_empty() {
885 request = request.query(&self.query_params);
886 }
887
888 if let Some(body) = &self.body {
890 request = request.body(body.clone());
891 }
892
893 let start = std::time::Instant::now();
896 let result = request.send().await;
897 let elapsed_ms = start.elapsed().as_millis();
898 let log_url = redact_url_for_log(&self.url);
899 match &result {
900 Ok(resp) => {
901 tracing::debug!(
902 target: "yang_base::http",
903 method = %self.method,
904 url = %log_url,
905 status = resp.status().as_u16(),
906 elapsed_ms = elapsed_ms as u64,
907 "HTTP 出站请求完成"
908 );
909 }
910 Err(e) => {
911 tracing::warn!(
912 target: "yang_base::http",
913 method = %self.method,
914 url = %log_url,
915 elapsed_ms = elapsed_ms as u64,
916 timeout = e.is_timeout(),
917 connect = e.is_connect(),
918 builder = e.is_builder(),
919 request = e.is_request(),
920 "HTTP 出站请求失败"
921 );
922 }
923 }
924 let response = result.map_err(BaseError::HttpRequestFailed)?;
925
926 Ok(Response::new(response, self.max_response_bytes))
927 }
928}
929
930#[cfg(test)]
931mod retry_config_tests {
932 use super::*;
933 use std::sync::atomic::Ordering;
934
935 #[tokio::test]
936 async fn failed_request_logs_do_not_expose_url_secrets() {
937 let _ = rustls::crypto::ring::default_provider().install_default();
938 use std::io::Write;
939 use std::sync::{Arc, Mutex};
940 use tracing::instrument::WithSubscriber;
941 struct Writer(Arc<Mutex<Vec<u8>>>);
942 impl Write for Writer {
943 fn write(&mut self, bytes: &[u8]) -> std::io::Result<usize> {
944 self.0.lock().expect("日志锁").write(bytes)
945 }
946 fn flush(&mut self) -> std::io::Result<()> {
947 Ok(())
948 }
949 }
950 let buf = Arc::new(Mutex::new(Vec::new()));
951 let writer_buf = buf.clone();
952 let subscriber = tracing_subscriber::fmt()
953 .with_ansi(false)
954 .with_max_level(tracing::Level::DEBUG)
955 .with_writer(move || Writer(writer_buf.clone()))
956 .finish();
957 let listener = std::net::TcpListener::bind("127.0.0.1:0").expect("本地端口");
958 let port = listener.local_addr().expect("地址").port();
959 drop(listener);
960 let result = RequestBuilder::new(
961 Client::builder().no_proxy().build().expect("客户端"), Method::GET,
962 format!("http://user-secret:password-secret@127.0.0.1:{port}/path?token=query-secret#fragment-secret"),
963 Duration::from_secs(2), 1024, None, None
964 ).query("extra", "builder-secret").send().with_subscriber(subscriber).await;
965 let Err(BaseError::HttpRequestFailed(error)) = result else {
966 panic!("应返回原始请求错误");
967 };
968 assert!(
969 error.is_connect() || error.is_builder() || error.is_request(),
970 "{error:?}"
971 );
972 if let Some(url) = error.url() {
976 assert!(
977 url.query()
978 .is_some_and(|query| query.contains("builder-secret")),
979 "{url}"
980 );
981 }
982 let logs = String::from_utf8(buf.lock().expect("日志锁").clone()).expect("日志 UTF8");
983 assert!(logs.contains("HTTP 出站请求失败"));
984 for secret in [
985 "user-secret",
986 "password-secret",
987 "query-secret",
988 "fragment-secret",
989 "builder-secret",
990 ] {
991 assert!(!logs.contains(secret), "不得记录 {secret}: {logs}");
992 }
993 }
994
995 #[test]
996 fn test_redact_url_for_log_removes_query_and_userinfo() {
997 let redacted = redact_url_for_log("https://user:secret@example.com/path?token=secret&x=1");
998
999 assert_eq!(redacted, "https://***:***@example.com/path");
1000 assert!(!redacted.contains("token"));
1001 assert!(!redacted.contains("secret"));
1002 assert!(!redacted.contains("user"));
1003 }
1004
1005 #[test]
1006 fn test_retry_config_validate_rejects_unsafe_values() {
1007 let invalid_configs = [
1008 RetryConfig {
1009 max_retries: 11,
1010 ..RetryConfig::default()
1011 },
1012 RetryConfig {
1013 max_retries: 1,
1014 retry_on: Vec::new(),
1015 ..RetryConfig::default()
1016 },
1017 RetryConfig {
1018 max_retries: 1,
1019 backoff_ms: 0,
1020 ..RetryConfig::default()
1021 },
1022 RetryConfig {
1023 max_retries: 1,
1024 backoff_ms: 60_001,
1025 ..RetryConfig::default()
1026 },
1027 RetryConfig {
1028 max_retries: 1,
1029 retry_on: vec![99],
1030 ..RetryConfig::default()
1031 },
1032 RetryConfig {
1033 max_retries: 1,
1034 retry_on: vec![600],
1035 ..RetryConfig::default()
1036 },
1037 ];
1038
1039 for config in invalid_configs {
1040 assert!(matches!(
1041 config.validate(),
1042 Err(BaseError::ParamInvalid(_, _))
1043 ));
1044 }
1045 }
1046
1047 #[test]
1048 fn test_retry_config_validate_rejects_bad_budget_and_jitter() {
1049 let cases = [
1050 (
1052 "http.retry.total_budget_ms",
1053 RetryConfig {
1054 max_retries: 1,
1055 total_budget_ms: 0,
1056 ..RetryConfig::default()
1057 },
1058 ),
1059 (
1061 "http.retry.total_budget_ms",
1062 RetryConfig {
1063 max_retries: 1,
1064 total_budget_ms: RetryConfig::MAX_TOTAL_BUDGET_MS + 1,
1065 ..RetryConfig::default()
1066 },
1067 ),
1068 (
1070 "http.retry.jitter_percent",
1071 RetryConfig {
1072 max_retries: 1,
1073 jitter_percent: 101,
1074 ..RetryConfig::default()
1075 },
1076 ),
1077 ];
1078
1079 for (expected_field, config) in cases {
1080 let err = match config.validate() {
1081 Ok(()) => panic!("非法 {expected_field} 应被 validate() 拒绝"),
1082 Err(err) => err,
1083 };
1084 assert!(
1085 matches!(&err, BaseError::ParamInvalid(field, _) if field == expected_field),
1086 "期望 ParamInvalid({expected_field}),实际 {err:?}"
1087 );
1088 }
1089 }
1090
1091 #[test]
1092 fn test_retry_config_default_and_boundaries_are_valid() {
1093 assert!(
1094 RetryConfig::default().validate().is_ok(),
1095 "默认配置必须通过校验"
1096 );
1097
1098 assert!(RetryConfig {
1100 max_retries: 1,
1101 total_budget_ms: RetryConfig::MAX_TOTAL_BUDGET_MS,
1102 jitter_percent: 100,
1103 ..RetryConfig::default()
1104 }
1105 .validate()
1106 .is_ok());
1107 }
1108
1109 #[test]
1110 fn test_jittered_backoff_identity_and_bounds() {
1111 for base in [0_u64, 1, 99, 100, 1_000, u64::MAX] {
1113 assert_eq!(
1114 jittered_backoff(base, 0, 0),
1115 base,
1116 "jitter_percent=0 时退避时长不应改变"
1117 );
1118 }
1119
1120 assert_eq!(jittered_backoff(0, 100, 3), 0);
1122
1123 assert_eq!(jittered_backoff(50, 1, 0), 50);
1125
1126 let base = 1_000_u64;
1128 let span = base / 100 * 100;
1129 for attempt in 0..64 {
1130 let got = jittered_backoff(base, 100, attempt);
1131 assert!(
1132 (base - span..=base + span).contains(&got),
1133 "第 {attempt} 次抖动的退避 {got} 应落在 [{}, {}]",
1134 base - span,
1135 base + span
1136 );
1137 }
1138 }
1139
1140 fn spawn_503_listener() -> (
1144 std::net::SocketAddr,
1145 std::sync::Arc<std::sync::atomic::AtomicUsize>,
1146 ) {
1147 use std::io::{Read, Write};
1148 use std::sync::atomic::{AtomicUsize, Ordering};
1149 use std::sync::Arc;
1150
1151 let listener = std::net::TcpListener::bind("127.0.0.1:0").expect("本地监听端口应可绑定");
1152 let addr = listener.local_addr().expect("应能取得监听地址");
1153 let counter = Arc::new(AtomicUsize::new(0));
1154 let counter_for_thread = Arc::clone(&counter);
1155
1156 std::thread::spawn(move || {
1157 for stream in listener.incoming() {
1158 let Ok(mut stream) = stream else { break };
1159 counter_for_thread.fetch_add(1, Ordering::SeqCst);
1160 let mut buf = [0u8; 1024];
1162 let _ = stream.read(&mut buf);
1163 let _ = stream.write_all(
1164 b"HTTP/1.1 503 Service Unavailable\r\nContent-Length: 0\r\nConnection: close\r\n\r\n",
1165 );
1166 let _ = stream.flush();
1167 }
1168 });
1169
1170 (addr, counter)
1171 }
1172
1173 #[tokio::test]
1175 async fn test_send_clamps_backoff_wait_to_total_budget() {
1176 let (addr, counter) = spawn_503_listener();
1177 let client = crate::http::HttpClient::new(30).expect("HTTP client should be valid");
1178
1179 let started = std::time::Instant::now();
1180 let result = client
1181 .get(&format!("http://{addr}/always-503"))
1182 .retry(RetryConfig {
1183 max_retries: 3,
1184 retry_on: vec![503],
1185 backoff_ms: 1_000,
1186 jitter_percent: 0,
1187 total_budget_ms: 5,
1188 ..RetryConfig::default()
1189 })
1190 .send()
1191 .await;
1192 let elapsed = started.elapsed();
1193
1194 let resp = match result {
1196 Ok(resp) => resp,
1197 Err(err) => panic!("预算耗尽后应返回最后一次响应而非错误: {err:?}"),
1198 };
1199 assert_eq!(resp.status(), 503);
1200
1201 assert!(
1203 elapsed < Duration::from_millis(500),
1204 "退避等待应被总预算钳制(未钳制需约 7s),实际耗时 {elapsed:?}"
1205 );
1206
1207 tokio::time::sleep(Duration::from_millis(200)).await;
1209 assert_eq!(
1210 counter.load(Ordering::SeqCst),
1211 2,
1212 "预算耗尽后应停止重试(首次 + 1 次重试共 2 次请求)"
1213 );
1214 }
1215
1216 #[tokio::test]
1217 async fn test_send_rejects_invalid_retry_config_before_network() {
1218 let builder = RequestBuilder::new(
1219 Client::new(),
1220 Method::GET,
1221 "http://127.0.0.1:1".to_string(),
1222 Duration::from_secs(30),
1223 10 * 1024 * 1024,
1224 None,
1225 None,
1226 )
1227 .retry(RetryConfig {
1228 max_retries: 11,
1229 ..RetryConfig::default()
1230 });
1231
1232 let err = match builder.send().await {
1233 Ok(_) => panic!("无效 retry 配置应在网络请求前被拒绝"),
1234 Err(err) => err,
1235 };
1236
1237 assert!(
1238 matches!(err, BaseError::ParamInvalid(field, _) if field == "http.retry.max_retries")
1239 );
1240 }
1241
1242 #[tokio::test]
1243 async fn test_send_rejects_zero_request_timeout_before_network() {
1244 let builder = RequestBuilder::new(
1245 Client::new(),
1246 Method::GET,
1247 "http://127.0.0.1:1".to_string(),
1248 Duration::from_secs(30),
1249 10 * 1024 * 1024,
1250 None,
1251 None,
1252 )
1253 .timeout(0);
1254
1255 let err = match builder.send().await {
1256 Ok(_) => panic!("0 秒请求超时应在网络请求前被拒绝"),
1257 Err(err) => err,
1258 };
1259
1260 assert!(matches!(err, BaseError::ParamInvalid(field, _) if field == "http.timeout_secs"));
1261 }
1262
1263 #[tokio::test]
1264 async fn test_send_rejects_blank_query_key_before_network() {
1265 let client = crate::http::HttpClient::new(30).expect("HTTP client should be valid");
1266 let result = client
1267 .get("https://api.example.com/users")
1268 .query(" ", "value")
1269 .send()
1270 .await;
1271
1272 let err = match result {
1273 Err(err) => err,
1274 Ok(_) => panic!("空白 query key 应在发送前被拒绝"),
1275 };
1276
1277 assert!(matches!(
1278 err,
1279 crate::error::BaseError::ParamInvalid(field, _) if field == "query"
1280 ));
1281 }
1282
1283 #[tokio::test]
1284 async fn test_send_rejects_invalid_bearer_token_before_network() {
1285 let builder = RequestBuilder::new(
1286 Client::new(),
1287 Method::GET,
1288 "http://127.0.0.1:1".to_string(),
1289 Duration::from_secs(30),
1290 10 * 1024 * 1024,
1291 Some("bad\r\ntoken".to_string()),
1292 None,
1293 );
1294
1295 let err = match builder.send().await {
1296 Ok(_) => panic!("非法 bearer token 应在网络请求前被拒绝"),
1297 Err(err) => err,
1298 };
1299
1300 assert!(matches!(err, BaseError::ParamInvalid(field, _) if field == "authorization"));
1301 }
1302
1303 #[tokio::test]
1304 async fn test_send_rejects_invalid_url_before_network() {
1305 let invalid_urls = ["not a url", "ftp://example.com/file"];
1306
1307 for url in invalid_urls {
1308 let builder = RequestBuilder::new(
1309 Client::new(),
1310 Method::GET,
1311 url.to_string(),
1312 Duration::from_secs(30),
1313 10 * 1024 * 1024,
1314 None,
1315 None,
1316 );
1317
1318 let err = match builder.send().await {
1319 Ok(_) => panic!("非法 URL 应在网络请求前被拒绝"),
1320 Err(err) => err,
1321 };
1322
1323 assert!(matches!(err, BaseError::ParamInvalid(field, _) if field == "url"));
1324 }
1325 }
1326
1327 #[test]
1328 fn test_is_idempotent_method_classification() {
1329 for method in [
1331 Method::GET,
1332 Method::HEAD,
1333 Method::OPTIONS,
1334 Method::TRACE,
1335 Method::PUT,
1336 Method::DELETE,
1337 ] {
1338 assert!(
1339 is_idempotent_method(&method),
1340 "{method} 应被判定为幂等/安全方法"
1341 );
1342 }
1343
1344 for method in [Method::POST, Method::PATCH] {
1346 assert!(
1347 !is_idempotent_method(&method),
1348 "{method} 不应被判定为幂等方法"
1349 );
1350 }
1351 }
1352
1353 fn spawn_closing_listener() -> (
1357 std::net::SocketAddr,
1358 std::sync::Arc<std::sync::atomic::AtomicUsize>,
1359 ) {
1360 use std::io::Read;
1361 use std::sync::atomic::{AtomicUsize, Ordering};
1362 use std::sync::Arc;
1363
1364 let listener = std::net::TcpListener::bind("127.0.0.1:0").expect("本地监听端口应可绑定");
1365 let addr = listener.local_addr().expect("应能取得监听地址");
1366 let counter = Arc::new(AtomicUsize::new(0));
1367 let counter_for_thread = Arc::clone(&counter);
1368
1369 std::thread::spawn(move || {
1370 for stream in listener.incoming() {
1371 let Ok(mut stream) = stream else { break };
1372 counter_for_thread.fetch_add(1, Ordering::SeqCst);
1373 let mut buf = [0u8; 1024];
1375 let _ = stream.read(&mut buf);
1376 }
1377 });
1378
1379 (addr, counter)
1380 }
1381
1382 #[tokio::test]
1385 #[ignore = "依赖网络栈行为,发起真实连接;默认跳过"]
1386 async fn test_post_not_retried_without_opt_in() {
1387 let (addr, counter) = spawn_closing_listener();
1388 let client = crate::http::HttpClient::new(1).expect("HTTP client should be valid");
1389
1390 let result = client
1391 .post(&format!("http://{addr}/never"))
1392 .retry(RetryConfig {
1393 max_retries: 3,
1394 retry_on: vec![503],
1395 backoff_ms: 1,
1396 retry_non_idempotent: false,
1397 ..RetryConfig::default()
1398 })
1399 .send()
1400 .await;
1401
1402 assert!(result.is_err(), "监听器直接断开,应返回传输错误");
1403 tokio::time::sleep(Duration::from_millis(200)).await;
1405 assert_eq!(
1406 counter.load(Ordering::SeqCst),
1407 1,
1408 "非幂等 POST 未 opt-in 时只应发送一次"
1409 );
1410 }
1411
1412 #[tokio::test]
1415 #[ignore = "依赖网络栈行为,发起真实连接;默认跳过"]
1416 async fn test_post_retried_when_opted_in() {
1417 let (addr, counter) = spawn_closing_listener();
1418 let client = crate::http::HttpClient::new(1).expect("HTTP client should be valid");
1419
1420 let result = client
1421 .post(&format!("http://{addr}/never"))
1422 .retry(RetryConfig {
1423 max_retries: 3,
1424 retry_on: vec![503],
1425 backoff_ms: 1,
1426 retry_non_idempotent: true,
1427 ..RetryConfig::default()
1428 })
1429 .send()
1430 .await;
1431
1432 assert!(result.is_err(), "监听器直接断开,应返回传输错误");
1433 tokio::time::sleep(Duration::from_millis(200)).await;
1434 assert_eq!(
1435 counter.load(Ordering::SeqCst),
1436 4,
1437 "opt-in 后应发送 1 + max_retries 次"
1438 );
1439 }
1440}