storage_blobs: Add support for snapshot blob.

sdk/storage/src/core/clients/storage_client.rs

@@ -336,6 +336,41 @@ impl StorageClient {
         }
     }
 
+    #[cfg(feature = "mock_transport_framework")]
+    /// Create a new instance of `StorageClient` using a mock backend. The
+    /// transaction name is used to look up which files to read to validate the
+    /// request and mock the response.
+    pub fn new_mock(
+        account: impl Into<String>,
+        storage_credentials: StorageCredentials,
+        transaction_name: impl Into<String>,
+    ) -> Self {
+        let account = account.into();
+        let options = ClientOptions::new_with_transaction_name(transaction_name.into());
+        let pipeline = new_pipeline_from_options(
+            StorageOptions {
+                options,
+                timeout_policy: Default::default(),
+            },
+            storage_credentials.clone(),
+        );
+        Self {
+            blob_storage_url: get_endpoint_uri(None, &account, "blob").unwrap(),
+            table_storage_url: get_endpoint_uri(None, &account, "table").unwrap(),
+            queue_storage_url: get_endpoint_uri(None, &account, "queue").unwrap(),
+            queue_storage_secondary_url: get_endpoint_uri(
+                None,
+                &format!("{}-secondary", account),
+                "queue",
+            )
+            .unwrap(),
+            filesystem_url: get_endpoint_uri(None, &account, "dfs").unwrap(),
+            storage_credentials,
+            account,
+            pipeline,
+        }
+    }
+
     pub fn blob_storage_url(&self) -> &Url {
         &self.blob_storage_url
     }

sdk/storage_blobs/Cargo.toml

@@ -39,6 +39,7 @@ oauth2 = { version = "4.0.0", default-features = false }
 [features]
 default = ["enable_reqwest", "azure_identity/default"]
 test_e2e = []
+mock_transport_framework = [ "azure_core/mock_transport_framework", "azure_storage/mock_transport_framework"]
 azurite_workaround = []
 enable_reqwest = ["azure_core/enable_reqwest", "azure_storage/enable_reqwest"]
 enable_reqwest_rustls = [

sdk/storage_blobs/examples/snapshot_blob.rs

@@ -0,0 +1,58 @@
+#[macro_use]
+extern crate log;
+
+use azure_storage::core::prelude::*;
+use azure_storage_blobs::prelude::*;
+use bytes::Bytes;
+
+#[tokio::main]
+async fn main() -> azure_core::Result<()> {
+    env_logger::init();
+    debug!("log initialized");
+    // First we retrieve the account name and access key from environment variables.
+    let account =
+        std::env::var("STORAGE_ACCOUNT").expect("Set env variable STORAGE_ACCOUNT first!");
+    let access_key =
+        std::env::var("STORAGE_ACCESS_KEY").expect("Set env variable STORAGE_ACCESS_KEY first!");
+
+    let container = std::env::args()
+        .nth(1)
+        .expect("please specify container name as command line parameter");
+    let blob_name = std::env::args()
+        .nth(2)
+        .expect("please specify blob name as command line parameter");
+
+    let blob_client = StorageClient::new_access_key(&account, &access_key)
+        .container_client(&container)
+        .blob_client(&blob_name);
+
+    let data = Bytes::from_static(b"something");
+
+    // this is not mandatory but it helps preventing
+    // spurious data to be uploaded.
+    let hash = md5::compute(&data[..]);
+
+    // The required parameters are container_name, blob_name and body.
+    // The builder supports many more optional
+    // parameters (such as LeaseID, or ContentDisposition, MD5 etc...)
+    // so make sure to check with the documentation.
+    let res = blob_client
+        .put_block_blob(data.clone())
+        .content_type("text/plain")
+        .hash(hash)
+        .into_future()
+        .await?;
+    println!("put_blob {:?}", res);
+
+    let res = blob_client.snapshot().into_future().await?;
+    println!("blob snapshot: {:?}", res.snapshot);
+
+    let res = blob_client
+        .delete()
+        .delete_snapshots_method(DeleteSnapshotsMethod::Include)
+        .into_future()
+        .await?;
+    println!("Delete blob == {:?}", res);
+
+    Ok(())
+}

sdk/storage_blobs/src/blob/block_with_size_list.rs

@@ -100,19 +100,19 @@ mod test {
             </BlockList>  ";
 
         let bl = BlockWithSizeList::try_from_xml(range).unwrap();
-        assert!(bl.blocks.len() == 2);
-        assert!(bl.blocks[0].size_in_bytes == 200);
-        assert!(bl.blocks[1].size_in_bytes == 4096);
+        assert_eq!(bl.blocks.len(), 2);
+        assert_eq!(bl.blocks[0].size_in_bytes, 200);
+        assert_eq!(bl.blocks[1].size_in_bytes, 4096);
 
-        assert!(
-            bl.blocks[0].block_list_type == BlobBlockType::new_committed("base64-encoded-block-id")
+        assert_eq!(
+            bl.blocks[0].block_list_type,
+            BlobBlockType::new_committed("base64-encoded-block-id")
         );
         let b2 = BlobBlockType::new_uncommitted("base64-encoded-block-id-number2");
-        assert!(
-            bl.blocks[1].block_list_type == b2,
+        assert_eq!(
+            bl.blocks[1].block_list_type, b2,
             "bl.blocks[1].block_list_type == {:?}, b2 == {:?}",
-            bl.blocks[1].block_list_type,
-            b2
+            bl.blocks[1].block_list_type, b2
         );
     }
 
@@ -121,10 +121,10 @@ mod test {
         let range = "<?xml version=\"1.0\" encoding=\"utf-8\"?><BlockList><CommittedBlocks /><UncommittedBlocks><Block><Name>YmxvY2sx</Name><Size>62</Size></Block><Block><Name>YmxvY2sy</Name><Size>62</Size></Block><Block><Name>YmxvY2sz</Name><Size>62</Size></Block></UncommittedBlocks></BlockList>";
 
         let bl = BlockWithSizeList::try_from_xml(range).unwrap();
-        assert!(bl.blocks.len() == 3);
-        assert!(bl.blocks[0].size_in_bytes == 62);
-        assert!(bl.blocks[1].size_in_bytes == 62);
-        assert!(bl.blocks[2].size_in_bytes == 62);
+        assert_eq!(bl.blocks.len(), 3);
+        assert_eq!(bl.blocks[0].size_in_bytes, 62);
+        assert_eq!(bl.blocks[1].size_in_bytes, 62);
+        assert_eq!(bl.blocks[2].size_in_bytes, 62);
     }
 
     /// Tests that we can explicitly deserialize the response even if not all
@@ -142,8 +142,8 @@ mod test {
         </BlockList>  ";
 
         let bl = BlockWithSizeList::try_from_xml(range).unwrap();
-        assert!(bl.blocks.len() == 1);
-        assert!(bl.blocks[0].size_in_bytes == 200);
+        assert_eq!(bl.blocks.len(), 1);
+        assert_eq!(bl.blocks[0].size_in_bytes, 200);
 
         let range = "<?xml version=\"1.0\" encoding=\"utf-8\"?>
         <BlockList>
@@ -156,8 +156,8 @@ mod test {
         </BlockList>  ";
 
         let bl = BlockWithSizeList::try_from_xml(range).unwrap();
-        assert!(bl.blocks.len() == 1);
-        assert!(bl.blocks[0].size_in_bytes == 4096);
+        assert_eq!(bl.blocks.len(), 1);
+        assert_eq!(bl.blocks[0].size_in_bytes, 4096);
 
         let range = "<?xml version=\"1.0\" encoding=\"utf-8\"?>
         <BlockList>
@@ -174,14 +174,14 @@ mod test {
         </BlockList>  ";
 
         let bl = BlockWithSizeList::try_from_xml(range).unwrap();
-        assert!(bl.blocks.len() == 2);
-        assert!(bl.blocks[0].size_in_bytes == 4096);
-        assert!(bl.blocks[1].size_in_bytes == 200);
+        assert_eq!(bl.blocks.len(), 2);
+        assert_eq!(bl.blocks[0].size_in_bytes, 4096);
+        assert_eq!(bl.blocks[1].size_in_bytes, 200);
 
         let range = "<?xml version=\"1.0\" encoding=\"utf-8\"?>
         <BlockList>
         </BlockList>  ";
         let bl = BlockWithSizeList::try_from_xml(range).unwrap();
-        assert!(bl.blocks.len() == 0);
+        assert!(bl.blocks.is_empty());
     }
 }

sdk/storage_blobs/src/blob/operations/mod.rs

@@ -27,6 +27,7 @@ mod set_expiry;
 mod set_metadata;
 mod set_properties;
 mod set_tags;
+mod snapshot_blob;
 
 pub use acquire_lease::*;
 pub use append_block::*;
@@ -57,3 +58,4 @@ pub use set_expiry::*;
 pub use set_metadata::*;
 pub use set_properties::*;
 pub use set_tags::*;
+pub use snapshot_blob::*;

sdk/storage_blobs/src/blob/operations/snapshot_blob.rs

@@ -0,0 +1,68 @@
+use crate::prelude::*;
+use azure_core::headers::{etag_from_headers, HeaderName};
+use azure_core::{
+    headers::{date_from_headers, last_modified_from_headers, request_id_from_headers, Headers},
+    prelude::*,
+    Method::Put,
+    RequestId,
+};
+use time::OffsetDateTime;
+
+operation! {
+    SnapshotBlob,
+    client: BlobClient,
+    ?metadata: Metadata,
+    ?if_modified_since: IfModifiedSinceCondition,
+    ?if_match: IfMatchCondition,
+    ?lease_id: LeaseId
+}
+
+impl SnapshotBlobBuilder {
+    pub fn into_future(mut self) -> SnapshotBlob {
+        Box::pin(async move {
+            let mut url = self.client.url()?;
+
+            url.query_pairs_mut().append_pair("comp", "snapshot");
+
+            let mut headers = Headers::new();
+            headers.add(self.lease_id);
+            headers.add(self.if_modified_since);
+            headers.add(self.if_match);
+            if let Some(metadata) = &self.metadata {
+                for m in metadata.iter() {
+                    headers.add(m);
+                }
+            }
+
+            let mut request = self.client.finalize_request(url, Put, headers, None)?;
+
+            let response = self.client.send(&mut self.context, &mut request).await?;
+            response.headers().try_into()
+        })
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct SnapshotBlobResponse {
+    pub request_id: RequestId,
+    pub etag: String,
+    pub date: OffsetDateTime,
+    pub snapshot: Snapshot,
+    pub last_modified: OffsetDateTime,
+}
+
+impl TryFrom<&Headers> for SnapshotBlobResponse {
+    type Error = crate::Error;
+
+    fn try_from(headers: &Headers) -> Result<Self, Self::Error> {
+        Ok(SnapshotBlobResponse {
+            request_id: request_id_from_headers(headers)?,
+            etag: etag_from_headers(headers)?,
+            date: date_from_headers(headers)?,
+            snapshot: Snapshot::new(headers.get_str(&SNAPSHOT)?.to_string()),
+            last_modified: last_modified_from_headers(headers)?,
+        })
+    }
+}
+
+pub const SNAPSHOT: HeaderName = HeaderName::from_static("x-ms-snapshot");

sdk/storage_blobs/src/clients/blob_client.rs

@@ -250,6 +250,11 @@ impl BlobClient {
         result
     }
 
+    /// Create a blob snapshot
+    pub fn snapshot(&self) -> SnapshotBlobBuilder {
+        SnapshotBlobBuilder::new(self.clone())
+    }
+
     pub fn blob_name(&self) -> &str {
         &self.blob_name
     }

sdk/storage_blobs/tests/blob.rs

@@ -368,6 +368,58 @@ async fn put_block_blob_and_get_properties() -> azure_core::Result<()> {
     Ok(())
 }
 
+#[tokio::test]
+async fn put_block_blob_and_snapshot() {
+    let blob_name: &'static str = "snapshot-blob.txt";
+    let container_name: &'static str = "rust-snapshot-test";
+    let data = Bytes::from_static(b"abcdef");
+
+    let storage = initialize();
+    let blob_service = storage.blob_service_client();
+    let container = storage.container_client(container_name);
+    let blob = container.blob_client(blob_name);
+
+    if blob_service
+        .list_containers()
+        .into_stream()
+        .next()
+        .await
+        .unwrap()
+        .unwrap()
+        .containers
+        .iter()
+        .find(|x| x.name == container_name)
+        .is_none()
+    {
+        container
+            .create()
+            .public_access(PublicAccess::None)
+            .into_future()
+            .await
+            .unwrap();
+    }
+
+    // calculate md5 too!
+    let digest = md5::compute(&data[..]);
+
+    blob.put_block_blob(data)
+        .content_type("text/plain")
+        .hash(digest)
+        .into_future()
+        .await
+        .unwrap();
+
+    trace!("created {:?}", blob_name);
+
+    let snapshot = blob.snapshot().into_future().await.unwrap().snapshot;
+
+    trace!("crated snapshot: {:?} of {:?}", snapshot, blob_name);
+
+    // Clean-up test
+    container.delete().into_future().await.unwrap();
+    trace!("container {} deleted!", container_name);
+}
+
 #[tokio::test]
 async fn set_blobtier() {
     let blob_name: &'static str = "m9";