Make Error constructions consistent (#3024)

We had some inconsistency in construction functions, and many didn't
align to our guidelines. This essentially migrates a pattern I evolved
for my own Rust crates' template based more or less on what we had.

Author: heaths

sdk/core/azure_core/CHANGELOG.md

@@ -4,12 +4,23 @@
 
 ### Features Added
 
+- Added `Error::with_error_fn()`.
+
 ### Breaking Changes
 
 - Changed `ClientOptions::retry` from `Option<RetryOptions>` to `RetryOptions`.
 - Removed several unreferenced HTTP headers and accessor structures for those headers.
 - Renamed `TransportOptions` to `Transport`.
 - Renamed `TransportOptions::new_custom_policy()` to `Transport::with_policy()`.
+- Renamed a number of construction functions for `Error` to align with [guidelines](https://azure.github.io/azure-sdk/rust_introduction.html)"
+  - Renamed `Error::full()` to `Error::with_error()`.
+  - Renamed `Error::with_message()` to `Error::with_message_fn()`.
+  - Renamed `Error::message()` to `Error::with_message()`.
+  - Renamed `Error::with_context()` to `Error::with_context_fn()`.
+  - Renamed `Error::context()` to `Error::with_context()`.
+  - Renamed `ResultExt::map_kind()` to `ResultExt::with_kind()`.
+  - Renamed `ResultExt::with_context()` to `ResultExt::with_context_fn()`.
+  - Renamed `ResultExt::context()` to `ResultExt::with_context()`.
 
 ### Bugs Fixed
 

sdk/core/azure_core/README.md

@@ -512,7 +512,7 @@ impl HttpClient for Agent {
         let response = self
             .0
             .run(request)
-            .with_context(ErrorKind::Io, || "failed to send request")?;
+            .with_context_fn(ErrorKind::Io, || "failed to send request")?;
 
         Ok(todo!("convert their response into our response"))
     }

sdk/core/azure_core/benches/http_transport_benchmarks.rs

@@ -50,7 +50,7 @@ impl TestServiceClient {
         let options = options.unwrap_or_default();
         let mut endpoint = Url::parse(endpoint)?;
         if !endpoint.scheme().starts_with("http") {
-            return Err(azure_core::Error::message(
+            return Err(azure_core::Error::with_message(
                 azure_core::error::ErrorKind::Other,
                 format!("{endpoint} must use http(s)"),
             ));
@@ -99,7 +99,7 @@ impl TestServiceClient {
             .send(&options.method_options.context, &mut request)
             .await?;
         if !response.status().is_success() {
-            return Err(azure_core::Error::message(
+            return Err(azure_core::Error::with_message(
                 azure_core::error::ErrorKind::HttpResponse {
                     status: response.status(),
                     error_code: None,

sdk/core/azure_core/examples/core_ureq_client.rs

@@ -40,7 +40,7 @@ impl HttpClient for Agent {
         let response = self
             .0
             .run(request)
-            .with_context(ErrorKind::Io, || "failed to send request")?;
+            .with_context_fn(ErrorKind::Io, || "failed to send request")?;
 
         into_response(response)
     }
@@ -81,19 +81,19 @@ fn into_request(request: &Request) -> azure_core::Result<::http::Request<Vec<u8>
         .url()
         .as_str()
         .parse()
-        .with_context(ErrorKind::DataConversion, || "failed to parse url")?;
+        .with_context_fn(ErrorKind::DataConversion, || "failed to parse url")?;
     *req.method_mut() = request
         .method()
         .as_str()
         .parse()
-        .with_context(ErrorKind::DataConversion, || "failed to parse method")?;
+        .with_context_fn(ErrorKind::DataConversion, || "failed to parse method")?;
     let headers = req.headers_mut();
     for (name, value) in request.headers().iter() {
         headers.insert(
             HeaderName::from_bytes(name.as_str().as_bytes())
-                .with_context(ErrorKind::DataConversion, || "failed to parse header name")?,
+                .with_context_fn(ErrorKind::DataConversion, || "failed to parse header name")?,
             HeaderValue::from_bytes(value.as_str().as_bytes())
-                .with_context(ErrorKind::DataConversion, || "failed to parse header value")?,
+                .with_context_fn(ErrorKind::DataConversion, || "failed to parse header value")?,
         );
     }
     let body: Bytes = request.body().into();
@@ -120,13 +120,13 @@ fn into_response(response: ::http::Response<ureq::Body>) -> azure_core::Result<B
             name.as_str().to_ascii_lowercase(),
             value
                 .to_str()
-                .with_context(ErrorKind::DataConversion, || "failed to parse header value")?
+                .with_context_fn(ErrorKind::DataConversion, || "failed to parse header value")?
                 .to_string(),
         );
     }
     let body: Vec<u8> = body
         .read_to_vec()
-        .with_context(ErrorKind::Io, || "failed to read response body")?;
+        .with_context_fn(ErrorKind::Io, || "failed to read response body")?;
 
     Ok(BufResponse::from_bytes(status, response_headers, body))
 }

sdk/core/azure_core/src/error/error_response.rs

@@ -130,7 +130,7 @@ pub async fn check_success(response: BufResponse) -> crate::Result<BufResponse>
     if response.body().is_empty() {
         let code = response.headers().get_optional_str(&ERROR_CODE);
         let error_kind = ErrorKind::http_response(status, code.map(str::to_owned));
-        return Err(Error::message(error_kind, status.to_string()));
+        return Err(Error::with_message(error_kind, status.to_string()));
     }
     let internal_response =
         serde_json::de::from_slice::<ErrorResponseInternal>(response.body()).map_err(Error::from);
@@ -144,7 +144,7 @@ pub async fn check_success(response: BufResponse) -> crate::Result<BufResponse>
                 status,
                 Some(code.map_or_else(|| response.status().to_string(), str::to_owned)),
             );
-            return Err(Error::message(
+            return Err(Error::with_message(
                 error_kind,
                 format!(
                     "{}: {}",
@@ -161,7 +161,7 @@ pub async fn check_success(response: BufResponse) -> crate::Result<BufResponse>
 
     let error_kind = ErrorKind::http_response(status, code.map(str::to_owned));
 
-    Err(Error::message(
+    Err(Error::with_message(
         error_kind,
         internal_response
             .error

sdk/core/azure_core/src/hmac.rs

@@ -27,7 +27,7 @@ pub fn hmac_sha256(data: &str, key: &Secret) -> crate::Result<String> {
     use sha2::Sha256;
     let key = base64::decode(key.secret())?;
     let mut hmac = Hmac::<Sha256>::new_from_slice(&key)
-        .with_context(ErrorKind::DataConversion, || {
+        .with_context_fn(ErrorKind::DataConversion, || {
             "failed to create hmac from key"
         })?;
     hmac.update(data.as_bytes());
@@ -58,7 +58,7 @@ pub fn hmac_sha256(data: &str, key: &Secret) -> crate::Result<String> {
         signer.update(data.as_bytes())?;
         signer.sign_to_vec()
     }()
-    .with_context(ErrorKind::DataConversion, || {
+    .with_context_fn(ErrorKind::DataConversion, || {
         "failed to create hmac from key"
     })?;
     Ok(base64::encode(signature))

sdk/core/azure_core/src/http/pager.rs

@@ -749,7 +749,7 @@ mod tests {
                     .into(),
                     continuation: "1",
                 }),
-                PagerState::More("1") => Err(typespec::Error::message(
+                PagerState::More("1") => Err(typespec::Error::with_message(
                     typespec::error::ErrorKind::Other,
                     "yon request didst fail",
                 )),

sdk/core/azure_core/src/http/policies/bearer_token_policy.rs

@@ -120,7 +120,7 @@ impl Policy for BearerTokenCredentialPolicy {
         }
 
         let access_token = self.access_token().await.ok_or_else(|| {
-            Error::message(
+            Error::with_message(
                 ErrorKind::Credential,
                 "The request failed due to an error while fetching the access token.",
             )
@@ -200,7 +200,7 @@ mod tests {
             let i = self.calls.fetch_add(1, Ordering::SeqCst);
             self.tokens
                 .get(i)
-                .ok_or_else(|| Error::message(ErrorKind::Credential, "no more mock tokens"))
+                .ok_or_else(|| Error::with_message(ErrorKind::Credential, "no more mock tokens"))
                 .cloned()
         }
     }

sdk/core/azure_core/src/test.rs

@@ -63,7 +63,7 @@ impl FromStr for TestMode {
             "playback" => Ok(Self::Playback),
             "record" => Ok(Self::Record),
             "live" => Ok(Self::Live),
-            _ => Err(Error::message(
+            _ => Err(Error::with_message(
                 ErrorKind::DataConversion,
                 "expected 'playback', 'record', or 'live'",
             )),
@@ -106,7 +106,7 @@ impl FromStr for RecordingMode {
         match s.to_ascii_lowercase().as_str() {
             "playback" => Ok(Self::Playback),
             "record" => Ok(Self::Record),
-            _ => Err(Error::message(
+            _ => Err(Error::with_message(
                 ErrorKind::DataConversion,
                 "expected 'playback' or 'record'",
             )),

sdk/core/azure_core_amqp/src/fe2o3/cbs.rs

@@ -25,19 +25,19 @@ impl Fe2o3ClaimsBasedSecurity {
     }
 
     fn cbs_already_attached() -> azure_core::Error {
-        azure_core::Error::message(
+        azure_core::Error::with_message(
             azure_core::error::ErrorKind::Amqp,
             "Claims Based Security is already attached",
         )
     }
     fn cbs_not_set() -> azure_core::Error {
-        azure_core::Error::message(
+        azure_core::Error::with_message(
             azure_core::error::ErrorKind::Amqp,
             "Claims Based Security is not set",
         )
     }
     fn cbs_not_attached() -> azure_core::Error {
-        azure_core::Error::message(
+        azure_core::Error::with_message(
             azure_core::error::ErrorKind::Amqp,
             "Claims Based Security is not attached",
         )
@@ -97,7 +97,7 @@ impl AmqpClaimsBasedSecurityApis for Fe2o3ClaimsBasedSecurity {
                     .unix_timestamp()
                     .checked_mul(1_000)
                     .ok_or_else(|| {
-                        azure_core::Error::message(
+                        azure_core::Error::with_message(
                             azure_core::error::ErrorKind::Amqp,
                             "Unable to convert time to unix timestamp.",
                         )
@@ -116,7 +116,7 @@ impl AmqpClaimsBasedSecurityApis for Fe2o3ClaimsBasedSecurity {
                 Ok(amqp_error) => amqp_error.into(),
                 Err(e) => {
                     debug!("Failed to convert management error to azure error: {:?}", e);
-                    azure_core::Error::full(
+                    azure_core::Error::with_error(
                         azure_core::error::ErrorKind::Amqp,
                         e,
                         "Failed to convert management error to azure error.",