docs: Refactor rust core examples (#4757)

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

core/Cargo.toml

@@ -36,7 +36,13 @@ rustdoc-args = ["--cfg", "docs"]
 
 [workspace]
 default-members = ["."]
-members = [".", "fuzz", "edge/*", "benches/vs_*"]
+members = [".", "examples/*", "fuzz", "edge/*", "benches/vs_*"]
+
+[workspace.package]
+edition = "2021"
+license = "Apache-2.0"
+rust-version = "1.75"
+version = "0.47.0"
 
 [features]
 default = ["reqwest/rustls-tls", "executors-tokio", "services-memory"]
@@ -95,6 +101,7 @@ layers-async-backtrace = ["dep:async-backtrace"]
 layers-blocking = ["internal-tokio-rt"]
 layers-dtrace = ["dep:probe"]
 
+services-aliyun-drive = []
 services-alluxio = []
 services-atomicserver = ["dep:atomic_lib"]
 services-azblob = [
@@ -193,7 +200,6 @@ services-vercel-blob = []
 services-webdav = []
 services-webhdfs = []
 services-yandex-disk = []
-services-aliyun-drive = []
 
 [lib]
 bench = false
@@ -233,7 +239,10 @@ chrono = { version = "0.4.28", default-features = false, features = [
     "std",
 ] }
 flagset = "0.4"
-futures = { version = "0.3", default-features = false, features = ["std", "async-await"] }
+futures = { version = "0.3", default-features = false, features = [
+    "std",
+    "async-await",
+] }
 http = "1.1"
 log = "0.4"
 md-5 = "0.10"
@@ -335,7 +344,11 @@ hdfs-native = { version = "0.9.4", optional = true }
 # for services-surrealdb
 surrealdb = { version = "1.3.0", optional = true, features = ["protocol-http"] }
 # for services-compfs
-compio = { version = "0.10.0", optional = true, features = ["runtime", "bytes", "polling"] }
+compio = { version = "0.10.0", optional = true, features = [
+    "runtime",
+    "bytes",
+    "polling",
+] }
 # for services-s3
 crc32c = { version = "0.6.6", optional = true }
 

core/README.md

@@ -17,6 +17,7 @@ OpenDAL offers a unified data access layer, empowering users to seamlessly and e
 ## Useful Links
 
 - Documentation: [release](https://docs.rs/opendal/) | [dev](https://opendal.apache.org/docs/rust/opendal/)
+- [Examples](./examples)
 - [Release Notes](https://docs.rs/opendal/latest/opendal/docs/changelog/index.html)
 - [Upgrade Guide](https://docs.rs/opendal/latest/opendal/docs/upgrade/index.html)
 - [RFC List](https://docs.rs/opendal/latest/opendal/docs/rfcs/index.html)
@@ -194,7 +195,15 @@ async fn main() -> Result<()> {
 
 ## Examples
 
-The examples are available at [here](../examples/rust).
+| Name                | Description                                                   |
+|---------------------|---------------------------------------------------------------|
+| [Basic]             | Show how to use opendal to operate storage service.           |
+| [Concurrent Upload] | Show how to perform upload concurrently to a storage service. |
+| [Multipart Upload]  | Show how to perform a multipart upload to a storage service.  |
+
+[Basic]: ./examples/basic
+[Concurrent Upload]: ./examples/concurrent-upload
+[Multipart Upload]: ./examples/multipart-upload
 
 ## Contributing
 

core/edge/file_write_on_full_disk/Cargo.toml

@@ -16,12 +16,13 @@
 # under the License.
 
 [package]
-edition = "2021"
-license = "Apache-2.0"
 name = "edge_test_file_write_on_full_disk"
+
+edition.workspace = true
+license.workspace = true
 publish = false
-rust-version = "1.75"
-version = "0.0.0"
+rust-version.workspace = true
+version.workspace = true
 
 [dependencies]
 futures = "0.3"

core/edge/s3_aws_assume_role_with_web_identity/Cargo.toml

@@ -16,12 +16,13 @@
 # under the License.
 
 [package]
-edition = "2021"
-license = "Apache-2.0"
 name = "edge_test_aws_s3_assume_role_with_web_identity"
+
+edition.workspace = true
+license.workspace = true
 publish = false
-rust-version = "1.75"
-version = "0.0.0"
+rust-version.workspace = true
+version.workspace = true
 
 [dependencies]
 opendal = { path = "../..", features = ["tests"] }

core/edge/s3_read_on_wasm/Cargo.toml

@@ -16,12 +16,13 @@
 # under the License.
 
 [package]
-edition = "2021"
-license = "Apache-2.0"
 name = "edge_test_s3_read_on_wasm"
+
+edition.workspace = true
+license.workspace = true
 publish = false
-rust-version = "1.75"
-version = "0.0.0"
+rust-version.workspace = true
+version.workspace = true
 
 [lib]
 crate-type = ["cdylib"]

core/examples/README.md

@@ -0,0 +1,23 @@
+# Apache OpenDAL™ Rust Core Examples
+
+Thank you for using OpenDAL!
+
+Those examples are designed to help you to understand how to use OpenDAL Rust Core.
+
+## Setup
+
+All examples following the same setup steps:
+
+To run this example, please copy the `.env.example`, which is at project root, to `.env` and change the values on need.
+
+Take `fs` for example, we need to change to enable behavior test on `fs` on `/tmp`.
+
+```dotenv
+OPENDAL_FS_ROOT=/path/to/dir
+```
+
+into
+
+```dotenv
+OPENDAL_FS_ROOT=/tmp
+```

core/examples/basic/Cargo.toml

@@ -0,0 +1,29 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+[package]
+name = "opendal-examples-basic"
+publish = false
+
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+futures = "0.3"
+opendal = { path = "../..", features = ["tests"] }
+tokio = { version = "1.38.0", features = ["macros", "rt-multi-thread"] }

core/examples/basic/README.md

@@ -0,0 +1,15 @@
+# Basic
+
+This example will show how to use opendal to operate storage service.
+
+## Setup
+
+Refer [Setup](../README.md) to setup all examples.
+
+## Run
+
+Use `OPENDAL_TEST` to control which service to run example:
+
+```shell
+OPENDAL_TEST=fs cargo run
+```

core/examples/basic/src/main.rs

@@ -0,0 +1,49 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+use opendal::{Operator, Result};
+
+async fn example(op: Operator) -> Result<()> {
+    // Write data to S3.
+    op.write("test.txt", "Hello, World!").await?;
+    println!("write succeeded");
+
+    // Read data from s3.
+    let bs = op.read("test.txt").await?;
+    println!("read: {}", String::from_utf8(bs.to_vec()).unwrap());
+
+    // Fetch metadata of s3.
+    let meta = op.stat("test.txt").await?;
+    println!("stat: {:?}", meta);
+
+    // Delete data from s3.
+    op.delete("test.txt").await?;
+    println!("delete succeeded");
+
+    Ok(())
+}
+
+// --- The following data is not part of this example ---
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    use opendal::raw::tests::init_test_service;
+    let op = init_test_service()?.expect("OPENDAL_TEST must be set");
+
+    println!("service {:?} has been initialized", op.info());
+    example(op).await
+}