ruma_serde/urlencoded/
ser.rs

1//! Serialization support for the `application/x-www-form-urlencoded` format.
2
3mod key;
4mod pair;
5mod part;
6mod value;
7
8use std::{borrow::Cow, error, fmt, str};
9
10use form_urlencoded::{Serializer as UrlEncodedSerializer, Target as UrlEncodedTarget};
11use serde::ser;
12
13/// Serializes a value into a `application/x-www-form-urlencoded` `String` buffer.
14///
15/// ```
16/// let meal = &[("bread", "baguette"), ("cheese", "comté"), ("meat", "ham"), ("fat", "butter")];
17///
18/// assert_eq!(
19///     ruma_serde::urlencoded::to_string(meal),
20///     Ok("bread=baguette&cheese=comt%C3%A9&meat=ham&fat=butter".to_owned())
21/// );
22/// ```
23pub fn to_string<T: ser::Serialize>(input: T) -> Result<String, Error> {
24    let mut urlencoder = UrlEncodedSerializer::new("".to_owned());
25    input.serialize(Serializer::new(&mut urlencoder))?;
26    Ok(urlencoder.finish())
27}
28
29/// A serializer for the `application/x-www-form-urlencoded` format.
30///
31/// * Supported top-level inputs are structs, maps and sequences of pairs, with or without a given
32///   length.
33///
34/// * Supported keys and values are integers, bytes (if convertible to strings), unit structs and
35///   unit variants.
36///
37/// * Newtype structs defer to their inner values.
38pub struct Serializer<'input, 'output, Target: UrlEncodedTarget> {
39    urlencoder: &'output mut UrlEncodedSerializer<'input, Target>,
40}
41
42impl<'input, 'output, Target: UrlEncodedTarget> Serializer<'input, 'output, Target> {
43    /// Returns a new `Serializer`.
44    pub fn new(urlencoder: &'output mut UrlEncodedSerializer<'input, Target>) -> Self {
45        Serializer { urlencoder }
46    }
47}
48
49/// Errors returned during serializing to `application/x-www-form-urlencoded`.
50#[derive(Clone, Debug, PartialEq, Eq)]
51#[non_exhaustive]
52pub enum Error {
53    /// UTF-8 validation failed.
54    Utf8(str::Utf8Error),
55    /// Something else.
56    Custom(Cow<'static, str>),
57}
58
59impl fmt::Display for Error {
60    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
61        match *self {
62            Error::Custom(ref msg) => msg.fmt(f),
63            Error::Utf8(ref err) => write!(f, "invalid UTF-8: {}", err),
64        }
65    }
66}
67
68impl error::Error for Error {
69    /// The lower-level cause of this error, in the case of a `Utf8` error.
70    fn cause(&self) -> Option<&dyn error::Error> {
71        match *self {
72            Error::Custom(_) => None,
73            Error::Utf8(ref err) => Some(err),
74        }
75    }
76
77    /// The lower-level source of this error, in the case of a `Utf8` error.
78    fn source(&self) -> Option<&(dyn error::Error + 'static)> {
79        match *self {
80            Error::Custom(_) => None,
81            Error::Utf8(ref err) => Some(err),
82        }
83    }
84}
85
86impl ser::Error for Error {
87    fn custom<T: fmt::Display>(msg: T) -> Self {
88        Error::Custom(format!("{}", msg).into())
89    }
90}
91
92/// Sequence serializer.
93pub struct SeqSerializer<'input, 'output, Target: UrlEncodedTarget> {
94    urlencoder: &'output mut UrlEncodedSerializer<'input, Target>,
95}
96
97/// Tuple serializer.
98///
99/// Mostly used for arrays.
100pub struct TupleSerializer<'input, 'output, Target: UrlEncodedTarget> {
101    urlencoder: &'output mut UrlEncodedSerializer<'input, Target>,
102}
103
104/// Tuple struct serializer.
105///
106/// Never instantiated, tuple structs are not supported.
107pub struct TupleStructSerializer<'input, 'output, T: UrlEncodedTarget> {
108    inner: ser::Impossible<&'output mut UrlEncodedSerializer<'input, T>, Error>,
109}
110
111/// Tuple variant serializer.
112///
113/// Never instantiated, tuple variants are not supported.
114pub struct TupleVariantSerializer<'input, 'output, T: UrlEncodedTarget> {
115    inner: ser::Impossible<&'output mut UrlEncodedSerializer<'input, T>, Error>,
116}
117
118/// Map serializer.
119pub struct MapSerializer<'input, 'output, Target: UrlEncodedTarget> {
120    urlencoder: &'output mut UrlEncodedSerializer<'input, Target>,
121    key: Option<Cow<'static, str>>,
122}
123
124/// Struct serializer.
125pub struct StructSerializer<'input, 'output, Target: UrlEncodedTarget> {
126    urlencoder: &'output mut UrlEncodedSerializer<'input, Target>,
127}
128
129/// Struct variant serializer.
130///
131/// Never instantiated, struct variants are not supported.
132pub struct StructVariantSerializer<'input, 'output, T: UrlEncodedTarget> {
133    inner: ser::Impossible<&'output mut UrlEncodedSerializer<'input, T>, Error>,
134}
135
136impl<'input, 'output, Target> ser::Serializer for Serializer<'input, 'output, Target>
137where
138    Target: UrlEncodedTarget,
139{
140    type Ok = &'output mut UrlEncodedSerializer<'input, Target>;
141    type Error = Error;
142    type SerializeSeq = SeqSerializer<'input, 'output, Target>;
143    type SerializeTuple = TupleSerializer<'input, 'output, Target>;
144    type SerializeTupleStruct = TupleStructSerializer<'input, 'output, Target>;
145    type SerializeTupleVariant = TupleVariantSerializer<'input, 'output, Target>;
146    type SerializeMap = MapSerializer<'input, 'output, Target>;
147    type SerializeStruct = StructSerializer<'input, 'output, Target>;
148    type SerializeStructVariant = StructVariantSerializer<'input, 'output, Target>;
149
150    /// Returns an error.
151    fn serialize_bool(self, _v: bool) -> Result<Self::Ok, Error> {
152        Err(Error::top_level())
153    }
154
155    /// Returns an error.
156    fn serialize_i8(self, _v: i8) -> Result<Self::Ok, Error> {
157        Err(Error::top_level())
158    }
159
160    /// Returns an error.
161    fn serialize_i16(self, _v: i16) -> Result<Self::Ok, Error> {
162        Err(Error::top_level())
163    }
164
165    /// Returns an error.
166    fn serialize_i32(self, _v: i32) -> Result<Self::Ok, Error> {
167        Err(Error::top_level())
168    }
169
170    /// Returns an error.
171    fn serialize_i64(self, _v: i64) -> Result<Self::Ok, Error> {
172        Err(Error::top_level())
173    }
174
175    /// Returns an error.
176    fn serialize_u8(self, _v: u8) -> Result<Self::Ok, Error> {
177        Err(Error::top_level())
178    }
179
180    /// Returns an error.
181    fn serialize_u16(self, _v: u16) -> Result<Self::Ok, Error> {
182        Err(Error::top_level())
183    }
184
185    /// Returns an error.
186    fn serialize_u32(self, _v: u32) -> Result<Self::Ok, Error> {
187        Err(Error::top_level())
188    }
189
190    /// Returns an error.
191    fn serialize_u64(self, _v: u64) -> Result<Self::Ok, Error> {
192        Err(Error::top_level())
193    }
194
195    /// Returns an error.
196    fn serialize_f32(self, _v: f32) -> Result<Self::Ok, Error> {
197        Err(Error::top_level())
198    }
199
200    /// Returns an error.
201    fn serialize_f64(self, _v: f64) -> Result<Self::Ok, Error> {
202        Err(Error::top_level())
203    }
204
205    /// Returns an error.
206    fn serialize_char(self, _v: char) -> Result<Self::Ok, Error> {
207        Err(Error::top_level())
208    }
209
210    /// Returns an error.
211    fn serialize_str(self, _value: &str) -> Result<Self::Ok, Error> {
212        Err(Error::top_level())
213    }
214
215    /// Returns an error.
216    fn serialize_bytes(self, _value: &[u8]) -> Result<Self::Ok, Error> {
217        Err(Error::top_level())
218    }
219
220    /// Returns `Ok`.
221    fn serialize_unit(self) -> Result<Self::Ok, Error> {
222        Ok(self.urlencoder)
223    }
224
225    /// Returns `Ok`.
226    fn serialize_unit_struct(self, _name: &'static str) -> Result<Self::Ok, Error> {
227        Ok(self.urlencoder)
228    }
229
230    /// Returns an error.
231    fn serialize_unit_variant(
232        self,
233        _name: &'static str,
234        _variant_index: u32,
235        _variant: &'static str,
236    ) -> Result<Self::Ok, Error> {
237        Err(Error::top_level())
238    }
239
240    /// Serializes the inner value, ignoring the newtype name.
241    fn serialize_newtype_struct<T: ?Sized + ser::Serialize>(
242        self,
243        _name: &'static str,
244        value: &T,
245    ) -> Result<Self::Ok, Error> {
246        value.serialize(self)
247    }
248
249    /// Returns an error.
250    fn serialize_newtype_variant<T: ?Sized + ser::Serialize>(
251        self,
252        _name: &'static str,
253        _variant_index: u32,
254        _variant: &'static str,
255        _value: &T,
256    ) -> Result<Self::Ok, Error> {
257        Err(Error::top_level())
258    }
259
260    /// Returns `Ok`.
261    fn serialize_none(self) -> Result<Self::Ok, Error> {
262        Ok(self.urlencoder)
263    }
264
265    /// Serializes the given value.
266    fn serialize_some<T: ?Sized + ser::Serialize>(self, value: &T) -> Result<Self::Ok, Error> {
267        value.serialize(self)
268    }
269
270    /// Serialize a sequence, given length (if any) is ignored.
271    fn serialize_seq(self, _len: Option<usize>) -> Result<Self::SerializeSeq, Error> {
272        Ok(SeqSerializer { urlencoder: self.urlencoder })
273    }
274
275    /// Returns an error.
276    fn serialize_tuple(self, _len: usize) -> Result<Self::SerializeTuple, Error> {
277        Ok(TupleSerializer { urlencoder: self.urlencoder })
278    }
279
280    /// Returns an error.
281    fn serialize_tuple_struct(
282        self,
283        _name: &'static str,
284        _len: usize,
285    ) -> Result<Self::SerializeTupleStruct, Error> {
286        Err(Error::top_level())
287    }
288
289    /// Returns an error.
290    fn serialize_tuple_variant(
291        self,
292        _name: &'static str,
293        _variant_index: u32,
294        _variant: &'static str,
295        _len: usize,
296    ) -> Result<Self::SerializeTupleVariant, Error> {
297        Err(Error::top_level())
298    }
299
300    /// Serializes a map, given length is ignored.
301    fn serialize_map(self, _len: Option<usize>) -> Result<Self::SerializeMap, Error> {
302        Ok(MapSerializer { urlencoder: self.urlencoder, key: None })
303    }
304
305    /// Serializes a struct, given length is ignored.
306    fn serialize_struct(
307        self,
308        _name: &'static str,
309        _len: usize,
310    ) -> Result<Self::SerializeStruct, Error> {
311        Ok(StructSerializer { urlencoder: self.urlencoder })
312    }
313
314    /// Returns an error.
315    fn serialize_struct_variant(
316        self,
317        _name: &'static str,
318        _variant_index: u32,
319        _variant: &'static str,
320        _len: usize,
321    ) -> Result<Self::SerializeStructVariant, Error> {
322        Err(Error::top_level())
323    }
324}
325
326impl<'input, 'output, Target> ser::SerializeSeq for SeqSerializer<'input, 'output, Target>
327where
328    Target: UrlEncodedTarget,
329{
330    type Ok = &'output mut UrlEncodedSerializer<'input, Target>;
331    type Error = Error;
332
333    fn serialize_element<T: ?Sized + ser::Serialize>(&mut self, value: &T) -> Result<(), Error> {
334        value.serialize(pair::PairSerializer::new(self.urlencoder))
335    }
336
337    fn end(self) -> Result<Self::Ok, Error> {
338        Ok(self.urlencoder)
339    }
340}
341
342impl<'input, 'output, Target> ser::SerializeTuple for TupleSerializer<'input, 'output, Target>
343where
344    Target: UrlEncodedTarget,
345{
346    type Ok = &'output mut UrlEncodedSerializer<'input, Target>;
347    type Error = Error;
348
349    fn serialize_element<T: ?Sized + ser::Serialize>(&mut self, value: &T) -> Result<(), Error> {
350        value.serialize(pair::PairSerializer::new(self.urlencoder))
351    }
352
353    fn end(self) -> Result<Self::Ok, Error> {
354        Ok(self.urlencoder)
355    }
356}
357
358impl<'input, 'output, Target> ser::SerializeTupleStruct
359    for TupleStructSerializer<'input, 'output, Target>
360where
361    Target: UrlEncodedTarget,
362{
363    type Ok = &'output mut UrlEncodedSerializer<'input, Target>;
364    type Error = Error;
365
366    fn serialize_field<T: ?Sized + ser::Serialize>(&mut self, value: &T) -> Result<(), Error> {
367        self.inner.serialize_field(value)
368    }
369
370    fn end(self) -> Result<Self::Ok, Error> {
371        self.inner.end()
372    }
373}
374
375impl<'input, 'output, Target> ser::SerializeTupleVariant
376    for TupleVariantSerializer<'input, 'output, Target>
377where
378    Target: UrlEncodedTarget,
379{
380    type Ok = &'output mut UrlEncodedSerializer<'input, Target>;
381    type Error = Error;
382
383    fn serialize_field<T: ?Sized + ser::Serialize>(&mut self, value: &T) -> Result<(), Error> {
384        self.inner.serialize_field(value)
385    }
386
387    fn end(self) -> Result<Self::Ok, Error> {
388        self.inner.end()
389    }
390}
391
392impl<'input, 'output, Target> ser::SerializeMap for MapSerializer<'input, 'output, Target>
393where
394    Target: UrlEncodedTarget,
395{
396    type Ok = &'output mut UrlEncodedSerializer<'input, Target>;
397    type Error = Error;
398
399    fn serialize_entry<K: ?Sized + ser::Serialize, V: ?Sized + ser::Serialize>(
400        &mut self,
401        key: &K,
402        value: &V,
403    ) -> Result<(), Error> {
404        let key_sink = key::KeySink::new(|key| {
405            let value_sink = value::ValueSink::new(self.urlencoder, &key);
406            value.serialize(part::PartSerializer::new(value_sink))?;
407            self.key = None;
408            Ok(())
409        });
410        let entry_serializer = part::PartSerializer::new(key_sink);
411        key.serialize(entry_serializer)
412    }
413
414    fn serialize_key<T: ?Sized + ser::Serialize>(&mut self, key: &T) -> Result<(), Error> {
415        let key_sink = key::KeySink::new(|key| Ok(key.into()));
416        let key_serializer = part::PartSerializer::new(key_sink);
417        self.key = Some(key.serialize(key_serializer)?);
418        Ok(())
419    }
420
421    fn serialize_value<T: ?Sized + ser::Serialize>(&mut self, value: &T) -> Result<(), Error> {
422        {
423            let key = self.key.as_ref().ok_or_else(Error::no_key)?;
424            let value_sink = value::ValueSink::new(self.urlencoder, key);
425            value.serialize(part::PartSerializer::new(value_sink))?;
426        }
427        self.key = None;
428        Ok(())
429    }
430
431    fn end(self) -> Result<Self::Ok, Error> {
432        Ok(self.urlencoder)
433    }
434}
435
436impl<'input, 'output, Target> ser::SerializeStruct for StructSerializer<'input, 'output, Target>
437where
438    Target: UrlEncodedTarget,
439{
440    type Ok = &'output mut UrlEncodedSerializer<'input, Target>;
441    type Error = Error;
442
443    fn serialize_field<T: ?Sized + ser::Serialize>(
444        &mut self,
445        key: &'static str,
446        value: &T,
447    ) -> Result<(), Error> {
448        let value_sink = value::ValueSink::new(self.urlencoder, key);
449        value.serialize(part::PartSerializer::new(value_sink))
450    }
451
452    fn end(self) -> Result<Self::Ok, Error> {
453        Ok(self.urlencoder)
454    }
455}
456
457impl<'input, 'output, Target> ser::SerializeStructVariant
458    for StructVariantSerializer<'input, 'output, Target>
459where
460    Target: UrlEncodedTarget,
461{
462    type Ok = &'output mut UrlEncodedSerializer<'input, Target>;
463    type Error = Error;
464
465    fn serialize_field<T: ?Sized + ser::Serialize>(
466        &mut self,
467        key: &'static str,
468        value: &T,
469    ) -> Result<(), Error> {
470        self.inner.serialize_field(key, value)
471    }
472
473    fn end(self) -> Result<Self::Ok, Error> {
474        self.inner.end()
475    }
476}
477
478impl Error {
479    fn top_level() -> Self {
480        let msg = "top-level serializer supports only maps and structs";
481        Error::Custom(msg.into())
482    }
483
484    fn no_key() -> Self {
485        let msg = "tried to serialize a value before serializing key";
486        Error::Custom(msg.into())
487    }
488}
ruma_serde/urlencoded/ser.rs

ruma_serde/urlencoded/
ser.rs
