anymap_serde/

lib.rs

//! A serializable AnyMap-like container keyed by `type_name::<T>()`.
//!
//! This crate provides `SerializableAnyMap`, an AnyMap-compatible container that
//! stores values in a serializable form (`serde_value::Value`) and optionally
//! caches a deserialized `Box<dyn Any>` for fast access. Keys are the stable
//! string returned by `key_for_type::<T>()`, not `TypeId`, which makes
//! the map suitable for sending over the network and reconstructing on another
//! process / compilation unit.
//!
//! Key properties:
//! - The on-disk / on-wire representation is a `HashMap<String, serde_value::Value>`.
//! - Deserialized values are stored in-memory only and are not serialized.
//! - Inserting a value serializes it immediately and stores the value in both forms.
//! - Deserialization reconstructs only the serialized representation; the cache is empty
//!   until a lazy access triggers deserialization, since we don't have access to type information
//!   at collection deserialization time
//!
//! # Motivation
//!
//! This is useful for extension holders (for example request extensions) where
//! heterogeneous typed data must be transported and reconstructed remotely.
//!
//! Example (illustrative):
//! ```rust
//! # use serde::{Serialize, Deserialize};
//! # use serde_json;
//! # use anymap_serde::SerializableAnyMap;
//! #[derive(Serialize, Deserialize, Debug, PartialEq)]
//! struct Ext { a: u32 }
//!
//! let mut map = SerializableAnyMap::new();
//! map.insert(Ext { a: 10 });
//!
//! // Serialize to JSON
//! let json = serde_json::to_string(&map).unwrap();
//!
//! // On the other side, deserialize and access the stored type by `type_name::<T>()`
//! let mut map2: SerializableAnyMap = serde_json::from_str(&json).unwrap();
//! let value: &Ext = map2.get::<Ext>().unwrap().unwrap();
//! assert_eq!(value.a, 10);
//! ```

#![deny(missing_docs, unused, warnings)]

mod entry;
mod write_guard;

use crate::entry::{Entry, OccupiedEntry, OccupiedError, VacantEntry};
use crate::write_guard::WriteGuard;
use serde::{Deserialize, Serialize};
use serde_value::{Value, to_value};
use std::collections::hash_map;
use std::{any::Any, collections::HashMap};

/// A serializable heterogeneous-map keyed by the stable `type_name::<T>()`.
///
/// `SerializableAnyMap` behaves like `anymap3` for most basic use-cases but
/// stores values in serialized form so the entire map can be serialized and
/// sent across process boundaries. The map implements `Serialize` and
/// `Deserialize` where only the serialized form is persisted; the cached
/// deserialized values are not persisted.
///
/// Inserted types must implement `Serialize + Deserialize<'de> + 'static`.
///
/// See method docs for usage patterns (`insert`, `get`, `get_mut`, `entry`, …).
///
/// Safety notes:
/// - Some escape hatches (`as_raw_mut`, `from_raw`) are `unsafe` — the caller
///   must ensure the key string matches the type stored under it.
///
/// A stored entry containing the serialized representation and an optional
/// cached runtime value.
///
#[derive(Default, Serialize, Deserialize, Debug, Clone)]
#[serde(transparent)]
pub struct SerializableAnyMap {
    raw: HashMap<String, Wrapper>,
}

impl SerializableAnyMap {
    /// Create a new empty `SerializableAnyMap`.
    #[inline]
    pub fn new() -> Self {
        Self {
            raw: HashMap::new(),
        }
    }

    /// Create a new `SerializableAnyMap` with the specified capacity.
    #[inline]
    pub fn with_capacity(capacity: usize) -> Self {
        Self {
            raw: HashMap::with_capacity(capacity),
        }
    }

    /// Returns the number of elements the map can hold without reallocating.
    #[inline]
    pub fn capacity(&self) -> usize {
        self.raw.capacity()
    }

    /// Reserves capacity for at least `additional` more elements to be inserted.
    /// The collection may reserve more space to avoid frequent reallocations.
    ///
    /// # Panics
    ///
    /// Panics if the new capacity overflows `usize`.
    #[inline]
    pub fn reserve(&mut self, additional: usize) {
        self.raw.reserve(additional);
    }

    /// Shrinks the capacity of the collection as much as possible. It will drop
    /// down as much as possible while maintaining the internal rules
    /// and possibly leaving some space in accordance with the resize policy.
    #[inline]
    pub fn shrink_to_fit(&mut self) {
        self.raw.shrink_to_fit()
    }

    // Additional stable methods (as of 1.60.0-nightly) that could be added:
    // try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError>    (1.57.0)
    // shrink_to(&mut self, min_capacity: usize)                                   (1.56.0)

    /// Returns the number of items in the collection.
    #[inline]
    pub fn len(&self) -> usize {
        self.raw.len()
    }

    /// Returns true if there are no items in the collection.
    #[inline]
    pub fn is_empty(&self) -> bool {
        self.raw.is_empty()
    }

    /// Removes all items from the collection. Keeps the allocated memory for reuse.
    #[inline]
    pub fn clear(&mut self) {
        self.raw.clear()
    }

    /// Get an immutable reference to a cached value of type `T` if it exists AND was deserialized.
    ///
    /// # Notes
    ///
    /// This does NOT lazily deserialize, use [`Self::get`] if you want lazy deserialization.
    /// This may return None even if the type is present in the map, but not deserialized.
    ///
    #[inline]
    pub fn try_get<T>(&self) -> Option<&T>
    where
        T: for<'de> Deserialize<'de> + Any + 'static,
    {
        let key = key_for_type::<T>().to_string();
        self.raw.get(&key)?.try_get()
    }

    /// Get an immutable reference to a value of type `T`, lazily deserializing if necessary.
    ///
    /// # Notes
    ///
    /// This requires a `&mut self` since it may need to deserialize and modify the entry.
    #[inline]
    pub fn get<T>(&mut self) -> Option<Result<&T, serde_value::DeserializerError>>
    where
        T: Serialize + for<'de> Deserialize<'de> + 'static,
    {
        Self::get_mut(self).map(|r| r.map(|v: WriteGuard<T>| v.into_ref()))
    }

    /// Gets a copy value of type `T`, by deserializing the value in the map.
    ///
    /// # Warning
    ///
    /// This always runs deserialization, and may return an instance that is not equivalent to the one
    /// in the map if any fields are marked `#[serde(skip)]` for example.
    ///
    #[inline]
    pub fn get_deserialized_copy<T>(&self) -> Option<T>
    where
        T: for<'de> Deserialize<'de> + Any + 'static,
    {
        self.get_serialized_value::<T>()
            .and_then(|v| T::deserialize(v.clone()).ok())
    }

    /// Get a mutable reference to a value of type `T`, lazily deserializing into the cache if necessary.
    pub fn get_mut<T>(
        &mut self,
    ) -> Option<Result<WriteGuard<'_, T>, serde_value::DeserializerError>>
    where
        T: Serialize + for<'de> Deserialize<'de> + Any + 'static,
    {
        let key = key_for_type::<T>().to_string();
        Some(self.raw.get_mut(&key)?.get_mut())
    }

    /// Get the serialized `serde_value::Value` for type `T` if present.
    #[inline]
    pub fn get_serialized_value<T>(&self) -> Option<&Value>
    where
        T: 'static,
    {
        let key = key_for_type::<T>().to_string();
        self.raw.get(&key).map(|e| &e.serialized)
    }

    /// Insert by type name key.
    ///
    /// This is lower-level and useful if you already have a Value.
    ///
    /// # Safety
    /// The provided Value needs to match the given matches the type name.
    #[inline]
    pub unsafe fn insert_value_by_name(
        &mut self,
        type_name: String,
        value: Value,
    ) -> Option<Value> {
        let e = Wrapper {
            serialized: value,
            value: None,
        };
        self.raw.insert(type_name, e).map(|e| e.serialized)
    }

    /// Insert a value of type `T`. Returns the previous value of that type if present.
    #[inline]
    pub fn insert<T>(&mut self, value: T) -> Option<Result<T, serde_value::DeserializerError>>
    where
        T: Serialize + for<'de> Deserialize<'de> + Any + 'static,
    {
        let key = key_for_type::<T>().to_string();
        let serialized = to_value(&value).expect("serialization failed");

        let new_entry = Wrapper {
            serialized,
            value: Some(Box::new(value)),
        };
        self.raw
            .insert(key, new_entry)
            .map(|old| old.into_inner::<T>())
    }

    /// Tries to insert a value into the map, and returns
    /// a mutable reference to the value if successful.
    ///
    /// If the map already had this type of value present, nothing is updated, and
    /// an error containing the occupied entry and the value is returned.
    pub fn try_insert<'a, T>(
        &'a mut self,
        value: T,
    ) -> Result<WriteGuard<'a, T>, OccupiedError<'a, T>>
    where
        T: Serialize + for<'de> Deserialize<'de> + Any + 'static,
    {
        match self.entry::<T>() {
            Entry::Occupied(entry) => Err(OccupiedError { entry, value }),
            Entry::Vacant(entry) => Ok(entry.insert(value)),
        }
    }

    /// Remove the stored value of type `T`, returning it if was present, or None if it was not.
    #[inline]
    pub fn remove<T>(&mut self) -> Option<T>
    where
        T: Serialize + for<'de> Deserialize<'de> + Any + 'static,
    {
        let key = key_for_type::<T>().to_string();
        self.raw
            .remove(&key)
            .and_then(|entry| entry.into_inner::<T>().ok())
    }

    /// Returns true if a value of type `T` exists in the map (regardless whether already deserialized or not).
    #[inline]
    pub fn contains<T>(&self) -> bool
    where
        T: 'static,
    {
        let key = key_for_type::<T>().to_string();
        self.raw.contains_key(&key)
    }

    /// Returns true if a value of type `T` exists in the map and has already been deserialized
    #[inline]
    pub fn contains_deserialized<T>(&self) -> bool
    where
        T: 'static,
    {
        let key = key_for_type::<T>().to_string();
        self.raw.contains_key(&key)
    }

    /// Entry API similar to `HashMap::entry` / `anymap3::entry::<T>()`.
    #[inline]
    pub fn entry<T>(&mut self) -> Entry<'_, T>
    where
        T: Serialize + for<'de> Deserialize<'de> + Any + 'static,
    {
        let key = key_for_type::<T>().to_string();

        let should_remove = match self.raw.entry(key.clone()) {
            hash_map::Entry::Occupied(mut inner) => inner.get_mut().get_mut::<T>().is_err(),
            _ => false,
        };

        if should_remove {
            self.raw.remove(&key);
        }

        match self.raw.entry(key) {
            hash_map::Entry::Occupied(inner) => Entry::Occupied(OccupiedEntry::new(inner)),
            hash_map::Entry::Vacant(inner) => Entry::Vacant(VacantEntry::new(inner)),
        }
    }

    /// Return an iterator over type-name keys.
    pub fn keys(&self) -> impl Iterator<Item = &String> {
        self.raw.keys()
    }

    /// Get access to the raw hash map that backs this.
    ///
    /// This will seldom be useful, but it’s conceivable that you could wish to iterate
    /// over all the items in the collection, and this lets you do that.
    #[inline]
    pub fn as_raw(&self) -> &HashMap<String, Wrapper> {
        &self.raw
    }

    /// Get mutable access to the raw hash map that backs this.
    ///
    /// This will seldom be useful, but it’s conceivable that you could wish to iterate
    /// over all the items in the collection mutably, or drain or something, or *possibly*
    /// even batch insert, and this lets you do that.
    ///
    /// # Safety
    ///
    /// If you insert any values to the raw map, the key (a `String`) must match the
    /// value’s type name as returned by any::type_name(), or *undefined behaviour* will occur when you access those values.
    ///
    /// (*Removing* entries is perfectly safe.)
    #[inline]
    pub unsafe fn as_raw_mut(&mut self) -> &mut HashMap<String, Wrapper> {
        &mut self.raw
    }

    /// Convert this into the raw hash map that backs this.
    ///
    /// This will seldom be useful, but it’s conceivable that you could wish to consume all
    /// the items in the collection and do *something* with some or all of them, and this
    /// lets you do that, without the `unsafe` that `.as_raw_mut().drain()` would require.
    #[inline]
    pub fn into_raw(self) -> HashMap<String, Wrapper> {
        self.raw
    }

    /// Construct a map from a collection of raw values.
    ///
    /// You know what? I can’t immediately think of any legitimate use for this.
    ///
    /// Perhaps this will be most practical as `unsafe { SerializableAnyMap::from_raw(iter.collect()) }`,
    /// `iter` being an iterator over `(String, Box<dyn Any + Serialize + Deserialize + 'static>)` pairs.
    /// Eh, this method provides symmetry with `into_raw`, so I don’t care if literally no one ever uses it. I’m not
    /// even going to write a test for it, it’s so trivial.
    ///
    /// # Safety
    ///
    /// For all entries in the raw map, the key (a `String`) must match the value’s type as returned by any::type_name(),
    /// or *undefined behaviour* will occur when you access that entry.
    #[inline]
    pub unsafe fn from_raw(raw: HashMap<String, Wrapper>) -> SerializableAnyMap {
        Self { raw }
    }
}

impl<A: Any + Serialize + for<'de> Deserialize<'de>> Extend<Box<A>> for SerializableAnyMap {
    #[inline]
    fn extend<T: IntoIterator<Item = Box<A>>>(&mut self, iter: T) {
        for item in iter {
            let serialized = to_value(&*item).expect("serialization failed");
            let _ = self.raw.insert(
                key_for_type::<T>().to_string(),
                Wrapper {
                    serialized,
                    value: Some(item),
                },
            );
        }
    }
}

/// A stored entry containing the serialized representation and an optional
/// cached runtime value.
///
/// - `serialized`: the `serde_value::Value` used for Serialize/Deserialize of the map.
/// - `value`: an optional `Box<dyn Any>` holding the deserialized value. This field is not
///   serialized and is cleared on `Clone` and `Deserialize`.
///
/// Semantics:
/// - On `insert`, both `serialized` and `value` are populated.
/// - On access (`get`/`get_mut`), the entry will lazily deserialize `serialized` into
///   `value` if the cache is empty.
/// - `into_inner` attempts to extract the concrete type from the cache or by deserializing.
///
/// Notes:
/// - The cloning, serialization and deserialization happens based on the serialized `serde_value::Value`, so
///   any modifications to fields that are marked `#[serde(skip)]` will not be lost after a serialization
///   round-trip, or after cloning the map.
/// - Currently any modifications to the cached `value` are not reflected back into the `serialized` form, so
///   serialization WILL reflect the original value only. This is a known limitation and is planned to be
///   addressed in a future version by returning a Guard object that will update the serialized value on Drop.
#[derive(Serialize, Deserialize, Debug)]
#[serde(transparent)]
pub struct Wrapper {
    serialized: Value,

    /// value runtime representation; skipped during (de)serialization.
    #[serde(skip)]
    #[serde(default)]
    value: Option<Box<dyn Any>>,
}

impl Clone for Wrapper {
    fn clone(&self) -> Self {
        Wrapper {
            serialized: self.serialized.clone(),
            value: None, // do not clone cached value
        }
    }
}

impl Wrapper {
    /// Attempt to get an immutable reference to the deserialized value of type `T`. Will return None
    /// if the value has not yet been deserialized, as we need a mutable reference to mutate the
    /// entry to save the deserialized value.
    pub fn try_get<T>(&self) -> Option<&T>
    where
        T: for<'de> Deserialize<'de> + 'static,
    {
        self.value.as_ref()?.downcast_ref::<T>()
    }

    /// Attempt to get an immutable reference to the deserialized value of type `T`,
    /// lazily deserializing if necessary. We need a mutable reference in order to save the
    /// deserialized value to the entry
    pub fn get<T>(&mut self) -> Result<&T, serde_value::DeserializerError>
    where
        T: Serialize + for<'de> Deserialize<'de> + 'static,
    {
        self.get_mut().map(|x: WriteGuard<T>| x.into_ref())
    }

    /// Attempt to an mutable reference to the deserialized value of type `T`,
    /// lazily deserializing if necessary.
    pub fn get_mut<'a, T>(&'a mut self) -> Result<WriteGuard<'a, T>, serde_value::DeserializerError>
    where
        T: for<'de> Deserialize<'de> + Serialize + 'static,
    {
        if self.value.is_none() {
            let deserialized = T::deserialize(self.serialized.clone())?;
            self.value = Some(Box::new(deserialized));
        }

        Ok(WriteGuard::new(self))
    }

    /// Attempt to extract the inner value by deserializing if necessary.
    pub fn into_inner<T>(mut self) -> Result<T, serde_value::DeserializerError>
    where
        T: for<'de> Deserialize<'de> + 'static,
    {
        self.value
            .take()
            .map(|a| Ok(*a.downcast::<T>().unwrap()))
            .unwrap_or_else(|| T::deserialize(self.serialized))
    }
}

/// Get the stable string key for type `T`. Implementation may only change across major versions.
fn key_for_type<T: ?Sized>() -> String {
    std::any::type_name::<T>().to_string()
}