Skip to content

Commit

Permalink
docs: Add README and rustdoc for fuse3_opendal (#4813)
Browse files Browse the repository at this point in the history 
* docs: Add README and rustdoc for fuse3_opendal

Signed-off-by: Xuanwo <github@xuanwo.io>

* Add links

Signed-off-by: Xuanwo <github@xuanwo.io>

---------

Signed-off-by: Xuanwo <github@xuanwo.io>
  • Loading branch information
@Xuanwo
Xuanwo authored Jun 26, 2024
1 parent 81c44cb commit 3baf71e
Show file tree
Hide file tree
Showing 5 changed files with 169 additions and 12 deletions.
26 changes: 19 additions & 7 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -82,13 +82,13 @@ OpenDAL offers a unified data access layer, empowering users to seamlessly and e

## For *ANY* integrations

| Name | Description | Release | Docs |
|------------------------|------------------------------------------------------|---------------------------------------------|-----------------------------------------------------------------------------------|
| [dav-server-opendalfs] | a [dav-server-rs] implementation using opendal. | [![dav-server image]][dav-server crate] | [![Docs Release]][dav-server release docs] [![Docs Dev]][dav-server dev docs] |
| [object_store_opendal] | an [object_store] implementation using opendal. | [![object_store image]][object_store crate] | [![Docs Release]][object_store release docs] [![Docs Dev]][object_store dev docs] |
| [fuse3_opendal] | Access data via integrations to [fuse3] | - | - |
| [virtiofs_opendal] | Access data via integrations to [vhost-user-backend] | - | - |
| [unftp-sbe-opendal] | an [unftp] storage backend implementation using opendal. | - | - |
| Name | Description | Release | Docs |
|------------------------|----------------------------------------------------------|---------------------------------------------|-----------------------------------------------------------------------------------|
| [dav-server-opendalfs] | a [dav-server-rs] implementation using opendal. | [![dav-server image]][dav-server crate] | [![Docs Release]][dav-server release docs] [![Docs Dev]][dav-server dev docs] |
| [object_store_opendal] | an [object_store] implementation using opendal. | [![object_store image]][object_store crate] | [![Docs Release]][object_store release docs] [![Docs Dev]][object_store dev docs] |
| [fuse3_opendal] | Access data via integrations to [fuse3] | [![fuse3 image]][fuse3 crate] | [![Docs Release]][fuse3 release docs] [![Docs Dev]][fuse3 dev docs] |
| [virtiofs_opendal] | Access data via integrations to [vhost-user-backend] | [![virtiofs image]][virtiofs crate] | [![Docs Release]][virtiofs release docs] [![Docs Dev]][virtiofs dev docs] |
| [unftp-sbe-opendal] | an [unftp] storage backend implementation using opendal. | [![unftp-sbe image]][unftp-sbe crate] | [![Docs Release]][unftp-sbe release docs] [![Docs Dev]][unftp-sbe dev docs] |

[dav-server-opendalfs]: integrations/dav-server/README.md
[dav-server-rs]: https://github.com/messense/dav-server-rs
Expand All @@ -106,12 +106,24 @@ OpenDAL offers a unified data access layer, empowering users to seamlessly and e

[fuse3_opendal]: integrations/fuse3/README.md
[fuse3]: https://docs.rs/fuse3
[fuse3 image]: https://img.shields.io/crates/v/fuse3_opendal.svg
[fuse3 crate]: https://crates.io/crates/fuse3_opendal
[fuse3 release docs]: https://docs.rs/fuse3_opendal/
[fuse3 dev docs]: https://opendal.apache.org/docs/fuse3-opendal/fuse3_opendal/

[virtiofs_opendal]: integrations/virtiofs/README.md
[vhost-user-backend]: https://docs.rs/vhost-user-backend
[virtiofs image]: https://img.shields.io/crates/v/virtiofs_opendal.svg
[virtiofs crate]: https://crates.io/crates/virtiofs_opendal
[virtiofs release docs]: https://docs.rs/virtiofs_opendal/
[virtiofs dev docs]: https://opendal.apache.org/docs/virtiofs-opendal/virtiofs_opendal/

[unftp-sbe-opendal]: integrations/unftp-sbe/README.md
[unftp]: https://crates.io/crates/unftp
[unftp-sbe image]: https://img.shields.io/crates/v/unftp-sbe-opendal.svg
[unftp-sbe crate]: https://crates.io/crates/unftp-sbe-opendal
[unftp-sbe release docs]: https://docs.rs/unftp-sbe-opendal/
[unftp-sbe dev docs]: https://opendal.apache.org/docs/unftp-sbe-opendal/unftp_sbe_opendal/

## For *ANY* services

Expand Down
70 changes: 68 additions & 2 deletions integrations/fuse3/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,69 @@
# fuse3_opendal
# Apache OpenDAL™ fuse3 integration

`fuse3_opendal` is an integration which uses OpenDAL as a backend to access data in various services with FUSE protocol.
[![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/ci_integration_fuse3.yml?branch=main
[actions]: https://github.com/apache/opendal/actions?query=branch%3Amain
[latest version]: https://img.shields.io/crates/v/fuse3_opendal.svg
[crates.io]: https://crates.io/crates/fuse3_opendal
[crate downloads]: https://img.shields.io/crates/d/fuse3_opendal.svg
[chat]: https://img.shields.io/discord/1081052318650339399
[discord]: https://opendal.apache.org/discord

`fuse3_opendal` is an [`fuse3`](https://github.com/Sherlock-Holo/fuse3) implementation using opendal.

This crate can help you to access ANY storage services by mounting locally by [`FUSE`](https://www.kernel.org/doc/html/next/filesystems/fuse.html).

## Useful Links

- Documentation: [release](https://docs.rs/fuse3_opendal/) | [dev](https://opendal.apache.org/docs/fuse3-opendal/fuse3_opendal/)

## Examples

```rust
use fuse3::path::Session;
use fuse3::MountOptions;
use fuse3::Result;
use fuse3_opendal::Filesystem;
use opendal::services::Memory;
use opendal::Operator;

#[tokio::test]
async fn test() -> Result<()> {
// Build opendal Operator.
let op = Operator::new(Memory::default())?.finish();

// Build fuse3 file system.
let fs = Filesystem::new(op, 1000, 1000);

// Configure mount options.
let mount_options = MountOptions::default();

// Start a fuse3 session and mount it.
let mut mount_handle = Session::new(mount_options)
.mount_with_unprivileged(fs, "/tmp/mount_test")
.await?;
let handle = &mut mount_handle;

tokio::select! {
res = handle => res?,
_ = tokio::signal::ctrl_c() => {
mount_handle.unmount().await?
}
}

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.

For more details, see the [Apache Product Name Usage Guide](https://www.apache.org/foundation/marks/guide).

## License and Trademarks

Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0

Apache OpenDAL, OpenDAL, and Apache are either registered trademarks or trademarks of the Apache Software Foundation.
5 changes: 3 additions & 2 deletions integrations/fuse3/src/file.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,11 @@
// specific language governing permissions and limitations
// under the License.

use fuse3::Errno;
use opendal::Writer;
use std::ffi::OsString;
use std::sync::Arc;

use fuse3::Errno;
use opendal::Writer;
use tokio::sync::Mutex;

/// Opened file represents file that opened in memory.
Expand Down
40 changes: 39 additions & 1 deletion integrations/fuse3/src/file_system.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,45 @@ use super::file::OpenedFile;

const TTL: Duration = Duration::from_secs(1); // 1 second

/// Filesystem represents the filesystem that implements [`PathFilesystem`].
/// `Filesystem` represents the filesystem that implements [`PathFilesystem`] by opendal.
///
/// `Filesystem` must be used along with `fuse3`'s `Session` like the following:
///
/// ```
/// use fuse3::path::Session;
/// use fuse3::MountOptions;
/// use fuse3::Result;
/// use fuse3_opendal::Filesystem;
/// use opendal::services::Memory;
/// use opendal::Operator;
///
/// #[tokio::test]
/// async fn test() -> Result<()> {
/// // Build opendal Operator.
/// let op = Operator::new(Memory::default())?.finish();
///
/// // Build fuse3 file system.
/// let fs = Filesystem::new(op, 1000, 1000);
///
/// // Configure mount options.
/// let mount_options = MountOptions::default();
///
/// // Start a fuse3 session and mount it.
/// let mut mount_handle = Session::new(mount_options)
/// .mount_with_unprivileged(fs, "/tmp/mount_test")
/// .await?;
/// let handle = &mut mount_handle;
///
/// tokio::select! {
/// res = handle => res?,
/// _ = tokio::signal::ctrl_c() => {
/// mount_handle.unmount().await?
/// }
/// }
///
/// Ok(())
/// }
/// ```
pub struct Filesystem {
op: Operator,
gid: u32,
Expand Down
40 changes: 40 additions & 0 deletions integrations/fuse3/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,46 @@
// specific language governing permissions and limitations
// under the License.

//! `fuse3_opendal` is an [`fuse3`](https://github.com/Sherlock-Holo/fuse3) implementation using opendal.
//!
//! This crate can help you to access ANY storage services by mounting locally by [`FUSE`](https://www.kernel.org/doc/html/next/filesystems/fuse.html).
//!
//! ```
//! use fuse3::path::Session;
//! use fuse3::MountOptions;
//! use fuse3::Result;
//! use fuse3_opendal::Filesystem;
//! use opendal::services::Memory;
//! use opendal::Operator;
//!
//! #[tokio::test]
//! async fn test() -> Result<()> {
//! // Build opendal Operator.
//! let op = Operator::new(Memory::default())?.finish();
//!
//! // Build fuse3 file system.
//! let fs = Filesystem::new(op, 1000, 1000);
//!
//! // Configure mount options.
//! let mount_options = MountOptions::default();
//!
//! // Start a fuse3 session and mount it.
//! let mut mount_handle = Session::new(mount_options)
//! .mount_with_unprivileged(fs, "/tmp/mount_test")
//! .await?;
//! let handle = &mut mount_handle;
//!
//! tokio::select! {
//! res = handle => res?,
//! _ = tokio::signal::ctrl_c() => {
//! mount_handle.unmount().await?
//! }
//! }
//!
//! Ok(())
//! }
//! ```
mod file;
mod file_system;
pub use file_system::Filesystem;

0 comments on commit 3baf71e

Please sign in to comment.