docs: Add docs for ghac service (#1126)

Signed-off-by: Xuanwo <[email protected]>

Signed-off-by: Xuanwo <[email protected]>

README.md

@@ -23,6 +23,7 @@ You may be looking for:
 - [fs](https://opendal.databend.rs/opendal/services/fs/index.html): POSIX alike file system.
 - [ftp](https://opendal.databend.rs/opendal/services/ftp/index.html): FTP and FTPS support.
 - [gcs](https://opendal.databend.rs/opendal/services/gcs/index.html): [Google Cloud Storage](https://cloud.google.com/storage) Service.
+- [ghac](https://opendal.databend.rs/opendal/services/ghac/index.html): [Github Action Cache](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows) Service.
 - [hdfs](https://opendal.databend.rs/opendal/services/hdfs/index.html): [Hadoop Distributed File System](https://hadoop.apache.org/docs/r3.3.4/hadoop-project-dist/hadoop-hdfs/HdfsDesign.html)(HDFS).
 - [http](https://opendal.databend.rs/opendal/services/http/index.html): HTTP read-only services.
 - [ipfs](https://opendal.databend.rs/opendal/services/ipfs/index.html): [InterPlanetary File System](https://ipfs.tech/) HTTP Gateway support.

src/lib.rs

@@ -27,6 +27,7 @@
 //! | [fs][services::fs] | POSIX alike file system. |
 //! | [ftp][services::ftp] | FTP and FTPS support. |
 //! | [gcs][services::gcs] | Google Cloud Storage service. |
+//! | [ghac][services::ghac] | Github Action Cache service. |
 //! | [hdfs][services::hdfs] | Hadoop Distributed File System(HDFS). |
 //! | [http][services::http] | HTTP read-only backend. |
 //! | [ipfs][services::ipfs] | IPFS HTTP Gateway support. |

src/raw/accessor.rs

@@ -50,7 +50,7 @@ use crate::*;
 /// | [`blocking_write`][Accessor::blocking_write] | `Blocking` |
 /// | [`blocking_delete`][Accessor::blocking_delete] | `Blocking` |
 /// | [`blocking_list`][Accessor::blocking_list] | `Blocking` |
-/// | [`blocking_open`][Accessor::blocking_open | `Blocking` && `Open` |
+/// | [`blocking_open`][Accessor::blocking_open] | `Blocking` && `Open` |
 ///
 /// - Path in args will all be normalized into the same style, services
 ///   should handle them based on services' requirement.

src/raw/io.rs

@@ -50,21 +50,21 @@ pub type BlockingBytesReader = Box<dyn BlockingBytesRead>;
 pub trait BlockingOutputBytesRead: BlockingBytesRead + Sync {}
 impl<T> BlockingOutputBytesRead for T where T: BlockingBytesRead + Sync {}
 
-/// BlockingOutputBytesReader is a boxed dyn [`u`].
+/// BlockingOutputBytesReader is a boxed dyn `BlockingOutputBytesRead`.
 pub type BlockingOutputBytesReader = Box<dyn BlockingOutputBytesRead>;
 
 /// BytesHandle represents a handle of bytes which can be read and seek.
 pub trait BytesHandle: AsyncRead + AsyncSeek + Unpin + Send {}
 impl<T> BytesHandle for T where T: AsyncRead + AsyncSeek + Unpin + Send {}
 
-/// BytesHandler is a boxed dyn [`BytesHandle`].
+/// BytesHandler is a boxed dyn `BytesHandle`.
 pub type BytesHandler = Box<dyn BytesHandle>;
 
 /// BytesHandle represents a handle of bytes which can be read an seek.
 pub trait BlockingBytesHandle: Read + Seek + Send {}
 impl<T> BlockingBytesHandle for T where T: Read + Seek + Send {}
 
-/// BlockingBytesHandler is a boxed dyn [`BlockingBytesHandle`].
+/// BlockingBytesHandler is a boxed dyn `BlockingBytesHandle`.
 pub type BlockingBytesHandler = Box<dyn BlockingBytesHandle>;
 
 /// BytesWrite represents a writer of bytes.

src/services/azblob/backend.rs

@@ -133,7 +133,7 @@ impl Builder {
     /// - If sas_token is set, we will take user's input first.
     /// - If not, we will try to load it from environment.
     ///
-    /// See https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview
+    /// See [Grant limited access to Azure Storage resources using shared access signatures (SAS)](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview)
     /// for more info.
     pub fn sas_token(&mut self, sas_token: &str) -> &mut Self {
         if !sas_token.is_empty() {

src/services/ghac/mod.rs

@@ -13,6 +13,111 @@
 // limitations under the License.
 
 //! Github Action Cache Services support.
+//!
+//! # Notes
+//!
+//! This service is mainly provided by github actions.
+//!
+//! Refer to [Caching dependencies to speed up workflows](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows) for more informatio.
+//!
+//! To make this service work as expected, please make sure the following
+//! environment has been setup correctly:
+//!
+//! - `ACTIONS_CACHE_URL`
+//! - `ACTIONS_RUNTIME_TOKEN`
+//!
+//! They can be exposed by following action:
+//!
+//! ```yaml
+//! - name: Configure Cache Env
+//!   uses: actions/github-script@v6
+//!   with:
+//!     script: |
+//!       core.exportVariable('ACTIONS_CACHE_URL', process.env.ACTIONS_CACHE_URL || '');
+//!       core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');
+//! ```
+//!
+//! To make `delete` work as expected, `GITHUB_TOKEN` should also be set via:
+//!
+//! ```yaml
+//! env:
+//!   GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+//! ```
+//!
+//! # Limitations
+//!
+//! Unlike other services, ghac doesn't support create empty files.
+//! We provide a `enable_create_simulation()` to support this operation but may result unexpected side effects.
+//!
+//! Also, `ghac` is a cache service which means the data store inside could
+//! be automatically evicted at any time.
+//!
+//! # Configuration
+//!
+//! - `root`: Set the work dir for backend.
+//!
+//! Refer to [`Builder`]'s public API docs for more information.
+//!
+//! # Environment
+//!
+//! - `OPENDAL_GHAC_ROOT`
+//!
+//! # Example
+//!
+//! ## Via Environment
+//!
+//! Set environment correctly:
+//!
+//! ```shell
+//! export OPENDAL_GHAC_ROOT=/path/to/dir/
+//! ```
+//!
+//! ```no_run
+//! use std::sync::Arc;
+//!
+//! use anyhow::Result;
+//! use opendal::Object;
+//! use opendal::Operator;
+//! use opendal::Scheme;
+//!
+//! #[tokio::main]
+//! async fn main() -> Result<()> {
+//!     let op: Operator = Operator::from_env(Scheme::Ghac)?;
+//!
+//!     // Create an object handle to start operation on object.
+//!     let _: Object = op.object("test_file");
+//!
+//!     Ok(())
+//! }
+//! ```
+//!
+//! ## Via Builder
+//!
+//! ```no_run
+//! use std::sync::Arc;
+//!
+//! use anyhow::Result;
+//! use opendal::services::ghac;
+//! use opendal::Object;
+//! use opendal::Operator;
+//!
+//! #[tokio::main]
+//! async fn main() -> Result<()> {
+//!     // Create ghac backend builder.
+//!     let mut builder = ghac::Builder::default();
+//!     // Set the root for ghac, all operations will happen under this root.
+//!     //
+//!     // NOTE: the root must be absolute path.
+//!     builder.root("/path/to/dir");
+//!
+//!     let op: Operator = Operator::new(builder.build()?);
+//!
+//!     // Create an object handle to start operation on object.
+//!     let _: Object = op.object("test_file");
+//!
+//!     Ok(())
+//! }
+//! ```
 
 mod backend;
 pub use backend::Builder;