This is an automated email from the ASF dual-hosted git repository.
xuanwo pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/opendal.git
The following commit(s) were added to refs/heads/main by this push:
new 7e984db4e1 docs(integrations/cloudfilter): improve docs and examples
(#5010)
7e984db4e1 is described below
commit 7e984db4e192903d008b3585cbf33d79925007d5
Author: Ho 229 <[email protected]>
AuthorDate: Thu Aug 15 15:08:03 2024 +0800
docs(integrations/cloudfilter): improve docs and examples (#5010)
* docs
* chore: improve readonly example
---
integrations/cloudfilter/Cargo.toml | 3 ++
integrations/cloudfilter/README.md | 75 +++++++++++++++++++++++++++
integrations/cloudfilter/examples/readonly.rs | 6 +--
integrations/cloudfilter/src/lib.rs | 70 +++++++++++++++++++++++++
4 files changed, 151 insertions(+), 3 deletions(-)
diff --git a/integrations/cloudfilter/Cargo.toml
b/integrations/cloudfilter/Cargo.toml
index 0329021d60..845331396d 100644
--- a/integrations/cloudfilter/Cargo.toml
+++ b/integrations/cloudfilter/Cargo.toml
@@ -26,6 +26,9 @@ repository = "https://github.com/apache/opendal";
rust-version = "1.75"
version = "0.0.0"
+[package.metadata.docs.rs]
+default-target = "x86_64-pc-windows-msvc"
+
[dependencies]
anyhow = "1.0.86"
bincode = "1.3.3"
diff --git a/integrations/cloudfilter/README.md
b/integrations/cloudfilter/README.md
index 1683c6e4ee..175349791a 100644
--- a/integrations/cloudfilter/README.md
+++ b/integrations/cloudfilter/README.md
@@ -1,7 +1,82 @@
# Apache OpenDAL™ Cloud Filter Integration
+[![Build Status]][actions] [![Latest Version]][crates.io] [![Crate
Downloads]][crates.io] [![chat]][discord]
+
+[build status]:
https://img.shields.io/github/actions/workflow/status/apache/opendal/test_behavior_integration_cloudfilter.yml?branch=main
+[actions]: https://github.com/apache/opendal/actions?query=branch%3Amain
+[latest version]: https://img.shields.io/crates/v/cloudfilter_opendal.svg
+[crates.io]: https://crates.io/crates/cloudfilter_opendal
+[crate downloads]: https://img.shields.io/crates/d/cloudfilter_opendal.svg
+[chat]: https://img.shields.io/discord/1081052318650339399
+[discord]: https://opendal.apache.org/discord
+
`cloudfilter_opendal` integrates OpenDAL with [cloud sync
engines](https://learn.microsoft.com/en-us/windows/win32/cfapi/build-a-cloud-file-sync-engine).
It provides a way to access various cloud storage on Windows.
+Note that `cloudfilter_opendal` is a read-only service, and it is not
recommended to use it in production.
+
+## Example
+
+```rust
+use anyhow::Result;
+use cloud_filter::root::PopulationType;
+use cloud_filter::root::SecurityId;
+use cloud_filter::root::Session;
+use cloud_filter::root::SyncRootIdBuilder;
+use cloud_filter::root::SyncRootInfo;
+use opendal::services;
+use opendal::Operator;
+use tokio::runtime::Handle;
+use tokio::signal;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+ // Create any service desired
+ let op = Operator::from_iter::<services::S3>([
+ ("bucket".to_string(), "my_bucket".to_string()),
+ ("access_key".to_string(), "my_access_key".to_string()),
+ ("secret_key".to_string(), "my_secret_key".to_string()),
+ ("endpoint".to_string(), "my_endpoint".to_string()),
+ ("region".to_string(), "my_region".to_string()),
+ ])?
+ .finish();
+
+ let client_path = std::env::var("CLIENT_PATH").expect("$CLIENT_PATH is
set");
+
+ // Create a sync root id
+ let sync_root_id = SyncRootIdBuilder::new("cloudfilter_opendal")
+ .user_security_id(SecurityId::current_user()?)
+ .build();
+
+ // Register the sync root if not exists
+ if !sync_root_id.is_registered()? {
+ sync_root_id.register(
+ SyncRootInfo::default()
+ .with_display_name("OpenDAL Cloud Filter")
+ .with_population_type(PopulationType::Full)
+ .with_icon("shell32.dll,3")
+ .with_version("1.0.0")
+
.with_recycle_bin_uri("http://cloudmirror.example.com/recyclebin";)?
+ .with_path(&client_path)?,
+ )?;
+ }
+
+ let handle = Handle::current();
+ let connection = Session::new().connect_async(
+ &client_path,
+ cloudfilter_opendal::CloudFilter::new(op, client_path.clone().into()),
+ move |f| handle.block_on(f),
+ )?;
+
+ signal::ctrl_c().await?;
+
+ // Drop the connection before unregister the sync root
+ drop(connection);
+ sync_root_id.unregister()?;
+
+ Ok(())
+}
+```
+
## Branding
The first and most prominent mentions must use the full form: **Apache
OpenDAL™** of the name for any individual usage (webpage, handout, slides,
etc.) Depending on the context and writing style, you should use the full form
of the name sufficiently often to ensure that readers clearly understand the
association of both the OpenDAL project and the OpenDAL software product to the
ASF as the parent organization.
diff --git a/integrations/cloudfilter/examples/readonly.rs
b/integrations/cloudfilter/examples/readonly.rs
index d2bd580f80..2859023ce2 100644
--- a/integrations/cloudfilter/examples/readonly.rs
+++ b/integrations/cloudfilter/examples/readonly.rs
@@ -1,4 +1,4 @@
-use std::{env, path::PathBuf};
+use std::env;
use cloud_filter::root::{
HydrationType, PopulationType, SecurityId, Session, SyncRootIdBuilder,
SyncRootInfo,
@@ -45,8 +45,8 @@ async fn main() {
let connection = Session::new()
.connect_async(
&client_path,
- cloudfilter_opendal::CloudFilter::new(op,
PathBuf::from(&client_path)),
- move |f| handle.clone().block_on(f),
+ cloudfilter_opendal::CloudFilter::new(op,
client_path.clone().into()),
+ move |f| handle.block_on(f),
)
.expect("create session");
diff --git a/integrations/cloudfilter/src/lib.rs
b/integrations/cloudfilter/src/lib.rs
index d2b3524f4c..05c34cf67a 100644
--- a/integrations/cloudfilter/src/lib.rs
+++ b/integrations/cloudfilter/src/lib.rs
@@ -15,6 +15,74 @@
// specific language governing permissions and limitations
// under the License.
+//! `cloudfilter_opendal` integrates OpenDAL with [cloud sync
engines](https://learn.microsoft.com/en-us/windows/win32/cfapi/build-a-cloud-file-sync-engine).
+//! It provides a way to access various cloud storage on Windows.
+//!
+//! Note that `cloudfilter_opendal` is a read-only service, and it is not
recommended to use it in production.
+//!
+//! # Example
+//!
+//! ```no_run
+//! use anyhow::Result;
+//! use cloud_filter::root::PopulationType;
+//! use cloud_filter::root::SecurityId;
+//! use cloud_filter::root::Session;
+//! use cloud_filter::root::SyncRootIdBuilder;
+//! use cloud_filter::root::SyncRootInfo;
+//! use opendal::services;
+//! use opendal::Operator;
+//! use tokio::runtime::Handle;
+//! use tokio::signal;
+//!
+//! #[tokio::main]
+//! async fn main() -> Result<()> {
+//! // Create any service desired
+//! let op = Operator::from_iter::<services::S3>([
+//! ("bucket".to_string(), "my_bucket".to_string()),
+//! ("access_key".to_string(), "my_access_key".to_string()),
+//! ("secret_key".to_string(), "my_secret_key".to_string()),
+//! ("endpoint".to_string(), "my_endpoint".to_string()),
+//! ("region".to_string(), "my_region".to_string()),
+//! ])?
+//! .finish();
+//!
+//! let client_path = std::env::var("CLIENT_PATH").expect("$CLIENT_PATH is
set");
+//!
+//! // Create a sync root id
+//! let sync_root_id = SyncRootIdBuilder::new("cloudfilter_opendal")
+//! .user_security_id(SecurityId::current_user()?)
+//! .build();
+//!
+//! // Register the sync root if not exists
+//! if !sync_root_id.is_registered()? {
+//! sync_root_id.register(
+//! SyncRootInfo::default()
+//! .with_display_name("OpenDAL Cloud Filter")
+//! .with_population_type(PopulationType::Full)
+//! .with_icon("shell32.dll,3")
+//! .with_version("1.0.0")
+//!
.with_recycle_bin_uri("http://cloudmirror.example.com/recyclebin";)?
+//! .with_path(&client_path)?,
+//! )?;
+//! }
+//!
+//! let handle = Handle::current();
+//! let connection = Session::new().connect_async(
+//! &client_path,
+//! cloudfilter_opendal::CloudFilter::new(op,
client_path.clone().into()),
+//! move |f| handle.block_on(f),
+//! )?;
+//!
+//! signal::ctrl_c().await?;
+//!
+//! // Drop the connection before unregister the sync root
+//! drop(connection);
+//! sync_root_id.unregister()?;
+//!
+//! Ok(())
+//! }
+//! ``````
+
mod file;
use std::{
@@ -37,12 +105,14 @@ use opendal::{Entry, Metakey, Operator};
const BUF_SIZE: usize = 65536;
+/// CloudFilter is a adapter that adapts Windows cloud sync engines.
pub struct CloudFilter {
op: Operator,
root: PathBuf,
}
impl CloudFilter {
+ /// Create a new CloudFilter.
pub fn new(op: Operator, root: PathBuf) -> Self {
Self { op, root }
}
