hyper_serde/
lib.rs

1//! This crate provides wrappers and convenience functions to make Hyper and
2//! Serde work hand in hand.
3//!
4//! The supported types are:
5//!
6//! * `cookie::Cookie`
7//! * `headers_ext::ContentType`
8//! * `hyper::header::Headers`
9//! * `hyper::StatusCode`
10//! * `hyper::Method`
11//! * `hyper::Uri`
12//! * `mime::Mime`
13//! * `time::Tm`
14//!
15//! # How do I use a data type with a `HeaderMap` member with Serde?
16//!
17//! Use the serde attributes `deserialize_with` and `serialize_with`.
18//!
19//! ```
20//! struct MyStruct {
21//! #[serde(deserialize_with = "hyper_serde::deserialize",
22//! serialize_with = "hyper_serde::serialize")]
23//! headers: HeaderMap,
24//! }
25//! ```
26//!
27//! # How do I encode a `HeaderMap` value with `serde_json::to_string`?
28//!
29//! Use the `Ser` wrapper.
30//!
31//! ```
32//! serde_json::to_string(&Ser::new(&headers))
33//! ```
34//!
35//! # How do I decode a `Method` value with `serde_json::parse`?
36//!
37//! Use the `De` wrapper.
38//!
39//! ```
40//! serde_json::parse::<De<Method>>("\"PUT\"").map(De::into_inner)
41//! ```
42//!
43//! # How do I send `Cookie` values as part of an IPC channel?
44//!
45//! Use the `Serde` wrapper. It implements `Deref` and `DerefMut` for
46//! convenience.
47//!
48//! ```
49//! ipc::channel::<Serde<Cookie>>()
50//! ```
51//!
52//!
53
54#![deny(missing_docs)]
55#![deny(unsafe_code)]
56
57use cookie::Cookie;
58use headers::ContentType;
59use hyper::StatusCode;
60use hyper::header::{HeaderName, HeaderValue};
61use http::HeaderMap;
62use hyper::Method;
63use mime::Mime;
64use serde::{Deserialize, Deserializer, Serialize, Serializer};
65use serde_bytes::{ByteBuf, Bytes};
66use serde::de::{self, MapAccess, SeqAccess, Visitor, Error};
67use serde::ser::{SerializeMap, SerializeSeq};
68use std::cmp;
69use std::fmt;
70use std::ops::{Deref, DerefMut};
71use std::str;
72use std::str::FromStr;
73use time::{Tm, strptime};
74use hyper::Uri;
75
76/// Deserialises a `T` value with a given deserializer.
77///
78/// This is useful to deserialize Hyper types used in structure fields or
79/// tuple members with `#[serde(deserialize_with = "hyper_serde::deserialize")]`.
80#[inline(always)]
81pub fn deserialize<'de, T, D>(deserializer: D) -> Result<T, D::Error>
82    where D: Deserializer<'de>,
83          De<T>: Deserialize<'de>,
84{
85    De::deserialize(deserializer).map(De::into_inner)
86}
87
88/// Serialises `value` with a given serializer.
89///
90/// This is useful to serialize Hyper types used in structure fields or
91/// tuple members with `#[serde(serialize_with = "hyper_serde::serialize")]`.
92#[inline(always)]
93pub fn serialize<T, S>(value: &T, serializer: S) -> Result<S::Ok, S::Error>
94    where S: Serializer,
95          for<'a> Ser<'a, T>: Serialize,
96{
97    Ser::new(value).serialize(serializer)
98}
99
100/// Serialises `value` with a given serializer in a pretty way.
101///
102/// This does the same job as `serialize` but with a prettier format
103/// for some combinations of types and serialisers.
104///
105/// For now, the only change from `serialize` is when serialising `Headers`,
106/// where the items in the header values get serialised as strings instead
107/// of sequences of bytes, if they represent UTF-8 text.
108#[inline(always)]
109pub fn serialize_pretty<T, S>(value: &T,
110                              serializer: S)
111                              -> Result<S::Ok, S::Error>
112    where S: Serializer,
113          for<'a> Ser<'a, T>: Serialize,
114{
115    Ser::new_pretty(value).serialize(serializer)
116}
117
118/// A wrapper to deserialize Hyper types.
119///
120/// This is useful with functions such as `serde_json::from_str`.
121///
122/// Values of this type can only be obtained through
123/// the `serde::Deserialize` trait.
124#[derive(Debug, PartialEq)]
125pub struct De<T> {
126    v: T,
127}
128
129impl<T> De<T> {
130    /// Returns a new `De` wrapper
131    #[inline(always)]
132    pub fn new(v: T) -> Self {
133        De { v: v }
134    }
135}
136
137impl<'de, T> De<T>
138    where De<T>: Deserialize<'de>,
139{
140    /// Consumes this wrapper, returning the deserialized value.
141    #[inline(always)]
142    pub fn into_inner(self) -> T {
143        self.v
144    }
145}
146
147/// A wrapper to serialize Hyper types.
148///
149/// This is useful with functions such as `serde_json::to_string`.
150///
151/// Values of this type can only be passed to the `serde::Serialize` trait.
152#[derive(Debug)]
153pub struct Ser<'a, T: 'a> {
154    v: &'a T,
155    pretty: bool,
156}
157
158impl<'a, T> Ser<'a, T>
159    where Ser<'a, T>: serde::Serialize,
160{
161    /// Returns a new `Ser` wrapper.
162    #[inline(always)]
163    pub fn new(value: &'a T) -> Self {
164        Ser {
165            v: value,
166            pretty: false,
167        }
168    }
169
170    /// Returns a new `Ser` wrapper, in pretty mode.
171    ///
172    /// See `serialize_pretty`.
173    #[inline(always)]
174    pub fn new_pretty(value: &'a T) -> Self {
175        Ser {
176            v: value,
177            pretty: true,
178        }
179    }
180}
181
182/// A convenience wrapper to be used as a type parameter, for example when
183/// a `Vec<T>` need to be passed to serde.
184#[derive(Clone, PartialEq)]
185pub struct Serde<T>(pub T)
186    where for<'de> De<T>: Deserialize<'de>,
187          for<'a> Ser<'a, T>: Serialize;
188
189impl<T> Serde<T>
190    where for<'de> De<T>: Deserialize<'de>,
191          for<'a> Ser<'a, T>: Serialize,
192{
193    /// Consumes this wrapper, returning the inner value.
194    #[inline(always)]
195    pub fn into_inner(self) -> T {
196        self.0
197    }
198}
199
200impl<T> fmt::Debug for Serde<T>
201    where T: fmt::Debug,
202          for<'de> De<T>: Deserialize<'de>,
203          for<'a> Ser<'a, T>: Serialize,
204{
205    fn fmt(&self, formatter: &mut fmt::Formatter) -> Result<(), fmt::Error> {
206        self.0.fmt(formatter)
207    }
208}
209
210impl<T> Deref for Serde<T>
211    where for<'de> De<T>: Deserialize<'de>,
212          for<'a> Ser<'a, T>: Serialize,
213{
214    type Target = T;
215
216    fn deref(&self) -> &T {
217        &self.0
218    }
219}
220
221impl<T> DerefMut for Serde<T>
222    where for<'de> De<T>: Deserialize<'de>,
223          for<'a> Ser<'a, T>: Serialize,
224{
225    fn deref_mut(&mut self) -> &mut T {
226        &mut self.0
227    }
228}
229
230impl<T: PartialEq> PartialEq<T> for Serde<T>
231    where for<'de> De<T>: Deserialize<'de>,
232          for<'a> Ser<'a, T>: Serialize,
233{
234    fn eq(&self, other: &T) -> bool {
235        self.0 == *other
236    }
237}
238
239impl<'b, T> Deserialize<'b> for Serde<T>
240    where for<'de> De<T>: Deserialize<'de>,
241          for<'a> Ser<'a, T>: Serialize,
242{
243    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
244        where D: Deserializer<'b>,
245    {
246        De::deserialize(deserializer).map(De::into_inner).map(Serde)
247    }
248}
249
250impl<T> Serialize for Serde<T>
251    where for<'de> De<T>: Deserialize<'de>,
252          for<'a> Ser<'a, T>: Serialize,
253{
254    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
255        where S: Serializer,
256    {
257        Ser::new(&self.0).serialize(serializer)
258    }
259}
260
261impl<'de> Deserialize<'de> for De<ContentType> {
262    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
263        where D: Deserializer<'de>,
264    {
265        deserialize(deserializer).map(|v: mime::Mime| ContentType::from(v)).map(De::new)
266    }
267}
268
269impl<'a> Serialize for Ser<'a, ContentType> {
270    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
271        where S: Serializer,
272    {
273        serialize(&mime::Mime::from(self.v.clone()), serializer)
274    }
275}
276
277impl<'de> Deserialize<'de> for De<Cookie<'static>> {
278    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
279        where D: Deserializer<'de>,
280    {
281        struct CookieVisitor;
282
283        impl<'de> Visitor<'de> for CookieVisitor {
284            type Value = De<Cookie<'static>>;
285
286            fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
287                write!(formatter, "an HTTP cookie header value")
288            }
289
290            fn visit_str<E>(self, v: &str) -> Result<Self::Value, E>
291                where E: de::Error,
292            {
293                Cookie::parse(v)
294                    .map(Cookie::into_owned)
295                    .map(De::new)
296                    .map_err(|e| E::custom(format!("{:?}", e)))
297            }
298        }
299
300        deserializer.deserialize_string(CookieVisitor)
301    }
302}
303
304impl<'a, 'cookie> Serialize for Ser<'a, Cookie<'cookie>> {
305    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
306        where S: Serializer,
307    {
308        serializer.serialize_str(&self.v.to_string())
309    }
310}
311
312
313impl<'de> Deserialize<'de> for De<HeaderMap> {
314    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
315        where D: Deserializer<'de>,
316    {
317        struct HeadersVisitor;
318
319        impl<'de> Visitor<'de> for HeadersVisitor {
320            type Value = De<HeaderMap>;
321
322            fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
323                write!(formatter, "a map from header names to header values")
324            }
325
326            fn visit_unit<E>(self) -> Result<Self::Value, E>
327                where E: de::Error,
328            {
329                Ok(De::new(HeaderMap::new()))
330            }
331
332            fn visit_map<V>(self,
333                            mut visitor: V)
334                            -> Result<Self::Value, V::Error>
335                where V: MapAccess<'de>,
336            {
337                let mut headers = HeaderMap::new();
338                while let Some((k, values)) = visitor.next_entry::<String, Value>()? {
339                    for v in values.0.iter() {
340                        headers.append(HeaderName::from_str(&k).map_err(V::Error::custom)?, HeaderValue::from_bytes(&v).map_err(V::Error::custom)?);
341                    }
342                }
343                Ok(De::new(headers))
344            }
345        }
346
347        struct Value(Vec<Vec<u8>>);
348
349        impl<'de> Deserialize<'de> for Value {
350            fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
351                where D: Deserializer<'de>,
352            {
353                deserializer.deserialize_seq(ValueVisitor)
354            }
355        }
356
357        struct ValueVisitor;
358
359        impl<'de> Visitor<'de> for ValueVisitor {
360            type Value = Value;
361
362            fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
363                write!(formatter, "an array of strings and sequences of bytes")
364            }
365
366            fn visit_unit<E>(self) -> Result<Value, E>
367                where E: de::Error,
368            {
369                Ok(Value(vec![]))
370            }
371
372            fn visit_seq<V>(self, mut visitor: V) -> Result<Value, V::Error>
373                where V: SeqAccess<'de>,
374            {
375                // Clamp to not OOM on rogue values.
376                let capacity = cmp::min(visitor.size_hint().unwrap_or(0), 64);
377                let mut values = Vec::with_capacity(capacity);
378                while let Some(v) = visitor.next_element::<ByteBuf>()? {
379                    values.push(v.into_vec());
380                }
381                Ok(Value(values))
382            }
383        }
384
385        deserializer.deserialize_map(HeadersVisitor)
386    }
387}
388
389impl<'a> Serialize for Ser<'a, HeaderMap> {
390    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
391        where S: Serializer,
392    {
393        struct Value<'headers>(&'headers [Vec<u8>], bool);
394
395        impl<'headers> Serialize for Value<'headers> {
396            fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
397                where S: Serializer,
398            {
399                let mut serializer =
400                    serializer.serialize_seq(Some(self.0.len()))?;
401                for v in self.0 {
402                    if self.1 {
403                        if let Ok(v) = str::from_utf8(v) {
404                            serializer.serialize_element(v)?;
405                            continue;
406                        }
407                    }
408                    serializer.serialize_element(&Bytes::new(v))?;
409                }
410                serializer.end()
411            }
412        }
413
414        let mut serializer = serializer.serialize_map(Some(self.v.keys_len()))?;
415        for name in self.v.keys() {
416            let values = self.v.get_all(name);
417            serializer.serialize_entry(name.as_str(), &Value(&values.iter().map(|v| v.as_bytes().iter().cloned().collect()).collect::<Vec<Vec<u8>>>(), self.pretty))?;
418        }
419        serializer.end()
420    }
421}
422
423impl<'de> Deserialize<'de> for De<Method> {
424    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
425        where D: Deserializer<'de>,
426    {
427        struct MethodVisitor;
428
429        impl<'de> Visitor<'de> for MethodVisitor {
430            type Value = De<Method>;
431
432            fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
433                write!(formatter, "an HTTP method")
434            }
435
436            fn visit_str<E>(self, v: &str) -> Result<Self::Value, E>
437                where E: de::Error,
438            {
439                v.parse::<Method>().map(De::new).map_err(E::custom)
440            }
441        }
442
443        deserializer.deserialize_string(MethodVisitor)
444    }
445}
446
447impl<'a> Serialize for Ser<'a, Method> {
448    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
449        where S: Serializer,
450    {
451        Serialize::serialize(self.v.as_ref(), serializer)
452    }
453}
454
455impl<'de> Deserialize<'de> for De<Mime> {
456    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
457        where D: Deserializer<'de>,
458    {
459        struct MimeVisitor;
460
461        impl<'de> Visitor<'de> for MimeVisitor {
462            type Value = De<Mime>;
463
464            fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
465                write!(formatter, "a mime type")
466            }
467
468            fn visit_str<E>(self, v: &str) -> Result<Self::Value, E>
469                where E: de::Error,
470            {
471                v.parse::<Mime>().map(De::new).map_err(|_| {
472                    E::custom("could not parse mime type")
473                })
474            }
475        }
476
477        deserializer.deserialize_string(MimeVisitor)
478    }
479}
480
481impl<'a> Serialize for Ser<'a, Mime> {
482    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
483        where S: Serializer,
484    {
485        serializer.serialize_str(&self.v.to_string())
486    }
487}
488
489impl<'de> Deserialize<'de> for De<StatusCode> {
490    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
491        where D: Deserializer<'de>,
492    {
493        let code = Deserialize::deserialize(deserializer)?;
494        Ok(De::new(StatusCode::from_u16(code).map_err(D::Error::custom)?))
495    }
496}
497
498impl<'a> Serialize for Ser<'a, StatusCode> {
499    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
500        where S: Serializer,
501    {
502        self.v.as_u16().serialize(serializer)
503    }
504}
505
506impl<'a> Serialize for Ser<'a, (StatusCode, String)> {
507    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
508        where S: Serializer,
509    {
510        let mut serializer = serializer.serialize_seq(Some(2))?;
511        serializer.serialize_element(&Ser::new(&self.v.0))?;
512        serializer.serialize_element(&self.v.1)?;
513        serializer.end()
514    }
515}
516
517impl<'de> Deserialize<'de> for De<(StatusCode, String)> {
518    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
519        where D: Deserializer<'de>,
520    {
521        Ok(De::new(deserializer.deserialize_seq(StatusVisitor)?))
522    }
523}
524
525struct StatusVisitor;
526
527impl<'de> Visitor<'de> for StatusVisitor {
528    type Value = (StatusCode, String);
529
530    fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
531        write!(formatter, "an array containing a status code and a reason string")
532    }
533
534    fn visit_seq<V>(self, mut visitor: V) -> Result<Self::Value, V::Error>
535        where V: SeqAccess<'de>,
536    {
537
538        let code = visitor.next_element::<u16>()?.ok_or_else(||
539            V::Error::custom("Can't find the status code")
540        )?;
541        let code = StatusCode::from_u16(code).map_err(V::Error::custom)?;
542        let reason = visitor.next_element::<String>()?.ok_or_else(||
543            V::Error::custom("Can't find the reason string")
544        )?;
545        Ok((code, reason))
546    }
547}
548
549impl<'de> Deserialize<'de> for De<Tm> {
550    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
551        where D: Deserializer<'de>,
552    {
553        struct TmVisitor;
554
555        impl<'de> Visitor<'de> for TmVisitor {
556            type Value = De<Tm>;
557
558            fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
559                write!(formatter, "a date and time according to RFC 3339")
560            }
561
562            fn visit_str<E>(self, v: &str) -> Result<Self::Value, E>
563                where E: de::Error,
564            {
565                strptime(v, "%Y-%m-%dT%H:%M:%SZ").map(De::new).map_err(|e| {
566                    E::custom(e.to_string())
567                })
568            }
569        }
570
571        deserializer.deserialize_string(TmVisitor)
572    }
573}
574
575impl<'a> Serialize for Ser<'a, Tm> {
576    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
577        where S: Serializer,
578    {
579        serializer.serialize_str(&self.v.rfc3339().to_string())
580    }
581}
582
583impl<'de> Deserialize<'de> for De<Uri> {
584    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
585        where D: Deserializer<'de>,
586    {
587        struct UriVisitor;
588
589        impl<'de> Visitor<'de> for UriVisitor {
590            type Value = De<Uri>;
591
592            fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
593                write!(formatter, "an HTTP Uri value")
594            }
595
596            fn visit_str<E>(self, v: &str) -> Result<Self::Value, E>
597                where E: de::Error,
598            {
599                Uri::from_str(v)
600                    .map(De::new)
601                    .map_err(|e| E::custom(format!("{}", e)))
602            }
603        }
604
605        deserializer.deserialize_string(UriVisitor)
606    }
607}
608
609impl<'a> Serialize for Ser<'a, Uri> {
610    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
611        where S: Serializer,
612    {
613        // As of hyper 0.12, hyper::Uri (re-exported http::Uri)
614        // does not implement as_ref due to underlying implementation
615        // so we must construct a string to serialize it
616        serializer.serialize_str(&self.v.to_string())
617    }
618}
hyper_serde/lib.rs

hyper_serde/
lib.rs
