opendal 0.1.6.pre.rc.1-arm64-darwin-23

data/core/src/services/s3/docs.md

@@ -0,0 +1,244 @@
+## Capabilities
+
+This service can be used to:
+
+- [x] stat
+- [x] read
+- [x] write
+- [x] append
+- [x] create_dir
+- [x] delete
+- [x] copy
+- [ ] rename
+- [x] list
+- [x] presign
+- [ ] blocking
+
+## Configuration
+
+- `root`: Set the work dir for backend.
+- `bucket`: Set the container name for backend.
+- `endpoint`: Set the endpoint for backend.
+- `region`: Set the region for backend.
+- `access_key_id`: Set the access_key_id for backend.
+- `secret_access_key`: Set the secret_access_key for backend.
+- `session_token`: Set the session_token for backend.
+- `default_storage_class`: Set the default storage_class for backend.
+- `server_side_encryption`: Set the server_side_encryption for backend.
+- `server_side_encryption_aws_kms_key_id`: Set the server_side_encryption_aws_kms_key_id for backend.
+- `server_side_encryption_customer_algorithm`: Set the server_side_encryption_customer_algorithm for backend.
+- `server_side_encryption_customer_key`: Set the server_side_encryption_customer_key for backend.
+- `server_side_encryption_customer_key_md5`: Set the server_side_encryption_customer_key_md5 for backend.
+- `disable_config_load`: Disable aws config load from env.
+- `enable_virtual_host_style`: Enable virtual host style.
+- `disable_write_with_if_match`: Disable write with if match.
+- `enable_request_payer`: Enable the request payer for backend.
+
+Refer to [`S3Builder`]'s public API docs for more information.
+
+## Temporary security credentials
+
+OpenDAL now provides support for S3 temporary security credentials in IAM.
+
+The way to take advantage of this feature is to build your S3 backend with `Builder::session_token`.
+
+But OpenDAL will not refresh the temporary security credentials, please keep in mind to refresh those credentials in time.
+
+## Server Side Encryption
+
+OpenDAL provides full support of S3 Server Side Encryption(SSE) features.
+
+The easiest way to configure them is to use helper functions like
+
+- SSE-KMS: `server_side_encryption_with_aws_managed_kms_key`
+- SSE-KMS: `server_side_encryption_with_customer_managed_kms_key`
+- SSE-S3: `server_side_encryption_with_s3_key`
+- SSE-C: `server_side_encryption_with_customer_key`
+
+If those functions don't fulfill need, low-level options are also provided:
+
+- Use service managed kms key
+    - `server_side_encryption="aws:kms"`
+- Use customer provided kms key
+    - `server_side_encryption="aws:kms"`
+    - `server_side_encryption_aws_kms_key_id="your-kms-key"`
+- Use S3 managed key
+    - `server_side_encryption="AES256"`
+- Use customer key
+    - `server_side_encryption_customer_algorithm="AES256"`
+    - `server_side_encryption_customer_key="base64-of-your-aes256-key"`
+    - `server_side_encryption_customer_key_md5="base64-of-your-aes256-key-md5"`
+
+After SSE have been configured, all requests send by this backed will attach those headers.
+
+Reference: [Protecting data using server-side encryption](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)
+
+## Example
+
+## Via Builder
+
+### Basic Setup
+
+```rust,no_run
+use std::sync::Arc;
+
+use anyhow::Result;
+use opendal::services::S3;
+use opendal::Operator;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    // Create s3 backend builder.
+    let mut builder = S3::default()
+      // Set the root for s3, all operations will happen under this root.
+      //
+      // NOTE: the root must be absolute path.
+      .root("/path/to/dir")
+      // Set the bucket name. This is required.
+      .bucket("test")
+      // Set the region. This is required for some services, if you don't care about it, for example Minio service, just set it to "auto", it will be ignored.
+      .region("us-east-1")
+      // Set the endpoint.
+      //
+      // For examples:
+      // - "https://s3.amazonaws.com"
+      // - "http://127.0.0.1:9000"
+      // - "https://oss-ap-northeast-1.aliyuncs.com"
+      // - "https://cos.ap-seoul.myqcloud.com"
+      //
+      // Default to "https://s3.amazonaws.com"
+      .endpoint("https://s3.amazonaws.com")
+      // Set the access_key_id and secret_access_key.
+      //
+      // OpenDAL will try load credential from the env.
+      // If credential not set and no valid credential in env, OpenDAL will
+      // send request without signing like anonymous user.
+      .access_key_id("access_key_id")
+      .secret_access_key("secret_access_key");
+
+    let op: Operator = Operator::new(builder)?.finish();
+
+    Ok(())
+}
+
+```
+
+### S3 with SSE-C
+
+```rust,no_run
+use anyhow::Result;
+use log::info;
+use opendal::services::S3;
+use opendal::Operator;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let mut builder = S3::default()
+      .root("/path/to/dir")
+      .bucket("test")
+      .region("us-east-1")
+      .endpoint("https://s3.amazonaws.com")
+      .access_key_id("access_key_id")
+      .secret_access_key("secret_access_key")
+      // Enable SSE-C
+      .server_side_encryption_with_customer_key("AES256", "customer_key".as_bytes());
+
+    let op = Operator::new(builder)?.finish();
+    info!("operator: {:?}", op);
+
+    // Writing your testing code here.
+
+    Ok(())
+}
+```
+
+### S3 with SSE-KMS and aws managed kms key
+
+```rust,no_run
+use anyhow::Result;
+use log::info;
+use opendal::services::S3;
+use opendal::Operator;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let mut builder = S3::default()
+      // Setup builders
+      .root("/path/to/dir")
+      .bucket("test")
+      .region("us-east-1")
+      .endpoint("https://s3.amazonaws.com")
+      .access_key_id("access_key_id")
+      .secret_access_key("secret_access_key")
+      // Enable SSE-KMS with aws managed kms key
+      .server_side_encryption_with_aws_managed_kms_key();
+
+    let op = Operator::new(builder)?.finish();
+    info!("operator: {:?}", op);
+
+    // Writing your testing code here.
+
+    Ok(())
+}
+```
+
+### S3 with SSE-KMS and customer managed kms key
+
+```rust,no_run
+use anyhow::Result;
+use log::info;
+use opendal::services::S3;
+use opendal::Operator;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let mut builder = S3::default()
+      // Setup builders
+      .root("/path/to/dir")
+      .bucket("test")
+      .region("us-east-1")
+      .endpoint("https://s3.amazonaws.com")
+      .access_key_id("access_key_id")
+      .secret_access_key("secret_access_key")
+      // Enable SSE-KMS with customer managed kms key
+      .server_side_encryption_with_customer_managed_kms_key("aws_kms_key_id");
+
+    let op = Operator::new(builder)?.finish();
+    info!("operator: {:?}", op);
+
+    // Writing your testing code here.
+
+    Ok(())
+}
+```
+
+### S3 with SSE-S3
+
+```rust,no_run
+use anyhow::Result;
+use log::info;
+use opendal::services::S3;
+use opendal::Operator;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let mut builder = S3::default()
+      // Setup builders
+      .root("/path/to/dir")
+      .bucket("test")
+      .region("us-east-1")
+      .endpoint("https://s3.amazonaws.com")
+      .access_key_id("access_key_id")
+      .secret_access_key("secret_access_key")
+      // Enable SSE-S3
+      .server_side_encryption_with_s3_key();
+
+    let op = Operator::new(builder)?.finish();
+    info!("operator: {:?}", op);
+
+    // Writing your testing code here.
+
+    Ok(())
+}
+```
+

data/core/src/services/seafile/docs.md

@@ -0,0 +1,54 @@
+## Capabilities
+
+This service can be used to:
+
+- [x] stat
+- [x] read
+- [x] write
+- [x] create_dir
+- [x] delete
+- [ ] copy
+- [ ] rename
+- [x] list
+- [ ] presign
+- [ ] blocking
+
+## Configuration
+
+- `root`: Set the work directory for backend
+- `endpoint`: Seafile endpoint address
+- `username` Seafile username
+- `password` Seafile password
+- `repo_name` Seafile repo name
+
+You can refer to [`SeafileBuilder`]'s docs for more information
+
+## Example
+
+### Via Builder
+
+```rust,no_run
+use anyhow::Result;
+use opendal::services::Seafile;
+use opendal::Operator;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    // create backend builder
+    let mut builder = Seafile::default()
+        // set the storage bucket for OpenDAL
+        .root("/")
+        // set the endpoint for OpenDAL
+        .endpoint("http://127.0.0.1:80")
+        // set the username for OpenDAL
+        .username("xxxxxxxxxx")
+        // set the password name for OpenDAL
+        .password("opendal")
+        // set the repo_name for OpenDAL
+        .repo_name("xxxxxxxxxxxxx");
+
+    let op: Operator = Operator::new(builder)?.finish();
+
+    Ok(())
+}
+```

data/core/src/services/sftp/docs.md

@@ -0,0 +1,49 @@
+## Capabilities
+
+This service can be used to:
+
+- [x] stat
+- [x] read
+- [x] write
+- [x] append
+- [x] create_dir
+- [x] delete
+- [x] copy
+- [x] rename
+- [x] list
+- [ ] ~~presign~~
+- [ ] blocking
+
+## Configuration
+
+- `endpoint`: Set the endpoint for connection. The format is same as `openssh`, using either `[user@]hostname` or `ssh://[user@]hostname[:port]`. A username or port that is specified in the endpoint overrides the one set in the builder (but does not change the builder).
+- `root`: Set the work directory for backend. It uses the default directory set by the remote `sftp-server` as default
+- `user`: Set the login user
+- `key`: Set the public key for login
+- `known_hosts_strategy`: Set the strategy for known hosts, default to `Strict`
+- `enable_copy`: Set whether the remote server has copy-file extension
+
+For security reasons, it doesn't support password login, you can use public key or ssh-copy-id instead.
+
+You can refer to [`SftpBuilder`]'s docs for more information
+
+## Example
+
+### Via Builder
+
+```rust,no_run
+use anyhow::Result;
+use opendal::services::Sftp;
+use opendal::Operator;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let mut builder = Sftp::default()
+        .endpoint("127.0.0.1")
+        .user("test")
+        .key("test_key");
+
+    let op: Operator = Operator::new(builder)?.finish();
+    Ok(())
+}
+```

data/core/src/services/sled/docs.md

@@ -0,0 +1,39 @@
+## Capabilities
+
+This service can be used to:
+
+- [x] stat
+- [x] read
+- [x] write
+- [x] create_dir
+- [x] delete
+- [x] copy
+- [x] rename
+- [ ] ~~list~~
+- [ ] ~~presign~~
+- [x] blocking
+
+## Configuration
+
+- `datadir`: Set the path to the sled data directory
+
+You can refer to [`SledBuilder`]'s docs for more information
+
+## Example
+
+### Via Builder
+
+```rust,no_run
+use anyhow::Result;
+use opendal::services::Sled;
+use opendal::Operator;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let mut builder = Sled::default()
+        .datadir("/tmp/opendal/sled");
+
+    let op: Operator = Operator::new(builder)?.finish();
+    Ok(())
+}
+```

data/core/src/services/sqlite/docs.md

@@ -0,0 +1,46 @@
+## Capabilities
+
+This service can be used to:
+
+- [x] stat
+- [x] read
+- [x] write
+- [x] create_dir
+- [x] delete
+- [ ] copy
+- [ ] rename
+- [x] list
+- [ ] blocking
+
+## Configuration
+
+- `root`: Set the working directory of `OpenDAL`
+- `connection_string`: Set the connection string of sqlite database
+- `table`: Set the table of sqlite
+- `key_field`: Set the key field of sqlite
+- `value_field`: Set the value field of sqlite
+
+## Example
+
+### Via Builder
+
+```rust,no_run
+use anyhow::Result;
+use opendal::services::Sqlite;
+use opendal::Operator;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let mut builder = Sqlite::default()
+        .root("/")
+        .connection_string("file//abc.db")
+        .table("your_table")
+        // key field type in the table should be compatible with Rust's &str like text
+        .key_field("key")
+        // value field type in the table should be compatible with Rust's Vec<u8> like bytea
+        .value_field("value");
+
+    let op = Operator::new(builder)?.finish();
+    Ok(())
+}
+```

data/core/src/services/surrealdb/docs.md

@@ -0,0 +1,54 @@
+## Capabilities
+
+This service can be used to:
+
+- [x] stat
+- [x] read
+- [x] write
+- [ ] create_dir
+- [x] delete
+- [ ] copy
+- [ ] rename
+- [ ] ~~list~~
+- [ ] ~~presign~~
+- [ ] blocking
+
+## Configuration
+
+- `root`: Set the working directory of `OpenDAL`
+- `connection_string`: Set the connection string of surrealdb server
+- `username`: set the username of surrealdb
+- `password`: set the password of surrealdb
+- `namespace`: set the namespace of surrealdb
+- `database`: set the database of surrealdb
+- `table`: Set the table of surrealdb
+- `key_field`: Set the key field of surrealdb
+- `value_field`: Set the value field of surrealdb
+-
+
+## Example
+
+### Via Builder
+
+```rust
+use anyhow::Result;
+use opendal::services::Surrealdb;
+use opendal::Operator;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let mut builder = Surrealdb::default()
+        .root("/")
+        .connection_string("ws://127.0.0.1:8000")
+        .username("username")
+        .password("password")
+        .namespace("namespace")
+        .database("database")
+        .table("table")
+        .key_field("key")
+        .value_field("value");
+
+    let op = Operator::new(builder)?.finish();
+    Ok(())
+}
+```

data/core/src/services/swift/compatible_services.md

@@ -0,0 +1,53 @@
+## Compatible Services
+
+### OpenStack Swift
+
+[OpenStack Swift](https://docs.openstack.org/swift/latest/) is the default implementations of swift services.
+
+To connect to OpenStack Swift, we need to set:
+
+- `endpoint`: The endpoint of OpenStack Swift, for example: `http://127.0.0.1:8080/v1/AUTH_test`.
+- `container`: The name of OpenStack Swift container.
+- `token`: OpenStack Swift container personal access token.
+
+```rust,ignore
+builder.endpoint("http://127.0.0.1:8080/v1/AUTH_test");
+builder.container("container");
+builder.token("token");
+```
+
+`endpoint` is the full URL that serves as the access point to all containers under an OpenStack Swift account. It represents the entry point for accessing the resources of the account. Alongside `endpoint`, `token` is used as a credential to verify the user's identity and authorize access to the relevant resources. Both `endpoint` and `token` can be obtained through OpenStack Swift authentication service.
+
+`endpoint` consists of server address and port, API version, authenticated account ID. For instance, it might appear as follows:
+
+- `http://127.0.0.1:8080/v1/AUTH_test`.
+- `http://192.168.66.88:8080/swift/v1`.
+- `https://openstack-controller.example.com:8080/v1/account`.
+
+Please note that the exact format of `endpoint` may vary depending on the deployment configuration and version of swift services. Users can refer to the specific services documentation for the correct `endpoint` format and authentication method.
+
+For more information, refer:
+
+- [OpenStack Swift API](https://docs.openstack.org/api-ref/object-store/).
+- [OpenStack Swift Authentication](https://docs.openstack.org/swift/latest/api/object_api_v1_overview.html).
+
+### Ceph Rados Gateway
+
+[Ceph Rados Gateway](https://docs.ceph.com/en/quincy/radosgw/) supports a RESTful API that is compatible with the basic data access model of OpenStack Swift API.
+
+To connect to Ceph Rados Gateway, we need to set:
+
+- `endpoint`: The endpoint of swift services, for example: `http://127.0.0.1:8080/swift/v1`.
+- `container`: The name of swift container.
+- `token`: swift container personal access token.
+
+```rust,ignore
+builder.endpoint("http://127.0.0.1:8080/swift/v1");
+builder.container("container");
+builder.token("token");
+```
+
+For more information, refer:
+
+- [Ceph Rados Gateway Swift API](https://docs.ceph.com/en/latest/radosgw/swift/#api).
+- [Ceph Rados Gateway Swift Authentication](https://docs.ceph.com/en/latest/radosgw/swift/auth/).

data/core/src/services/swift/docs.md

@@ -0,0 +1,52 @@
+## Capabilities
+
+This service can be used to:
+
+- [x] stat
+- [x] read
+- [x] write
+- [x] create_dir
+- [x] delete
+- [x] copy
+- [ ] ~~rename~~
+- [x] list
+- [ ] ~~presign~~
+- [ ] blocking
+
+## Configurations
+
+- `endpoint`: Set the endpoint for backend.
+- `container`: Swift container.
+- `token`: Swift personal access token.
+
+Refer to [`SwiftBuilder`]'s public API docs for more information.
+
+## Examples
+
+### Via Builder
+
+```rust,no_run
+use std::sync::Arc;
+
+use anyhow::Result;
+use opendal::services::Swift;
+use opendal::Operator;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    // Create Swift backend builder
+    let mut builder = Swift::default() 
+        // Set the root for swift, all operations will happen under this root
+        .root("/path/to/dir")
+        // set the endpoint of Swift backend
+        .endpoint("https://openstack-controller.example.com:8080/v1/account")
+        // set the container name of Swift workspace
+        .container("container")
+        // set the auth token for builder
+        .token("token");
+
+    let op: Operator = Operator::new(builder)?.finish();
+
+    Ok(())
+}
+```

data/core/src/services/tikv/docs.md

@@ -0,0 +1,43 @@
+## Capabilities
+
+This service can be used to:
+
+- [x] stat
+- [x] read
+- [x] write
+- [x] create_dir
+- [x] delete
+- [x] copy
+- [x] rename
+- [ ] ~~list~~
+- [ ] ~~presign~~
+- [ ] ~~blocking~~
+
+## Configuration
+
+- `endpoints`: Set the endpoints to the tikv cluster
+- `insecure`: Set the insecure flag to the tikv cluster
+- `ca_path`: Set the ca path to the tikv connection
+- `cert_path`: Set the cert path to the tikv connection
+- `key_path`: Set the key path to the tikv connection
+
+You can refer to [`TikvBuilder`]'s docs for more information
+
+## Example
+
+### Via Builder
+
+```rust,no_run
+use anyhow::Result;
+use opendal::services::Tikv;
+use opendal::Operator;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let mut builder = Tikv::default()
+        .endpoints(vec!["127.0.0.1:2379".to_string()]);
+
+    let op: Operator = Operator::new(builder)?.finish();
+    Ok(())
+}
+```

data/core/src/services/upyun/docs.md

@@ -0,0 +1,51 @@
+## Capabilities
+
+This service can be used to:
+
+- [x] stat
+- [x] read
+- [x] write
+- [x] create_dir
+- [x] delete
+- [x] copy
+- [x] rename
+- [x] list
+- [ ] presign
+- [ ] blocking
+
+## Configuration
+
+- `root`: Set the work directory for backend
+- `bucket`: Upyun bucket name
+- `operator` Upyun operator
+- `password` Upyun password
+
+You can refer to [`UpyunBuilder`]'s docs for more information
+
+## Example
+
+### Via Builder
+
+```rust,no_run
+use anyhow::Result;
+use opendal::services::Upyun;
+use opendal::Operator;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    // create backend builder
+    let mut builder = Upyun::default()
+        // set the storage bucket for OpenDAL
+        .root("/")
+        // set the bucket for OpenDAL
+        .bucket("test")
+        // set the operator for OpenDAL
+        .operator("xxxxxxxxxx")
+        // set the password name for OpenDAL
+        .password("opendal");
+
+    let op: Operator = Operator::new(builder)?.finish();
+
+    Ok(())
+}
+```