examples: Add more examples for services and operations

examples/fs.rs

@@ -0,0 +1,43 @@
+// Copyright 2022 Datafuse Labs.
+//
+// Licensed 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 std::sync::Arc;
+
+/// Example for initiating a fs backend.
+use anyhow::Result;
+use opendal::services::fs;
+use opendal::services::fs::Builder;
+use opendal::Accessor;
+use opendal::Object;
+use opendal::Operator;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    // Create fs backend builder.
+    let mut builder: Builder = fs::Backend::build();
+    // Set the root for fs, all operations will happen under this root.
+    //
+    // NOTE: the root must be absolute path.
+    builder.root("/tmp");
+    // Build the `Accessor`.
+    let accessor: Arc<dyn Accessor> = builder.finish().await?;
+
+    // `Accessor` provides the low level APIs, we will use `Operator` normally.
+    let op: Operator = Operator::new(accessor);
+
+    // Create an object handle to start operation on object.
+    let _: Object = op.object("test_file");
+
+    Ok(())
+}

examples/list.rs

@@ -0,0 +1,54 @@
+// Copyright 2022 Datafuse Labs.
+//
+// Licensed 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 anyhow::Result;
+use futures::StreamExt;
+use opendal::ObjectMode;
+use opendal::ObjectStream;
+use opendal::Operator;
+use opendal_test::services::fs;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    // Using opendal internal test framework for example.
+    // Don't use this in production.
+    // Please init your backend via related example instead.
+    let acc = fs::new().await?;
+    if acc.is_none() {
+        return Ok(());
+    }
+    let op = Operator::new(acc.unwrap());
+
+    // Real example starts from here.
+
+    // Start listing a dir.
+    let mut obs: ObjectStream = op.objects("test_dir");
+    // ObjectStream implements `futures::Stream`
+    while let Some(o) = obs.next().await {
+        let mut o = o?;
+        // It's highly possible that OpenDAL already did metadata during list.
+        // Use `Object::metadata_cached()` to get cached metadata at first.
+        let meta = o.metadata_cached().await?;
+        match meta.mode() {
+            ObjectMode::FILE => {
+                println!("Handling file")
+            }
+            ObjectMode::DIR => {
+                println!("Handling dir like start a new list via meta.path()")
+            }
+            ObjectMode::Unknown => continue,
+        }
+    }
+
+    Ok(())
+}

examples/metadata.rs

@@ -0,0 +1,56 @@
+// Copyright 2022 Datafuse Labs.
+//
+// Licensed 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 anyhow::Result;
+use opendal::ObjectMode;
+use opendal::Operator;
+use opendal_test::services::fs;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    // Using opendal internal test framework for example.
+    // Don't use this in production.
+    // Please init your backend via related example instead.
+    let acc = fs::new().await?;
+    if acc.is_none() {
+        return Ok(());
+    }
+    let op = Operator::new(acc.unwrap());
+
+    // Real example starts from here.
+
+    // Get metadata of an object.
+    let meta = op.object("test_file").metadata().await?;
+    println!("path: {}", meta.path());
+    println!("mode: {:?}", meta.mode());
+    println!("content_length: {}", meta.content_length());
+
+    // Use mode to check whether this object is a file or dir.
+    let meta = op.object("test_file").metadata().await?;
+    match meta.mode() {
+        ObjectMode::FILE => {
+            println!("Handle a file")
+        }
+        ObjectMode::DIR => {
+            println!("Handle a dir")
+        }
+        ObjectMode::Unknown => {
+            println!("Handle unknown")
+        }
+    }
+    println!("path: {}", meta.path());
+    println!("mode: {}", meta.mode());
+    println!("content_length: {}", meta.content_length());
+
+    Ok(())
+}

examples/read.rs

@@ -0,0 +1,59 @@
+// Copyright 2022 Datafuse Labs.
+//
+// Licensed 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 std::io::SeekFrom;
+
+use anyhow::Result;
+use futures::io;
+use futures::AsyncReadExt;
+use futures::AsyncSeekExt;
+use opendal::Operator;
+use opendal_test::services::fs;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    // Using opendal internal test framework for example.
+    // Don't use this in production.
+    // Please init your backend via related example instead.
+    let acc = fs::new().await?;
+    if acc.is_none() {
+        return Ok(());
+    }
+    let op = Operator::new(acc.unwrap());
+
+    // Real example starts from here.
+
+    // Get a while file reader.
+    let mut r = op.object("test_file").reader();
+    io::copy(&mut r, &mut io::sink()).await?;
+
+    // Get file reader in range [1024, 2048).
+    let mut r = op.object("test_file").range_reader(1024, 1024);
+    io::copy(&mut r, &mut io::sink()).await?;
+
+    // Get a file reader from offset 1024.
+    let mut r = op.object("test_file").offset_reader(1024);
+    io::copy(&mut r, &mut io::sink()).await?;
+
+    // Get a file reader inside limit 1024.
+    let mut r = op.object("test_file").limited_reader(1024);
+    io::copy(&mut r, &mut io::sink()).await?;
+
+    // Our reader implement `futures::AsyncRead`.
+    let mut r = op.object("test_file").reader();
+    r.seek(SeekFrom::End(-1024)).await?;
+    r.read_exact(&mut vec![0; 1024]).await?;
+
+    Ok(())
+}

examples/s3.rs

@@ -0,0 +1,56 @@
+// Copyright 2022 Datafuse Labs.
+//
+// Licensed 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 std::sync::Arc;
+
+/// Example for initiating a s3 backend.
+use anyhow::Result;
+use opendal::credential::Credential;
+use opendal::services::s3;
+use opendal::services::s3::Builder;
+use opendal::Accessor;
+use opendal::Object;
+use opendal::Operator;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    // Create s3 backend builder.
+    let mut builder: Builder = s3::Backend::build();
+    // Set the root for s3, all operations will happen under this root.
+    //
+    // NOTE: the root must be absolute path.
+    builder.root("/path/to/dir");
+    // Set the bucket name, this is required.
+    builder.bucket("bucket_name");
+    // Set the endpoint.
+    //
+    // Default to "https://s3.amazonaws.com"
+    builder.endpoint("http://127.0.0.1:9090");
+    // Set the credential.
+    //
+    // 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.
+    builder.credential(Credential::hmac("access_key_id", "secret_access_key"));
+    // Build the `Accessor`.
+    let accessor: Arc<dyn Accessor> = builder.finish().await?;
+
+    // `Accessor` provides the low level APIs, we will use `Operator` normally.
+    let op: Operator = Operator::new(accessor);
+
+    // Create an object handle to start operation on object.
+    let _: Object = op.object("test_file");
+
+    Ok(())
+}

examples/write.rs

@@ -0,0 +1,42 @@
+// Copyright 2022 Datafuse Labs.
+//
+// Licensed 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 anyhow::Result;
+use futures::io;
+use opendal::Operator;
+use opendal_test::services::fs;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    // Using opendal internal test framework for example.
+    // Don't use this in production.
+    // Please init your backend via related example instead.
+    let acc = fs::new().await?;
+    if acc.is_none() {
+        return Ok(());
+    }
+    let op = Operator::new(acc.unwrap());
+
+    // Real example starts from here.
+
+    // Get a file writer.
+    let w = op.object("test_file").writer();
+    w.write_bytes(vec![0; 1024]).await?;
+
+    // Or write data from a readers.
+    let w = op.object("test_file").writer();
+    let r = io::Cursor::new(vec![0; 1024]);
+    w.write_reader(Box::new(r), 1024).await?;
+
+    Ok(())
+}