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
121pub enum TermBound<T> {
122    Single(ops::Bound<T>),
123    Range(ops::Bound<T>, ops::Bound<T>),
124}
125impl<Bound: FilterableValue> TermBound<&Bound> {
126    #[inline]
127    /// If `self` is [`TermBound::Range`], returns the `rend_idx` value for `IndexScanRangeArgs`,
128    /// i.e. the index in `buf` of the first byte in the end range
129    pub fn serialize_into(&self, buf: &mut Vec<u8>) -> Option<usize> {
130        let (start, end) = match self {
131            TermBound::Single(elem) => (elem, None),
132            TermBound::Range(start, end) => (start, Some(end)),
133        };
134        bsatn::to_writer(buf, start).unwrap();
135        end.map(|end| {
136            let rend_idx = buf.len();
137            bsatn::to_writer(buf, end).unwrap();
138            rend_idx
139        })
140    }
141}
142pub trait IndexScanRangeBoundsTerminator {
143    /// Whether this bound terminator is a point.
144    const POINT: bool = false;
145
146    /// The key type of the bound.
147    type Arg;
148
149    /// Returns the point bound, assuming `POINT == true`.
150    fn point(&self) -> &Self::Arg {
151        unimplemented!()
152    }
153
154    /// Returns the terminal bound for the range scan.
155    /// This bound can either be a point, as in most cases, or an actual bound.
156    fn bounds(&self) -> TermBound<&Self::Arg>;
157}
158
159impl<Col, Arg: FilterableValue<Column = Col>> IndexScanRangeBoundsTerminator for Arg {
160    const POINT: bool = true;
161    type Arg = Arg;
162    fn point(&self) -> &Arg {
163        self
164    }
165    fn bounds(&self) -> TermBound<&Arg> {
166        TermBound::Single(ops::Bound::Included(self))
167    }
168}
169
170macro_rules! impl_terminator {
171    ($($range:ty),* $(,)?) => {
172        $(impl<T: FilterableValue> IndexScanRangeBoundsTerminator for $range {
173            type Arg = T;
174            fn bounds(&self) -> TermBound<&T> {
175                TermBound::Range(
176                    ops::RangeBounds::start_bound(self),
177                    ops::RangeBounds::end_bound(self),
178                )
179            }
180        })*
181    };
182}
183
184impl_terminator!(
185    ops::Range<T>,
186    ops::RangeFrom<T>,
187    ops::RangeInclusive<T>,
188    ops::RangeTo<T>,
189    ops::RangeToInclusive<T>,
190    (ops::Bound<T>, ops::Bound<T>),
191);
spacetimedb_lib/filterable_value.rs

spacetimedb_lib/
filterable_value.rs
