spacetimedb_lib/filterable_value.rs
1use crate::{ConnectionId, Identity, Timestamp, Uuid};
2use core::ops;
3use spacetimedb_sats::bsatn;
4use spacetimedb_sats::{hash::Hash, i256, u256, Serialize};
5
6/// Types which can appear as an argument to an index filtering operation
7/// for a column of type `Column`.
8///
9/// Types which can appear specifically as a terminating bound in a BTree index,
10/// which may be a range, instead use [`IndexScanRangeBoundsTerminator`].
11///
12/// Because SpacetimeDB supports a only restricted set of types as index keys,
13/// only a small set of `Column` types have corresponding `FilterableValue` implementations.
14/// Specifically, these types are:
15/// - Signed and unsigned integers of various widths.
16/// - [`bool`].
17/// - [`String`], which is also filterable with `&str`.
18/// - [`Identity`].
19/// - [`Uuid`].
20/// - [`Timestamp`].
21/// - [`ConnectionId`].
22/// - [`Hash`](struct@Hash).
23/// - No-payload enums annotated with `#[derive(SpacetimeType)]`.
24/// No-payload enums are sometimes called "plain," "simple" or "C-style."
25/// They are enums where no variant has any payload data.
26///
27/// Because SpacetimeDB indexes are present both on the server
28/// and in clients which use our various SDKs,
29/// implementing `FilterableValue` for a new column type is a significant burden,
30/// and **is not as simple** as adding a new `impl FilterableValue` block to our Rust code.
31/// To implement `FilterableValue` for a new column type, you must also:
32/// - Ensure (with automated tests) that the `spacetimedb-codegen` crate
33/// and accompanying SpacetimeDB client SDK can equality-compare and ordering-compare values of the column type,
34/// and that the resulting ordering is the same as the canonical ordering
35/// implemented by `spacetimedb-sats` for [`spacetimedb_sats::AlgebraicValue`].
36/// This will nearly always require implementing bespoke comparison methods for the type in question,
37/// as most languages do not automatically make product types (structs or classes) sortable.
38/// - Extend our other supported module languages' bindings libraries.
39/// so that they can also define tables with indexes keyed by the new filterable type.
40//
41// General rules for implementors of this type:
42// - See above doc comment for requirements to add implementations for new column types.
43// - It should only be implemented for owned values if those values are `Copy`.
44// Otherwise it should only be implemented for references.
45// This is so that rustc and IDEs will recommend rewriting `x` to `&x` rather than `x.clone()`.
46// - `Arg: FilterableValue<Column = Col>`
47// for any pair of types `(Arg, Col)` which meet the above criteria
48// is desirable if `Arg` and `Col` have the same BSATN layout.
49// E.g. `&str: FilterableValue<Column = String>` is desirable.
50#[diagnostic::on_unimplemented(
51 message = "`{Self}` cannot appear as an argument to an index filtering operation",
52 label = "should be an integer type, `bool`, `String`, `&str`, `Identity`, `Uuid`, `Timestamp`, `ConnectionId`, `Hash` or a no-payload enum which derives `SpacetimeType`, not `{Self}`",
53 note = "The allowed set of types are limited to integers, bool, strings, `Identity`, `Uuid`, `Timestamp`, `ConnectionId`, `Hash` and no-payload enums which derive `SpacetimeType`,"
54)]
55pub trait FilterableValue: Serialize + Private {
56 type Column;
57}
58
59/// Hidden supertrait for [`FilterableValue`],
60/// to discourage users from hand-writing implementations.
61///
62/// We want to expose [`FilterableValue`] in the docs, but to prevent users from implementing it.
63/// Normally, we would just make this `Private` trait inaccessible,
64/// but we need to macro-generate implementations, so it must be `pub`.
65/// We mark it `doc(hidden)` to discourage use.
66#[doc(hidden)]
67pub trait Private {}
68
69macro_rules! impl_filterable_value {
70 (@one $arg:ty => $col:ty) => {
71 impl Private for $arg {}
72 impl FilterableValue for $arg {
73 type Column = $col;
74 }
75 };
76 (@one $arg:ty: Copy) => {
77 impl_filterable_value!(@one $arg => $arg);
78 impl_filterable_value!(@one &$arg => $arg);
79 };
80 (@one $arg:ty) => {
81 impl_filterable_value!(@one &$arg => $arg);
82 };
83 ($($arg:ty $(: $copy:ident)? $(=> $col:ty)?),* $(,)?) => {
84 $(impl_filterable_value!(@one $arg $(: $copy)? $(=> $col)?);)*
85 };
86}
87
88impl_filterable_value! {
89 u8: Copy,
90 u16: Copy,
91 u32: Copy,
92 u64: Copy,
93 u128: Copy,
94 u256: Copy,
95
96 i8: Copy,
97 i16: Copy,
98 i32: Copy,
99 i64: Copy,
100 i128: Copy,
101 i256: Copy,
102
103 bool: Copy,
104
105 String,
106 &str => String,
107
108 Identity: Copy,
109 Uuid: Copy,
110 Timestamp: Copy,
111 ConnectionId: Copy,
112 Hash: Copy,
113
114 // Some day we will likely also want to support `Vec<u8>` and `[u8]`,
115 // as they have trivial portable equality and ordering,
116 // but @RReverser's proposed filtering rules do not include them.
117 // Vec<u8>,
118 // &[u8] => Vec<u8>,
119}
120
121/// Marker trait for column types supported as procedural view primary keys.
122#[doc(hidden)]
123#[diagnostic::on_unimplemented(
124 message = "view primary key column type `{Self}` is not supported",
125 label = "view primary key columns must use an index-filterable key type",
126 note = "view primary keys must be integer, bool, string, Identity, Uuid, Timestamp, ConnectionId, Hash, or a no-payload enum which derives SpacetimeType"
127)]
128pub trait ViewPrimaryKeyColumn {}
129impl<T> ViewPrimaryKeyColumn for T where for<'a> &'a T: FilterableValue<Column = T> {}
130
131pub enum TermBound<T> {
132 Single(ops::Bound<T>),
133 Range(ops::Bound<T>, ops::Bound<T>),
134}
135impl<Bound: FilterableValue> TermBound<&Bound> {
136 #[inline]
137 /// If `self` is [`TermBound::Range`], returns the `rend_idx` value for `IndexScanRangeArgs`,
138 /// i.e. the index in `buf` of the first byte in the end range
139 pub fn serialize_into(&self, buf: &mut Vec<u8>) -> Option<usize> {
140 let (start, end) = match self {
141 TermBound::Single(elem) => (elem, None),
142 TermBound::Range(start, end) => (start, Some(end)),
143 };
144 bsatn::to_writer(buf, start).unwrap();
145 end.map(|end| {
146 let rend_idx = buf.len();
147 bsatn::to_writer(buf, end).unwrap();
148 rend_idx
149 })
150 }
151}
152pub trait IndexScanRangeBoundsTerminator {
153 /// Whether this bound terminator is a point.
154 const POINT: bool = false;
155
156 /// The key type of the bound.
157 type Arg;
158
159 /// Returns the point bound, assuming `POINT == true`.
160 fn point(&self) -> &Self::Arg {
161 unimplemented!()
162 }
163
164 /// Returns the terminal bound for the range scan.
165 /// This bound can either be a point, as in most cases, or an actual bound.
166 fn bounds(&self) -> TermBound<&Self::Arg>;
167}
168
169impl<Col, Arg: FilterableValue<Column = Col>> IndexScanRangeBoundsTerminator for Arg {
170 const POINT: bool = true;
171 type Arg = Arg;
172 fn point(&self) -> &Arg {
173 self
174 }
175 fn bounds(&self) -> TermBound<&Arg> {
176 TermBound::Single(ops::Bound::Included(self))
177 }
178}
179
180macro_rules! impl_terminator {
181 ($($range:ty),* $(,)?) => {
182 $(impl<T: FilterableValue> IndexScanRangeBoundsTerminator for $range {
183 type Arg = T;
184 fn bounds(&self) -> TermBound<&T> {
185 TermBound::Range(
186 ops::RangeBounds::start_bound(self),
187 ops::RangeBounds::end_bound(self),
188 )
189 }
190 })*
191 };
192}
193
194impl_terminator!(
195 ops::Range<T>,
196 ops::RangeFrom<T>,
197 ops::RangeInclusive<T>,
198 ops::RangeTo<T>,
199 ops::RangeToInclusive<T>,
200 (ops::Bound<T>, ops::Bound<T>),
201);