remi_azure/lib.rs
1// 🐻❄️🧶 remi-rs: Asynchronous Rust crate to handle communication between applications and object storage providers
2// Copyright (c) 2022-2025 Noelware, LLC. <team@noelware.org>
3//
4// Permission is hereby granted, free of charge, to any person obtaining a copy
5// of this software and associated documentation files (the "Software"), to deal
6// in the Software without restriction, including without limitation the rights
7// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8// copies of the Software, and to permit persons to whom the Software is
9// furnished to do so, subject to the following conditions:
10//
11// The above copyright notice and this permission notice shall be included in all
12// copies or substantial portions of the Software.
13//
14// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
20// SOFTWARE.
21
22//! # 🐻❄️🧶 `remi_azure`
23//! This crate is an official implementation of [`remi::StorageService`] for Microsoft's
24//! Azure Blob Storage service using the unofficial Azure crates: [`azure_core`], [`azure_storage`],
25//! and [`azure_storage_blobs`].
26//!
27//! [`remi::StorageService`]: https://docs.rs/remi/*/remi/trait.StorageService.html
28//! [`azure_storage_blobs`]: https://docs.rs/azure-storage-blobs
29//! [`azure_storage`]: https://docs.rs/azure-storage
30//! [`azure_core`]: https://docs.rs/azure-core
31//!
32//! ## Example
33//! ```rust,no_run
34//! // Cargo.toml:
35//! //
36//! // [dependencies]
37//! // remi = "^0"
38//! // remi-azure = "^0"
39//! // tokio = { version = "^1", features = ["full"] }
40//!
41//! use remi_azure::{StorageService, StorageConfig, Credential, CloudLocation};
42//! use remi::{StorageService as _, UploadRequest};
43//!
44//! #[tokio::main]
45//! async fn main() {
46//! let storage = StorageService::new(StorageConfig {
47//! credentials: Credential::Anonymous,
48//! container: "my-container".into(),
49//! location: CloudLocation::Public("my-account".into()),
50//! }).unwrap();
51//!
52//! // Initialize the container. This will:
53//! //
54//! // * create `my-container` if it doesn't exist
55//! storage.init().await.unwrap();
56//!
57//! // Now we can upload files to Azure.
58//!
59//! // We define a `UploadRequest`, which will set the content type to `text/plain` and set the
60//! // contents of `weow.txt` to `weow fluff`.
61//! let upload = UploadRequest::default()
62//! .with_content_type(Some("text/plain"))
63//! .with_data("weow fluff");
64//!
65//! // Let's upload it!
66//! storage.upload("weow.txt", upload).await.unwrap();
67//!
68//! // Let's check if it exists! This `assert!` will panic if it failed
69//! // to upload.
70//! assert!(storage.exists("weow.txt").await.unwrap());
71//! }
72//! ```
73//!
74//! ## Crate Features
75//! | Crate Features | Description | Enabled by default? |
76//! | :------------- | :----------------------------------------------------------------------------------- | ------------------- |
77//! | `export-azure` | Exports all the used Azure crates as a module called `core` | No. |
78//! | `unstable` | Tap into unstable features from `remi_azure` and the `remi` crate. | No. |
79//! | [`tracing`] | Enables the use of [`tracing::instrument`] and emit events for actions by the crate. | No. |
80//! | [`serde`] | Enables the use of **serde** in `StorageConfig` | No. |
81//! | [`log`] | Emits log records for actions by the crate | No. |
82//!
83//! [`tracing::instrument`]: https://docs.rs/tracing/*/tracing/attr.instrument.html
84//! [`tracing`]: https://crates.io/crates/tracing
85//! [`serde`]: https://serde.rs
86//! [`log`]: https://crates.io/crates/log
87
88#![doc(html_logo_url = "https://cdn.floofy.dev/images/trans.png")]
89#![doc(html_favicon_url = "https://cdn.floofy.dev/images/trans.png")]
90#![cfg_attr(any(noeldoc, docsrs), feature(doc_cfg))]
91
92#[cfg(feature = "export-azure")]
93#[cfg_attr(any(noeldoc, docsrs), doc(cfg(feature = "export-azure")))]
94/// Exports the [`azure_core`], [`azure_storage`], and [`azure_storage_blobs`]
95/// crates without defining them as owned dependencies.
96///
97/// [`azure_storage_blobs`]: https://docs.rs/azure-storage-blobs
98/// [`azure_storage`]: https://docs.rs/azure-storage
99/// [`azure_core`]: https://docs.rs/azure-core
100pub mod core {
101 pub use azure_core::*;
102
103 /// Exports the [`azure_storage`] and [`azure_storage_blobs`]
104 /// crates without defining them as owned dependencies.
105 ///
106 /// [`azure_storage_blobs`]: https://docs.rs/azure-storage-blobs
107 /// [`azure_storage`]: https://docs.rs/azure-storage
108 #[cfg_attr(any(noeldoc, docsrs), doc(cfg(feature = "export-azure")))]
109 pub mod storage {
110 pub use azure_storage::*;
111
112 /// Exports the [`azure_storage_blobs`] crate without defining them as owned dependencies.
113 ///
114 /// [`azure_storage_blobs`]: https://docs.rs/azure-storage-blobs
115 pub use azure_storage_blobs as blobs;
116 }
117}
118
119mod config;
120pub use config::*;
121
122mod service;
123pub use service::*;