1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
pub mod value;
use crux_core::capability::Operation;
use facet::Facet;
use serde::{Deserialize, Serialize};
use crate::error::KeyValueError;
pub use value::*;
/// Supported operations
#[derive(Facet, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[repr(C)]
pub enum KeyValueOperation {
/// Read bytes stored under a key
Get { key: String },
/// Write bytes under a key
Set {
key: String,
#[serde(with = "serde_bytes")]
value: Vec<u8>,
},
/// Remove a key and its value
Delete { key: String },
/// Test if a key exists
Exists { key: String },
// List keys that start with a prefix, starting at the cursor
ListKeys {
/// The prefix to list keys for, or an empty string to list all keys
prefix: String,
/// The cursor to start listing from, or 0 to start from the beginning.
/// If there are more keys to list, the response will include a new cursor.
/// If there are no more keys, the response will include a cursor of 0.
/// The cursor is opaque to the caller, and should be passed back to the
/// `ListKeys` operation to continue listing keys.
/// If the cursor is not found for the specified prefix, the response will include
/// a `KeyValueError::CursorNotFound` error.
cursor: u64,
},
}
impl std::fmt::Debug for KeyValueOperation {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
KeyValueOperation::Get { key } => f.debug_struct("Get").field("key", key).finish(),
KeyValueOperation::Set { key, value } => {
let body_repr = if let Ok(s) = std::str::from_utf8(value) {
if s.len() < 50 {
format!("\"{s}\"")
} else {
format!("\"{}\"...", s.chars().take(50).collect::<String>())
}
} else {
format!("<binary data - {} bytes>", value.len())
};
f.debug_struct("Set")
.field("key", key)
.field("value", &format_args!("{body_repr}"))
.finish()
}
KeyValueOperation::Delete { key } => {
f.debug_struct("Delete").field("key", key).finish()
}
KeyValueOperation::Exists { key } => {
f.debug_struct("Exists").field("key", key).finish()
}
KeyValueOperation::ListKeys { prefix, cursor } => f
.debug_struct("ListKeys")
.field("prefix", prefix)
.field("cursor", cursor)
.finish(),
}
}
}
/// The result of an operation on the store.
///
/// Note: we can't use [`core::result::Result`] here because it is not currently
/// supported across the FFI boundary, when using `typegen` or `facet_typegen`.
#[derive(Facet, Clone, Serialize, Deserialize, Debug, PartialEq, Eq)]
#[repr(C)]
pub enum KeyValueResult {
Ok { response: KeyValueResponse },
Err { error: KeyValueError },
}
#[derive(Facet, Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[repr(C)]
pub enum KeyValueResponse {
/// Response to a `KeyValueOperation::Get`,
/// returning the value stored under the key, which may be empty
Get { value: Value },
/// Response to a `KeyValueOperation::Set`,
/// returning the value that was previously stored under the key, may be empty
Set { previous: Value },
/// Response to a `KeyValueOperation::Delete`,
/// returning the value that was previously stored under the key, may be empty
Delete { previous: Value },
/// Response to a `KeyValueOperation::Exists`,
/// returning whether the key is present in the store
Exists { is_present: bool },
/// Response to a `KeyValueOperation::ListKeys`,
/// returning a list of keys that start with the prefix, and a cursor to continue listing
/// if there are more keys
///
/// Note: the cursor is 0 if there are no more keys
ListKeys {
keys: Vec<String>,
/// The cursor to continue listing keys, or 0 if there are no more keys.
/// If the cursor is not found for the specified prefix, the response should instead
/// include a `KeyValueError::CursorNotFound` error.
next_cursor: u64,
},
}
impl Operation for KeyValueOperation {
type Output = KeyValueResult;
#[cfg(feature = "typegen")]
fn register_types(
generator: &mut crux_core::type_generation::serde::TypeGen,
) -> crux_core::type_generation::serde::Result {
generator.register_type::<KeyValueResponse>()?;
generator.register_type::<KeyValueError>()?;
generator.register_type::<Value>()?;
generator.register_type::<Self>()?;
generator.register_type::<Self::Output>()?;
Ok(())
}
}
impl KeyValueResult {
/// Converts a [`KeyValueResult`] into a [`Result`]
/// # Errors
/// Passes any errors from the underlying [`KeyValueError`] to the returned `Result`.
/// # Panics
/// Panics if the [`KeyValueResult`] is not a [`KeyValueResponse::Get`].
pub fn unwrap_get(self) -> Result<Option<Vec<u8>>, KeyValueError> {
match self {
KeyValueResult::Ok { response } => match response {
KeyValueResponse::Get { value } => Ok(value.into()),
_ => {
panic!("attempt to convert KeyValueResponse other than Get to Option<Vec<u8>>")
}
},
KeyValueResult::Err { error } => Err(error.clone()),
}
}
/// Converts a [`KeyValueResult`] into a [`Result`]
/// # Errors
/// Passes any errors from the underlying [`KeyValueError`] to the returned `Result`.
/// # Panics
/// Panics if the [`KeyValueResult`] is not a [`KeyValueResponse::Set`].
pub fn unwrap_set(self) -> Result<Option<Vec<u8>>, KeyValueError> {
match self {
KeyValueResult::Ok { response } => match response {
KeyValueResponse::Set { previous } => Ok(previous.into()),
_ => {
panic!("attempt to convert KeyValueResponse other than Set to Option<Vec<u8>>")
}
},
KeyValueResult::Err { error } => Err(error.clone()),
}
}
/// Converts a [`KeyValueResult`] into a [`Result`]
/// # Errors
/// Passes any errors from the underlying [`KeyValueError`] to the returned `Result`.
/// # Panics
/// Panics if the [`KeyValueResult`] is not a [`KeyValueResponse::Delete`].
pub fn unwrap_delete(self) -> Result<Option<Vec<u8>>, KeyValueError> {
match self {
KeyValueResult::Ok { response } => match response {
KeyValueResponse::Delete { previous } => Ok(previous.into()),
_ => panic!(
"attempt to convert KeyValueResponse other than Delete to Option<Vec<u8>>"
),
},
KeyValueResult::Err { error } => Err(error.clone()),
}
}
/// Converts a [`KeyValueResult`] into a [`Result`]
/// # Errors
/// Passes any errors from the underlying [`KeyValueError`] to the returned `Result`.
/// # Panics
/// Panics if the [`KeyValueResult`] is not a [`KeyValueResponse::Exists`].
pub fn unwrap_exists(self) -> Result<bool, KeyValueError> {
match self {
KeyValueResult::Ok { response } => match response {
KeyValueResponse::Exists { is_present } => Ok(is_present),
_ => panic!("attempt to convert KeyValueResponse other than Exists to bool"),
},
KeyValueResult::Err { error } => Err(error.clone()),
}
}
/// Converts a [`KeyValueResult`] into a [`Result`]
/// # Errors
/// Passes any errors from the underlying [`KeyValueError`] to the returned `Result`.
/// # Panics
/// Panics if the [`KeyValueResult`] is not a [`KeyValueResponse::ListKeys`].
pub fn unwrap_list_keys(self) -> Result<(Vec<String>, u64), KeyValueError> {
match self {
KeyValueResult::Ok { response } => match response {
KeyValueResponse::ListKeys {
keys,
next_cursor: cursor,
} => Ok((keys, cursor)),
_ => panic!(
"attempt to convert KeyValueResponse other than ListKeys to (Vec<String>, u64)"
),
},
KeyValueResult::Err { error } => Err(error.clone()),
}
}
}