salvo_oapi/extract/parameter/
header.rs

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

salvo_oapi/extract/parameter/
header.rs
