Skip to main content

yang_base/action/
request.rs

1//! Action 请求结构
2//!
3//! 提供 Action 系统的请求封装,包含请求体、请求头、查询参数和路径参数。
4
5use std::any::Any;
6use std::collections::HashMap;
7use std::fmt;
8use std::sync::Arc;
9
10fn parse_bearer_token(value: &str) -> Option<&str> {
11    let mut parts = value.split_whitespace();
12    let scheme = parts.next()?;
13    let token = parts.next()?;
14
15    if parts.next().is_some() || !scheme.eq_ignore_ascii_case("Bearer") {
16        return None;
17    }
18
19    Some(token)
20}
21
22/// Action 请求
23///
24/// 封装 HTTP 请求信息,用于 Action 执行
25///
26/// # 字段
27///
28/// - `body`: 请求体(JSON 格式)
29/// - `headers`: 请求头
30/// - `query`: 查询参数
31/// - `path_params`: 路径参数
32///
33/// # 示例
34///
35/// ```rust,ignore
36/// use yang_base::action::Request;
37/// use serde_json::json;
38/// use std::collections::HashMap;
39///
40/// // 创建请求
41/// let mut request = Request::new(json!({
42///     "username": "alice",
43///     "email": "alice@example.com"
44/// }));
45///
46/// // 添加请求头
47/// request = request.header("Content-Type", "application/json");
48/// request = request.header("Authorization", "Bearer token123");
49///
50/// // 添加查询参数
51/// request = request.query("page", "1");
52/// request = request.query("limit", "10");
53///
54/// // 添加路径参数
55/// request = request.path_param("id", "123");
56///
57/// // 提取 Token
58/// if let Some(token) = request.token() {
59///     println!("Token: {}", token);
60/// }
61/// ```
62pub struct Request {
63    /// 请求体(JSON)
64    pub body: serde_json::Value,
65
66    /// 请求头
67    pub headers: HashMap<String, String>,
68
69    /// 查询参数
70    pub query: HashMap<String, String>,
71
72    /// 路径参数
73    pub path_params: HashMap<String, String>,
74
75    /// 绑定请求生命周期的非业务资源;例如 multipart 临时目录。
76    resource_guards: Vec<Arc<dyn Any + Send + Sync>>,
77}
78
79impl Clone for Request {
80    fn clone(&self) -> Self {
81        Self {
82            body: self.body.clone(),
83            headers: self.headers.clone(),
84            query: self.query.clone(),
85            path_params: self.path_params.clone(),
86            // 请求作用域资源不得通过 Request::clone 逃逸 Handler 生命周期。
87            resource_guards: Vec::new(),
88        }
89    }
90}
91
92impl Request {
93    /// 创建新请求
94    ///
95    /// # 参数
96    ///
97    /// - `body`: 请求体(JSON 格式)
98    ///
99    /// # 返回
100    ///
101    /// - 新的 Request 实例
102    ///
103    /// # 示例
104    ///
105    /// ```rust,ignore
106    /// use yang_base::action::Request;
107    /// use serde_json::json;
108    ///
109    /// let request = Request::new(json!({
110    ///     "name": "Alice",
111    ///     "age": 30
112    /// }));
113    /// ```
114    pub fn new(body: serde_json::Value) -> Self {
115        Self {
116            body,
117            headers: HashMap::new(),
118            query: HashMap::new(),
119            path_params: HashMap::new(),
120            resource_guards: Vec::new(),
121        }
122    }
123
124    /// 添加请求头
125    ///
126    /// # 参数
127    ///
128    /// - `name`: 请求头名称
129    /// - `value`: 请求头值
130    ///
131    /// # 返回
132    ///
133    /// - 修改后的 Request 实例(支持链式调用)
134    ///
135    /// # 示例
136    ///
137    /// ```rust,ignore
138    /// use yang_base::action::Request;
139    /// use serde_json::json;
140    ///
141    /// let request = Request::new(json!({}))
142    ///     .header("Content-Type", "application/json")
143    ///     .header("Authorization", "Bearer token123");
144    /// ```
145    pub fn header(mut self, name: impl Into<String>, value: impl Into<String>) -> Self {
146        let name = name.into();
147        let name = name.trim();
148        if name.is_empty() {
149            return self;
150        }
151
152        self.headers.insert(name.to_ascii_lowercase(), value.into());
153        self
154    }
155
156    /// 批量添加请求头
157    ///
158    /// # 参数
159    ///
160    /// - `headers`: 请求头映射
161    ///
162    /// # 返回
163    ///
164    /// - 修改后的 Request 实例(支持链式调用)
165    ///
166    /// # 示例
167    ///
168    /// ```rust,ignore
169    /// use yang_base::action::Request;
170    /// use serde_json::json;
171    /// use std::collections::HashMap;
172    ///
173    /// let mut headers = HashMap::new();
174    /// headers.insert("Content-Type".to_string(), "application/json".to_string());
175    /// headers.insert("Authorization".to_string(), "Bearer token123".to_string());
176    ///
177    /// let request = Request::new(json!({}))
178    ///     .headers(headers);
179    /// ```
180    pub fn headers(mut self, headers: HashMap<String, String>) -> Self {
181        for (name, value) in headers {
182            self = self.header(name, value);
183        }
184        self
185    }
186
187    /// 添加查询参数
188    ///
189    /// # 参数
190    ///
191    /// - `key`: 参数名
192    /// - `value`: 参数值
193    ///
194    /// # 返回
195    ///
196    /// - 修改后的 Request 实例(支持链式调用)
197    ///
198    /// # 示例
199    ///
200    /// ```rust,ignore
201    /// use yang_base::action::Request;
202    /// use serde_json::json;
203    ///
204    /// let request = Request::new(json!({}))
205    ///     .query("page", "1")
206    ///     .query("limit", "10");
207    /// ```
208    pub fn query(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
209        let key = key.into();
210        let key = key.trim();
211        if key.is_empty() {
212            return self;
213        }
214
215        self.query.insert(key.to_string(), value.into());
216        self
217    }
218
219    /// 批量添加查询参数
220    ///
221    /// # 参数
222    ///
223    /// - `query`: 查询参数映射
224    ///
225    /// # 返回
226    ///
227    /// - 修改后的 Request 实例(支持链式调用)
228    ///
229    /// # 示例
230    ///
231    /// ```rust,ignore
232    /// use yang_base::action::Request;
233    /// use serde_json::json;
234    /// use std::collections::HashMap;
235    ///
236    /// let mut query = HashMap::new();
237    /// query.insert("page".to_string(), "1".to_string());
238    /// query.insert("limit".to_string(), "10".to_string());
239    ///
240    /// let request = Request::new(json!({}))
241    ///     .queries(query);
242    /// ```
243    pub fn queries(mut self, query: HashMap<String, String>) -> Self {
244        for (key, value) in query {
245            self = self.query(key, value);
246        }
247        self
248    }
249
250    /// 添加路径参数
251    ///
252    /// # 参数
253    ///
254    /// - `key`: 参数名
255    /// - `value`: 参数值
256    ///
257    /// # 返回
258    ///
259    /// - 修改后的 Request 实例(支持链式调用)
260    ///
261    /// # 示例
262    ///
263    /// ```rust,ignore
264    /// use yang_base::action::Request;
265    /// use serde_json::json;
266    ///
267    /// let request = Request::new(json!({}))
268    ///     .path_param("id", "123")
269    ///     .path_param("action", "update");
270    /// ```
271    pub fn path_param(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
272        let key = key.into();
273        let key = key.trim();
274        if key.is_empty() {
275            return self;
276        }
277
278        self.path_params.insert(key.to_string(), value.into());
279        self
280    }
281
282    /// 批量添加路径参数
283    ///
284    /// # 参数
285    ///
286    /// - `path_params`: 路径参数映射
287    ///
288    /// # 返回
289    ///
290    /// - 修改后的 Request 实例(支持链式调用)
291    ///
292    /// # 示例
293    ///
294    /// ```rust,ignore
295    /// use yang_base::action::Request;
296    /// use serde_json::json;
297    /// use std::collections::HashMap;
298    ///
299    /// let mut path_params = HashMap::new();
300    /// path_params.insert("id".to_string(), "123".to_string());
301    /// path_params.insert("action".to_string(), "update".to_string());
302    ///
303    /// let request = Request::new(json!({}))
304    ///     .path_params(path_params);
305    /// ```
306    pub fn path_params(mut self, path_params: HashMap<String, String>) -> Self {
307        for (key, value) in path_params {
308            self = self.path_param(key, value);
309        }
310        self
311    }
312
313    #[cfg(feature = "transport-axum")]
314    pub(crate) fn retain_resource<T>(mut self, resource: Arc<T>) -> Self
315    where
316        T: Any + Send + Sync,
317    {
318        self.resource_guards.push(resource);
319        self
320    }
321
322    /// 从 Authorization 头提取 Token
323    ///
324    /// 支持 Bearer Token 格式:`Authorization: Bearer <token>`
325    ///
326    /// # 返回
327    ///
328    /// - `Some(&str)`: Token 字符串
329    /// - `None`: 未找到 Token 或格式不正确
330    ///
331    /// # 示例
332    ///
333    /// ```rust,ignore
334    /// use yang_base::action::Request;
335    /// use serde_json::json;
336    ///
337    /// let request = Request::new(json!({}))
338    ///     .header("Authorization", "Bearer my_secret_token");
339    ///
340    /// assert_eq!(request.token(), Some("my_secret_token"));
341    /// ```
342    pub fn token(&self) -> Option<&str> {
343        self.get_header("authorization")
344            .and_then(parse_bearer_token)
345    }
346
347    /// 获取规范化 headers 中的 `User-Agent`。
348    pub fn user_agent(&self) -> Option<&str> {
349        self.get_header("user-agent")
350    }
351
352    /// 获取规范化 headers 中的 `Cookie`。
353    pub fn cookie(&self) -> Option<&str> {
354        self.get_header("cookie")
355    }
356
357    /// 获取请求头值
358    ///
359    /// # 参数
360    ///
361    /// - `name`: 请求头名称
362    ///
363    /// # 返回
364    ///
365    /// - `Some(&str)`: 请求头值
366    /// - `None`: 请求头不存在
367    ///
368    /// # 示例
369    ///
370    /// ```rust,ignore
371    /// use yang_base::action::Request;
372    /// use serde_json::json;
373    ///
374    /// let request = Request::new(json!({}))
375    ///     .header("Content-Type", "application/json");
376    ///
377    /// assert_eq!(request.get_header("Content-Type"), Some("application/json"));
378    /// ```
379    pub fn get_header(&self, name: &str) -> Option<&str> {
380        let name = name.trim();
381        if name.is_empty() {
382            return None;
383        }
384
385        self.headers
386            .get(name)
387            .or_else(|| {
388                self.headers
389                    .iter()
390                    .find_map(|(key, value)| key.eq_ignore_ascii_case(name).then_some(value))
391            })
392            .map(|s| s.as_str())
393    }
394
395    /// 获取查询参数值
396    ///
397    /// # 参数
398    ///
399    /// - `key`: 参数名
400    ///
401    /// # 返回
402    ///
403    /// - `Some(&str)`: 参数值
404    /// - `None`: 参数不存在
405    ///
406    /// # 示例
407    ///
408    /// ```rust,ignore
409    /// use yang_base::action::Request;
410    /// use serde_json::json;
411    ///
412    /// let request = Request::new(json!({}))
413    ///     .query("page", "1");
414    ///
415    /// assert_eq!(request.get_query("page"), Some("1"));
416    /// ```
417    pub fn get_query(&self, key: &str) -> Option<&str> {
418        let key = key.trim();
419        if key.is_empty() {
420            return None;
421        }
422
423        self.query.get(key).map(|s| s.as_str())
424    }
425
426    /// 获取路径参数值
427    ///
428    /// # 参数
429    ///
430    /// - `key`: 参数名
431    ///
432    /// # 返回
433    ///
434    /// - `Some(&str)`: 参数值
435    /// - `None`: 参数不存在
436    ///
437    /// # 示例
438    ///
439    /// ```rust,ignore
440    /// use yang_base::action::Request;
441    /// use serde_json::json;
442    ///
443    /// let request = Request::new(json!({}))
444    ///     .path_param("id", "123");
445    ///
446    /// assert_eq!(request.get_path_param("id"), Some("123"));
447    /// ```
448    pub fn get_path_param(&self, key: &str) -> Option<&str> {
449        let key = key.trim();
450        if key.is_empty() {
451            return None;
452        }
453
454        self.path_params.get(key).map(|s| s.as_str())
455    }
456}
457
458struct RedactedMap<'a>(&'a HashMap<String, String>);
459
460impl fmt::Debug for RedactedMap<'_> {
461    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
462        let mut map = formatter.debug_map();
463        for key in self.0.keys() {
464            map.entry(key, &"[REDACTED]");
465        }
466        map.finish()
467    }
468}
469
470/// `body` 的 Debug 安全摘要:只输出顶层类型 / 键名集合 / 长度,不输出任何值。
471///
472/// 纵深防御:登录密码、Refresh Token、验证码等凭据常以 JSON body 承载,
473/// `tracing::debug!(?ctx)` 等日志不应把它们写进日志。该摘要只保护 `Debug`
474/// 输出;显式读取 [`Request::body`] 的调用方(如审计快照)仍需自行脱敏。
475struct RedactedBody<'a>(&'a serde_json::Value);
476
477/// 不暴露值内容的类型/尺寸描述。
478fn body_shape_summary(value: &serde_json::Value) -> String {
479    match value {
480        serde_json::Value::Null => "null".to_string(),
481        serde_json::Value::Bool(_) => "bool".to_string(),
482        serde_json::Value::Number(_) => "number".to_string(),
483        serde_json::Value::String(value) => format!("string(len={})", value.len()),
484        serde_json::Value::Array(values) => format!("array(len={})", values.len()),
485        serde_json::Value::Object(map) => format!("object(keys={})", map.len()),
486    }
487}
488
489impl fmt::Debug for RedactedBody<'_> {
490    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
491        match self.0 {
492            serde_json::Value::Object(map) => {
493                let mut summary = formatter.debug_map();
494                for (key, value) in map {
495                    let shape = body_shape_summary(value);
496                    summary.entry(key, &format!("[REDACTED:{shape}]"));
497                }
498                summary.finish()
499            }
500            value => write!(formatter, "[REDACTED:{}]", body_shape_summary(value)),
501        }
502    }
503}
504
505impl fmt::Debug for Request {
506    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
507        formatter
508            .debug_struct("Request")
509            .field("body", &RedactedBody(&self.body))
510            .field("headers", &RedactedMap(&self.headers))
511            .field("query", &RedactedMap(&self.query))
512            .field("path_params", &RedactedMap(&self.path_params))
513            .field("resource_guard_count", &self.resource_guards.len())
514            .finish()
515    }
516}
517
518impl Default for Request {
519    fn default() -> Self {
520        Self::new(serde_json::Value::Null)
521    }
522}
523
524#[cfg(test)]
525mod tests {
526    use super::*;
527    use serde_json::json;
528    #[cfg(feature = "transport-axum")]
529    use std::sync::atomic::{AtomicUsize, Ordering};
530
531    #[cfg(feature = "transport-axum")]
532    struct DropResource(Arc<AtomicUsize>);
533
534    #[cfg(feature = "transport-axum")]
535    impl Drop for DropResource {
536        fn drop(&mut self) {
537            self.0.fetch_add(1, Ordering::SeqCst);
538        }
539    }
540
541    #[test]
542    fn test_header_lookup_is_case_insensitive() {
543        let request = Request::new(json!({}))
544            .header("Content-Type", "application/json")
545            .header("aUtHoRiZaTiOn", "Bearer token123");
546
547        assert_eq!(request.get_header("content-type"), Some("application/json"));
548        assert_eq!(request.get_header("AUTHORIZATION"), Some("Bearer token123"));
549        assert_eq!(request.token(), Some("token123"));
550    }
551
552    #[test]
553    #[cfg(feature = "transport-axum")]
554    fn clone_does_not_extend_request_scoped_resource_lifetime() {
555        let drops = Arc::new(AtomicUsize::new(0));
556        let resource = Arc::new(DropResource(Arc::clone(&drops)));
557        let request = Request::new(json!({})).retain_resource(Arc::clone(&resource));
558        drop(resource);
559        let cloned = request.clone();
560
561        drop(request);
562        assert_eq!(drops.load(Ordering::SeqCst), 1);
563        drop(cloned);
564        assert_eq!(drops.load(Ordering::SeqCst), 1);
565    }
566
567    #[test]
568    fn test_header_insert_normalizes_name_and_overwrites_case_variants() {
569        let request = Request::new(json!({}))
570            .header("Authorization", "Bearer old")
571            .header("authorization", "Bearer new");
572
573        assert_eq!(request.headers.len(), 1);
574        assert_eq!(
575            request.headers.get("authorization").map(String::as_str),
576            Some("Bearer new")
577        );
578        assert_eq!(request.get_header("Authorization"), Some("Bearer new"));
579        assert_eq!(request.token(), Some("new"));
580    }
581
582    #[test]
583    fn test_header_trims_name_before_normalizing() {
584        let request = Request::new(json!({})).header(" Authorization ", "Bearer token123");
585
586        assert_eq!(request.headers.len(), 1);
587        assert_eq!(request.get_header("authorization"), Some("Bearer token123"));
588        assert_eq!(
589            request.get_header(" Authorization "),
590            Some("Bearer token123")
591        );
592        assert_eq!(request.token(), Some("token123"));
593    }
594
595    #[test]
596    fn test_header_rejects_blank_names() {
597        let request = Request::new(json!({}))
598            .header("", "empty")
599            .header("   ", "blank")
600            .header("X-Request-Id", "abc");
601
602        assert_eq!(request.get_header("x-request-id"), Some("abc"));
603        assert_eq!(request.get_header(""), None);
604        assert_eq!(request.get_header("   "), None);
605    }
606
607    #[test]
608    fn test_get_header_rejects_blank_names() {
609        let mut request = Request::new(json!({}));
610        request.headers.insert("".to_string(), "empty".to_string());
611        request
612            .headers
613            .insert("   ".to_string(), "blank".to_string());
614        request
615            .headers
616            .insert("x-request-id".to_string(), "abc".to_string());
617
618        assert_eq!(request.get_header("x-request-id"), Some("abc"));
619        assert_eq!(request.get_header(""), None);
620        assert_eq!(request.get_header("   "), None);
621    }
622
623    #[test]
624    fn test_token_accepts_case_insensitive_bearer_scheme() {
625        let lower = Request::new(json!({})).header("authorization", "bearer lower-token");
626        let upper = Request::new(json!({})).header("authorization", "BEARER upper-token");
627
628        assert_eq!(lower.token(), Some("lower-token"));
629        assert_eq!(upper.token(), Some("upper-token"));
630    }
631
632    #[test]
633    fn test_token_trims_scheme_spacing_and_rejects_empty_or_split_token() {
634        let padded = Request::new(json!({})).header("authorization", "Bearer    padded-token");
635        let empty = Request::new(json!({})).header("authorization", "Bearer ");
636        let split = Request::new(json!({})).header("authorization", "Bearer token extra");
637
638        assert_eq!(padded.token(), Some("padded-token"));
639        assert_eq!(empty.token(), None);
640        assert_eq!(split.token(), None);
641    }
642
643    #[test]
644    fn test_query_rejects_blank_keys() {
645        let request = Request::new(json!({}))
646            .query("", "empty")
647            .query("   ", "blank")
648            .query("page", "1");
649
650        let mut query = std::collections::HashMap::new();
651        query.insert("".to_string(), "empty-bulk".to_string());
652        query.insert("   ".to_string(), "blank-bulk".to_string());
653        query.insert("limit".to_string(), "10".to_string());
654
655        let request = request.queries(query);
656
657        assert_eq!(request.get_query("page"), Some("1"));
658        assert_eq!(request.get_query("limit"), Some("10"));
659        assert_eq!(request.get_query(""), None);
660        assert_eq!(request.get_query("   "), None);
661    }
662
663    #[test]
664    fn test_query_trims_keys_before_storing() {
665        let request = Request::new(json!({})).query(" page ", "1");
666
667        assert_eq!(request.query.len(), 1);
668        assert_eq!(request.get_query("page"), Some("1"));
669        assert_eq!(request.get_query(" page "), Some("1"));
670    }
671
672    #[test]
673    fn test_get_query_rejects_blank_keys() {
674        let mut request = Request::new(json!({}));
675        request.query.insert("".to_string(), "empty".to_string());
676        request.query.insert("   ".to_string(), "blank".to_string());
677        request.query.insert("page".to_string(), "1".to_string());
678
679        assert_eq!(request.get_query("page"), Some("1"));
680        assert_eq!(request.get_query(""), None);
681        assert_eq!(request.get_query("   "), None);
682    }
683
684    #[test]
685    fn test_path_param_rejects_blank_keys() {
686        let request = Request::new(json!({}))
687            .path_param("", "empty")
688            .path_param("   ", "blank")
689            .path_param("id", "42");
690
691        let mut path_params = std::collections::HashMap::new();
692        path_params.insert("".to_string(), "empty-bulk".to_string());
693        path_params.insert("   ".to_string(), "blank-bulk".to_string());
694        path_params.insert("slug".to_string(), "demo".to_string());
695
696        let request = request.path_params(path_params);
697
698        assert_eq!(request.get_path_param("id"), Some("42"));
699        assert_eq!(request.get_path_param("slug"), Some("demo"));
700        assert_eq!(request.get_path_param(""), None);
701        assert_eq!(request.get_path_param("   "), None);
702    }
703
704    #[test]
705    fn test_path_param_trims_keys_before_storing() {
706        let request = Request::new(json!({})).path_param(" id ", "42");
707
708        assert_eq!(request.path_params.len(), 1);
709        assert_eq!(request.get_path_param("id"), Some("42"));
710        assert_eq!(request.get_path_param(" id "), Some("42"));
711    }
712
713    #[test]
714    fn test_get_path_param_rejects_blank_keys() {
715        let mut request = Request::new(json!({}));
716        request
717            .path_params
718            .insert("".to_string(), "empty".to_string());
719        request
720            .path_params
721            .insert("   ".to_string(), "blank".to_string());
722        request
723            .path_params
724            .insert("id".to_string(), "42".to_string());
725
726        assert_eq!(request.get_path_param("id"), Some("42"));
727        assert_eq!(request.get_path_param(""), None);
728        assert_eq!(request.get_path_param("   "), None);
729    }
730
731    #[test]
732    fn debug_redacts_request_body_values() {
733        // F030 RED 场景:旧 Debug 直接输出 `body`,登录密码、Refresh Token 等
734        // 凭据会经 `format!("{request:?}")` / `tracing::debug!(?ctx)` 进入日志。
735        let request = Request::new(json!({
736            "username": "alice",
737            "password": "body-password-secret",
738            "refresh_token": "body-refresh-secret",
739            "nested": { "code": "body-code-secret" },
740            "items": ["body-list-secret"],
741        }))
742        .header("Authorization", "Bearer header-secret")
743        .query("access_token", "query-secret")
744        .path_param("session", "path-secret");
745
746        let debug = format!("{request:?}");
747        for secret in [
748            "alice",
749            "body-password-secret",
750            "body-refresh-secret",
751            "body-code-secret",
752            "body-list-secret",
753            "header-secret",
754            "query-secret",
755            "path-secret",
756        ] {
757            assert!(
758                !debug.contains(secret),
759                "Request Debug 泄露 {secret}: {debug}"
760            );
761        }
762        // 键名与类型/长度摘要保留,维持排障可用性。
763        assert!(debug.contains("password"), "应保留 body 键名: {debug}");
764        assert!(debug.contains("string(len="), "应保留长度摘要: {debug}");
765        assert!(debug.contains("object(keys=1)"), "应保留类型摘要: {debug}");
766        assert!(debug.contains("[REDACTED]"), "{debug}");
767    }
768}