Added sdk/storage/azure_storage_queue (#2730)

Cargo.toml

@@ -21,6 +21,7 @@ members = [
   "sdk/template/azure_template",
   "sdk/storage/azure_storage_common",
   "sdk/storage/azure_storage_blob",
+  "sdk/storage/azure_storage_queue",
 ]
 exclude = [
   "eng/scripts",

sdk/storage/.dict.txt

@@ -24,3 +24,5 @@ testblob1
 testblob2
 testblob3
 testblob4
+numofmessages
+peekonly

sdk/storage/azure_storage_blob/assets.json

@@ -3,4 +3,4 @@
   "AssetsRepoPrefixPath": "rust",
   "Tag": "rust/azure_storage_blob_873d66a4ea",
   "TagPrefix": "rust/azure_storage_blob"
-}
+}

sdk/storage/azure_storage_queue/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Release History
+
+## 0.1.0 (Unreleased)
+
+### Features Added
+
+* Initial supported release.

sdk/storage/azure_storage_queue/Cargo.toml

@@ -0,0 +1,46 @@
+[package]
+name = "azure_storage_queue"
+version = "0.1.0"
+description = "Microsoft Azure Queue client library for Rust"
+readme = "README.md"
+authors.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+homepage = "https://github.com/azure/azure-sdk-for-rust"
+documentation = "https://docs.rs/azure_storage_queue"
+keywords = ["sdk", "azure", "storage", "queue", "queues"]
+categories = ["api-bindings"]
+
+# Manual example definitions pointing to samples/ directory
+[[example]]
+name = "queue_client"
+path = "samples/queue_client.rs"
+
+[[example]]
+name = "queue_service_client"
+path = "samples/queue_service_client.rs"
+
+[features]
+default = ["reqwest"]
+reqwest = ["dep:reqwest"]
+
+[dependencies]
+azure_core = { workspace = true, features = ["xml"] }
+quick-xml.workspace = true
+rand.workspace = true
+reqwest = { workspace = true, optional = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+time = { workspace = true }
+typespec_client_core = { workspace = true, features = ["derive"] }
+
+[lints]
+workspace = true
+
+[dev-dependencies]
+azure_core_test.workspace = true
+azure_identity.workspace = true
+futures.workspace = true
+tokio = { workspace = true, features = ["macros"] }

sdk/storage/azure_storage_queue/README.md

@@ -0,0 +1,98 @@
+# Azure Queue client library for Rust
+
+Azure Queue Storage is a service for storing large numbers of messages.
+
+[Source code] | [Package (crates.io)] | [API reference documentation] | [REST API documentation] | [Product documentation]
+
+## Getting started
+
+**⚠️ Note: The `azure_storage_queue` crate is currently under active development and not all features may be implemented or work as intended. This crate is in beta and not suitable for Production environments. For any general feedback or usage issues, please open a GitHub issue [here](https://github.com/Azure/azure-sdk-for-rust/issues).**
+
+### Install the package
+
+Install the Azure Storage Queue client library for Rust with [cargo]:
+
+```sh
+cargo add azure_storage_queue
+```
+
+### Prerequisites
+
+* You must have an [Azure subscription] and an [Azure storage account] to use this package.
+
+### Create a storage account
+
+If you wish to create a new storage account, you can use the
+[Azure Portal], [Azure PowerShell], or [Azure CLI]:
+
+```sh
+# Create a new resource group to hold the storage account -
+# if using an existing resource group, skip this step
+az group create --name my-resource-group --location westus2
+
+# Create the storage account
+az storage account create -n my-storage-account-name -g my-resource-group
+```
+
+#### Authenticate the client
+
+In order to interact with the Azure Queue service, you'll need to create an instance of a client, `QueueClient`. The [Azure Identity] library makes it easy to add Microsoft Entra ID support for authenticating Azure SDK clients with their corresponding Azure services:
+
+```rust no_run
+use azure_storage_queue::{QueueClient, QueueClientOptions};
+use azure_identity::DeveloperToolsCredential;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Create a QueueClient that will authenticate through Microsoft Entra ID
+    let credential = DeveloperToolsCredential::new(None)?;
+    let queue_client = QueueClient::new(
+        "https://<storage_account_name>.blob.core.windows.net/", // endpoint
+        "queue-name",                                            // queue name
+        credential,                                              // credential
+        Some(QueueClientOptions::default()),                     // QueueClient options
+    )?;
+    Ok(())
+}
+```
+
+#### Permissions
+
+You may need to specify RBAC roles to access Queues via Microsoft Entra ID. Please see [Assign an Azure role for access to queue data] for more details.
+
+## Examples
+
+<!-- TODO: Uncomment the links below when the PR is merged -->
+You can find executable examples for all major SDK functions in:
+- [queue_client.rs]<!--(https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_queue/samples/queue_client.rs)-->
+- [queue_service_client.rs]<!--(https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_queue/samples/queue_service_client.rs)-->
+
+## Next steps
+
+### Provide feedback
+
+If you encounter bugs or have suggestions, [open an issue](https://github.com/Azure/azure-sdk-for-rust/issues).
+
+## Contributing
+
+This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [https://cla.microsoft.com](https://cla.microsoft.com).
+
+When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You'll only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information, see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
+
+<!-- TODO: Uncomment the links below when the PR is merged -->
+<!-- LINKS -->
+[Azure subscription]: https://azure.microsoft.com/free/
+[Azure storage account]: https://learn.microsoft.com/azure/storage/common/storage-account-overview
+[Azure Portal]: https://learn.microsoft.com/azure/storage/common/storage-quickstart-create-account?tabs=azure-portal
+[Azure PowerShell]: https://learn.microsoft.com/azure/storage/common/storage-quickstart-create-account?tabs=azure-powershell
+[Azure CLI]: https://learn.microsoft.com/azure/storage/common/storage-quickstart-create-account?tabs=azure-cli
+[cargo]: https://dev-doc.rust-lang.org/stable/cargo/commands/cargo.html
+[Azure Identity]: https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/identity/azure_identity
+<!--[API reference documentation]: https://docs.rs/crate/azure_storage_queue/latest-->
+<!--[Package (crates.io)]: https://crates.io/crates/azure_storage_queue-->
+[Source code]: https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_queue
+[REST API documentation]: https://learn.microsoft.com/rest/api/storageservices/blob-service-rest-api
+[Product documentation]: https://learn.microsoft.com/azure/storage/blobs/storage-blobs-overview
+[Assign an Azure role for access to queue data]: https://learn.microsoft.com/azure/storage/queues/assign-azure-role-data-access?tabs=portal

sdk/storage/azure_storage_queue/assets.json

@@ -0,0 +1,6 @@
+{
+  "AssetsRepo": "Azure/azure-sdk-assets",
+  "AssetsRepoPrefixPath": "rust",
+  "Tag": "rust/azure_storage_queue_3ebef0dc87",
+  "TagPrefix": "rust/azure_storage_queue"
+}

sdk/storage/azure_storage_queue/samples/README.md

@@ -0,0 +1,10 @@
+# Storage Queue Examples
+
+This directory contains a set of example for the use of the Storage Queue clients.
+
+## Setup
+
+The following environment variables need to be set:
+
+- AZURE_QUEUE_STORAGE_ACCOUNT_NAME=<storage_account_name>
+

sdk/storage/azure_storage_queue/samples/helpers/endpoint.rs

@@ -0,0 +1,32 @@
+pub fn get_endpoint() -> String {
+    // Retrieve the storage account endpoint from environment variable.
+    let storage_account_name = std::env::var("AZURE_QUEUE_STORAGE_ACCOUNT_NAME");
+    let storage_account_name = match storage_account_name {
+        Ok(url) => url,
+        Err(_) => {
+            eprintln!("Environment variable AZURE_QUEUE_STORAGE_ACCOUNT_NAME is not set");
+            std::process::exit(1);
+        }
+    };
+
+    format!("https://{}.queue.core.windows.net/", storage_account_name)
+}
+
+// This function is used only for the queue service client example, hence the `allow(dead_code)` attribute.
+#[allow(dead_code)]
+pub fn get_secondary_endpoint() -> String {
+    // Retrieve the storage account endpoint from environment variable.
+    let storage_account_name = std::env::var("AZURE_QUEUE_STORAGE_ACCOUNT_NAME");
+    let storage_account_name = match storage_account_name {
+        Ok(url) => url,
+        Err(_) => {
+            eprintln!("Environment variable AZURE_QUEUE_STORAGE_ACCOUNT_NAME is not set");
+            std::process::exit(1);
+        }
+    };
+
+    format!(
+        "https://{}-secondary.queue.core.windows.net/",
+        storage_account_name
+    )
+}

sdk/storage/azure_storage_queue/samples/helpers/logs.rs

@@ -0,0 +1,25 @@
+use azure_core::{error::Error, http::StatusCode};
+
+/// Helper function to log operation results
+pub fn log_operation_result<T>(result: &Result<T, Error>, operation: &str)
+where
+    T: std::fmt::Debug,
+{
+    match result {
+        Ok(response) => println!("Successfully {}: {:?}", operation, response),
+        Err(e) => match e.http_status() {
+            Some(StatusCode::NotFound) => println!("Unable to {}, resource not found", operation),
+            Some(StatusCode::Forbidden) => println!(
+                "Unable to {}, access forbidden - check credentials",
+                operation
+            ),
+            _ => {
+                eprintln!("Error during {}: {}", operation, e);
+                if let Some(status) = e.http_status() {
+                    eprintln!("HTTP Status: {}", status);
+                }
+                eprintln!("Full Error: {:#?}", e);
+            }
+        },
+    }
+}

sdk/storage/azure_storage_queue/samples/helpers/mod.rs

@@ -0,0 +1,3 @@
+pub mod endpoint;
+pub mod logs;
+pub mod random_queue_name;

sdk/storage/azure_storage_queue/samples/helpers/random_queue_name.rs

@@ -0,0 +1,7 @@
+/// Generates a random queue name with a suffix to ensure uniqueness.
+pub fn get_random_queue_name() -> String {
+    use rand::Rng;
+    let mut rng = rand::rng();
+    let random_suffix: u32 = rng.random_range(1000..9999);
+    format!("sdk-test-queue-{}", random_suffix)
+}