[Storage] More azure_storage_blob housekeeping (aligning Etag, HttpRange, etc.)

sdk/storage/azure_storage_blob/CHANGELOG.md

@@ -15,13 +15,21 @@
 ### Features Added
 
 - Added the `reqwest_rustls` feature to use `aws-lc-rs` as the default TLS provider.
+- Added `From` implementations on `HttpRange` for standard Rust range types: `Range<u64>`, `RangeFrom<u64>`, `RangeInclusive<u64>`, `RangeTo<u64>`, `RangeToInclusive<u64>`, and their `usize` equivalents. This allows `(0..100u64).into()`, `(100u64..).into()`, etc.
 
 ### Breaking Changes
 
 - Added default connection timeout of 20s and read timeout of 60s.
 - Removed the `reqwest_native_tls` feature in favor of `reqwest_rustls`.
 - Responses are no longer automatically decompressed.
 - Removed `download_into()` from existing clients. Callers can still use `download()` and collect the streamed `Bytes` into memory.
+- Changed `BlobClientDownloadOptions.range` from `Option<Range<usize>>` to `Option<HttpRange>`.
+- Changed `BlobClientDownloadOptions.if_match` and `if_none_match` from `Option<String>` to `Option<Etag>`.
+- Changed `PageBlobClient::upload_pages()` and `clear_pages()` `range` parameter from `String` to `HttpRange`.
+- Changed `PageBlobClient::upload_pages_from_url()` `range` and `source_range` parameters from `String` to `HttpRange`.
+- Changed `PageBlobClientGetPageRangesOptions.range` from `Option<String>` to `Option<HttpRange>`.
+- Changed `AppendBlobClientAppendBlockFromUrlOptions.source_range` from `Option<String>` to `Option<HttpRange>`.
+- Changed `BlockBlobClientUploadBlobFromUrlOptions.source_range` from `Option<String>` to `Option<HttpRange>`.
 
 ### Other Changes
 

sdk/storage/azure_storage_blob/README.md

@@ -6,7 +6,7 @@ Azure Blob storage is Microsoft's object storage solution for the cloud. Blob st
 
 ## Getting started
 
-**⚠️ Note: The `azure_storage_blob` 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).**
+**⚠️ Note: The `azure_storage_blob` 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](https://github.com/Azure/azure-sdk-for-rust/issues).**
 
 ### Install the package
 
@@ -18,7 +18,7 @@ cargo add azure_storage_blob
 
 ### Prerequisites
 
-* You must have an [Azure subscription] and an [Azure storage account] to use this package.
+- You must have an [Azure subscription] and an [Azure storage account] to use this package.
 
 ### Create a storage account
 
@@ -48,10 +48,10 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     let credential = DeveloperToolsCredential::new(None)?;
     let blob_client = BlobClient::new(
         "https://<storage_account_name>.blob.core.windows.net/", // Endpoint
-        "container_name",                                        // Container Name
-        "blob_name",                                             // Blob Name
-        Some(credential),                                        // Credential
-        Some(BlobClientOptions::default()),                      // BlobClient Options
+        "<container_name>",                                       // Container Name
+        "<blob_name>",                                            // Blob Name
+        Some(credential),                                         // Credential
+        Some(BlobClientOptions::default()),                       // BlobClient Options
     )?;
     Ok(())
 }
@@ -65,14 +65,16 @@ You may need to specify RBAC roles to access Blob Storage via Microsoft Entra ID
 
 You can find executable examples for all major SDK functions in:
 
-* [blob_hello_world.rs](https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_blob/examples/blob_hello_world.rs) - Getting started: create a container, upload and download a blob
-* [blob_container_client.rs](https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_blob/examples/blob_container_client.rs) - Container-level operations: metadata, list blobs with continuation, access policies
-* [blob_service_client.rs](https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_blob/examples/blob_service_client.rs) - Service-level operations: list containers, service properties, statistics
-* [block_blob_client.rs](https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_blob/examples/block_blob_client.rs) - Block blob operations: staged block upload, copy from URL
-* [append_blob_client.rs](https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_blob/examples/append_blob_client.rs) - Append blob operations: create, append blocks, seal
-* [page_blob_client.rs](https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_blob/examples/page_blob_client.rs) - Page blob operations: create, upload/clear pages, list page ranges, resize
-* [blob_storage_logging.rs](https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_blob/examples/blob_storage_logging.rs) - Logging and OpenTelemetry distributed tracing
-* [storage_error.rs](https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_blob/examples/storage_error.rs) - Structured error handling with `StorageError`
+- [blob_hello_world.rs](https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_blob/examples/blob_hello_world.rs) - Getting started: create a container, upload and download a blob
+- [blob_client.rs](https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_blob/examples/blob_client.rs) - Blob-level operations: exists, metadata, index tags, access tier
+- [blob_container_client.rs](https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_blob/examples/blob_container_client.rs) - Container-level operations: metadata, list blobs with continuation, access policies
+- [blob_service_client.rs](https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_blob/examples/blob_service_client.rs) - Service-level operations: list containers, service properties, statistics
+- [block_blob_client.rs](https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_blob/examples/block_blob_client.rs) - Block blob operations: staged block upload, copy from URL
+- [append_blob_client.rs](https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_blob/examples/append_blob_client.rs) - Append blob operations: create, append blocks, seal
+- [page_blob_client.rs](https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_blob/examples/page_blob_client.rs) - Page blob operations: create, upload/clear pages, list page ranges, resize
+- [blob_storage_upload_file.rs](https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_blob/examples/blob_storage_upload_file.rs) - Upload a local file with streaming support for large files
+- [blob_storage_logging.rs](https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_blob/examples/blob_storage_logging.rs) - Logging and OpenTelemetry distributed tracing
+- [storage_error.rs](https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_blob/examples/storage_error.rs) - Structured error handling with `StorageError`
 
 ### Upload a blob
 
@@ -86,8 +88,8 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     let credential = DeveloperToolsCredential::new(None)?;
     let blob_client = BlobClient::new(
         "https://<storage_account_name>.blob.core.windows.net/",
-        "container_name",
-        "blob_name",
+        "<container_name>",
+        "<blob_name>",
         Some(credential),
         Some(BlobClientOptions::default()),
     )?;
@@ -114,12 +116,14 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     let credential = DeveloperToolsCredential::new(None)?;
     let blob_client = BlobClient::new(
         "https://<storage_account_name>.blob.core.windows.net/", // Endpoint
-        "container_name",                                        // Container Name
-        "blob_name",                                             // Blob Name
-        Some(credential),                                        // Credential
-        Some(BlobClientOptions::default()),                      // BlobClient Options
+        "<container_name>",                                       // Container Name
+        "<blob_name>",                                            // Blob Name
+        Some(credential),                                         // Credential
+        Some(BlobClientOptions::default()),                       // BlobClient Options
     )?;
-    let blob_properties = blob_client.get_properties(None).await?;
+    let response = blob_client.download(None).await?;
+    let data = String::from_utf8(response.body.collect().await?.into())?;
+    println!("Downloaded: {data}");
     Ok(())
 }
 ```
@@ -131,7 +135,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 By default, all storage clients create an HTTP transport with automatic decompression disabled,
 which is required for partitioned (multi-part) downloads to work correctly. If you set a custom transport
 in client options (e.g., a `reqwest::Client` with gzip enabled) without disabling automatic
-decompression, partitioned downloads via [`BlobClient::download`](https://docs.rs/azure_storage_blob/latest/azure_storage_blob/clients/struct.BlobClient.html#method.download).
+decompression, partitioned downloads via [`BlobClient::download`](https://docs.rs/azure_storage_blob/latest/azure_storage_blob/clients/struct.BlobClient.html#method.download) may not work correctly.
 If you need to provide a custom transport, disable automatic decompression to be consistent with default SDK behavior.
 
 ## Next Steps
@@ -154,7 +158,7 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope
 [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
+[cargo]: https://doc.rust-lang.org/cargo/
 [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_blob/latest
 [Package (crates.io)]: https://crates.io/crates/azure_storage_blob

sdk/storage/azure_storage_blob/assets.json

@@ -1,6 +1,6 @@
 {
   "AssetsRepo": "Azure/azure-sdk-assets",
   "AssetsRepoPrefixPath": "rust",
-  "Tag": "rust/azure_storage_blob_3bcbe9fe6f",
+  "Tag": "rust/azure_storage_blob_a6b159d0dc",
   "TagPrefix": "rust/azure_storage_blob"
 }

sdk/storage/azure_storage_blob/examples/README.md

@@ -14,6 +14,7 @@ This directory contains a set of examples for the use of the Blob Storage client
 | `append_blob_client.rs` | Append blob operations: create, append blocks, seal |
 | `page_blob_client.rs` | Page blob operations: create, upload/clear pages, list page ranges, resize |
 | `blob_storage_logging.rs` | Logging and OpenTelemetry distributed tracing |
+| `blob_storage_upload_file.rs` | Upload a local file with streaming support for large files |
 | `storage_error.rs` | Structured error handling with `StorageError` |
 
 ## Setup

sdk/storage/azure_storage_blob/examples/page_blob_client.rs

@@ -64,7 +64,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
     // Write 512 bytes of data to bytes 0-511.
     let page_data = vec![b'A'; 512];
-    let range = HttpRange::new(0, 512).to_string();
+    let range = HttpRange::new(0, 512);
     page_blob_client
         .upload_pages(RequestContent::from(page_data), 512, range, None)
         .await?;
@@ -80,7 +80,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
     // Clear the page range (zeroes out those bytes).
     page_blob_client
-        .clear_pages(HttpRange::new(0, 512).to_string(), None)
+        .clear_pages(HttpRange::new(0, 512), None)
         .await?;
     println!("Cleared page range 0-511");
 

sdk/storage/azure_storage_blob/src/clients/blob_client.rs

@@ -7,8 +7,8 @@ use crate::{
     generated::clients::BlobClient as GeneratedBlobClient,
     generated::models::BlobClientDownloadInternalOptions,
     models::{
-        http_ranges::IntoRangeHeader, BlobClientDownloadOptions, BlobClientDownloadResult,
-        BlobClientUploadOptions, BlobClientUploadResult, StorageErrorCode,
+        BlobClientDownloadOptions, BlobClientDownloadResult, BlobClientUploadOptions,
+        BlobClientUploadResult, HttpRange, StorageErrorCode,
     },
     partitioned_transfer::{self, PartitionedDownloadBehavior},
     AppendBlobClient, BlockBlobClient, PageBlobClient,
@@ -19,8 +19,8 @@ use azure_core::{
     error::ErrorKind,
     http::{
         policies::{auth::BearerTokenAuthorizationPolicy, Policy},
-        AsyncRawResponse, ClientMethodOptions, NoFormat, Pipeline, RequestContent, StatusCode, Url,
-        UrlExt,
+        AsyncRawResponse, ClientMethodOptions, Etag, NoFormat, Pipeline, RequestContent,
+        StatusCode, Url, UrlExt,
     },
     tracing, Bytes, Result,
 };
@@ -309,10 +309,10 @@ impl PartitionedDownloadBehavior for BlobClientDownloadBehavior<'_> {
     async fn transfer_range(
         &self,
         range: Option<Range<usize>>,
-        etag_lock: Option<String>,
+        etag_lock: Option<Etag>,
     ) -> Result<AsyncRawResponse> {
         let mut opt = self.options.clone();
-        opt.range = range.map(|r| r.as_range_header());
+        opt.range = range.map(HttpRange::from);
         if let Some(etag) = etag_lock {
             opt.if_match = Some(etag);
             opt.if_none_match = None;