rcfe_core/kv.rs
1use tonic::Response;
2use crate::{error::Error, etcdserverpb::RangeResponse, ByteSequence};
3use crate::etcdserverpb::RangeRequest;
4
5/// KVClient defines the interface for interacting with the key-value store.
6/// It provides methods to perform range queries with various options.
7#[tonic::async_trait]
8pub trait KVClient {
9
10 /// Performs a range query for the specified key.
11 /// # Arguments
12 /// * `key` - The key to query.
13 /// # Returns
14 /// * `Result<Response<RangeResponse>, Error>` - The response containing the range results or an error if the operation fails.
15 /// # Errors
16 /// * Returns an `Error` if the range operation fails.
17 async fn range(&mut self, key: ByteSequence) -> Result<Response<RangeResponse>, Error> {
18 self.range_with_options(
19 Some(key),
20 None,
21 None,
22 None,
23 None,
24 None,
25 None,
26 None,
27 None,
28 None,
29 None,
30 None,
31 ).await
32 }
33
34 /// Performs a range query for all keys with the specified prefix.
35 /// # Arguments
36 /// * `prefix` - The prefix to query.
37 /// # Returns
38 /// * `Result<Response<RangeResponse>, Error>` - The response containing the range results or an error if the operation fails.
39 /// # Errors
40 /// * Returns an `Error` if the range operation fails.
41 async fn range_with_prefix(&mut self, prefix: ByteSequence) -> Result<Response<RangeResponse>, Error> {
42 let range_end = prefix.next();
43 self.range_with_options(
44 Some(prefix),
45 Some(range_end),
46 None,
47 None,
48 None,
49 None,
50 None,
51 None,
52 None,
53 None,
54 None,
55 None,
56 ).await
57 }
58
59 /// Performs a range query for the specified key as a string.
60 /// # Arguments
61 /// * `key` - The key to query as a string.
62 /// # Returns
63 /// * `Result<Response<RangeResponse>, Error>` - The response containing the range results or an error if the operation fails.
64 /// # Errors
65 /// * Returns an `Error` if the range operation fails.
66 async fn range_with_str(&mut self, key: &str) -> Result<Response<RangeResponse>, Error> {
67 self.range(ByteSequence::from(key)).await
68 }
69
70 /// Performs a range query for the specified key and range end.
71 /// # Arguments
72 /// * `key` - The key to query as a string.
73 /// * `range_end` - The end of the range to query.
74 /// # Returns
75 /// * `Result<Response<RangeResponse>, Error>` - The response containing the range results or an error if the operation fails.
76 /// # Errors
77 /// * Returns an `Error` if the range operation fails.
78 async fn range_with_end(&mut self, key: ByteSequence, range_end: ByteSequence) -> Result<Response<RangeResponse>, Error> {
79 self.range_with_options(
80 Some(key),
81 Some(range_end),
82 None,
83 None,
84 None,
85 None,
86 None,
87 None,
88 None,
89 None,
90 None,
91 None,
92 ).await
93 }
94
95 /// Performs a range query for all keys.
96 /// # Returns
97 /// * `Result<Response<RangeResponse>, Error>` - The response containing the range results or an error if the operation fails.
98 /// # Errors
99 /// * Returns an `Error` if the range operation fails.
100 async fn range_all(&mut self) -> Result<Response<RangeResponse>, Error> {
101 self.range_with_options(
102 Some(ByteSequence::empty()),
103 Some(ByteSequence::empty()),
104 None,
105 None,
106 None,
107 None,
108 None,
109 None,
110 None,
111 None,
112 None,
113 None,
114 ).await
115 }
116
117 /// Performs a range query with various options.
118 /// # Arguments
119 /// * `key` - The key to query (optional).
120 /// * `range_end` - The end of the range to query (optional).
121 /// * `revision` - The revision to query at (optional).
122 /// * `sort_order` - The order to sort the results (optional).
123 /// * `sort_target` - The target to sort the results by (optional).
124 /// * `serializable` - Whether to perform a serializable read (optional).
125 /// * `keys_only` - Whether to return only keys (optional).
126 /// * `count_only` - Whether to return only the count of keys (optional).
127 /// * `min_mod_revision` - Minimum modification revision to filter results (optional).
128 /// * `max_mod_revision` - Maximum modification revision to filter results (optional).
129 /// * `min_create_revision` - Minimum creation revision to filter results (optional).
130 /// * `max_create_revision` - Maximum creation revision to filter results (optional).
131 /// # Returns
132 /// * `Result<Response<RangeResponse>, Error>` - The response containing the range results or an error if the operation fails.
133 /// # Errors
134 /// * Returns an `Error` if the range operation fails.
135 async fn range_with_options(
136 &mut self,
137 key: Option<ByteSequence>,
138 range_end: Option<ByteSequence>,
139 revision: Option<i64>,
140 sort_order: Option<i32>,
141 sort_target: Option<i32>,
142 serializable: Option<bool>,
143 keys_only: Option<bool>,
144 count_only: Option<bool>,
145 min_mod_revision: Option<i64>,
146 max_mod_revision: Option<i64>,
147 min_create_revision: Option<i64>,
148 max_create_revision: Option<i64>,
149 ) -> Result<Response<RangeResponse>, Error> {
150 let request = self.build_range_request(
151 key,
152 range_end,
153 None,
154 revision,
155 sort_order,
156 sort_target,
157 serializable,
158 keys_only,
159 count_only,
160 min_mod_revision,
161 max_mod_revision,
162 min_create_revision,
163 max_create_revision,
164 );
165 self.range_with_request(request).await
166 }
167
168 /// Builds a RangeRequest with the specified parameters.
169 /// # Arguments
170 /// * `key` - The key to query (optional).
171 /// * `range_end` - The end of the range to query (optional).
172 /// * `limit` - The maximum number of results to return (optional).
173 /// * `revision` - The revision to query at (optional).
174 /// * `sort_order` - The order to sort the results (optional).
175 /// * `sort_target` - The target to sort the results by (optional).
176 /// * `serializable` - Whether to perform a serializable read (optional).
177 /// * `keys_only` - Whether to return only keys (optional).
178 /// * `count_only` - Whether to return only the count of keys (optional).
179 /// * `min_mod_revision` - Minimum modification revision to filter results (optional).
180 /// * `max_mod_revision` - Maximum modification revision to filter results (optional).
181 /// * `min_create_revision` - Minimum creation revision to filter results (optional).
182 /// * `max_create_revision` - Maximum creation revision to filter results (optional).
183 /// # Returns
184 /// * `RangeRequest` - The constructed RangeRequest.
185 fn build_range_request(
186 &self,
187 key: Option<ByteSequence>,
188 range_end: Option<ByteSequence>,
189 limit: Option<i64>,
190 revision: Option<i64>,
191 sort_order: Option<i32>,
192 sort_target: Option<i32>,
193 serializable: Option<bool>,
194 keys_only: Option<bool>,
195 count_only: Option<bool>,
196 min_mod_revision: Option<i64>,
197 max_mod_revision: Option<i64>,
198 min_create_revision: Option<i64>,
199 max_create_revision: Option<i64>,
200 ) -> RangeRequest {
201 let mut request = RangeRequest {
202 ..Default::default()
203 };
204
205 if let Some(k) = key {
206 request.key = k.as_bytes().to_vec();
207 }
208
209 if let Some(re) = range_end {
210 request.range_end = re.as_bytes().to_vec();
211 }
212
213 if let Some(l) = limit {
214 request.limit = l;
215 }
216
217 if let Some(r) = revision {
218 request.revision = r;
219 }
220
221 if let Some(so) = sort_order {
222 request.sort_order = so;
223 }
224
225 if let Some(st) = sort_target {
226 request.sort_target = st;
227 }
228
229 if let Some(s) = serializable {
230 request.serializable = s;
231 }
232
233 if let Some(ko) = keys_only {
234 request.keys_only = ko;
235 }
236
237 if let Some(co) = count_only {
238 request.count_only = co;
239 }
240
241 if let Some(mmr) = min_mod_revision {
242 request.min_mod_revision = mmr;
243 }
244
245 if let Some(xmr) = max_mod_revision {
246 request.max_mod_revision = xmr;
247 }
248
249 if let Some(mcr) = min_create_revision {
250 request.min_create_revision = mcr;
251 }
252
253 if let Some(xcr) = max_create_revision {
254 request.max_create_revision = xcr;
255 }
256
257 request
258 }
259
260 /// Performs a range query using a pre-constructed RangeRequest.
261 /// # Arguments
262 /// * `request` - The RangeRequest to use for the query.
263 /// # Returns
264 /// * `Result<Response<RangeResponse>, Error>` - The response containing the range results or an error if the operation fails.
265 /// # Errors
266 /// * Returns an `Error` if the range operation fails.
267 async fn range_with_request(
268 &mut self,
269 request: RangeRequest,
270 ) -> Result<Response<RangeResponse>, Error>;
271
272 /// Retrieves the KV options associated with this client.
273 /// # Returns
274 /// * `&KVOptions` - A reference to the KVOptions.
275 fn get_options(&self) -> &crate::options::kv::KVOptions;
276}