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};