salvo_oapi/extract/parameter/
header.rs

1use std::fmt::{self, Debug, Display, Formatter};
2use std::ops::{Deref, DerefMut};
3
4use salvo_core::Depot;
5use salvo_core::extract::{Extractible, Metadata};
6use salvo_core::http::{ParseError, Request};
7use serde::{Deserialize, Deserializer};
8
9use crate::endpoint::EndpointArgRegister;
10use crate::{Components, Operation, Parameter, ParameterIn, ToSchema};
11
12/// Represents the parameters passed by header.
13pub struct HeaderParam<T, const REQUIRED: bool = true>(Option<T>);
14impl<T> HeaderParam<T, true> {
15    /// Consumes self and returns the value of the parameter.
16    pub fn into_inner(self) -> T {
17        self.0
18            .expect("`HeaderParam<T, true>` into_inner get `None`")
19    }
20}
21impl<T> HeaderParam<T, false> {
22    /// Consumes self and returns the value of the parameter.
23    pub fn into_inner(self) -> Option<T> {
24        self.0
25    }
26}
27
28impl<T> Deref for HeaderParam<T, true> {
29    type Target = T;
30
31    fn deref(&self) -> &Self::Target {
32        self.0
33            .as_ref()
34            .expect("`HeaderParam<T, true>` defref get `None`")
35    }
36}
37impl<T> Deref for HeaderParam<T, false> {
38    type Target = Option<T>;
39
40    fn deref(&self) -> &Self::Target {
41        &self.0
42    }
43}
44
45impl<T> DerefMut for HeaderParam<T, true> {
46    fn deref_mut(&mut self) -> &mut Self::Target {
47        self.0
48            .as_mut()
49            .expect("`HeaderParam<T, true>` defref_mut get `None`")
50    }
51}
52impl<T> DerefMut for HeaderParam<T, false> {
53    fn deref_mut(&mut self) -> &mut Self::Target {
54        &mut self.0
55    }
56}
57
58impl<'de, T, const R: bool> Deserialize<'de> for HeaderParam<T, R>
59where
60    T: Deserialize<'de>,
61{
62    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
63    where
64        D: Deserializer<'de>,
65    {
66        T::deserialize(deserializer).map(|value| Self(Some(value)))
67    }
68}
69// impl<'de, T> Deserialize<'de> for HeaderParam<T, false>
70// where
71//     T: Deserialize<'de>,
72// {
73//     fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
74//     where
75//         D: Deserializer<'de>,
76//     {
77//         T::deserialize(deserializer).map(|value| Self(Some(value)))
78//     }
79// }
80
81impl<T, const R: bool> fmt::Debug for HeaderParam<T, R>
82where
83    T: Debug,
84{
85    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
86        self.0.fmt(f)
87    }
88}
89impl<T: Display> Display for HeaderParam<T, true> {
90    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
91        self.0
92            .as_ref()
93            .expect("HeaderParam value should not None.")
94            .fmt(f)
95    }
96}
97
98impl<'ex, T> Extractible<'ex> for HeaderParam<T, true>
99where
100    T: Deserialize<'ex>,
101{
102    fn metadata() -> &'static Metadata {
103        static METADATA: Metadata = Metadata::new("");
104        &METADATA
105    }
106    #[allow(refining_impl_trait)]
107    async fn extract(_req: &'ex mut Request, _depot: &'ex mut Depot) -> Result<Self, ParseError> {
108        unimplemented!("header parameter can not be extracted from request")
109    }
110    #[allow(refining_impl_trait)]
111    async fn extract_with_arg(
112        req: &'ex mut Request,
113        _depot: &'ex mut Depot,
114        arg: &str,
115    ) -> Result<Self, ParseError> {
116        let value = req.header(arg).ok_or_else(|| {
117            ParseError::other(format!(
118                "header parameter {arg} not found or convert to type failed"
119            ))
120        })?;
121        Ok(Self(value))
122    }
123}
124
125impl<'ex, T> Extractible<'ex> for HeaderParam<T, false>
126where
127    T: Deserialize<'ex>,
128{
129    fn metadata() -> &'static Metadata {
130        static METADATA: Metadata = Metadata::new("");
131        &METADATA
132    }
133    #[allow(refining_impl_trait)]
134    async fn extract(_req: &'ex mut Request, _depot: &'ex mut Depot) -> Result<Self, ParseError> {
135        unimplemented!("header parameter can not be extracted from request")
136    }
137    #[allow(refining_impl_trait)]
138    async fn extract_with_arg(
139        req: &'ex mut Request,
140        _depot: &'ex mut Depot,
141        arg: &str,
142    ) -> Result<Self, ParseError> {
143        Ok(Self(req.header(arg)))
144    }
145}
146
147impl<T, const R: bool> EndpointArgRegister for HeaderParam<T, R>
148where
149    T: ToSchema,
150{
151    fn register(components: &mut Components, operation: &mut Operation, arg: &str) {
152        let parameter = Parameter::new(arg)
153            .parameter_in(ParameterIn::Header)
154            .description(format!("Get parameter `{arg}` from request headers."))
155            .schema(T::to_schema(components))
156            .required(R);
157        operation.parameters.insert(parameter);
158    }
159}
160
161#[cfg(test)]
162mod tests {
163    use assert_json_diff::assert_json_eq;
164    use http::header::HeaderValue;
165    use salvo_core::test::TestClient;
166    use serde_json::json;
167
168    use super::*;
169
170    #[test]
171    fn test_required_header_param_into_inner() {
172        let param = HeaderParam::<String, true>(Some("param".to_owned()));
173        assert_eq!("param".to_owned(), param.into_inner());
174    }
175
176    #[test]
177    fn test_required_header_param_deref() {
178        let param = HeaderParam::<String, true>(Some("param".to_owned()));
179        assert_eq!(&"param".to_owned(), param.deref())
180    }
181
182    #[test]
183    fn test_required_header_param_deref_mut() {
184        let mut param = HeaderParam::<String, true>(Some("param".to_owned()));
185        assert_eq!(&mut "param".to_owned(), param.deref_mut())
186    }
187
188    #[test]
189    fn test_header_param_into_inner() {
190        let param = HeaderParam::<String, false>(Some("param".to_owned()));
191        assert_eq!(Some("param".to_owned()), param.into_inner());
192    }
193
194    #[test]
195    fn test_header_param_deref() {
196        let param = HeaderParam::<String, false>(Some("param".to_owned()));
197        assert_eq!(&Some("param".to_owned()), param.deref())
198    }
199
200    #[test]
201    fn test_header_param_deref_mut() {
202        let mut param = HeaderParam::<String, false>(Some("param".to_owned()));
203        assert_eq!(&mut Some("param".to_owned()), param.deref_mut())
204    }
205
206    #[test]
207    fn test_header_param_deserialize() {
208        let param = serde_json::from_str::<HeaderParam<String, true>>(r#""param""#).unwrap();
209        assert_eq!(param.0.unwrap(), "param");
210    }
211
212    #[test]
213    fn test_header_param_debug() {
214        let param = HeaderParam::<String, true>(Some("param".to_owned()));
215        assert_eq!(format!("{param:?}"), r#"Some("param")"#);
216    }
217
218    #[test]
219    fn test_header_param_display() {
220        let param = HeaderParam::<String, true>(Some("param".to_owned()));
221        assert_eq!(format!("{param}"), "param");
222    }
223
224    #[test]
225    fn test_required_header_param_metadata() {
226        let metadata = HeaderParam::<String, true>::metadata();
227        assert_eq!("", metadata.name);
228    }
229
230    #[tokio::test]
231    #[should_panic]
232    async fn test_required_header_prarm_extract() {
233        let mut req = Request::new();
234        let mut depot = Depot::new();
235        let _ = HeaderParam::<String, true>::extract(&mut req, &mut depot).await;
236    }
237
238    #[tokio::test]
239    async fn test_required_header_prarm_extract_with_value() {
240        let mut req = TestClient::get("http://127.0.0.1:5801").build_hyper();
241        req.headers_mut()
242            .append("param", HeaderValue::from_static("param"));
243        let schema = req.uri().scheme().cloned().unwrap();
244        let mut req = Request::from_hyper(req, schema);
245        let mut depot = Depot::new();
246        let result =
247            HeaderParam::<String, true>::extract_with_arg(&mut req, &mut depot, "param").await;
248        assert_eq!(result.unwrap().0.unwrap(), "param");
249    }
250
251    #[tokio::test]
252    #[should_panic]
253    async fn test_required_header_prarm_extract_with_value_panic() {
254        let req = TestClient::get("http://127.0.0.1:5801").build_hyper();
255        let schema = req.uri().scheme().cloned().unwrap();
256        let mut req = Request::from_hyper(req, schema);
257        let mut depot = Depot::new();
258        let result =
259            HeaderParam::<String, true>::extract_with_arg(&mut req, &mut depot, "param").await;
260        assert_eq!(result.unwrap().0.unwrap(), "param");
261    }
262
263    #[test]
264    fn test_header_param_metadata() {
265        let metadata = HeaderParam::<String, false>::metadata();
266        assert_eq!("", metadata.name);
267    }
268
269    #[tokio::test]
270    #[should_panic]
271    async fn test_header_prarm_extract() {
272        let mut req = Request::new();
273        let mut depot = Depot::new();
274        let _ = HeaderParam::<String, false>::extract(&mut req, &mut depot).await;
275    }
276
277    #[tokio::test]
278    async fn test_header_prarm_extract_with_value() {
279        let mut req = TestClient::get("http://127.0.0.1:5801").build_hyper();
280        req.headers_mut()
281            .append("param", HeaderValue::from_static("param"));
282        let schema = req.uri().scheme().cloned().unwrap();
283        let mut req = Request::from_hyper(req, schema);
284        let mut depot = Depot::new();
285        let result =
286            HeaderParam::<String, false>::extract_with_arg(&mut req, &mut depot, "param").await;
287        assert_eq!(result.unwrap().0.unwrap(), "param");
288    }
289
290    #[tokio::test]
291    #[should_panic]
292    async fn test_header_prarm_extract_with_value_panic() {
293        let req = TestClient::get("http://127.0.0.1:5801").build_hyper();
294        let schema = req.uri().scheme().cloned().unwrap();
295        let mut req = Request::from_hyper(req, schema);
296        let mut depot = Depot::new();
297        let result =
298            HeaderParam::<String, false>::extract_with_arg(&mut req, &mut depot, "param").await;
299        assert_eq!(result.unwrap().0.unwrap(), "param");
300    }
301
302    #[test]
303    fn test_header_param_register() {
304        let mut components = Components::new();
305        let mut operation = Operation::new();
306        HeaderParam::<String, false>::register(&mut components, &mut operation, "arg");
307
308        assert_json_eq!(
309            operation,
310            json!({
311                "parameters": [
312                    {
313                        "name": "arg",
314                        "in": "header",
315                        "description": "Get parameter `arg` from request headers.",
316                        "required": false,
317                        "schema": {
318                            "type": "string"
319                        }
320                    }
321                ],
322                "responses": {}
323            })
324        )
325    }
326}
salvo_oapi/extract/parameter/header.rs

salvo_oapi/extract/parameter/
header.rs
