Skip to main content

opendal_service_etcd/
backend.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::sync::Arc;
19
20use etcd_client::Certificate;
21use etcd_client::ConnectOptions;
22use etcd_client::Identity;
23use etcd_client::TlsOptions;
24
25use super::ETCD_SCHEME;
26use super::config::EtcdConfig;
27use super::core::EtcdCore;
28use super::core::constants::DEFAULT_ETCD_ENDPOINTS;
29use super::deleter::EtcdDeleter;
30use super::lister::EtcdLazyLister;
31use super::reader::*;
32use super::writer::EtcdWriter;
33use opendal_core::raw::*;
34use opendal_core::*;
35
36/// [Etcd](https://etcd.io/) services support.
37#[doc = include_str!("docs.md")]
38#[derive(Debug, Default)]
39pub struct EtcdBuilder {
40    pub(super) config: EtcdConfig,
41}
42
43impl EtcdBuilder {
44    /// set the network address of etcd service.
45    ///
46    /// default: "http://127.0.0.1:2379"
47    pub fn endpoints(mut self, endpoints: &str) -> Self {
48        if !endpoints.is_empty() {
49            self.config.endpoints = Some(endpoints.to_owned());
50        }
51        self
52    }
53
54    /// set the username for etcd
55    ///
56    /// default: no username
57    pub fn username(mut self, username: &str) -> Self {
58        if !username.is_empty() {
59            self.config.username = Some(username.to_owned());
60        }
61        self
62    }
63
64    /// set the password for etcd
65    ///
66    /// default: no password
67    pub fn password(mut self, password: &str) -> Self {
68        if !password.is_empty() {
69            self.config.password = Some(password.to_owned());
70        }
71        self
72    }
73
74    /// set the working directory, all operations will be performed under it.
75    ///
76    /// default: "/"
77    pub fn root(mut self, root: &str) -> Self {
78        self.config.root = if root.is_empty() {
79            None
80        } else {
81            Some(root.to_string())
82        };
83
84        self
85    }
86
87    /// Set the PEM certificate authority file used to verify the server.
88    ///
89    /// This enables TLS without requiring a client certificate or private key.
90    /// Use HTTPS endpoints when configuring TLS.
91    ///
92    /// No custom certificate authority is configured by default.
93    pub fn ca_path(mut self, ca_path: &str) -> Self {
94        if !ca_path.is_empty() {
95            self.config.ca_path = Some(ca_path.to_string())
96        }
97        self
98    }
99
100    /// Set the PEM client certificate file used for mutual TLS.
101    ///
102    /// Set this together with [`Self::key_path`]. Building an operator with
103    /// only one of these paths returns [`ErrorKind::ConfigInvalid`].
104    ///
105    /// No client certificate is configured by default.
106    pub fn cert_path(mut self, cert_path: &str) -> Self {
107        if !cert_path.is_empty() {
108            self.config.cert_path = Some(cert_path.to_string())
109        }
110        self
111    }
112
113    /// Set the PEM client private key file used for mutual TLS.
114    ///
115    /// Set this together with [`Self::cert_path`]. Building an operator with
116    /// only one of these paths returns [`ErrorKind::ConfigInvalid`].
117    ///
118    /// No client private key is configured by default.
119    pub fn key_path(mut self, key_path: &str) -> Self {
120        if !key_path.is_empty() {
121            self.config.key_path = Some(key_path.to_string())
122        }
123        self
124    }
125
126    /// Set the maximum size in bytes of a gRPC response that the etcd client decodes.
127    ///
128    /// default is None, which keeps the etcd client default of 4 MiB
129    pub fn max_decoding_message_size(mut self, size: usize) -> Self {
130        self.config.max_decoding_message_size = Some(size);
131        self
132    }
133}
134
135impl Builder for EtcdBuilder {
136    type Config = EtcdConfig;
137
138    fn build(self) -> Result<impl Service> {
139        let endpoints = self
140            .config
141            .endpoints
142            .clone()
143            .unwrap_or_else(|| DEFAULT_ETCD_ENDPOINTS.to_string());
144
145        let endpoints: Vec<String> = endpoints.split(',').map(|s| s.to_string()).collect();
146
147        let mut options = ConnectOptions::new();
148
149        if self.config.cert_path.is_some() != self.config.key_path.is_some() {
150            return Err(Error::new(
151                ErrorKind::ConfigInvalid,
152                "cert_path and key_path must be configured together",
153            )
154            .with_operation("Builder::build")
155            .with_context("service", ETCD_SCHEME));
156        }
157
158        if self.config.ca_path.is_some() || self.config.cert_path.is_some() {
159            let mut tls_options = TlsOptions::default();
160            if let Some(path) = &self.config.ca_path {
161                let ca = self.load_pem(path)?;
162                tls_options = tls_options.ca_certificate(Certificate::from_pem(ca));
163            }
164            if let (Some(cert_path), Some(key_path)) =
165                (&self.config.cert_path, &self.config.key_path)
166            {
167                let cert = self.load_pem(cert_path)?;
168                let key = self.load_pem(key_path)?;
169                tls_options = tls_options.identity(Identity::from_pem(cert, key));
170            }
171            options = options.with_tls(tls_options);
172        }
173
174        if let Some(username) = self.config.username.clone() {
175            options = options.with_user(
176                username,
177                self.config.password.clone().unwrap_or("".to_string()),
178            );
179        }
180
181        let root = normalize_root(
182            self.config
183                .root
184                .clone()
185                .unwrap_or_else(|| "/".to_string())
186                .as_str(),
187        );
188
189        let core = EtcdCore::new(endpoints, options, self.config.max_decoding_message_size);
190        Ok(EtcdBackend::new(core, &root))
191    }
192}
193
194impl EtcdBuilder {
195    fn load_pem(&self, path: &str) -> Result<String> {
196        std::fs::read_to_string(path)
197            .map_err(|err| Error::new(ErrorKind::Unexpected, "invalid file path").set_source(err))
198    }
199}
200
201#[cfg(test)]
202mod tests {
203    use super::*;
204
205    #[test]
206    fn incomplete_client_identity_is_rejected() {
207        for ca_path in [None, Some("ca.pem")] {
208            for (cert_path, key_path) in
209                [(Some("client.pem"), None), (None, Some("client-key.pem"))]
210            {
211                let config = EtcdConfig {
212                    ca_path: ca_path.map(str::to_owned),
213                    cert_path: cert_path.map(str::to_owned),
214                    key_path: key_path.map(str::to_owned),
215                    ..Default::default()
216                };
217                let err = Operator::from_config(config).expect_err(
218                    "incomplete client identity must fail before reading certificate files",
219                );
220                assert_eq!(err.kind(), ErrorKind::ConfigInvalid);
221            }
222        }
223    }
224}
225
226#[derive(Debug, Clone)]
227pub struct EtcdBackend {
228    pub(crate) core: Arc<EtcdCore>,
229    pub(crate) info: ServiceInfo,
230    pub(crate) capability: Capability,
231}
232
233impl EtcdBackend {
234    fn new(core: EtcdCore, root: &str) -> Self {
235        let info = ServiceInfo::new(ETCD_SCHEME, root, "etcd");
236        let capability = Capability {
237            read: true,
238
239            write: true,
240            write_can_empty: true,
241
242            delete: true,
243            stat: true,
244            list: true,
245
246            shared: true,
247
248            ..Default::default()
249        };
250
251        Self {
252            core: Arc::new(core),
253            info,
254            capability,
255        }
256    }
257}
258
259impl Service for EtcdBackend {
260    type Reader = oio::StreamReader<EtcdReader>;
261    type Writer = EtcdWriter;
262    type Lister = oio::HierarchyLister<EtcdLazyLister>;
263    type Deleter = oio::OneShotDeleter<EtcdDeleter>;
264    type Copier = ();
265    type Composer = ();
266
267    fn info(&self) -> ServiceInfo {
268        self.info.clone()
269    }
270
271    fn capability(&self) -> Capability {
272        self.capability
273    }
274
275    async fn create_dir(
276        &self,
277        _ctx: &OperationContext,
278        path: &str,
279        _args: OpCreateDir,
280    ) -> Result<RpCreateDir> {
281        let abs_path = build_abs_path(&self.info.root(), path);
282
283        // In etcd, we simulate directory creation by storing an empty value
284        // with the directory path (ensuring it ends with '/')
285        let dir_path = if abs_path.ends_with('/') {
286            abs_path
287        } else {
288            format!("{abs_path}/")
289        };
290
291        // Store an empty buffer to represent the directory
292        self.core.set(&dir_path, Buffer::new()).await?;
293
294        Ok(RpCreateDir::default())
295    }
296
297    async fn stat(&self, _ctx: &OperationContext, path: &str, _: OpStat) -> Result<RpStat> {
298        let abs_path = build_abs_path(&self.info.root(), path);
299
300        // First check if it's a direct key
301        match self.core.get(&abs_path).await? {
302            Some(buffer) => {
303                let metadata = if abs_path.ends_with('/') {
304                    MetadataBuilder::dir()
305                } else {
306                    MetadataBuilder::file(buffer.len() as u64)
307                };
308                Ok(RpStat::new(metadata.build()))
309            }
310            None => {
311                // Check if it's a directory by looking for keys with this prefix
312                let prefix = if abs_path.ends_with('/') {
313                    abs_path
314                } else {
315                    format!("{abs_path}/")
316                };
317
318                // Use etcd prefix query to check if any keys exist with this prefix
319                let has_children = self.core.has_prefix(&prefix).await?;
320                if has_children {
321                    // Has children, it's a directory
322                    let metadata = MetadataBuilder::dir().build();
323                    Ok(RpStat::new(metadata))
324                } else {
325                    Err(Error::new(ErrorKind::NotFound, "path not found"))
326                }
327            }
328        }
329    }
330    fn read(&self, _ctx: &OperationContext, path: &str, op: OpRead) -> Result<Self::Reader> {
331        let output: oio::StreamReader<EtcdReader> = {
332            Ok(oio::StreamReader::new(EtcdReader::new(
333                self.clone(),
334                path,
335                op,
336            )))
337        }?;
338
339        Ok(output)
340    }
341
342    fn write(&self, _ctx: &OperationContext, path: &str, _op: OpWrite) -> Result<Self::Writer> {
343        let output: EtcdWriter = {
344            let abs_path = build_abs_path(&self.info.root(), path);
345            let writer = EtcdWriter::new(self.core.clone(), abs_path);
346            Ok(writer)
347        }?;
348
349        Ok(output)
350    }
351
352    fn delete(&self, _ctx: &OperationContext) -> Result<Self::Deleter> {
353        let output: oio::OneShotDeleter<EtcdDeleter> = {
354            let deleter = oio::OneShotDeleter::new(EtcdDeleter::new(
355                self.core.clone(),
356                self.info.root().to_string(),
357            ));
358            Ok(deleter)
359        }?;
360
361        Ok(output)
362    }
363
364    fn list(&self, _ctx: &OperationContext, path: &str, args: OpList) -> Result<Self::Lister> {
365        let output: oio::HierarchyLister<EtcdLazyLister> = {
366            let lister = EtcdLazyLister::new(
367                self.core.clone(),
368                self.info.root().to_string(),
369                path.to_string(),
370            );
371            let lister = oio::HierarchyLister::new(lister, path, args.recursive());
372            Ok(lister)
373        }?;
374
375        Ok(output)
376    }
377
378    fn copy(
379        &self,
380        _ctx: &OperationContext,
381        _from: &str,
382        _to: &str,
383        _args: OpCopy,
384    ) -> Result<Self::Copier> {
385        Err(Error::new(
386            ErrorKind::Unsupported,
387            "operation is not supported",
388        ))
389    }
390
391    async fn rename(
392        &self,
393        _ctx: &OperationContext,
394        _from: &str,
395        _to: &str,
396        _args: OpRename,
397    ) -> Result<RpRename> {
398        Err(Error::new(
399            ErrorKind::Unsupported,
400            "operation is not supported",
401        ))
402    }
403
404    async fn presign(
405        &self,
406        _ctx: &OperationContext,
407        _path: &str,
408        _args: OpPresign,
409    ) -> Result<RpPresign> {
410        Err(Error::new(
411            ErrorKind::Unsupported,
412            "operation is not supported",
413        ))
414    }
415}