Skip to main content

ruma_common/
serde.rs

1//! (De)serialization helpers for other Ruma crates.
2//!
3//! Part of that is a fork of [serde_urlencoded], with support for sequences in `Deserialize` /
4//! `Serialize` structs (e.g. `Vec<Something>`) that are (de)serialized as `field=val1&field=val2`.
5//!
6//! [serde_urlencoded]: https://github.com/nox/serde_urlencoded
7
8use std::{fmt, marker::PhantomData};
9
10use serde::{
11    Deserialize, Deserializer,
12    de::{self, DeserializeOwned, SeqAccess, Visitor},
13};
14use serde_json::{Value as JsonValue, value::RawValue as RawJsonValue};
15use tracing::debug;
16
17pub mod base64;
18mod buf;
19pub mod can_be_empty;
20mod cow;
21pub mod duration;
22pub mod json_string;
23mod raw;
24pub mod single_element_seq;
25mod strings;
26pub mod test;
27
28pub use self::{
29    base64::{Base64, Base64DecodeError},
30    buf::{json_to_buf, slice_to_buf},
31    can_be_empty::{CanBeEmpty, is_empty},
32    cow::deserialize_cow_str,
33    raw::{JsonCastable, Raw},
34    strings::{
35        btreemap_deserialize_v1_powerlevel_values, deserialize_as_number_or_string,
36        deserialize_as_optional_number_or_string, deserialize_v1_powerlevel, empty_string_as_none,
37        none_as_empty_string,
38    },
39};
40
41/// The inner type of [`JsonValue::Object`].
42pub type JsonObject = serde_json::Map<String, JsonValue>;
43
44/// Check whether a value is equal to its default value.
45pub fn is_default<T: Default + PartialEq>(val: &T) -> bool {
46    *val == T::default()
47}
48
49/// Deserialize a `T` via `Option<T>`, falling back to `T::default()`.
50pub fn none_as_default<'de, D, T>(deserializer: D) -> Result<T, D::Error>
51where
52    D: Deserializer<'de>,
53    T: Default + Deserialize<'de>,
54{
55    Ok(Option::deserialize(deserializer)?.unwrap_or_default())
56}
57
58/// Simply returns `true`.
59///
60/// Useful for `#[serde(default = ...)]`.
61pub fn default_true() -> bool {
62    true
63}
64
65/// Simply dereferences the given bool.
66///
67/// Useful for `#[serde(skip_serializing_if = ...)]`.
68#[allow(clippy::trivially_copy_pass_by_ref)]
69pub fn is_true(b: &bool) -> bool {
70    *b
71}
72
73/// Helper function for `serde_json::value::RawValue` deserialization.
74pub fn from_raw_json_value<'a, T, E>(val: &'a RawJsonValue) -> Result<T, E>
75where
76    T: Deserialize<'a>,
77    E: de::Error,
78{
79    serde_json::from_str(val.get()).map_err(E::custom)
80}
81
82/// Helper function for returning a default value if deserialization of the type fails.
83///
84/// Assumes that the content being deserialized is JSON.
85///
86/// Used as `#[serde(deserialize_with = "default_on_error")]`.
87pub fn default_on_error<'de, D, T>(deserializer: D) -> Result<T, D::Error>
88where
89    D: Deserializer<'de>,
90    T: DeserializeOwned + Default,
91{
92    let value = match Box::<RawJsonValue>::deserialize(deserializer) {
93        Ok(value) => value,
94        Err(error) => {
95            debug!("deserialization error, using default value: {error}");
96            return Ok(T::default());
97        }
98    };
99
100    Ok(from_raw_json_value(&value).unwrap_or_else(|error: D::Error| {
101        debug!("deserialization error, using default value: {error}");
102        T::default()
103    }))
104}
105
106/// Helper function for ignoring invalid items in a sequence, instead of letting them cause the
107/// entire sequence to fail deserialization.
108///
109/// The output `A` type is any type that implements `Default` and `Extend<T>`, so it should work
110/// with `Vec<T>` and `BTreeSet<T>` for example.
111pub fn ignore_invalid_sequence_items<'de, D, A, T>(deserializer: D) -> Result<A, D::Error>
112where
113    D: Deserializer<'de>,
114    A: Default + Extend<T>,
115    T: Deserialize<'de>,
116{
117    struct SkipInvalid<A, T>(PhantomData<A>, PhantomData<T>);
118
119    impl<'de, A, T> Visitor<'de> for SkipInvalid<A, T>
120    where
121        A: Default + Extend<T>,
122        T: Deserialize<'de>,
123    {
124        type Value = A;
125
126        fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
127            formatter.write_str("sequence with possibly invalid items")
128        }
129
130        fn visit_seq<S>(self, mut seq: S) -> Result<Self::Value, S::Error>
131        where
132            S: SeqAccess<'de>,
133        {
134            let mut array = A::default();
135            let mut i = 0_usize;
136
137            while let Some(result) = seq.next_element::<T>().transpose() {
138                let Ok(item) = result.inspect_err(|error| {
139                    debug!("deserialization error, ignoring item {i} in sequence: {error}");
140                }) else {
141                    continue;
142                };
143
144                array.extend(Some(item));
145                i += 1;
146            }
147
148            Ok(array)
149        }
150    }
151
152    deserializer.deserialize_seq(SkipInvalid(PhantomData, PhantomData))
153}
154
155/// Deserialize a `Raw<T>` and reject any value whose top-level JSON shape is not an object.
156///
157/// Use as `#[serde(deserialize_with = "ruma_common::serde::deserialize_raw_object")]` wherever
158/// the Matrix spec mandates an object (e.g., `Raw<EventContent>` on the body of
159/// `/_matrix/client/.../send` endpoints, or on inner fields, response fields, etc.).
160pub fn deserialize_raw_object<'de, T, D>(deserializer: D) -> Result<Raw<T>, D::Error>
161where
162    D: Deserializer<'de>,
163{
164    use serde::de::Error;
165
166    let raw = <Raw<T> as Deserialize>::deserialize(deserializer)?;
167    if !raw.json().get().trim_start().starts_with('{') {
168        return Err(D::Error::invalid_type(
169            de::Unexpected::Other("non-object value"),
170            &"a JSON object",
171        ));
172    }
173
174    Ok(raw)
175}
176
177pub use ruma_macros::{
178    _FakeDeriveSerde, AsRefStr, AsStrAsRefStr, DebugAsRefStr, DeserializeFromCowStr,
179    DisplayAsRefStr, EqAsRefStr, FromString, OrdAsRefStr, SerializeAsRefStr, StringEnum,
180};