willow_data_model/
lib.rs

1#![doc(html_logo_url = "https://willowprotocol.org/named_assets/willow_emblem_standalone.png")]
2//! # Willow Data Model
3//!
4//! This crate provides implementation of the [Willow Data Model](https://willowprotocol.org/specs/data-model/index.html#data_model), including:
5//!
6//! - Traits to assist in your implementation of Willow [parameters](https://willowprotocol.org/specs/data-model/index.html#willow_parameters), such as [`NamespaceId`](https://willowprotocol.org/specs/data-model/index.html#NamespaceId) and [`SubspaceId`](https://willowprotocol.org/specs/data-model/index.html#SubspaceId).  
7//! - A [zero-copy](https://en.wikipedia.org/wiki/Zero-copy) implementation of Willow [paths](https://willowprotocol.org/specs/data-model/index.html#Path) and their constituent [components](https://willowprotocol.org/specs/data-model/index.html#Component).
8//! - An implementation of Willow's [entries](https://willowprotocol.org/specs/data-model/index.html#Entry).
9//! - Utilities for Willow's entry [groupings](https://willowprotocol.org/specs/grouping-entries/index.html#grouping_entries), such as [ranges](https://willowprotocol.org/specs/grouping-entries/index.html#ranges) and [areas](https://willowprotocol.org/specs/grouping-entries/index.html#areas)
10//! - Implementations of various [relative encodings](https://willowprotocol.org/specs/encodings/index.html#relativity).
11//!
12//! This crate **does not yet have** anything for Willow's concept of [stores](https://willowprotocol.org/specs/data-model/index.html#store). Stay tuned!
13//!
14//! ## Type parameters
15//!
16//! Willow is a parametrised family of protocols, and so this crate makes heavy use of generic parameters.
17//!
18//! The following generic parameter names are used consistently across this crate:
19//!
20//! - `MCL` - A `usize` representing [`max_component_length`](https://willowprotocol.org/specs/data-model/index.html#max_component_length).
21//! - `MCC` - A `usize` representing [`max_component_count`](https://willowprotocol.org/specs/data-model/index.html#max_component_count).
22//! - `MPL` - A `usize` representing [`max_path_length`](https://willowprotocol.org/specs/data-model/index.html#max_path_length).
23//! - `N` - The type used for [`NamespaceId`](https://willowprotocol.org/specs/data-model/index.html#NamespaceId) (willowprotocol.org), must implement the [`NamespaceId`] trait.
24//! - `S` - The type used for [`SubspaceId`](https://willowprotocol.org/specs/data-model/index.html#SubspaceId) (willowprotocol.org), must implement the [`SubspaceId`] trait.
25//! - `PD` - The type used for [`PayloadDigest`](https://willowprotocol.org/specs/data-model/index.html#PayloadDigest) (willowprotocol.org), must implement the [`PayloadDigest`] trait.
26//! - `AT` - The type used for [`AuthorisationToken`](https://willowprotocol.org/specs/data-model/index.html#AuthorisationToken) (willowprotocol.org), must implement the [`AuthorisationToken`] trait.
27
28mod entry;
29use std::future::Future;
30
31pub use entry::*;
32mod lengthy_entry;
33pub use lengthy_entry::*;
34pub mod grouping;
35mod parameters;
36pub use parameters::*;
37mod path;
38pub use path::*;
39mod private_encodings;
40pub use private_encodings::*;
41mod relative_encodings;
42mod store;
43pub use store::*;
44use ufotofu_codec::Blame;
45
46/// Methods for decoding **trusted** encodings,that is, data which was already deemed trustworthy *prior* to encoding.
47pub trait TrustedDecodable: Sized {
48    /// # Safety
49    /// This function is only intended to decode types which have been deemed *trusted* prior to their encoding.
50    /// Using it to decode encodings from untrusted sources will result in immediate undefined behaviour!
51    unsafe fn trusted_decode<P>(
52        producer: &mut P,
53    ) -> impl Future<Output = Result<Self, ufotofu_codec::DecodeError<P::Final, P::Error, Blame>>>
54    where
55        P: ufotofu::BulkProducer<Item = u8>;
56}
57
58/// Methods for decoding **trusted** encodings (that is, data which was deemed trustworthy *prior* to encoding), **relative** to type `R`.
59pub trait TrustedRelativeDecodable<R>: Sized {
60    /// # Safety
61    /// This function is only intended to decode types which have been deemed *trusted* prior to their encoding.
62    /// Using it to decode encodings from untrusted sources will result in immediate undefined behaviour!
63    unsafe fn trusted_relative_decode<P>(
64        producer: &mut P,
65        r: &R,
66    ) -> impl Future<Output = Result<Self, ufotofu_codec::DecodeError<P::Final, P::Error, Blame>>>
67    where
68        P: ufotofu::BulkProducer<Item = u8>;
69}
willow_data_model/lib.rs

willow_data_model/
lib.rs
