opendal/raw/adapters/kv/
api.rs

1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements.  See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership.  The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License.  You may obtain a copy of the License at
8//
9//   http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied.  See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18use std::fmt::Debug;
19use std::future::ready;
20use std::ops::DerefMut;
21
22use futures::Future;
23
24use crate::raw::*;
25use crate::Capability;
26use crate::Scheme;
27use crate::*;
28
29/// Scan is the async iterator returned by `Adapter::scan`.
30pub trait Scan: Send + Sync + Unpin {
31    /// Fetch the next key in the current key prefix
32    ///
33    /// `Ok(None)` means no further key will be returned
34    fn next(&mut self) -> impl Future<Output = Result<Option<String>>> + MaybeSend;
35}
36
37/// A noop implementation of Scan
38impl Scan for () {
39    async fn next(&mut self) -> Result<Option<String>> {
40        Ok(None)
41    }
42}
43
44/// A Scan implementation for all trivial non-async iterators
45pub struct ScanStdIter<I>(I);
46
47#[cfg(any(
48    feature = "services-cloudflare-kv",
49    feature = "services-etcd",
50    feature = "services-nebula-graph",
51    feature = "services-rocksdb",
52    feature = "services-sled"
53))]
54impl<I> ScanStdIter<I>
55where
56    I: Iterator<Item = Result<String>> + Unpin + Send + Sync,
57{
58    /// Create a new ScanStdIter from an Iterator
59    pub(crate) fn new(inner: I) -> Self {
60        Self(inner)
61    }
62}
63
64impl<I> Scan for ScanStdIter<I>
65where
66    I: Iterator<Item = Result<String>> + Unpin + Send + Sync,
67{
68    async fn next(&mut self) -> Result<Option<String>> {
69        self.0.next().transpose()
70    }
71}
72
73/// A type-erased wrapper of Scan
74pub type Scanner = Box<dyn ScanDyn>;
75
76pub trait ScanDyn: Unpin + Send + Sync {
77    fn next_dyn(&mut self) -> BoxedFuture<Result<Option<String>>>;
78}
79
80impl<T: Scan + ?Sized> ScanDyn for T {
81    fn next_dyn(&mut self) -> BoxedFuture<Result<Option<String>>> {
82        Box::pin(self.next())
83    }
84}
85
86impl<T: ScanDyn + ?Sized> Scan for Box<T> {
87    async fn next(&mut self) -> Result<Option<String>> {
88        self.deref_mut().next_dyn().await
89    }
90}
91
92/// KvAdapter is the adapter to underlying kv services.
93///
94/// By implement this trait, any kv service can work as an OpenDAL Service.
95pub trait Adapter: Send + Sync + Debug + Unpin + 'static {
96    /// TODO: use default associate type `= ()` after stabilized
97    type Scanner: Scan;
98
99    /// Return the info of this key value accessor.
100    fn info(&self) -> Info;
101
102    /// Get a key from service.
103    ///
104    /// - return `Ok(None)` if this key is not exist.
105    fn get(&self, path: &str) -> impl Future<Output = Result<Option<Buffer>>> + MaybeSend;
106
107    /// The blocking version of get.
108    fn blocking_get(&self, path: &str) -> Result<Option<Buffer>> {
109        let _ = path;
110
111        Err(Error::new(
112            ErrorKind::Unsupported,
113            "kv adapter doesn't support this operation",
114        )
115        .with_operation("kv::Adapter::blocking_get"))
116    }
117
118    /// Set a key into service.
119    fn set(&self, path: &str, value: Buffer) -> impl Future<Output = Result<()>> + MaybeSend;
120
121    /// The blocking version of set.
122    fn blocking_set(&self, path: &str, value: Buffer) -> Result<()> {
123        let _ = (path, value);
124
125        Err(Error::new(
126            ErrorKind::Unsupported,
127            "kv adapter doesn't support this operation",
128        )
129        .with_operation("kv::Adapter::blocking_set"))
130    }
131
132    /// Delete a key from service.
133    ///
134    /// - return `Ok(())` even if this key is not exist.
135    fn delete(&self, path: &str) -> impl Future<Output = Result<()>> + MaybeSend;
136
137    /// Delete a key from service in blocking way.
138    ///
139    /// - return `Ok(())` even if this key is not exist.
140    fn blocking_delete(&self, path: &str) -> Result<()> {
141        let _ = path;
142
143        Err(Error::new(
144            ErrorKind::Unsupported,
145            "kv adapter doesn't support this operation",
146        )
147        .with_operation("kv::Adapter::blocking_delete"))
148    }
149
150    /// Scan a key prefix to get all keys that start with this key.
151    fn scan(&self, path: &str) -> impl Future<Output = Result<Self::Scanner>> + MaybeSend {
152        let _ = path;
153
154        ready(Err(Error::new(
155            ErrorKind::Unsupported,
156            "kv adapter doesn't support this operation",
157        )
158        .with_operation("kv::Adapter::scan")))
159    }
160
161    /// Scan a key prefix to get all keys that start with this key
162    /// in blocking way.
163    fn blocking_scan(&self, path: &str) -> Result<Vec<String>> {
164        let _ = path;
165
166        Err(Error::new(
167            ErrorKind::Unsupported,
168            "kv adapter doesn't support this operation",
169        )
170        .with_operation("kv::Adapter::blocking_scan"))
171    }
172
173    /// Append a key into service
174    fn append(&self, path: &str, value: &[u8]) -> impl Future<Output = Result<()>> + MaybeSend {
175        let _ = path;
176        let _ = value;
177
178        ready(Err(Error::new(
179            ErrorKind::Unsupported,
180            "kv adapter doesn't support this operation",
181        )
182        .with_operation("kv::Adapter::append")))
183    }
184
185    /// Append a key into service
186    /// in blocking way.
187    fn blocking_append(&self, path: &str, value: &[u8]) -> Result<()> {
188        let _ = path;
189        let _ = value;
190
191        Err(Error::new(
192            ErrorKind::Unsupported,
193            "kv adapter doesn't support this operation",
194        )
195        .with_operation("kv::Adapter::blocking_append"))
196    }
197}
198
199/// Info for this key value accessor.
200pub struct Info {
201    scheme: Scheme,
202    name: String,
203    capabilities: Capability,
204}
205
206impl Info {
207    /// Create a new KeyValueAccessorInfo.
208    pub fn new(scheme: Scheme, name: &str, capabilities: Capability) -> Self {
209        Self {
210            scheme,
211            name: name.to_string(),
212            capabilities,
213        }
214    }
215
216    /// Get the scheme.
217    pub fn scheme(&self) -> Scheme {
218        self.scheme
219    }
220
221    /// Get the name.
222    pub fn name(&self) -> &str {
223        &self.name
224    }
225
226    /// Get the capabilities.
227    pub fn capabilities(&self) -> Capability {
228        self.capabilities
229    }
230}
opendal/raw/adapters/kv/api.rs

opendal/raw/adapters/kv/
api.rs
