[Storage] stage_block, commit_block_list for BlobClient, get_container_properties for ContainerClient, ServiceClient (#2273)

Author: vincenttran-msft

.vscode/cspell.json

@@ -5,6 +5,7 @@
   "ignorePaths": [
     "**/test-resources.bicep",
     "**/test-resources.json",
+    "**/assets.json",
     ".config",
     ".devcontainer/devcontainer.json",
     ".devcontainer/Dockerfile",
@@ -193,4 +194,4 @@
       ]
     }
   ]
-}
+}

Cargo.lock

@@ -71,10 +71,6 @@ path = "sdk/core/azure_core_test_macros"
 # azure_identity should only ever be in dev-dependencies herein
 path = "sdk/identity/azure_identity"
 
-[workspace.dependencies.azure_storage_common]
-version = "0.1.0"
-path = "sdk/storage"
-
 [workspace.dependencies]
 async-lock = "3.0"
 async-process = "2.0"

Cargo.toml

@@ -1,3 +1,4 @@
+AAABBBCCC
 appendblock
 appendpos
 blockid

sdk/storage/.dict.txt

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

sdk/storage/assets.json

@@ -11,18 +11,19 @@ rust-version.workspace = true
 
 [dependencies]
 async-trait.workspace = true
-azure_storage_common.workspace = true
 azure_core = { workspace = true, features = ["xml"] }
+azure_storage_common = { version = "0.1.0", path = ".." }
 serde.workspace = true
 time.workspace = true
 typespec_client_core = { workspace = true, features = ["derive"] }
-uuid.workspace = true
 url.workspace = true
+uuid.workspace = true
 
 [lints]
 workspace = true
 
 [dev-dependencies]
-tokio = { workspace = true, features = ["macros"] }
-azure_identity.workspace = true
 azure_core_test.workspace = true
+azure_identity.workspace = true
+azure_storage_blob_test.path = "../azure_storage_blob_test"
+tokio = { workspace = true, features = ["macros"] }

sdk/storage/azure_storage_blob/Cargo.toml

@@ -5,17 +5,19 @@ use crate::{
     clients::GeneratedBlobClient,
     models::{
         BlobBlobClientDownloadOptions, BlobBlobClientGetPropertiesOptions,
-        BlobBlockBlobClientUploadOptions, BlobProperties,
+        BlobBlockBlobClientCommitBlockListOptions, BlobBlockBlobClientStageBlockOptions,
+        BlobBlockBlobClientUploadOptions, BlobProperties, BlockLookupList,
     },
     pipeline::StorageHeadersPolicy,
     BlobClientOptions,
 };
 use azure_core::{
-    credentials::TokenCredential, BearerTokenCredentialPolicy, Bytes, Policy, RequestContent,
-    Response, Result, Url,
+    base64, credentials::TokenCredential, BearerTokenCredentialPolicy, Bytes, Policy,
+    RequestContent, Response, Result, Url,
 };
 use std::sync::Arc;
 
+/// A client to interact with a specific Azure storage blob, although that blob may not yet exist.
 pub struct BlobClient {
     endpoint: Url,
     container_name: String,
@@ -24,6 +26,15 @@ pub struct BlobClient {
 }
 
 impl BlobClient {
+    /// Creates a new BlobClient, using Entra ID authentication.
+    ///
+    /// # Arguments
+    ///
+    /// * `endpoint` - The full URL of the Azure storage account, for example `https://myaccount.blob.core.windows.net/`
+    /// * `container_name` - The name of the container containing this blob.
+    /// * `blob_name` - The name of the blob to interact with.
+    /// * `credential` - An implementation of [`TokenCredential`] that can provide an Entra ID token to use when authenticating.
+    /// * `options` - Optional configuration for the client.
     pub fn new(
         endpoint: &str,
         container_name: String,
@@ -57,18 +68,27 @@ impl BlobClient {
         })
     }
 
+    /// Gets the endpoint of the Storage account this client is connected to.
     pub fn endpoint(&self) -> &Url {
         &self.endpoint
     }
 
+    /// Gets the container name of the Storage account this client is connected to.
     pub fn container_name(&self) -> &str {
         &self.container_name
     }
 
+    /// Gets the blob name of the Storage account this client is connected to.
     pub fn blob_name(&self) -> &str {
         &self.blob_name
     }
 
+    /// Returns all user-defined metadata, standard HTTP properties, and system properties for the blob.
+    /// The data returned does not include the content of the blob.
+    ///
+    /// # Arguments
+    ///
+    /// * `options` - Optional configuration for the request.
     pub async fn get_blob_properties(
         &self,
         options: Option<BlobBlobClientGetPropertiesOptions<'_>>,
@@ -83,6 +103,11 @@ impl BlobClient {
         Ok(blob_properties)
     }
 
+    /// Downloads a blob from the service, including its metadata and properties.
+    ///
+    /// # Arguments
+    ///
+    /// * `options` - Optional configuration for the request.
     pub async fn download_blob(
         &self,
         options: Option<BlobBlobClientDownloadOptions<'_>>,
@@ -95,7 +120,15 @@ impl BlobClient {
         Ok(response)
     }
 
-    // For now, this is single-shot, block blob hot path only.
+    /// Creates a new blob from a data source.
+    ///
+    /// # Arguments
+    ///
+    /// * `data` - The blob data to upload.
+    /// * `overwrite` - Whether the blob to be uploaded should overwrite the current data. If True, `upload_blob` will overwrite the existing data.
+    ///   If False, the operation will fail with ResourceExistsError.
+    /// * `content_length` - Total length of the blob data to be uploaded.
+    /// * `options` - Optional configuration for the request.
     pub async fn upload_blob(
         &self,
         data: RequestContent<Bytes>,
@@ -105,7 +138,6 @@ impl BlobClient {
     ) -> Result<Response<()>> {
         let mut options = options.unwrap_or_default();
 
-        // Check if they want overwrite, by default overwrite=False
         if !overwrite {
             options.if_none_match = Some(String::from("*"));
         }
@@ -117,4 +149,48 @@ impl BlobClient {
             .await?;
         Ok(response)
     }
+
+    /// Creates a new block to be later committed as part of a blob.
+    ///
+    /// # Arguments
+    ///
+    /// * `block_id` - The unique identifier for the block. The identifier should be less than or equal to 64 bytes in size.
+    ///   For a given blob, the `block_id` must be the same size for each block.
+    /// * `content_length` - Total length of the blob data to be staged.
+    /// * `data` - The content of the blob.
+    /// * `options` - Optional configuration for the request.
+    pub async fn stage_block(
+        &self,
+        block_id: &str,
+        content_length: i64,
+        data: RequestContent<Bytes>,
+        options: Option<BlobBlockBlobClientStageBlockOptions<'_>>,
+    ) -> Result<Response<()>> {
+        let block_id = base64::encode(block_id);
+        let response = self
+            .client
+            .get_blob_block_blob_client(self.container_name.clone(), self.blob_name.clone())
+            .stage_block(&block_id, content_length, data, options)
+            .await?;
+        Ok(response)
+    }
+
+    /// Writes to a blob based on blocks specified by the list of IDs and content that make up the blob.
+    ///
+    /// # Arguments
+    ///
+    /// * `blocks` - The list of Block Blobs to commit.
+    /// * `options` - Optional configuration for the request.
+    pub async fn commit_block_list(
+        &self,
+        blocks: RequestContent<BlockLookupList>,
+        options: Option<BlobBlockBlobClientCommitBlockListOptions<'_>>,
+    ) -> Result<Response<()>> {
+        let response = self
+            .client
+            .get_blob_block_blob_client(self.container_name.clone(), self.blob_name.clone())
+            .commit_block_list(blocks, options)
+            .await?;
+        Ok(response)
+    }
 }

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

@@ -1,22 +1,36 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
-use crate::clients::GeneratedBlobClient;
-use crate::models::{BlobContainerClientCreateOptions, BlobContainerClientDeleteOptions};
-use crate::pipeline::StorageHeadersPolicy;
-use crate::BlobClientOptions;
+use crate::{
+    clients::GeneratedBlobClient,
+    models::{
+        BlobContainerClientCreateOptions, BlobContainerClientDeleteOptions,
+        BlobContainerClientGetPropertiesOptions, ContainerProperties,
+    },
+    pipeline::StorageHeadersPolicy,
+    BlobClientOptions,
+};
 use azure_core::{
     credentials::TokenCredential, BearerTokenCredentialPolicy, Policy, Response, Result, Url,
 };
 use std::sync::Arc;
 
+/// A client to interact with a specified Azure storage container.
 pub struct BlobContainerClient {
     endpoint: Url,
     container_name: String,
     client: GeneratedBlobClient,
 }
 
 impl BlobContainerClient {
+    /// Creates a new BlobContainerClient, using Entra ID authentication.
+    ///
+    /// # Arguments
+    ///
+    /// * `endpoint` - The full URL of the Azure storage account, for example `https://myaccount.blob.core.windows.net/`
+    /// * `container_name` - The name of the container.
+    /// * `credential` - An implementation of [`TokenCredential`] that can provide an Entra ID token to use when authenticating.
+    /// * `options` - Optional configuration for the client.
     pub fn new(
         endpoint: &str,
         container_name: String,
@@ -49,14 +63,21 @@ impl BlobContainerClient {
         })
     }
 
+    /// Gets the endpoint of the Storage account this client is connected to.
     pub fn endpoint(&self) -> &Url {
         &self.endpoint
     }
 
+    /// Gets the container name of the Storage account this client is connected to.
     pub fn container_name(&self) -> &str {
         &self.container_name
     }
 
+    /// Creates a new container under the specified account. If the container with the same name already exists, the operation fails.
+    ///
+    /// # Arguments
+    ///
+    /// * `options` - Optional configuration for the request.
     pub async fn create_container(
         &self,
         options: Option<BlobContainerClientCreateOptions<'_>>,
@@ -69,6 +90,11 @@ impl BlobContainerClient {
         Ok(response)
     }
 
+    /// Marks the specified container for deletion. The container and any blobs contained within are later deleted during garbage collection.
+    ///
+    /// # Arguments
+    ///
+    /// * `options` - Optional configuration for the request.
     pub async fn delete_container(
         &self,
         options: Option<BlobContainerClientDeleteOptions<'_>>,
@@ -80,4 +106,24 @@ impl BlobContainerClient {
             .await?;
         Ok(response)
     }
+
+    /// Returns all user-defined metadata and system properties for the specified container.
+    /// The data returned does not include the container's list of blobs.
+    ///
+    /// # Arguments
+    ///
+    /// * `options` - Optional configuration for the request.
+    pub async fn get_container_properties(
+        &self,
+        options: Option<BlobContainerClientGetPropertiesOptions<'_>>,
+    ) -> Result<ContainerProperties> {
+        let response = self
+            .client
+            .get_blob_container_client(self.container_name.clone())
+            .get_properties(options)
+            .await?;
+
+        let container_properties: ContainerProperties = response.headers().get()?;
+        Ok(container_properties)
+    }
 }