Rename async response types, into_body to into_model (#3295)

Resolves #3288. Read that issue for full details or CHANGELOGs herein.

Author: heaths

.github/instructions/changelog.instructions.md

@@ -8,3 +8,5 @@ applyTo: "**/CHANGELOG.md"
 -   Do not create new category headers; use only those already present in the file.
 -   Ensure all entries are concise, accurate, and relevant to the release.
 -   Follow the existing formatting and style conventions of the file.
+-   Changes in `sdk/core/typespec/CHANGELOG.md` should be reflected in `sdk/core/typespec_client_core/CHANGELOG.md`.
+-   Changes in `sdk/core/typespec_client_core/CHANGELOG.md` should be reflected in `sdk/core/azure_core/CHANGELOG.md`.

eng/scripts/verify-dependencies.rs

@@ -33,6 +33,7 @@ static EXEMPTIONS: &[(&str, &str)] = &[
         "azure_messaging_eventhubs_checkpointstore_blob",
         "opentelemetry-appender-tracing",
     ),
+    ("azure_data_cosmos_native", "cbindgen"),
 ];
 
 fn main() {

sdk/core/azure_core/CHANGELOG.md

@@ -5,7 +5,9 @@
 ### Features Added
 
 - Added `ItemIterator::continuation_token()` and `with_continuation_token()` to resume paging items. The current page is restarted until _after_ all items have been iterated.
-- Added `Response::to_raw_response()` function to create a `RawResponse` from cloned data.
+- Added `PipelineOptions::retry_status_codes` for configuring which status codes should trigger a retry.
+- Added `Response<T, F>::body(&self) -> &ResponseBody`.
+- Added `Response<T, F>::to_raw_response()` function to create a `RawResponse` from cloned data.
 - Added `UrlExt::append_path()`.
 - Implemented `IntoFuture` for a `Poller`. Call `await` on a Poller to get the final model, or `into_stream()` to get a `futures::Stream` to poll the operation manually.
 - Re-exported `serde_json::Value` as `azure_core::Value` ([#1687](https://github.com/Azure/azure-sdk-for-rust/issues/1687))
@@ -24,6 +26,9 @@
 - Removed `Poller::wait()` function. Call `await` on a `Poller` to wait for it to complete and, upon success, return the final model.
 - Removed `xml::read_xml_str()`.
 - Renamed `BearerTokenCredentialPolicy` to `BearerTokenAuthorizationPolicy`.
+- Renamed `BufResponse` to `AsyncRawResponse` so that `AsyncRawResponse` is to `RawResponse` as `AsyncIterator` is to `Iterator`.
+- Renamed `BufResponseBody` to `AsyncResponseBody` so that `AsyncResponseBody` is to `ResponseBody` as `AsyncIterator` is to `Iterator`.
+- Renamed `Response<T, F>::into_body(self) -> Result<Response<T>>` to `into_model(self) -> Result<Response<T>>`. `into_body(self)` now returns a `ResponseBody`.
 - Renamed `RetryPolicy::get_retry_headers()` to `RetryPolicy::retry_headers()`
 - Renamed `xml::read_xml()` to `xml::from_xml()` congruent with `json::from_json()`.
 

sdk/core/azure_core/README.md

@@ -158,8 +158,8 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     let response = client.get_secret("secret-name", None).await?;
 
     // Response<T> has two main accessors:
-    // 1. The `into_body()` function consumes self to deserialize into a model type
-    let secret = response.into_body()?;
+    // 1. The `into_model()` function consumes self to deserialize into a model type
+    let secret = response.into_model()?;
 
     // get response again because it was moved in above statement
     let response: Response<Secret> = client.get_secret("secret-name", None).await?;
@@ -199,7 +199,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     )?;
 
     match client.get_secret("secret-name", None).await {
-        Ok(secret) => println!("Secret: {:?}", secret.into_body()?.value),
+        Ok(secret) => println!("Secret: {:?}", secret.into_model()?.value),
         Err(e) => match e.kind() {
             ErrorKind::HttpResponse { status, error_code, .. } if *status == StatusCode::NotFound => {
                 // handle not found error
@@ -276,7 +276,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
     // poll the pager until there are no more SecretListResults
     while let Some(secrets) = pager.try_next().await? {
-        let secrets = secrets.into_body()?.value;
+        let secrets = secrets.into_model()?.value;
         // loop through secrets in SecretsListResults
         for secret in secrets {
             // get the secret name from the ID
@@ -332,7 +332,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     let certificate = client
         .create_certificate("certificate-name", body.try_into()?, None)?
         .await?
-        .into_body()?;
+        .into_model()?;
 
     Ok(())
 }
@@ -378,7 +378,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     // The Poller implements futures::Stream and automatically waits between polls.
     let mut poller = client.create_certificate("certificate-name", body.try_into()?, None)?;
     while let Some(operation) = poller.try_next().await? {
-        let operation = operation.into_body()?;
+        let operation = operation.into_model()?;
         match operation.status.as_deref().unwrap_or("unknown") {
             "inProgress" => continue,
             "completed" => {
@@ -528,7 +528,7 @@ ureq = { version = "3", default-features = false, features = [
 Then we need to implement `HttpClient` for another HTTP client like [`ureq`](https://docs.rs/ureq):
 
 ```rust no_run
-use azure_core::{error::{ErrorKind, ResultExt as _}, http::{HttpClient, BufResponse, Request}};
+use azure_core::{error::{ErrorKind, ResultExt as _}, http::{HttpClient, AsyncRawResponse, Request}};
 use ureq::tls::{TlsConfig, TlsProvider};
 
 #[derive(Debug)]
@@ -552,7 +552,7 @@ impl Default for Agent {
 
 #[async_trait::async_trait]
 impl HttpClient for Agent {
-    async fn execute_request(&self, request: &Request) -> azure_core::Result<BufResponse> {
+    async fn execute_request(&self, request: &Request) -> azure_core::Result<AsyncRawResponse> {
         let request: ::http::request::Request<Vec<u8>> = todo!("convert our request into their request");
         let response = self
             .0
@@ -625,7 +625,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     // get a secret
     let secret = client.get_secret("secret-name", None)
         .await?
-        .into_body()?;
+        .into_model()?;
 
     println!("{secret:#?}");
 

sdk/core/azure_core/benches/benchmarks.rs

@@ -2,7 +2,7 @@
 // Licensed under the MIT License.
 
 use azure_core::http::{
-    headers::Headers, BufResponse, HttpClient, Method, Request, StatusCode, Url,
+    headers::Headers, AsyncRawResponse, HttpClient, Method, Request, StatusCode, Url,
 };
 use azure_core_test::http::MockHttpClient;
 use criterion::{black_box, criterion_group, criterion_main, Criterion};
@@ -72,7 +72,7 @@ fn http_transport_test(c: &mut Criterion) {
     // client to be used in the benchmark
     let mock_client = Arc::new(MockHttpClient::new(move |_| {
         async move {
-            Ok(BufResponse::from_bytes(
+            Ok(AsyncRawResponse::from_bytes(
                 StatusCode::Ok,
                 Headers::new(),
                 vec![],

sdk/core/azure_core/examples/core_error_response.rs

@@ -4,7 +4,7 @@
 use azure_core::{
     credentials::TokenCredential,
     error::ErrorResponse,
-    http::{headers::Headers, BufResponse, HttpClient, StatusCode, Transport},
+    http::{headers::Headers, AsyncRawResponse, HttpClient, StatusCode, Transport},
     json,
 };
 use azure_core_test::{credentials::MockCredential, http::MockHttpClient, ErrorKind};
@@ -92,7 +92,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 fn setup() -> Result<(Arc<dyn TokenCredential>, Arc<dyn HttpClient>), Box<dyn std::error::Error>> {
     let client = MockHttpClient::new(|_| {
         async move {
-            Ok(BufResponse::from_bytes(
+            Ok(AsyncRawResponse::from_bytes(
                 StatusCode::BadRequest,
                 Headers::new(),
                 r#"{

sdk/core/azure_core/examples/core_pager.rs

@@ -3,7 +3,7 @@
 
 use azure_core::{
     credentials::TokenCredential,
-    http::{headers::Headers, BufResponse, HttpClient, Method, StatusCode, Transport},
+    http::{headers::Headers, AsyncRawResponse, HttpClient, Method, StatusCode, Transport},
 };
 use azure_core_test::{credentials::MockCredential, http::MockHttpClient};
 use azure_security_keyvault_secrets::{ResourceExt, SecretClient, SecretClientOptions};
@@ -64,7 +64,7 @@ async fn test_page_iterator() -> Result<(), Box<dyn std::error::Error>> {
     let mut pager = client.list_secret_properties(None)?.into_pages();
     let mut names = Vec::new();
     while let Some(page) = pager.try_next().await? {
-        let page = page.into_body()?;
+        let page = page.into_model()?;
         for secret in page.value {
             names.push(secret.resource_id()?.name);
         }
@@ -106,7 +106,7 @@ fn setup() -> Result<(Arc<dyn TokenCredential>, Arc<dyn HttpClient>), Box<dyn st
                 assert_eq!(request.method(), Method::Get);
                 assert_eq!(request.url().path(), "/secrets");
                 match idx {
-                    0 => Ok(BufResponse::from_bytes(
+                    0 => Ok(AsyncRawResponse::from_bytes(
                         StatusCode::Ok,
                         Headers::new(),
                         // First page with continuation (nextLink)
@@ -116,7 +116,7 @@ fn setup() -> Result<(Arc<dyn TokenCredential>, Arc<dyn HttpClient>), Box<dyn st
                           ],
                           "nextLink":"https://my-vault.vault.azure.net/secrets?api-version=7.4&$skiptoken=page2"}"#,
                     )),
-                    1 => Ok(BufResponse::from_bytes(
+                    1 => Ok(AsyncRawResponse::from_bytes(
                         StatusCode::Ok,
                         Headers::new(),
                         // Second (final) page without nextLink

sdk/core/azure_core/examples/core_poller.rs

@@ -5,7 +5,7 @@ use azure_core::{
     credentials::TokenCredential,
     http::{
         headers::{Headers, RETRY_AFTER},
-        BufResponse, HttpClient, Method, StatusCode, Transport,
+        AsyncRawResponse, HttpClient, Method, StatusCode, Transport,
     },
 };
 use azure_core_test::{credentials::MockCredential, http::MockHttpClient};
@@ -41,7 +41,7 @@ async fn test_poller() -> Result<(), Box<dyn std::error::Error>> {
     let certificate = client
         .create_certificate("my-cert", params.try_into()?, None)?
         .await?
-        .into_body()?;
+        .into_model()?;
     assert_eq!(
         certificate.id,
         Some("https://my-vault.vault.azure.net/certificates/my-cert/version".into())
@@ -79,7 +79,7 @@ async fn test_poller_stream() -> Result<(), Box<dyn std::error::Error>> {
     // Manually poll status updates until completion
     let mut final_status = None;
     while let Some(status) = poller.try_next().await? {
-        let status = status.into_body()?;
+        let status = status.into_model()?;
         assert!(status.error.is_none());
         final_status = Some(status);
     }
@@ -132,7 +132,7 @@ fn setup() -> Result<(Arc<dyn TokenCredential>, Arc<dyn HttpClient>), Box<dyn st
                         assert_eq!(request.url().path(), "/certificates/my-cert/create");
                         let mut headers = Headers::new();
                         headers.insert(RETRY_AFTER, "0");
-                        Ok(BufResponse::from_bytes(
+                        Ok(AsyncRawResponse::from_bytes(
                             StatusCode::Ok,
                             headers,
                             r#"{"id":"https://my-vault.vault.azure.net/certificates/my-cert/pending","status":"inProgress"}"#,
@@ -142,7 +142,7 @@ fn setup() -> Result<(Arc<dyn TokenCredential>, Arc<dyn HttpClient>), Box<dyn st
                         // Polling GET for status
                         assert_eq!(request.method(), Method::Get);
                         assert_eq!(request.url().path(), "/certificates/my-cert/pending");
-                        Ok(BufResponse::from_bytes(
+                        Ok(AsyncRawResponse::from_bytes(
                             StatusCode::Ok,
                             Headers::new(),
                             r#"{"id":"https://my-vault.vault.azure.net/certificates/my-cert/pending","status":"completed","target":"https://my-vault.vault.azure.net/certificates/my-cert"}"#,
@@ -152,7 +152,7 @@ fn setup() -> Result<(Arc<dyn TokenCredential>, Arc<dyn HttpClient>), Box<dyn st
                         // Final GET for the target
                         assert_eq!(request.method(), Method::Get);
                         assert_eq!(request.url().path(), "/certificates/my-cert");
-                        Ok(BufResponse::from_bytes(
+                        Ok(AsyncRawResponse::from_bytes(
                             StatusCode::Ok,
                             Headers::new(),
                             r#"{"id":"https://my-vault.vault.azure.net/certificates/my-cert/version","cer":"dGVzdA=="}"#,

sdk/core/azure_core/examples/core_remove_user_agent.rs

@@ -7,7 +7,7 @@ use azure_core::{
     http::{
         headers::Headers,
         policies::{Policy, PolicyResult},
-        BufResponse, Context, HttpClient, Method, Request, StatusCode, Transport,
+        AsyncRawResponse, Context, HttpClient, Method, Request, StatusCode, Transport,
     },
 };
 use azure_core_test::{credentials::MockCredential, http::MockHttpClient};
@@ -62,7 +62,7 @@ async fn test_remove_user_agent() -> Result<(), Box<dyn std::error::Error>> {
     )?;
 
     // We'll fetch a secret and let the mock client assert the User-Agent header was removed.
-    let secret = client.get_secret("my-secret", None).await?.into_body()?;
+    let secret = client.get_secret("my-secret", None).await?.into_model()?;
     assert_eq!(secret.value.as_deref(), Some("secret-value"));
 
     Ok(())
@@ -92,7 +92,7 @@ fn setup() -> Result<(Arc<dyn TokenCredential>, Arc<dyn HttpClient>), Box<dyn st
                     .any(|(name, _)| name.as_str().eq_ignore_ascii_case("user-agent")),
                 "user-agent header should be absent"
             );
-            Ok(BufResponse::from_bytes(
+            Ok(AsyncRawResponse::from_bytes(
                 StatusCode::Ok,
                 Headers::new(),
                 r#"{"value":"secret-value"}"#,

sdk/core/azure_core/examples/core_ureq_client.rs

@@ -4,7 +4,7 @@
 use async_trait::async_trait;
 use azure_core::{
     error::ErrorKind,
-    http::{headers::Headers, BufResponse, ClientOptions, HttpClient, Request, Transport},
+    http::{headers::Headers, AsyncRawResponse, ClientOptions, HttpClient, Request, Transport},
 };
 use azure_identity::DeveloperToolsCredential;
 use azure_security_keyvault_secrets::{ResourceExt as _, SecretClient, SecretClientOptions};
@@ -35,7 +35,7 @@ impl Default for Agent {
 #[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
 #[cfg_attr(not(target_arch = "wasm32"), async_trait)]
 impl HttpClient for Agent {
-    async fn execute_request(&self, request: &Request) -> azure_core::Result<BufResponse> {
+    async fn execute_request(&self, request: &Request) -> azure_core::Result<AsyncRawResponse> {
         let request = into_request(request)?;
         let response = self
             .0
@@ -102,7 +102,7 @@ fn into_request(request: &Request) -> azure_core::Result<::http::Request<Vec<u8>
     Ok(req)
 }
 
-fn into_response(response: ::http::Response<ureq::Body>) -> azure_core::Result<BufResponse> {
+fn into_response(response: ::http::Response<ureq::Body>) -> azure_core::Result<AsyncRawResponse> {
     use ::http::response::Parts;
     use azure_core::http::StatusCode;
 
@@ -128,5 +128,5 @@ fn into_response(response: ::http::Response<ureq::Body>) -> azure_core::Result<B
         .read_to_vec()
         .with_context_fn(ErrorKind::Io, || "failed to read response body")?;
 
-    Ok(BufResponse::from_bytes(status, response_headers, body))
+    Ok(AsyncRawResponse::from_bytes(status, response_headers, body))
 }