rcfe_core/
kv.rs

1use crate::{
2    ByteSequence,
3    error::Error,
4    etcdserverpb::{DeleteRangeResponse, PutResponse, RangeResponse},
5    options::{delete::DeleteOptions, get::GetOptions, kv::KVOptions, put::PutOptions},
6};
7use tonic::Response;
8
9/// KVClient defines the interface for interacting with the key-value store.
10/// It provides methods to perform range queries with various options.
11#[tonic::async_trait]
12pub trait KVClient {
13    async fn delete(&mut self, key: ByteSequence) -> Result<Response<DeleteRangeResponse>, Error> {
14        self.delete_with_options(key, DeleteOptions::default())
15            .await
16    }
17
18    /// Deletes a key-value pair from the store with the specified options.
19    /// # Arguments
20    /// * `key` - The key to delete.
21    /// * `options` - The options to customize the delete operation.
22    /// # Returns
23    /// * `Result<Response<etcdserverpb::DeleteRangeResponse>, error::Error>` - The response containing the delete result or an error.
24    /// # Examples
25    /// ```rust
26    /// use rcfe_core::kv::KVClient;
27    /// use rcfe_core::ByteSequence;
28    /// use rcfe_core::error::Error;
29    /// use tonic::Response;
30    /// use rcfe_core::etcdserverpb::DeleteRangeResponse;
31    /// use rcfe_core::options::kv::DeleteOptions;
32    /// async fn example<KV: KVClient>(kv_client: &mut KV, key: ByteSequence, options: DeleteOptions) -> Result<Response<DeleteRangeResponse>, Error> {
33    ///     kv_client.delete_with_options(key, options).await
34    /// }
35    /// ```
36    async fn delete_with_options(
37        &mut self,
38        key: ByteSequence,
39        options: DeleteOptions,
40    ) -> Result<Response<DeleteRangeResponse>, Error>;
41
42    /// Puts a key-value pair into the store.
43    /// # Arguments
44    /// * `key` - The key to put.
45    /// * `value` - The value to associate with the key.
46    /// # Returns
47    /// * `Result<Response<etcdserverpb::PutResponse>, error::Error>` - The response containing the put result or an error.
48    /// # Examples
49    /// ```rust
50    /// use rcfe_core::kv::KVClient;
51    /// use rcfe_core::ByteSequence;
52    /// use rcfe_core::error::Error;
53    /// use tonic::Response;
54    /// use rcfe_core::etcdserverpb::PutResponse;
55    ///
56    /// async fn example<KV: KVClient>(kv_client: &mut KV, key: ByteSequence, value: ByteSequence) -> Result<Response<PutResponse>, Error> {
57    ///     kv_client.put(key, value).await
58    /// }
59    /// ```
60    async fn put(
61        &mut self,
62        key: ByteSequence,
63        value: ByteSequence,
64    ) -> Result<Response<PutResponse>, Error> {
65        self.put_with_options(key, value, PutOptions::default())
66            .await
67    }
68
69    /// Puts a key-value pair into the store with the specified options.
70    /// # Arguments
71    /// * `key` - The key to put.
72    /// * `value` - The value to associate with the key.
73    /// * `options` - The options to customize the put operation.
74    /// # Returns
75    /// * `Result<Response<etcdserverpb::PutResponse>, error::Error>` - The response containing the put result or an error.
76    /// # Examples
77    /// ```rust
78    /// use rcfe_core::kv::KVClient;
79    /// use rcfe_core::ByteSequence;
80    /// use rcfe_core::error::Error;
81    /// use tonic::Response;
82    /// use rcfe_core::etcdserverpb::PutResponse;
83    /// use rcfe_core::options::kv::PutOptions;
84    ///
85    /// async fn example<KV: KVClient>(kv_client: &mut KV, key: ByteSequence, value: ByteSequence, options: PutOptions) -> Result<Response<PutResponse>, Error> {
86    ///     kv_client.put_with_options(key, value, options).await
87    /// }
88    /// ```
89    async fn put_with_options(
90        &mut self,
91        key: ByteSequence,
92        value: ByteSequence,
93        options: PutOptions,
94    ) -> Result<Response<PutResponse>, Error>;
95
96    /// Performs a range query with the specified key.
97    /// # Arguments
98    /// * `key` - The key to query.
99    /// # Returns
100    /// * `Result<Response<etcdserverpb::RangeResponse>, error::Error>` - The response containing the range results or an error.
101    /// # Examples
102    /// ```rust
103    /// use rcfe_core::kv::KVClient;
104    /// use rcfe_core::ByteSequence;
105    /// use rcfe_core::error::Error;
106    /// use tonic::Response;
107    /// use rcfe_core::etcdserverpb::RangeResponse;
108    ///
109    /// async fn example<KV: KVClient>(kv_client: &mut KV, key: ByteSequence) -> Result<Response<RangeResponse>, Error> {
110    ///     kv_client.get(key).await
111    /// }
112    /// ```
113    async fn get(&mut self, key: ByteSequence) -> Result<Response<RangeResponse>, Error> {
114        self.get_with_options(key, GetOptions::default()).await
115    }
116
117    /// Performs a range query to retrieve all key-value pairs in the store.
118    /// # Returns
119    /// * `Result<Response<etcdserverpb::RangeResponse>, error::Error>` - The response containing all key-value pairs or an error.
120    /// # Examples
121    /// ```rust
122    /// use rcfe_core::kv::KVClient;
123    /// use rcfe_core::error::Error;
124    /// use tonic::Response;
125    /// use rcfe_core::etcdserverpb::RangeResponse;
126    ///
127    /// async fn example<KV: KVClient>(kv_client: &mut KV) -> Result<Response<RangeResponse>, Error> {
128    ///     kv_client.get_all().await
129    /// }
130    /// ```
131    async fn get_all(&mut self) -> Result<Response<RangeResponse>, Error> {
132        let options = GetOptions::builder()
133            .end_key(ByteSequence::from("\0"))
134            .build();
135        self.get_with_options(ByteSequence::from("\0"), options)
136            .await
137    }
138
139    /// Performs a range query with the specified key and options.
140    /// # Arguments
141    /// * `key` - The key to query.
142    /// * `options` - The options to customize the range query.
143    /// # Returns
144    /// * `Result<Response<etcdserverpb::RangeResponse>, error::Error>` - The response containing the range results or an error.
145    /// # Examples
146    /// ```rust
147    /// use rcfe_core::kv::KVClient;
148    /// use rcfe_core::ByteSequence;
149    /// use rcfe_core::error::Error;
150    /// use tonic::Response;
151    /// use rcfe_core::etcdserverpb::RangeResponse;
152    /// use rcfe_core::options::kv::GetOptions;
153    ///
154    /// async fn example<KV: KVClient>(kv_client: &mut KV, key: ByteSequence, options: GetOptions) -> Result<Response<RangeResponse>, Error> {
155    ///     kv_client.get_with_options(key, options).await
156    /// }
157    /// ```
158    async fn get_with_options(
159        &mut self,
160        key: ByteSequence,
161        options: GetOptions,
162    ) -> Result<Response<RangeResponse>, Error>;
163
164    /// Retrieves the KV options associated with this client.
165    /// # Returns
166    /// * `&KVOptions` - A reference to the KVOptions.
167    fn get_options(&self) -> &KVOptions;
168}
rcfe_core/kv.rs

rcfe_core/
kv.rs
