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
470impl fmt::Debug for Request {
471    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
472        formatter
473            .debug_struct("Request")
474            .field("body", &self.body)
475            .field("headers", &RedactedMap(&self.headers))
476            .field("query", &RedactedMap(&self.query))
477            .field("path_params", &RedactedMap(&self.path_params))
478            .field("resource_guard_count", &self.resource_guards.len())
479            .finish()
480    }
481}
482
483impl Default for Request {
484    fn default() -> Self {
485        Self::new(serde_json::Value::Null)
486    }
487}
488
489#[cfg(test)]
490mod tests {
491    use super::*;
492    use serde_json::json;
493    #[cfg(feature = "transport-axum")]
494    use std::sync::atomic::{AtomicUsize, Ordering};
495
496    #[cfg(feature = "transport-axum")]
497    struct DropResource(Arc<AtomicUsize>);
498
499    #[cfg(feature = "transport-axum")]
500    impl Drop for DropResource {
501        fn drop(&mut self) {
502            self.0.fetch_add(1, Ordering::SeqCst);
503        }
504    }
505
506    #[test]
507    fn test_header_lookup_is_case_insensitive() {
508        let request = Request::new(json!({}))
509            .header("Content-Type", "application/json")
510            .header("aUtHoRiZaTiOn", "Bearer token123");
511
512        assert_eq!(request.get_header("content-type"), Some("application/json"));
513        assert_eq!(request.get_header("AUTHORIZATION"), Some("Bearer token123"));
514        assert_eq!(request.token(), Some("token123"));
515    }
516
517    #[test]
518    #[cfg(feature = "transport-axum")]
519    fn clone_does_not_extend_request_scoped_resource_lifetime() {
520        let drops = Arc::new(AtomicUsize::new(0));
521        let resource = Arc::new(DropResource(Arc::clone(&drops)));
522        let request = Request::new(json!({})).retain_resource(Arc::clone(&resource));
523        drop(resource);
524        let cloned = request.clone();
525
526        drop(request);
527        assert_eq!(drops.load(Ordering::SeqCst), 1);
528        drop(cloned);
529        assert_eq!(drops.load(Ordering::SeqCst), 1);
530    }
531
532    #[test]
533    fn test_header_insert_normalizes_name_and_overwrites_case_variants() {
534        let request = Request::new(json!({}))
535            .header("Authorization", "Bearer old")
536            .header("authorization", "Bearer new");
537
538        assert_eq!(request.headers.len(), 1);
539        assert_eq!(
540            request.headers.get("authorization").map(String::as_str),
541            Some("Bearer new")
542        );
543        assert_eq!(request.get_header("Authorization"), Some("Bearer new"));
544        assert_eq!(request.token(), Some("new"));
545    }
546
547    #[test]
548    fn test_header_trims_name_before_normalizing() {
549        let request = Request::new(json!({})).header(" Authorization ", "Bearer token123");
550
551        assert_eq!(request.headers.len(), 1);
552        assert_eq!(request.get_header("authorization"), Some("Bearer token123"));
553        assert_eq!(
554            request.get_header(" Authorization "),
555            Some("Bearer token123")
556        );
557        assert_eq!(request.token(), Some("token123"));
558    }
559
560    #[test]
561    fn test_header_rejects_blank_names() {
562        let request = Request::new(json!({}))
563            .header("", "empty")
564            .header("   ", "blank")
565            .header("X-Request-Id", "abc");
566
567        assert_eq!(request.get_header("x-request-id"), Some("abc"));
568        assert_eq!(request.get_header(""), None);
569        assert_eq!(request.get_header("   "), None);
570    }
571
572    #[test]
573    fn test_get_header_rejects_blank_names() {
574        let mut request = Request::new(json!({}));
575        request.headers.insert("".to_string(), "empty".to_string());
576        request
577            .headers
578            .insert("   ".to_string(), "blank".to_string());
579        request
580            .headers
581            .insert("x-request-id".to_string(), "abc".to_string());
582
583        assert_eq!(request.get_header("x-request-id"), Some("abc"));
584        assert_eq!(request.get_header(""), None);
585        assert_eq!(request.get_header("   "), None);
586    }
587
588    #[test]
589    fn test_token_accepts_case_insensitive_bearer_scheme() {
590        let lower = Request::new(json!({})).header("authorization", "bearer lower-token");
591        let upper = Request::new(json!({})).header("authorization", "BEARER upper-token");
592
593        assert_eq!(lower.token(), Some("lower-token"));
594        assert_eq!(upper.token(), Some("upper-token"));
595    }
596
597    #[test]
598    fn test_token_trims_scheme_spacing_and_rejects_empty_or_split_token() {
599        let padded = Request::new(json!({})).header("authorization", "Bearer    padded-token");
600        let empty = Request::new(json!({})).header("authorization", "Bearer ");
601        let split = Request::new(json!({})).header("authorization", "Bearer token extra");
602
603        assert_eq!(padded.token(), Some("padded-token"));
604        assert_eq!(empty.token(), None);
605        assert_eq!(split.token(), None);
606    }
607
608    #[test]
609    fn test_query_rejects_blank_keys() {
610        let request = Request::new(json!({}))
611            .query("", "empty")
612            .query("   ", "blank")
613            .query("page", "1");
614
615        let mut query = std::collections::HashMap::new();
616        query.insert("".to_string(), "empty-bulk".to_string());
617        query.insert("   ".to_string(), "blank-bulk".to_string());
618        query.insert("limit".to_string(), "10".to_string());
619
620        let request = request.queries(query);
621
622        assert_eq!(request.get_query("page"), Some("1"));
623        assert_eq!(request.get_query("limit"), Some("10"));
624        assert_eq!(request.get_query(""), None);
625        assert_eq!(request.get_query("   "), None);
626    }
627
628    #[test]
629    fn test_query_trims_keys_before_storing() {
630        let request = Request::new(json!({})).query(" page ", "1");
631
632        assert_eq!(request.query.len(), 1);
633        assert_eq!(request.get_query("page"), Some("1"));
634        assert_eq!(request.get_query(" page "), Some("1"));
635    }
636
637    #[test]
638    fn test_get_query_rejects_blank_keys() {
639        let mut request = Request::new(json!({}));
640        request.query.insert("".to_string(), "empty".to_string());
641        request.query.insert("   ".to_string(), "blank".to_string());
642        request.query.insert("page".to_string(), "1".to_string());
643
644        assert_eq!(request.get_query("page"), Some("1"));
645        assert_eq!(request.get_query(""), None);
646        assert_eq!(request.get_query("   "), None);
647    }
648
649    #[test]
650    fn test_path_param_rejects_blank_keys() {
651        let request = Request::new(json!({}))
652            .path_param("", "empty")
653            .path_param("   ", "blank")
654            .path_param("id", "42");
655
656        let mut path_params = std::collections::HashMap::new();
657        path_params.insert("".to_string(), "empty-bulk".to_string());
658        path_params.insert("   ".to_string(), "blank-bulk".to_string());
659        path_params.insert("slug".to_string(), "demo".to_string());
660
661        let request = request.path_params(path_params);
662
663        assert_eq!(request.get_path_param("id"), Some("42"));
664        assert_eq!(request.get_path_param("slug"), Some("demo"));
665        assert_eq!(request.get_path_param(""), None);
666        assert_eq!(request.get_path_param("   "), None);
667    }
668
669    #[test]
670    fn test_path_param_trims_keys_before_storing() {
671        let request = Request::new(json!({})).path_param(" id ", "42");
672
673        assert_eq!(request.path_params.len(), 1);
674        assert_eq!(request.get_path_param("id"), Some("42"));
675        assert_eq!(request.get_path_param(" id "), Some("42"));
676    }
677
678    #[test]
679    fn test_get_path_param_rejects_blank_keys() {
680        let mut request = Request::new(json!({}));
681        request
682            .path_params
683            .insert("".to_string(), "empty".to_string());
684        request
685            .path_params
686            .insert("   ".to_string(), "blank".to_string());
687        request
688            .path_params
689            .insert("id".to_string(), "42".to_string());
690
691        assert_eq!(request.get_path_param("id"), Some("42"));
692        assert_eq!(request.get_path_param(""), None);
693        assert_eq!(request.get_path_param("   "), None);
694    }
695}