Struct TlsMap 

pub struct TlsMap<K, V> { /* private fields */ }

A sorted key-value map with deterministic TLS codec serialization.

Entries are maintained in sorted order by key, ensuring byte-identical serialization across all implementations. Keys must be unique.

Wire format: vlen(total_byte_length) || entry[0] || entry[1] || ... where each entry is K(tls) || V(tls) and vlen is the QUIC variable-length encoding (RFC 9000 §16).

Examples

use xmtp_mls_common::tls_map::TlsMap;
use tls_codec::{Serialize, Deserialize};

let mut map = TlsMap::<u16, u16>::new();
map.insert(3, 30).unwrap();
map.insert(1, 10).unwrap();
map.insert(2, 20).unwrap();

// Serialization is deterministic regardless of insertion order
let bytes = map.tls_serialize_detached().unwrap();
let deserialized = TlsMap::<u16, u16>::tls_deserialize_exact(&bytes).unwrap();
assert_eq!(map, deserialized);

Implementations

impl<K, V> TlsMap<K, V>

where K: Ord + Eq,

pub fn new() -> Self

Create an empty map.

use xmtp_mls_common::tls_map::TlsMap;

let map = TlsMap::<u8, u16>::new();
assert!(map.is_empty());

pub fn from_pairs(iter: impl IntoIterator<Item = (K, V)>) -> Self

Create a map from an iterator of key-value pairs.

Entries are sorted by key. If duplicate keys exist, the last value wins.

use xmtp_mls_common::tls_map::TlsMap;

let map = TlsMap::from_pairs([(2, "b"), (1, "a"), (2, "c")]);
assert_eq!(map.get(&1), Some(&"a"));
assert_eq!(map.get(&2), Some(&"c")); // last value wins
assert_eq!(map.len(), 2);

pub fn insert(&mut self, key: K, value: V) -> Result<(), TlsMapError>

Insert a key-value pair. Returns an error if the key already exists.

use xmtp_mls_common::tls_map::TlsMap;

let mut map = TlsMap::<u8, u8>::new();
assert!(map.insert(1, 10).is_ok());
assert!(map.insert(1, 20).is_err()); // duplicate key

pub fn update(&mut self, key: K, value: V) -> Result<(), TlsMapError>

Update an existing key’s value. Returns an error if the key doesn’t exist.

use xmtp_mls_common::tls_map::TlsMap;

let mut map = TlsMap::<u8, u8>::new();
map.insert(1, 10).unwrap();
map.update(1, 20).unwrap();
assert_eq!(map.get(&1), Some(&20));
assert!(map.update(99, 0).is_err()); // key not found

pub fn set(&mut self, key: K, value: V)

Insert or update a key-value pair. Always succeeds.

use xmtp_mls_common::tls_map::TlsMap;

let mut map = TlsMap::<u8, u8>::new();
map.set(1, 10);
map.set(1, 20); // overwrites
assert_eq!(map.get(&1), Some(&20));
assert_eq!(map.len(), 1);

pub fn remove(&mut self, key: &K) -> Result<V, TlsMapError>

Remove a key. Returns the removed value, or an error if the key doesn’t exist.

use xmtp_mls_common::tls_map::TlsMap;

let mut map = TlsMap::<u8, u8>::new();
map.insert(1, 10).unwrap();
assert_eq!(map.remove(&1).unwrap(), 10);
assert!(map.remove(&1).is_err()); // already removed

pub fn get(&self, key: &K) -> Option<&V>

Get a value by key. Returns None if the key is not present.

use xmtp_mls_common::tls_map::TlsMap;

let mut map = TlsMap::<u8, u8>::new();
map.insert(1, 10).unwrap();
assert_eq!(map.get(&1), Some(&10));
assert_eq!(map.get(&2), None);

pub fn get_mut(&mut self, key: &K) -> Option<&mut V>

Get a mutable reference to a value by key. Returns None if the key is not present.

use xmtp_mls_common::tls_map::TlsMap;

let mut map = TlsMap::<u8, u8>::new();
map.insert(1, 10).unwrap();
*map.get_mut(&1).unwrap() = 20;
assert_eq!(map.get(&1), Some(&20));

pub fn contains_key(&self, key: &K) -> bool

Check if a key exists in the map.

pub fn len(&self) -> usize

Returns the number of entries in the map.

pub fn is_empty(&self) -> bool

Returns true if the map contains no entries.

pub fn iter(&self) -> impl Iterator<Item = (&K, &V)>

Iterate over key-value pairs in key-sorted order.

use xmtp_mls_common::tls_map::TlsMap;

let map = TlsMap::from_pairs([(2, "b"), (1, "a")]);
let pairs: Vec<_> = map.iter().collect();
assert_eq!(pairs, vec![(&1, &"a"), (&2, &"b")]);

pub fn keys(&self) -> impl Iterator<Item = &K>

Iterate over keys in sorted order.

pub fn values(&self) -> impl Iterator<Item = &V>

Iterate over values in key-sorted order.

impl<K, V> TlsMap<K, V>

where K: Ord + Eq + Clone,

pub fn apply_delta( &mut self, delta: TlsMapDelta<K, V>, ) -> Result<(), TlsMapError>

Apply a delta atomically. If any mutation fails, the map is unchanged.

use xmtp_mls_common::tls_map::{TlsMap, TlsMapDelta};

let mut map = TlsMap::<u8, u8>::new();
map.insert(1, 10).unwrap();

let delta = TlsMapDelta::new()
    .insert(2, 20)
    .update(1, 15)
    .delete(1);

map.apply_delta(delta).unwrap();
assert_eq!(map.get(&2), Some(&20));
assert!(!map.contains_key(&1));

Trait Implementations

impl<K: Clone, V: Clone> Clone for TlsMap<K, V>

fn clone(&self) -> TlsMap<K, V>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<K: Debug, V: Debug> Debug for TlsMap<K, V>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<K, V> Default for TlsMap<K, V>

fn default() -> Self

Returns the “default value” for a type.

impl<K, V> Deserialize for TlsMap<K, V>

where K: Deserialize + Size + Ord + Eq, V: Deserialize + Size,

fn tls_deserialize<R: Read>(bytes: &mut R) -> Result<Self, Error>

where Self: Sized,

This function deserializes the bytes from the provided a std::io::Read and returns the populated struct.

fn tls_deserialize_exact(bytes: impl AsRef<[u8]>) -> Result<Self, Error>

where Self: Sized,

This function deserializes the provided bytes and returns the populated struct. All bytes must be consumed.

impl<K: Ord + Eq, V> FromIterator<(K, V)> for TlsMap<K, V>

fn from_iter<T: IntoIterator<Item = (K, V)>>(iter: T) -> Self

Creates a value from an iterator.

impl<K, V> IntoIterator for TlsMap<K, V>

type Item = (K, V)

The type of the elements being iterated over.

type IntoIter = Map<IntoIter<TlsMapEntry<K, V>>, fn(TlsMapEntry<K, V>) -> (K, V)>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<K: PartialEq, V: PartialEq> PartialEq for TlsMap<K, V>

fn eq(&self, other: &TlsMap<K, V>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<K: Serialize + Size + Debug, V: Serialize + Size + Debug> Serialize for TlsMap<K, V>

fn tls_serialize<W: Write>(&self, writer: &mut W) -> Result<usize, Error>

Serialize self and write it to the writer. The function returns the number of bytes written to writer.

fn tls_serialize_detached(&self) -> Result<Vec<u8>, Error>

Serialize self and return it as a byte vector.

impl<K: Size, V: Size> Size for TlsMap<K, V>

fn tls_serialized_len(&self) -> usize

impl<K: Eq, V: Eq> Eq for TlsMap<K, V>

impl<K, V> StructuralPartialEq for TlsMap<K, V>