opendal/services/gridfs/
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::fmt::Debug;
19use std::fmt::Formatter;
20
21use mongodb::bson::doc;
22use tokio::sync::OnceCell;
23
24use super::config::GridfsConfig;
25use super::core::GridFsCore;
26use crate::raw::adapters::kv;
27use crate::raw::*;
28use crate::*;
29
30impl Configurator for GridfsConfig {
31    type Builder = GridfsBuilder;
32    fn into_builder(self) -> Self::Builder {
33        GridfsBuilder { config: self }
34    }
35}
36
37#[doc = include_str!("docs.md")]
38#[derive(Default)]
39pub struct GridfsBuilder {
40    config: GridfsConfig,
41}
42
43impl Debug for GridfsBuilder {
44    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
45        let mut d = f.debug_struct("GridFsBuilder");
46        d.field("config", &self.config);
47        d.finish_non_exhaustive()
48    }
49}
50
51impl GridfsBuilder {
52    /// Set the connection_string of the MongoDB service.
53    ///
54    /// This connection string is used to connect to the MongoDB service. It typically follows the format:
55    ///
56    /// ## Format
57    ///
58    /// `mongodb://[username:password@]host1[:port1][,...hostN[:portN]][/[defaultauthdb][?options]]`
59    ///
60    /// Examples:
61    ///
62    /// - Connecting to a local MongoDB instance: `mongodb://localhost:27017`
63    /// - Using authentication: `mongodb://myUser:myPassword@localhost:27017/myAuthDB`
64    /// - Specifying authentication mechanism: `mongodb://myUser:myPassword@localhost:27017/myAuthDB?authMechanism=SCRAM-SHA-256`
65    ///
66    /// ## Options
67    ///
68    /// - `authMechanism`: Specifies the authentication method to use. Examples include `SCRAM-SHA-1`, `SCRAM-SHA-256`, and `MONGODB-AWS`.
69    /// - ... (any other options you wish to highlight)
70    ///
71    /// For more information, please refer to [MongoDB Connection String URI Format](https://docs.mongodb.com/manual/reference/connection-string/).
72    pub fn connection_string(mut self, v: &str) -> Self {
73        if !v.is_empty() {
74            self.config.connection_string = Some(v.to_string());
75        }
76        self
77    }
78
79    /// Set the working directory, all operations will be performed under it.
80    ///
81    /// default: "/"
82    pub fn root(mut self, root: &str) -> Self {
83        self.config.root = if root.is_empty() {
84            None
85        } else {
86            Some(root.to_string())
87        };
88
89        self
90    }
91
92    /// Set the database name of the MongoDB GridFs service to read/write.
93    pub fn database(mut self, database: &str) -> Self {
94        if !database.is_empty() {
95            self.config.database = Some(database.to_string());
96        }
97        self
98    }
99
100    /// Set the bucket name of the MongoDB GridFs service to read/write.
101    ///
102    /// Default to `fs` if not specified.
103    pub fn bucket(mut self, bucket: &str) -> Self {
104        if !bucket.is_empty() {
105            self.config.bucket = Some(bucket.to_string());
106        }
107        self
108    }
109
110    /// Set the chunk size of the MongoDB GridFs service used to break the user file into chunks.
111    ///
112    /// Default to `255 KiB` if not specified.
113    pub fn chunk_size(mut self, chunk_size: u32) -> Self {
114        if chunk_size > 0 {
115            self.config.chunk_size = Some(chunk_size);
116        }
117        self
118    }
119}
120
121impl Builder for GridfsBuilder {
122    const SCHEME: Scheme = Scheme::Gridfs;
123    type Config = GridfsConfig;
124
125    fn build(self) -> Result<impl Access> {
126        let conn = match &self.config.connection_string.clone() {
127            Some(v) => v.clone(),
128            None => {
129                return Err(
130                    Error::new(ErrorKind::ConfigInvalid, "connection_string is required")
131                        .with_context("service", Scheme::Gridfs),
132                )
133            }
134        };
135        let database = match &self.config.database.clone() {
136            Some(v) => v.clone(),
137            None => {
138                return Err(Error::new(ErrorKind::ConfigInvalid, "database is required")
139                    .with_context("service", Scheme::Gridfs))
140            }
141        };
142        let bucket = match &self.config.bucket.clone() {
143            Some(v) => v.clone(),
144            None => "fs".to_string(),
145        };
146        let chunk_size = self.config.chunk_size.unwrap_or(255);
147
148        let root = normalize_root(
149            self.config
150                .root
151                .clone()
152                .unwrap_or_else(|| "/".to_string())
153                .as_str(),
154        );
155
156        Ok(GridFsBackend::new(GridFsCore {
157            connection_string: conn,
158            database,
159            bucket,
160            chunk_size,
161            bucket_instance: OnceCell::new(),
162        })
163        .with_normalized_root(root))
164    }
165}
166
167pub type GridFsBackend = kv::Backend<GridFsCore>;