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