cnidarium/
read.rs

1use std::{any::Any, future::Future, ops::RangeBounds, sync::Arc};
2
3use anyhow::Result;
4use futures::Stream;
5
6/// Read access to chain state.
7pub trait StateRead: Send + Sync {
8    type GetRawFut: Future<Output = Result<Option<Vec<u8>>>> + Send + 'static;
9    type PrefixRawStream: Stream<Item = Result<(String, Vec<u8>)>> + Send + 'static;
10    type PrefixKeysStream: Stream<Item = Result<String>> + Send + 'static;
11    type NonconsensusPrefixRawStream: Stream<Item = Result<(Vec<u8>, Vec<u8>)>> + Send + 'static;
12    type NonconsensusRangeRawStream: Stream<Item = Result<(Vec<u8>, Vec<u8>)>> + Send + 'static;
13
14    /// Gets a value from the verifiable key-value store as raw bytes.
15    ///
16    /// Users should generally prefer to use `get` or `get_proto` from an extension trait.
17    fn get_raw(&self, key: &str) -> Self::GetRawFut;
18
19    /// Gets a byte value from the non-verifiable key-value store.
20    ///
21    /// This is intended for application-specific indexes of the verifiable
22    /// consensus state, rather than for use as a primary data storage method.
23    fn nonverifiable_get_raw(&self, key: &[u8]) -> Self::GetRawFut;
24
25    /// Gets an object from the ephemeral key-object store.
26    ///
27    /// This is intended to allow application components to build up batched
28    /// data transactionally, ensuring that a transaction's contributions to
29    /// some batched data are only included if the entire transaction executed
30    /// successfully.  This data is not persisted to the `Storage` during
31    /// `commit`.
32    ///
33    /// # Returns
34    ///
35    /// - `Some(&T)` if a value of type `T` was present at `key`.
36    /// - `None` if `key` was not present.
37    ///
38    /// # Panics
39    ///
40    /// If there *is* a value at `key` but it is not of the type requested.
41    fn object_get<T: Any + Send + Sync + Clone>(&self, key: &'static str) -> Option<T>;
42
43    /// Gets the [`TypeId`] of the object stored at `key` in the ephemeral key-object store, if any
44    /// is present.
45    fn object_type(&self, key: &'static str) -> Option<std::any::TypeId>;
46
47    /// Retrieve all values for keys matching a prefix from the verifiable key-value store, as raw bytes.
48    ///
49    /// Users should generally prefer to use `prefix` or `prefix_proto` from an extension trait.
50    fn prefix_raw(&self, prefix: &str) -> Self::PrefixRawStream;
51
52    /// Retrieve all keys (but not values) matching a prefix from the verifiable key-value store.
53    fn prefix_keys(&self, prefix: &str) -> Self::PrefixKeysStream;
54
55    /// Retrieve all values for keys matching a prefix from the non-verifiable key-value store, as raw bytes.
56    ///
57    /// Users should generally prefer to use wrapper methods in an extension trait.
58    fn nonverifiable_prefix_raw(&self, prefix: &[u8]) -> Self::NonconsensusPrefixRawStream;
59
60    /// Retrieve all values for keys in a range from the non-verifiable key-value store, as raw bytes.
61    /// This method does not support inclusive ranges, and will return an error if passed one.
62    ///
63    /// Users should generally prefer to use wrapper methods in an extension trait.
64    fn nonverifiable_range_raw(
65        &self,
66        prefix: Option<&[u8]>,
67        range: impl RangeBounds<Vec<u8>>,
68    ) -> Result<Self::NonconsensusRangeRawStream>;
69}
70
71impl<'a, S: StateRead + Send + Sync> StateRead for &'a S {
72    type GetRawFut = S::GetRawFut;
73    type PrefixRawStream = S::PrefixRawStream;
74    type PrefixKeysStream = S::PrefixKeysStream;
75    type NonconsensusPrefixRawStream = S::NonconsensusPrefixRawStream;
76    type NonconsensusRangeRawStream = S::NonconsensusRangeRawStream;
77
78    fn get_raw(&self, key: &str) -> Self::GetRawFut {
79        (**self).get_raw(key)
80    }
81
82    fn prefix_raw(&self, prefix: &str) -> S::PrefixRawStream {
83        (**self).prefix_raw(prefix)
84    }
85
86    fn prefix_keys(&self, prefix: &str) -> S::PrefixKeysStream {
87        (**self).prefix_keys(prefix)
88    }
89
90    fn nonverifiable_prefix_raw(&self, prefix: &[u8]) -> S::NonconsensusPrefixRawStream {
91        (**self).nonverifiable_prefix_raw(prefix)
92    }
93
94    fn nonverifiable_range_raw(
95        &self,
96        prefix: Option<&[u8]>,
97        range: impl std::ops::RangeBounds<Vec<u8>>,
98    ) -> anyhow::Result<Self::NonconsensusRangeRawStream> {
99        (**self).nonverifiable_range_raw(prefix, range)
100    }
101
102    fn nonverifiable_get_raw(&self, key: &[u8]) -> Self::GetRawFut {
103        (**self).nonverifiable_get_raw(key)
104    }
105
106    fn object_get<T: Any + Send + Sync + Clone>(&self, key: &'static str) -> Option<T> {
107        (**self).object_get(key)
108    }
109
110    fn object_type(&self, key: &'static str) -> Option<std::any::TypeId> {
111        (**self).object_type(key)
112    }
113}
114
115impl<'a, S: StateRead + Send + Sync> StateRead for &'a mut S {
116    type GetRawFut = S::GetRawFut;
117    type PrefixRawStream = S::PrefixRawStream;
118    type PrefixKeysStream = S::PrefixKeysStream;
119    type NonconsensusPrefixRawStream = S::NonconsensusPrefixRawStream;
120    type NonconsensusRangeRawStream = S::NonconsensusRangeRawStream;
121
122    fn get_raw(&self, key: &str) -> Self::GetRawFut {
123        (**self).get_raw(key)
124    }
125
126    fn prefix_raw(&self, prefix: &str) -> S::PrefixRawStream {
127        (**self).prefix_raw(prefix)
128    }
129
130    fn prefix_keys(&self, prefix: &str) -> S::PrefixKeysStream {
131        (**self).prefix_keys(prefix)
132    }
133
134    fn nonverifiable_prefix_raw(&self, prefix: &[u8]) -> S::NonconsensusPrefixRawStream {
135        (**self).nonverifiable_prefix_raw(prefix)
136    }
137
138    fn nonverifiable_range_raw(
139        &self,
140        prefix: Option<&[u8]>,
141        range: impl RangeBounds<Vec<u8>>,
142    ) -> Result<S::NonconsensusRangeRawStream> {
143        (**self).nonverifiable_range_raw(prefix, range)
144    }
145
146    fn nonverifiable_get_raw(&self, key: &[u8]) -> Self::GetRawFut {
147        (**self).nonverifiable_get_raw(key)
148    }
149
150    fn object_get<T: Any + Send + Sync + Clone>(&self, key: &'static str) -> Option<T> {
151        (**self).object_get(key)
152    }
153
154    fn object_type(&self, key: &'static str) -> Option<std::any::TypeId> {
155        (**self).object_type(key)
156    }
157}
158
159impl<S: StateRead + Send + Sync> StateRead for Arc<S> {
160    type GetRawFut = S::GetRawFut;
161    type PrefixRawStream = S::PrefixRawStream;
162    type PrefixKeysStream = S::PrefixKeysStream;
163    type NonconsensusPrefixRawStream = S::NonconsensusPrefixRawStream;
164    type NonconsensusRangeRawStream = S::NonconsensusRangeRawStream;
165
166    fn get_raw(&self, key: &str) -> Self::GetRawFut {
167        (**self).get_raw(key)
168    }
169
170    fn prefix_raw(&self, prefix: &str) -> S::PrefixRawStream {
171        (**self).prefix_raw(prefix)
172    }
173
174    fn prefix_keys(&self, prefix: &str) -> S::PrefixKeysStream {
175        (**self).prefix_keys(prefix)
176    }
177
178    fn nonverifiable_prefix_raw(&self, prefix: &[u8]) -> S::NonconsensusPrefixRawStream {
179        (**self).nonverifiable_prefix_raw(prefix)
180    }
181
182    fn nonverifiable_range_raw(
183        &self,
184        prefix: Option<&[u8]>,
185        range: impl RangeBounds<Vec<u8>>,
186    ) -> Result<Self::NonconsensusRangeRawStream> {
187        (**self).nonverifiable_range_raw(prefix, range)
188    }
189
190    fn nonverifiable_get_raw(&self, key: &[u8]) -> Self::GetRawFut {
191        (**self).nonverifiable_get_raw(key)
192    }
193
194    fn object_get<T: Any + Send + Sync + Clone>(&self, key: &'static str) -> Option<T> {
195        (**self).object_get(key)
196    }
197
198    fn object_type(&self, key: &'static str) -> Option<std::any::TypeId> {
199        (**self).object_type(key)
200    }
201}
202
203impl StateRead for () {
204    type GetRawFut = futures::future::Ready<Result<Option<Vec<u8>>>>;
205    type PrefixRawStream = futures::stream::Iter<std::iter::Empty<Result<(String, Vec<u8>)>>>;
206    type PrefixKeysStream = futures::stream::Iter<std::iter::Empty<Result<String>>>;
207    type NonconsensusPrefixRawStream =
208        futures::stream::Iter<std::iter::Empty<Result<(Vec<u8>, Vec<u8>)>>>;
209    type NonconsensusRangeRawStream =
210        futures::stream::Iter<std::iter::Empty<Result<(Vec<u8>, Vec<u8>)>>>;
211
212    fn get_raw(&self, _key: &str) -> Self::GetRawFut {
213        futures::future::ready(Ok(None))
214    }
215
216    fn nonverifiable_get_raw(&self, _key: &[u8]) -> Self::GetRawFut {
217        futures::future::ready(Ok(None))
218    }
219
220    fn object_get<T: Any + Send + Sync + Clone>(&self, _key: &'static str) -> Option<T> {
221        None
222    }
223
224    fn object_type(&self, _key: &'static str) -> Option<std::any::TypeId> {
225        None
226    }
227
228    fn prefix_raw(&self, _prefix: &str) -> Self::PrefixRawStream {
229        futures::stream::iter(std::iter::empty())
230    }
231
232    fn prefix_keys(&self, _prefix: &str) -> Self::PrefixKeysStream {
233        futures::stream::iter(std::iter::empty())
234    }
235
236    fn nonverifiable_prefix_raw(&self, _prefix: &[u8]) -> Self::NonconsensusPrefixRawStream {
237        futures::stream::iter(std::iter::empty())
238    }
239
240    fn nonverifiable_range_raw(
241        &self,
242        _prefix: Option<&[u8]>,
243        _range: impl RangeBounds<Vec<u8>>,
244    ) -> Result<Self::NonconsensusRangeRawStream> {
245        Ok(futures::stream::iter(std::iter::empty()))
246    }
247}
cnidarium/read.rs

cnidarium/
read.rs
