diff --git a/crates/azure/Cargo.toml b/crates/azure/Cargo.toml index 8024a19..a128bb7 100644 --- a/crates/azure/Cargo.toml +++ b/crates/azure/Cargo.toml @@ -21,15 +21,20 @@ [package] name = "remi-azure" -description = "๐Ÿปโ€โ„๏ธ๐Ÿงถ Azure Blob Storage implementation of `remi-rs`" +description = "๐Ÿปโ€โ„๏ธ๐Ÿงถ Support of Microsoft's Azure Blob Storage with remi-rs primitives" version.workspace = true repository.workspace = true license.workspace = true edition.workspace = true rust-version.workspace = true +[lints.rust] +unexpected_cfgs = { level = "warn", check-cfg = ['cfg(noeldoc)'] } + [features] -default = ["serde"] +default = ["export-azure"] + +export-azure = [] tracing = ["dep:tracing"] serde = ["dep:serde"] log = ["dep:log"] diff --git a/crates/azure/README.md b/crates/azure/README.md index e04c91f..a1515d1 100644 --- a/crates/azure/README.md +++ b/crates/azure/README.md @@ -1,12 +1,65 @@ -# ๐Ÿปโ€โ„๏ธ๐Ÿงถ Microsoft Azure Blob Storage Support for `remi-rs` -**remi-azure** is an official implementation of using Remi with Microsoft Azure Blob Storage by Noelware. +
+

Official and maintained remi-rs crate for support of Microsoft's Azure Blob Storage

+
+ v0.9.0 | :scroll: Documentation +
-## Features -### serde (disabled) -Enables the use of [`serde`](https://docs.rs/serde) for (de)serializing for configuration files. +| Crate Features | Description | Enabled by default? | +| :------------- | :----------------------------------------------------------------------------------- | ------------------- | +| `export-azure` | Exports all the used Azure crates as a module called `core` | Yes. | +| [`tracing`] | Enables the use of [`tracing::instrument`] and emit events for actions by the crate. | No. | +| [`serde`] | Enables the use of **serde** in `StorageConfig` | No. | +| [`log`] | Emits log records for actions by the crate | No. | -### log (disabled) -Enables the use of [`log`](https://docs.rs/log) for adding unstructured logging events to track down why something broke. +## Example +```rust,no_run +// Cargo.toml: +// +// [dependencies] +// remi = "^0" +// remi-azure = "^0" +// tokio = { version = "^1", features = ["full"] } -### tracing (disabled) -Enables the use of [`tracing::instrument`](https://docs.rs/tracing/*/tracing/attr.instrument.html) for adding spans to method calls to track down why something went wrong or to debug performance hits. +use remi_azure::{StorageService, StorageConfig, Credential, core}; +use remi::{StorageService as _, UploadRequest}; + +#[tokio::main] +async fn main() { + let storage = StorageService::new(StorageConfig { + credential: Credential::Anonymous, + location: core::storage::CloudLocation::Public, + container: "my-container".into(), + }); + + // Initialize the container. This will: + // + // * create `my-container` if it doesn't exist + storage.init().await.unwrap(); + + // Now we can upload files to Azure. + + // We define a `UploadRequest`, which will set the content type to `text/plain` and set the + // contents of `weow.txt` to `weow fluff`. + let upload = UploadRequest::default() + .with_content_type(Some("text/plain")) + .with_data("weow fluff"); + + // Let's upload it! + storage.upload("weow.txt", upload).await.unwrap(); + + // Let's check if it exists! This `assert!` will panic if it failed + // to upload. + assert!(storage.exists("weow.txt").await.unwrap()); + + // Now we can query multiple "blobs" + // + // remi-rs defines blobs as either a directory or a file, since + // Azure only lets us look up files as files, all of them will + // be of `Blob::File`. +} +``` + +[`tracing::instrument`]: https://docs.rs/tracing/*/tracing/attr.instrument.html +[`tracing`]: https://crates.io/crates/tracing +[`serde`]: https://serde.rs +[`log`]: https://crates.io/crates/log diff --git a/crates/azure/src/lib.rs b/crates/azure/src/lib.rs index 0433ed2..7eb5f82 100644 --- a/crates/azure/src/lib.rs +++ b/crates/azure/src/lib.rs @@ -20,8 +20,28 @@ // SOFTWARE. #![doc(html_logo_url = "https://cdn.floofy.dev/images/trans.png")] +#![cfg_attr(any(noeldoc, docsrs), feature(doc_cfg))] #![doc = include_str!("../README.md")] +#[cfg(feature = "export-azure")] +#[cfg_attr(any(noeldoc, docsrs), doc(cfg(feature = "export-azure")))] +/// Exports the [`azure_core`], [`azure_storage`], and [`azure_storage_blobs`] +/// crates without defining them as owned dependencies. +pub mod core { + pub use azure_core::*; + + /// Exports the [`azure_storage`] and [`azure_storage_blobs`] + /// crates without defining them as owned dependencies. + pub mod storage { + pub use azure_storage::*; + + /// Exports the [`azure_storage_blobs`] crate without defining them as owned dependencies. + pub mod blobs { + pub use azure_storage_blobs::*; + } + } +} + mod config; pub use config::*;