Skip to main content

yang_base/action/
request_meta.rs

1//! 与具体 Web 框架无关的请求传输元数据。
2
3use std::collections::BTreeMap;
4use std::fmt;
5use std::net::SocketAddr;
6
7const REDACTED: &str = "[REDACTED]";
8
9/// Action 请求的传输层元数据。
10///
11/// 所有字段均可缺失,便于非 HTTP 调用、测试和内部任务继续通过现有
12/// `Request::new(body)` / `ActionContext::new(request, tools)` 构造。耗时不属于本结构,
13/// 应由 dispatch span 或 metrics 在执行完成后计算。
14#[derive(Clone, Default, PartialEq, Eq)]
15#[non_exhaustive]
16pub struct RequestMeta {
17    /// 原始请求方法,例如 `GET`、`POST`。
18    pub method: Option<String>,
19    /// 传输适配器观察到的原始 URI;可能包含敏感 query,因此 Debug 始终脱敏。
20    pub original_uri: Option<String>,
21    /// URI scheme,例如 `http`、`https`。
22    pub scheme: Option<String>,
23    /// 对端网络地址。
24    pub peer_addr: Option<SocketAddr>,
25    /// 本地监听地址。
26    pub local_addr: Option<SocketAddr>,
27    /// 传输适配器附加的可选字符串元数据。
28    ///
29    /// 使用有序映射使测试、诊断和后续 catalog 投影保持确定性;Debug 只展示 key。
30    pub extensions: BTreeMap<String, String>,
31}
32
33impl RequestMeta {
34    /// 创建所有传输字段均缺失的元数据。
35    pub fn new() -> Self {
36        Self::default()
37    }
38
39    /// 设置请求方法。
40    pub fn with_method(mut self, method: impl Into<String>) -> Self {
41        self.method = Some(method.into());
42        self
43    }
44
45    /// 设置原始 URI。
46    pub fn with_original_uri(mut self, uri: impl Into<String>) -> Self {
47        self.original_uri = Some(uri.into());
48        self
49    }
50
51    /// 设置 URI scheme。
52    pub fn with_scheme(mut self, scheme: impl Into<String>) -> Self {
53        self.scheme = Some(scheme.into());
54        self
55    }
56
57    /// 设置对端地址。
58    pub fn with_peer_addr(mut self, peer_addr: SocketAddr) -> Self {
59        self.peer_addr = Some(peer_addr);
60        self
61    }
62
63    /// 设置本地监听地址。
64    pub fn with_local_addr(mut self, local_addr: SocketAddr) -> Self {
65        self.local_addr = Some(local_addr);
66        self
67    }
68
69    /// 添加一项传输扩展;空白 key 被忽略。
70    pub fn extension(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
71        let key = key.into();
72        let key = key.trim();
73        if !key.is_empty() {
74            self.extensions.insert(key.to_string(), value.into());
75        }
76        self
77    }
78}
79
80impl fmt::Debug for RequestMeta {
81    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
82        let original_uri = self.original_uri.as_ref().map(|_| REDACTED);
83        let peer_addr = self.peer_addr.as_ref().map(|_| REDACTED);
84        let local_addr = self.local_addr.as_ref().map(|_| REDACTED);
85        let extension_keys: Vec<&str> = self.extensions.keys().map(String::as_str).collect();
86
87        formatter
88            .debug_struct("RequestMeta")
89            .field("method", &self.method)
90            .field("original_uri", &original_uri)
91            .field("scheme", &self.scheme)
92            .field("peer_addr", &peer_addr)
93            .field("local_addr", &local_addr)
94            .field("extension_keys", &extension_keys)
95            .finish()
96    }
97}