Skip to main content

kevy_verbs/
lib.rs

1//! The command layer shared by kevy's server and its embedded engine.
2//!
3//! [`exec`] runs one command against one `kevy_store::Store` and writes
4//! its RESP reply: the argv grammar, the checks, the store call and the
5//! reply wording all live here, once. What differs between the server
6//! and the embedded engine — locking, routing keys to shards, multi-key
7//! coordination, where a write is recorded — stays with each of them,
8//! and [`Effect`] tells them what the command did so they can record it.
9//!
10//! [`args`] reads argv tokens the way Redis does and [`reply`] writes
11//! replies with Redis's wording, for the commands that live outside
12//! this crate.
13//!
14//! The stream (`X*`) and geo (`GEO*`) commands are behind the
15//! `streams-geo` feature, off by default.
16//!
17//! ```
18//! use kevy_verbs::{Effect, exec};
19//!
20//! let mut store = kevy_store::Store::new();
21//! let argv = kevy_resp::Argv::from(vec![b"HSET".to_vec(), b"h".to_vec(), b"f".to_vec(), b"v".to_vec()]);
22//! let mut out = Vec::new();
23//! assert_eq!(exec(&mut store, b"HSET", &argv, &mut out), Some(Effect::Write));
24//! assert_eq!(out, b":1\r\n");
25//! ```
26
27use kevy_resp::ArgvView;
28use kevy_store::{Store, StreamId};
29
30pub mod aof;
31pub mod args;
32mod bitmap;
33pub mod cmd;
34#[cfg(feature = "streams-geo")]
35pub mod geo;
36mod hash;
37mod hash_ttl;
38mod keyspace;
39mod list;
40mod list_move;
41mod record;
42mod record_group;
43mod record_read;
44pub mod reply;
45mod set;
46#[cfg(feature = "streams-geo")]
47mod stream;
48mod stream_resp3;
49mod strings;
50mod verbs;
51mod zset;
52mod zset_range;
53
54pub use verbs::{VERBS, Verb, is_streams_geo, is_write, verb};
55
56/// What a command did, for a caller that records writes.
57///
58/// It describes a command whose reply was not an error. An error reply
59/// always means nothing changed, whatever this says.
60///
61/// ```
62/// use kevy_verbs::{Effect, exec};
63///
64/// let mut store = kevy_store::Store::new();
65/// let del = kevy_resp::Argv::from(vec![b"DEL".to_vec(), b"missing".to_vec()]);
66/// let mut out = Vec::new();
67/// assert_eq!(exec(&mut store, b"DEL", &del, &mut out), Some(Effect::Unchanged));
68/// ```
69#[derive(Debug, Clone, PartialEq, Eq)]
70pub enum Effect {
71    /// A read: nothing to record.
72    ///
73    /// ```
74    /// use kevy_verbs::{Effect, exec};
75    /// let argv = |s: &str| kevy_resp::Argv::from(s.split(' ').map(|p| p.as_bytes().to_vec()).collect::<Vec<_>>());
76    /// let mut store = kevy_store::Store::new();
77    /// assert_eq!(exec(&mut store, b"GET", &argv("GET k"), &mut Vec::new()), Some(Effect::Read));
78    /// ```
79    Read,
80    /// A write: record the argv as it was run.
81    ///
82    /// ```
83    /// use kevy_verbs::{Effect, exec};
84    /// let argv = |s: &str| kevy_resp::Argv::from(s.split(' ').map(|p| p.as_bytes().to_vec()).collect::<Vec<_>>());
85    /// let mut store = kevy_store::Store::new();
86    /// assert_eq!(exec(&mut store, b"SET", &argv("SET k v"), &mut Vec::new()), Some(Effect::Write));
87    /// ```
88    Write,
89    /// A write that changed nothing this time, such as `SET … NX` on a
90    /// key that exists or `HDEL` of a missing field. Recording the argv
91    /// is harmless; a caller that records only changes can skip it.
92    ///
93    /// ```
94    /// use kevy_verbs::{Effect, exec};
95    /// let argv = |s: &str| kevy_resp::Argv::from(s.split(' ').map(|p| p.as_bytes().to_vec()).collect::<Vec<_>>());
96    /// let mut store = kevy_store::Store::new();
97    /// exec(&mut store, b"SET", &argv("SET k v"), &mut Vec::new());
98    /// let nx = argv("SET k w NX");
99    /// assert_eq!(exec(&mut store, b"SET", &nx, &mut Vec::new()), Some(Effect::Unchanged));
100    /// ```
101    Unchanged,
102    /// Record this frame instead of the argv. A command whose effect is
103    /// random (`SPOP`) is recorded as what it did (`SREM key member…`),
104    /// so replaying the record cannot pick differently.
105    ///
106    /// ```
107    /// use kevy_verbs::{Effect, exec};
108    /// let argv = |s: &str| kevy_resp::Argv::from(s.split(' ').map(|p| p.as_bytes().to_vec()).collect::<Vec<_>>());
109    /// let mut store = kevy_store::Store::new();
110    /// exec(&mut store, b"SADD", &argv("SADD s only"), &mut Vec::new());
111    /// let effect = exec(&mut store, b"SPOP", &argv("SPOP s"), &mut Vec::new());
112    /// let srem = ["SREM", "s", "only"].map(|w| w.as_bytes().to_vec()).to_vec();
113    /// assert_eq!(effect, Some(Effect::Record(srem)));
114    /// ```
115    Record(Vec<Vec<u8>>),
116    /// Record the argv with argument `.0` replaced by the ID `.1`: an `XADD`
117    /// whose ID was generated (`*`, `ms-*`), recorded as the ID it gave so
118    /// a replay's clock cannot pick another. Carries no frame: a caller
119    /// that records builds it with [`aof::deferred_frames`].
120    ///
121    /// ```
122    /// use kevy_verbs::{Effect, exec};
123    /// if kevy_verbs::verb(b"XADD").is_none() {
124    ///     return; // built without the `streams-geo` feature
125    /// }
126    /// let mut store = kevy_store::Store::new();
127    /// let argv = kevy_resp::Argv::from(vec![b"XADD".to_vec(), b"s".to_vec(), b"7-*".to_vec(), b"f".to_vec(), b"v".to_vec()]);
128    /// let id = kevy_store::StreamId::new(7, 0);
129    /// assert_eq!(exec(&mut store, b"XADD", &argv, &mut Vec::new()), Some(Effect::RecordId(2, id)));
130    /// ```
131    RecordId(usize, StreamId),
132    /// Record an `XADD` that trimmed approximately (`~`) as the exact trim
133    /// it made: `.0` is where its ID sits, `.1` the ID it gave, `.2` the
134    /// length it left the stream at, or `u64::MAX` when it removed
135    /// nothing (recorded without a trim). Where an approximate trim cuts
136    /// depends on the stream's history, which a replay need not share.
137    ///
138    /// ```
139    /// use kevy_verbs::{Effect, exec};
140    /// if kevy_verbs::verb(b"XADD").is_none() {
141    ///     return; // built without the `streams-geo` feature
142    /// }
143    /// let argv = |s: &str| kevy_resp::Argv::from(s.split(' ').map(|p| p.as_bytes().to_vec()).collect::<Vec<_>>());
144    /// let mut store = kevy_store::Store::new();
145    /// let add = argv("XADD s MAXLEN ~ 10 5-1 f v");
146    /// let effect = exec(&mut store, b"XADD", &add, &mut Vec::new()).unwrap();
147    /// let frame = &kevy_verbs::aof::deferred_frames(&store, &add, &effect)[0];
148    /// let words: Vec<&[u8]> = (0..frame.len()).map(|i| &frame[i]).collect();
149    /// assert_eq!(words, [&b"XADD"[..], b"s", b"5-1", b"f", b"v"], "it removed nothing");
150    /// ```
151    RecordAdd(usize, StreamId, u64),
152    /// Record a claim as its outcome: an `XCLAIM` / `XAUTOCLAIM`, which
153    /// picks by idle time and stamps with the clock. Carries no frame: a
154    /// caller that records builds them with [`aof::deferred_frames`].
155    ///
156    /// ```
157    /// use kevy_verbs::{Effect, exec};
158    /// if kevy_verbs::verb(b"XCLAIM").is_none() {
159    ///     return; // built without the `streams-geo` feature
160    /// }
161    /// let mut store = kevy_store::Store::new();
162    /// let argv = |s: &str| kevy_resp::Argv::from(s.split(' ').map(|p| p.as_bytes().to_vec()).collect::<Vec<_>>());
163    /// for c in ["XADD s 1-1 f v", "XGROUP CREATE s g 0", "XREADGROUP GROUP g a STREAMS s >"] {
164    ///     let up = c.split(' ').next().unwrap().as_bytes();
165    ///     exec(&mut store, up, &argv(c), &mut Vec::new());
166    /// }
167    /// let claim = argv("XCLAIM s g b 0 1-1 JUSTID");
168    /// let effect = exec(&mut store, b"XCLAIM", &claim, &mut Vec::new()).unwrap();
169    /// assert!(matches!(effect, Effect::RecordClaim(_)));
170    /// let frames = kevy_verbs::aof::deferred_frames(&mut store, &claim, &effect);
171    /// // b made, the claim, then b's times as the claim left them
172    /// assert_eq!(&frames[0][1], b"CREATECONSUMER");
173    /// let head: Vec<&[u8]> = (0..6).map(|i| &frames[1][i]).collect();
174    /// assert_eq!(head, [&b"XCLAIM"[..], b"s", b"g", b"b", b"0", b"1-1"]);
175    /// assert_eq!(&frames[2][0], b"XINTERNAL.CONSUMERSEEN");
176    /// ```
177    RecordClaim(Box<aof::Claim>),
178    /// Record a one-stream `XREADGROUP` as what it left, not as a read a
179    /// replay would stamp with its own clock: `.0` is the group's
180    /// last-delivered ID before the read, `.1` whether the read created its
181    /// consumer. Carries no frame: a caller that records builds them with
182    /// [`aof::deferred_frames`].
183    ///
184    /// ```
185    /// use kevy_verbs::{Effect, exec};
186    /// if kevy_verbs::verb(b"XREADGROUP").is_none() {
187    ///     return; // built without the `streams-geo` feature
188    /// }
189    /// let mut store = kevy_store::Store::new();
190    /// let argv = |s: &str| kevy_resp::Argv::from(s.split(' ').map(|p| p.as_bytes().to_vec()).collect::<Vec<_>>());
191    /// for c in ["XADD s 1-1 f v", "XGROUP CREATE s g 0"] {
192    ///     exec(&mut store, c.split(' ').next().unwrap().as_bytes(), &argv(c), &mut Vec::new());
193    /// }
194    /// let read = argv("XREADGROUP GROUP g a STREAMS s >");
195    /// let effect = exec(&mut store, b"XREADGROUP", &read, &mut Vec::new()).unwrap();
196    /// assert_eq!(effect, Effect::RecordRead(kevy_store::StreamId::MIN, kevy_verbs::aof::Consumer::Created));
197    /// let frames = kevy_verbs::aof::deferred_frames(&store, &read, &effect);
198    /// let verbs: Vec<&[u8]> = frames.iter().map(|f| &f[0]).collect();
199    /// // the group's move and read counter, the consumer made, the
200    /// // delivery, then the consumer's times
201    /// let group = &b"XGROUP"[..];
202    /// assert_eq!(verbs, [group, group, group, b"XCLAIM", b"XINTERNAL.CONSUMERSEEN"]);
203    /// ```
204    RecordRead(StreamId, aof::Consumer),
205    /// [`Effect::RecordRead`] for an `XREADGROUP` over several streams:
206    /// one `(last-delivered before, consumer created)` pair per stream, in
207    /// `STREAMS` order.
208    ///
209    /// ```
210    /// use kevy_verbs::{Effect, exec};
211    /// if kevy_verbs::verb(b"XREADGROUP").is_none() {
212    ///     return; // built without the `streams-geo` feature
213    /// }
214    /// let mut store = kevy_store::Store::new();
215    /// let argv = |s: &str| kevy_resp::Argv::from(s.split(' ').map(|p| p.as_bytes().to_vec()).collect::<Vec<_>>());
216    /// for c in ["XADD a 1-1 f v", "XADD b 1-1 f v", "XGROUP CREATE a g 0", "XGROUP CREATE b g 0"] {
217    ///     exec(&mut store, c.split(' ').next().unwrap().as_bytes(), &argv(c), &mut Vec::new());
218    /// }
219    /// let read = argv("XREADGROUP GROUP g c STREAMS a b > >");
220    /// let Some(Effect::RecordReads(marks)) = exec(&mut store, b"XREADGROUP", &read, &mut Vec::new()) else {
221    ///     panic!("a read of two streams is marked per stream")
222    /// };
223    /// assert_eq!(marks.len(), 2);
224    /// ```
225    RecordReads(Vec<(StreamId, aof::Consumer)>),
226    /// [`Effect::RecordReads`] for an `XREADGROUP` that read a consumer's
227    /// history and delivered entries again, which counts each of them as
228    /// delivered once more and stamps it with the clock.
229    ///
230    /// ```
231    /// use kevy_verbs::{Effect, exec};
232    /// if kevy_verbs::verb(b"XREADGROUP").is_none() {
233    ///     return; // built without the `streams-geo` feature
234    /// }
235    /// let mut store = kevy_store::Store::new();
236    /// let argv = |s: &str| kevy_resp::Argv::from(s.split(' ').map(|p| p.as_bytes().to_vec()).collect::<Vec<_>>());
237    /// for c in ["XADD s 1-1 f v", "XGROUP CREATE s g 0", "XREADGROUP GROUP g a STREAMS s >"] {
238    ///     exec(&mut store, c.split(' ').next().unwrap().as_bytes(), &argv(c), &mut Vec::new());
239    /// }
240    /// let again = argv("XREADGROUP GROUP g a STREAMS s 0");
241    /// let effect = exec(&mut store, b"XREADGROUP", &again, &mut Vec::new()).unwrap();
242    /// assert!(matches!(effect, Effect::RecordHistory(_)));
243    /// let frames = kevy_verbs::aof::deferred_frames(&store, &again, &effect);
244    /// assert_eq!(&frames[0][0], b"XCLAIM", "the delivery, with its count now 2");
245    /// ```
246    RecordHistory(Box<aof::History>),
247    /// Record an `XGROUP CREATECONSUMER` that created its consumer as the
248    /// command, then `XINTERNAL.CONSUMERSEEN key group consumer t`, `t` the
249    /// time it was created at, so a replay does not keep its own. Carries no
250    /// frame: a caller that records builds it with
251    /// [`aof::deferred_frames`].
252    ///
253    /// ```
254    /// use kevy_verbs::{Effect, exec};
255    /// if kevy_verbs::verb(b"XGROUP").is_none() {
256    ///     return; // built without the `streams-geo` feature
257    /// }
258    /// let mut store = kevy_store::Store::new();
259    /// let argv = |s: &str| kevy_resp::Argv::from(s.split(' ').map(|p| p.as_bytes().to_vec()).collect::<Vec<_>>());
260    /// exec(&mut store, b"XGROUP", &argv("XGROUP CREATE s g $ MKSTREAM"), &mut Vec::new());
261    /// let create = argv("XGROUP CREATECONSUMER s g c");
262    /// let effect = exec(&mut store, b"XGROUP", &create, &mut Vec::new()).unwrap();
263    /// assert_eq!(effect, Effect::RecordSeen);
264    /// let frame = &kevy_verbs::aof::deferred_frames(&store, &create, &effect)[1];
265    /// assert_eq!((frame.len(), &frame[0]), (5, &b"XINTERNAL.CONSUMERSEEN"[..]));
266    /// ```
267    RecordSeen,
268    /// Record an `XGROUP CREATE` or `SETID` that set the group's read
269    /// counter (`ENTRIESREAD n`) as the same command without it, then
270    /// `XGROUP SETID key group id ENTRIESREAD n` alone: a reader that
271    /// does not know the option still takes the first. Carries no frame:
272    /// a caller that records builds them with [`aof::deferred_frames`].
273    ///
274    /// ```
275    /// use kevy_verbs::{Effect, exec};
276    /// if kevy_verbs::verb(b"XGROUP").is_none() {
277    ///     return; // built without the `streams-geo` feature
278    /// }
279    /// let mut store = kevy_store::Store::new();
280    /// let argv = |s: &str| kevy_resp::Argv::from(s.split(' ').map(|p| p.as_bytes().to_vec()).collect::<Vec<_>>());
281    /// let create = argv("XGROUP CREATE s g $ MKSTREAM ENTRIESREAD 0");
282    /// let effect = exec(&mut store, b"XGROUP", &create, &mut Vec::new()).unwrap();
283    /// assert_eq!(effect, Effect::RecordGroup);
284    /// let frames = kevy_verbs::aof::deferred_frames(&store, &create, &effect);
285    /// assert_eq!((frames[0].len(), frames[1].len()), (6, 7), "CREATE … MKSTREAM, then SETID … ENTRIESREAD 0");
286    /// ```
287    RecordGroup,
288    /// Record nothing, not even the argv: a random command that removed
289    /// nothing, or a claim that changed nothing.
290    ///
291    /// ```
292    /// use kevy_verbs::{Effect, exec};
293    /// let argv = |s: &str| kevy_resp::Argv::from(s.split(' ').map(|p| p.as_bytes().to_vec()).collect::<Vec<_>>());
294    /// let mut store = kevy_store::Store::new();
295    /// // popping from a set that does not exist removes nothing
296    /// assert_eq!(exec(&mut store, b"SPOP", &argv("SPOP none"), &mut Vec::new()), Some(Effect::Skip));
297    /// ```
298    Skip,
299}
300
301/// Run one command against `store`, appending its RESP2 reply to `out`.
302///
303/// `verb` is `args[0]` uppercased (see [`args::upper_verb`]). `None`
304/// means the verb is not one this layer executes; `out` is untouched.
305///
306/// ```
307/// let mut store = kevy_store::Store::new();
308/// let argv = kevy_resp::Argv::from(vec![b"INCR".to_vec(), b"n".to_vec()]);
309/// let mut out = Vec::new();
310/// assert!(kevy_verbs::exec(&mut store, b"INCR", &argv, &mut out).is_some());
311/// assert_eq!(out, b":1\r\n");
312/// assert!(kevy_verbs::exec(&mut store, b"PING", &argv, &mut out).is_none());
313/// ```
314pub fn exec<A: ArgvView + ?Sized>(
315    store: &mut Store,
316    verb: &[u8],
317    args: &A,
318    out: &mut Vec<u8>,
319) -> Option<Effect> {
320    if let Some(e) = strings::exec(verb, store, args, out) {
321        return Some(e);
322    }
323    if let Some(e) = bitmap::exec(verb, store, args, out) {
324        return Some(e);
325    }
326    if let Some(e) = hash::exec(verb, store, args, out) {
327        return Some(e);
328    }
329    if let Some(e) = list::exec(verb, store, args, out) {
330        return Some(e);
331    }
332    if let Some(e) = set::exec(verb, store, args, out) {
333        return Some(e);
334    }
335    if let Some(e) = zset::exec(verb, store, args, out) {
336        return Some(e);
337    }
338    if let Some(e) = keyspace::exec(verb, store, args, out) {
339        return Some(e);
340    }
341    #[cfg(feature = "streams-geo")]
342    if let Some(e) = geo::exec(verb, store, args, out) {
343        return Some(e);
344    }
345    #[cfg(feature = "streams-geo")]
346    if let Some(e) = stream::exec(verb, store, args, out) {
347        return Some(e);
348    }
349    None
350}
351
352/// `Write` when `changed`, `Unchanged` otherwise.
353fn changed(changed: bool) -> Effect {
354    if changed { Effect::Write } else { Effect::Unchanged }
355}
356
357#[cfg(test)]
358mod tests;
359
360const _: () = {
361    const fn send_sync<T: Send + Sync>() {}
362    send_sync::<Effect>();
363    send_sync::<Verb>();
364    send_sync::<args::ScanOpts>();
365    send_sync::<args::ScanOptsError>();
366    send_sync::<aof::Claim>();
367    send_sync::<aof::Consumer>();
368    send_sync::<reply::Scores>();
369    #[cfg(feature = "streams-geo")]
370    send_sync::<geo::StoreSearchError>();
371};