move storage_blob operations to follow the into_future pattern (#838)

* move storage_blob operations to follow the into_future pattern

Changes beyond the into_future pattern updates:
1. This updates ContentDisposition, ContentEncoding, ContentLanguage, and ContentType to follow other header types.
2. This adds a `BlobClient.get_content` helper that iterates over `BlobClient.get().stream()` and writes the data into a single Vec, returning the Vec.  This was an extremely common pattern in the examples and something akin to it is available in most of the other SDKs as well.

TODO:
* move container operations to the into_future model

* fmt

* finish moving from .execute() to .into_future()

* fmt

* add IntoFuture impls

* update tests & examples

* move back to original implementation

* address feedback

* fmt

* make pub

* make pub

* address feedback

* remove debug/trace from runtime per discussion

* fmt

* address clippy

* more consistent formatting of response_from_headers uses

* address feedback

* remove useless .into()

Co-authored-by: Brian Caswell <[email protected]>

Author: bmc-msft

sdk/core/src/request_options/content_disposition.rs

@@ -1,23 +1,42 @@
 use crate::headers::{self, Header};
 
-#[derive(Debug, Clone, Copy)]
-pub struct ContentDisposition<'a>(&'a str);
-
-impl<'a, S> From<S> for ContentDisposition<'a>
-where
-    S: Into<&'a str>,
-{
-    fn from(s: S) -> Self {
-        Self(s.into())
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ContentDisposition(std::borrow::Cow<'static, str>);
+
+impl ContentDisposition {
+    pub fn as_str(&self) -> &str {
+        self.0.as_ref()
+    }
+
+    pub const fn from_static(s: &'static str) -> Self {
+        Self(std::borrow::Cow::Borrowed(s))
+    }
+}
+
+impl From<&'static str> for ContentDisposition {
+    fn from(s: &'static str) -> Self {
+        Self::from_static(s)
+    }
+}
+
+impl From<String> for ContentDisposition {
+    fn from(s: String) -> Self {
+        Self(std::borrow::Cow::Owned(s))
+    }
+}
+
+impl From<&String> for ContentDisposition {
+    fn from(s: &String) -> Self {
+        Self(std::borrow::Cow::Owned(s.clone()))
     }
 }
 
-impl<'a> Header for ContentDisposition<'a> {
+impl Header for ContentDisposition {
     fn name(&self) -> headers::HeaderName {
-        http::header::CONTENT_DISPOSITION.into()
+        http::header::CONTENT_TYPE.into()
     }
 
     fn value(&self) -> headers::HeaderValue {
-        self.0.to_owned().into()
+        self.0.to_string().into()
     }
 }

sdk/core/src/request_options/content_encoding.rs

@@ -1,23 +1,42 @@
 use crate::headers::{self, Header};
 
-#[derive(Debug, Clone, Copy)]
-pub struct ContentEncoding<'a>(&'a str);
-
-impl<'a, S> From<S> for ContentEncoding<'a>
-where
-    S: Into<&'a str>,
-{
-    fn from(s: S) -> Self {
-        Self(s.into())
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ContentEncoding(std::borrow::Cow<'static, str>);
+
+impl ContentEncoding {
+    pub fn as_str(&self) -> &str {
+        self.0.as_ref()
+    }
+
+    pub const fn from_static(s: &'static str) -> Self {
+        Self(std::borrow::Cow::Borrowed(s))
+    }
+}
+
+impl From<&'static str> for ContentEncoding {
+    fn from(s: &'static str) -> Self {
+        Self::from_static(s)
+    }
+}
+
+impl From<String> for ContentEncoding {
+    fn from(s: String) -> Self {
+        Self(std::borrow::Cow::Owned(s))
+    }
+}
+
+impl From<&String> for ContentEncoding {
+    fn from(s: &String) -> Self {
+        Self(std::borrow::Cow::Owned(s.clone()))
     }
 }
 
-impl<'a> Header for ContentEncoding<'a> {
+impl Header for ContentEncoding {
     fn name(&self) -> headers::HeaderName {
-        http::header::CONTENT_ENCODING.into()
+        http::header::CONTENT_TYPE.into()
     }
 
     fn value(&self) -> headers::HeaderValue {
-        self.0.to_owned().into()
+        self.0.to_string().into()
     }
 }

sdk/core/src/request_options/content_language.rs

@@ -1,23 +1,42 @@
 use crate::headers::{self, Header};
 
-#[derive(Debug, Clone, Copy)]
-pub struct ContentLanguage<'a>(&'a str);
-
-impl<'a, S> From<S> for ContentLanguage<'a>
-where
-    S: Into<&'a str>,
-{
-    fn from(s: S) -> Self {
-        Self(s.into())
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ContentLanguage(std::borrow::Cow<'static, str>);
+
+impl ContentLanguage {
+    pub fn as_str(&self) -> &str {
+        self.0.as_ref()
+    }
+
+    pub const fn from_static(s: &'static str) -> Self {
+        Self(std::borrow::Cow::Borrowed(s))
+    }
+}
+
+impl From<&'static str> for ContentLanguage {
+    fn from(s: &'static str) -> Self {
+        Self::from_static(s)
+    }
+}
+
+impl From<String> for ContentLanguage {
+    fn from(s: String) -> Self {
+        Self(std::borrow::Cow::Owned(s))
+    }
+}
+
+impl From<&String> for ContentLanguage {
+    fn from(s: &String) -> Self {
+        Self(std::borrow::Cow::Owned(s.clone()))
     }
 }
 
-impl<'a> Header for ContentLanguage<'a> {
+impl Header for ContentLanguage {
     fn name(&self) -> headers::HeaderName {
-        http::header::CONTENT_LANGUAGE.into()
+        http::header::CONTENT_TYPE.into()
     }
 
     fn value(&self) -> headers::HeaderValue {
-        self.0.to_owned().into()
+        self.0.to_string().into()
     }
 }

sdk/core/src/request_options/content_type.rs

@@ -1,33 +1,44 @@
 use crate::headers::{self, Header};
 
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct ContentType<'a>(&'a str);
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ContentType(std::borrow::Cow<'static, str>);
 
-impl<'a> ContentType<'a> {
-    pub fn new(s: &'a str) -> Self {
-        Self(s)
+impl ContentType {
+    pub fn as_str(&self) -> &str {
+        self.0.as_ref()
     }
+}
 
-    pub fn as_str(&self) -> &str {
-        self.0
+impl From<&'static str> for ContentType {
+    fn from(s: &'static str) -> Self {
+        Self(std::borrow::Cow::Borrowed(s))
+    }
+}
+
+impl From<String> for ContentType {
+    fn from(s: String) -> Self {
+        Self(std::borrow::Cow::Owned(s))
+    }
+}
+
+impl From<&String> for ContentType {
+    fn from(s: &String) -> Self {
+        Self(std::borrow::Cow::Owned(s.clone()))
     }
 }
 
-impl<'a, S> From<S> for ContentType<'a>
-where
-    S: Into<&'a str>,
-{
-    fn from(s: S) -> Self {
-        Self(s.into())
+impl ContentType {
+    pub fn new(s: impl Into<ContentType>) -> Self {
+        s.into()
     }
 }
 
-impl<'a> Header for ContentType<'a> {
+impl<'a> Header for ContentType {
     fn name(&self) -> headers::HeaderName {
         http::header::CONTENT_TYPE.into()
     }
 
     fn value(&self) -> headers::HeaderValue {
-        self.0.to_owned().into()
+        self.0.to_string().into()
     }
 }

sdk/core/src/request_options/delimiter.rs

@@ -1,22 +1,23 @@
 use crate::AppendToUrlQuery;
 
 #[derive(Debug, Clone)]
-pub struct Delimiter<'a>(&'a str);
+pub struct Delimiter(String);
 
-impl<'a> Delimiter<'a> {
-    pub fn new(delimiter: &'a str) -> Self {
-        Self(delimiter)
+impl AppendToUrlQuery for Delimiter {
+    fn append_to_url_query(&self, url: &mut url::Url) {
+        url.query_pairs_mut()
+            .append_pair("delimiter", self.0.as_ref());
     }
 }
 
-impl<'a> AppendToUrlQuery for Delimiter<'a> {
-    fn append_to_url_query(&self, url: &mut url::Url) {
-        url.query_pairs_mut().append_pair("delimiter", self.0);
+impl From<&str> for Delimiter {
+    fn from(delimiter: &str) -> Self {
+        Self(delimiter.into())
     }
 }
 
-impl<'a> From<&'a str> for Delimiter<'a> {
-    fn from(delimiter: &'a str) -> Self {
+impl From<String> for Delimiter {
+    fn from(delimiter: String) -> Self {
         Self(delimiter)
     }
 }

sdk/storage_blobs/Cargo.toml

@@ -48,3 +48,4 @@ enable_reqwest_rustls = [
   "azure_core/enable_reqwest_rustls",
   "azure_storage/enable_reqwest_rustls",
 ]
+into_future = []

sdk/storage_blobs/examples/blob_00.rs

@@ -1,12 +1,9 @@
 #[macro_use]
 extern crate log;
-use azure_core::{
-    error::{ErrorKind, ResultExt},
-    prelude::*,
-};
+use azure_core::error::{ErrorKind, ResultExt};
 use azure_storage::core::prelude::*;
 use azure_storage_blobs::prelude::*;
-use futures::stream::StreamExt;
+use futures::StreamExt;
 
 #[tokio::main]
 async fn main() -> azure_core::Result<()> {
@@ -40,23 +37,21 @@ async fn main() -> azure_core::Result<()> {
 
     // this is a single call that retrieves the first 1KB of the blob (or less if the blob is
     // smaller). The range(...) call is optional.
-    let response = blob_client
-        .get()
-        .range(Range::new(0, 1024))
-        .execute()
-        .await?;
+    let response = Box::pin(blob_client.get().range(0u64..1024).stream(1024))
+        .next()
+        .await
+        .expect("stream failed")?;
 
     println!("{:#?}", response);
 
-    let mut complete_response = Vec::new();
-
+    let mut complete_response = vec![];
     // this is how you stream a blob. You can specify the range(...) value as above if necessary.
     // In this case we are retrieving the whole blob in 8KB chunks.
     let mut stream = Box::pin(blob_client.get().stream(1024 * 8));
     while let Some(value) = stream.next().await {
         let data = value?.data;
         println!("received {:?} bytes", data.len());
-        complete_response.extend(&data as &[u8]);
+        complete_response.extend(&data);
     }
 
     let s_content = String::from_utf8(complete_response).map_kind(ErrorKind::DataConversion)?;

sdk/storage_blobs/examples/blob_01.rs

@@ -1,5 +1,6 @@
 use azure_storage::core::prelude::*;
 use azure_storage_blobs::prelude::*;
+use futures::StreamExt;
 
 #[tokio::main]
 async fn main() -> azure_core::Result<()> {
@@ -22,18 +23,11 @@ async fn main() -> azure_core::Result<()> {
     let container_client = storage_client.as_container_client(&container_name);
     let blob_client = container_client.as_blob_client("SorgeniaReorganizeRebuildIndexes.zip");
 
-    let _res = container_client
-        .list_blobs()
-        .include_copy(true)
-        .include_deleted(true)
-        .include_metadata(true)
-        .include_snapshots(true)
-        .include_uncommitted_blobs(true)
-        .execute()
-        .await?;
-
-    let result = blob_client.get().execute().await?;
-
+    // only get the first 8k chunk
+    let result = Box::pin(blob_client.get().stream(1024 * 8))
+        .next()
+        .await
+        .expect("stream failed")?;
     println!("{:?}", result);
 
     Ok(())

sdk/storage_blobs/examples/blob_02_bearer_token.rs

@@ -1,7 +1,6 @@
 #[macro_use]
 extern crate log;
 
-use azure_core::error::{ErrorKind, ResultExt};
 use azure_storage::core::prelude::*;
 use azure_storage_blobs::prelude::*;
 
@@ -30,12 +29,8 @@ async fn main() -> azure_core::Result<()> {
 
     trace!("Requesting blob");
 
-    let response = blob_client.get().execute().await?;
-
-    let s_content =
-        String::from_utf8(response.data.to_vec()).map_kind(ErrorKind::DataConversion)?;
-    println!("blob == {:?}", blob);
-    println!("s_content == {}", s_content);
+    let blob = blob_client.get_content().await?;
+    println!("response == {:?}", blob);
 
     Ok(())
 }

sdk/storage_blobs/examples/blob_04.rs

@@ -42,12 +42,12 @@ async fn main() -> azure_core::Result<()> {
 
         let block_id = Bytes::from(format!("{}", i));
         block_ids.push(block_id.clone());
-        let hash = md5::compute(slice.clone()).into();
+        let hash = md5::compute(slice.clone());
 
         let put_block_response = blob_client
             .put_block(block_id, slice)
-            .hash(&hash)
-            .execute()
+            .hash(hash)
+            .into_future()
             .await?;
 
         println!("put_block_response == {:#?}", put_block_response);
@@ -59,16 +59,15 @@ async fn main() -> azure_core::Result<()> {
     }
 
     let res = blob_client
-        .put_block_list(&block_list)
+        .put_block_list(block_list)
         .content_md5(md5::compute(data))
-        .execute()
+        .into_future()
         .await?;
     println!("PutBlockList == {:?}", res);
 
-    let retrieved_blob = blob_client.get().execute().await?;
-    println!("retrieved_blob == {:?}", retrieved_blob);
+    let blob = blob_client.get_content().await?;
 
-    let s = String::from_utf8(retrieved_blob.data.to_vec()).map_kind(ErrorKind::DataConversion)?;
+    let s = String::from_utf8(blob).map_kind(ErrorKind::DataConversion)?;
     println!("retrieved contents == {}", s);
 
     Ok(())