[pbs-devel] [PATCH proxmox v7 7/9] s3 client: add example usage for basic operations

[Christian Ebner]

Add an examples for how to create the client instance using its
configuration options and how to perform some basic api requests on
the S3 endpoint.

Guarded by the cfg attribute for conditional compilation to not fail
if feature "impl" is not set.

Further, excluded via `Cargo.toml` from being executed as test, as
this requires S3 object store to be available and configured.

Signed-off-by: Christian Ebner <c.ebner at proxmox.com>
---
changes since version 6:
- no changes

 proxmox-s3-client/Cargo.toml            |  4 ++
 proxmox-s3-client/examples/s3_client.rs | 65 +++++++++++++++++++++++++
 proxmox-s3-client/src/lib.rs            |  7 +++
 3 files changed, 76 insertions(+)
 create mode 100644 proxmox-s3-client/examples/s3_client.rs

diff --git a/proxmox-s3-client/Cargo.toml b/proxmox-s3-client/Cargo.toml
index 18bddddd..4388d5f6 100644
--- a/proxmox-s3-client/Cargo.toml
+++ b/proxmox-s3-client/Cargo.toml
@@ -42,3 +42,7 @@ proxmox-time.workspace = true
 [features]
 default = []
 impl = []
+
+[[example]]
+name = "s3_client"
+test = false
diff --git a/proxmox-s3-client/examples/s3_client.rs b/proxmox-s3-client/examples/s3_client.rs
new file mode 100644
index 00000000..25044e89
--- /dev/null
+++ b/proxmox-s3-client/examples/s3_client.rs
@@ -0,0 +1,65 @@
+// Execute via `cargo run --example s3_client --features impl` in `proxmox` main repo folder
+
+#[cfg(not(feature = "impl"))]
+fn main() {
+    // intentionally left empty
+}
+
+#[cfg(feature = "impl")]
+use proxmox_s3_client::{S3ObjectKey, S3Client, S3ClientOptions, S3PathPrefix};
+
+#[cfg(feature = "impl")]
+fn main() -> Result<(), anyhow::Error> {
+    tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+        .unwrap()
+        .block_on(run())
+}
+
+#[cfg(feature = "impl")]
+async fn run() -> Result<(), anyhow::Error> {
+    // Configure the client via the client options
+    let options = S3ClientOptions {
+        // Must be resolvable, e.g. the Ceph RADOS gateway.
+        // Allows to use {{bucket}} or {{region}} template pattern for ease of configuration.
+        // In this example, the final authority is `https://testbucket.s3.pve-c1.local:7480/`.
+        endpoint: "{{bucket}}.s3.pve-c1.local".to_string(),
+        // Must match the port the api is listening on
+        port: Some(7480),
+        // Name of the bucket to be used
+        bucket: "testbucket".to_string(),
+        common_prefix: "teststore".to_string(),
+        path_style: false,
+        access_key: "<your-access-key>".to_string(),
+        secret_key: "<your-secret-key>".to_string(),
+        region: "us-west-1".to_string(),
+        // Only required for self signed certificates, can be obtained by, e.g.
+        // `openssl s_client -connect testbucket.s3.pve-c1.local:7480 < /dev/null | openssl x509 -fingerprint -sha256 -noout`
+        fingerprint: Some("<s3-api-fingerprint>".to_string()),
+        put_rate_limit: None,
+    };
+
+    // Creating a client instance and connect to api endpoint
+    let s3_client = S3Client::new(options)?;
+
+    // Check if the bucket can be accessed
+    s3_client.head_bucket().await?;
+
+    let rel_object_key = S3ObjectKey::from("object.txt");
+    let body = proxmox_http::Body::empty();
+    let replace_existing_key = true;
+    let _response = s3_client.put_object(rel_object_key, body, replace_existing_key).await?;
+
+    // List object, limiting to ones matching the given prefix. Since the api limits the response
+    // to 1000 entries, the following contents might be fetched using a continuation token, being
+    // part of the previouis response.
+    let prefix = S3PathPrefix::Some("/teststore/".to_string());
+    let continuation_token = None;
+    let _response = s3_client.list_objects_v2(&prefix, continuation_token).await?;
+
+    // Delete a single object
+    let rel_object_key = S3ObjectKey::from("object.txt");
+    let _response = s3_client.delete_object(rel_object_key).await?;
+    Ok(())
+}
diff --git a/proxmox-s3-client/src/lib.rs b/proxmox-s3-client/src/lib.rs
index 991e1546..f485ac46 100644
--- a/proxmox-s3-client/src/lib.rs
+++ b/proxmox-s3-client/src/lib.rs
@@ -1,4 +1,11 @@
 //! Low level REST API client for AWS S3 compatible object stores
+//!
+//! # Example
+//! A basic example on how to use the client can be found in
+//! `proxmox-s3-client/examples/s3_client.rs` and run via
+//! `cargo run --example s3_client --features impl` from the main
+//! repository folder.
+
 #![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
 #![deny(unsafe_op_in_unsafe_fn)]
 #![deny(missing_docs)]
-- 
2.47.2