feat(types): Add gRPC Richer Error Model support (RetryInfo) (#1095)

Add the code related to richer error model support to a new
`richer_error` module. This improves readability and hopefully will
make it easier to add new features to `tonic-types` in the future.

Author: flemosr

tonic-types/src/lib.rs

@@ -1,4 +1,6 @@
-use super::std_messages::{BadRequest, FieldViolation};
+use std::time;
+
+use super::std_messages::{BadRequest, FieldViolation, RetryInfo};
 
 pub(crate) mod vec;
 
@@ -9,6 +11,9 @@ pub(crate) mod vec;
 #[non_exhaustive]
 #[derive(Clone, Debug)]
 pub struct ErrorDetails {
+    /// This field stores [`RetryInfo`] data, if any.
+    pub(crate) retry_info: Option<RetryInfo>,
+
     /// This field stores [`BadRequest`] data, if any.
     pub(crate) bad_request: Option<BadRequest>,
 }
@@ -24,7 +29,28 @@ impl ErrorDetails {
     /// let err_details = ErrorDetails::new();
     /// ```
     pub fn new() -> Self {
-        ErrorDetails { bad_request: None }
+        ErrorDetails {
+            retry_info: None,
+            bad_request: None,
+        }
+    }
+
+    /// Generates an [`ErrorDetails`] struct with [`RetryInfo`] details and
+    /// remaining fields set to `None`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::time::Duration;
+    /// use tonic_types::{ErrorDetails};
+    ///
+    /// let err_details = ErrorDetails::with_retry_info(Some(Duration::from_secs(5)));
+    /// ```
+    pub fn with_retry_info(retry_delay: Option<time::Duration>) -> Self {
+        ErrorDetails {
+            retry_info: Some(RetryInfo::new(retry_delay)),
+            ..ErrorDetails::new()
+        }
     }
 
     /// Generates an [`ErrorDetails`] struct with [`BadRequest`] details and
@@ -70,11 +96,34 @@ impl ErrorDetails {
         }
     }
 
+    /// Get [`RetryInfo`] details, if any
+    pub fn retry_info(&self) -> Option<RetryInfo> {
+        self.retry_info.clone()
+    }
+
     /// Get [`BadRequest`] details, if any
     pub fn bad_request(&self) -> Option<BadRequest> {
         self.bad_request.clone()
     }
 
+    /// Set [`RetryInfo`] details. Can be chained with other `.set_` and
+    /// `.add_` [`ErrorDetails`] methods.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::time::Duration;
+    /// use tonic_types::{ErrorDetails};
+    ///
+    /// let mut err_details = ErrorDetails::new();
+    ///
+    /// err_details.set_retry_info(Some(Duration::from_secs(5)));
+    /// ```
+    pub fn set_retry_info(&mut self, retry_delay: Option<time::Duration>) -> &mut Self {
+        self.retry_info = Some(RetryInfo::new(retry_delay));
+        self
+    }
+
     /// Set [`BadRequest`] details. Can be chained with other `.set_` and
     /// `.add_` [`ErrorDetails`] methods.
     ///

tonic-types/src/error_details.rs tonic-types/src/richer_error/error_details/mod.rs

@@ -1,14 +1,23 @@
-use super::super::std_messages::BadRequest;
+use super::super::std_messages::{BadRequest, RetryInfo};
 
 /// Wraps the structs corresponding to the standard error messages, allowing
 /// the implementation and handling of vectors containing any of them.
 #[non_exhaustive]
 #[derive(Clone, Debug)]
 pub enum ErrorDetail {
+    /// Wraps the [`RetryInfo`] struct.
+    RetryInfo(RetryInfo),
+
     /// Wraps the [`BadRequest`] struct.
     BadRequest(BadRequest),
 }
 
+impl From<RetryInfo> for ErrorDetail {
+    fn from(err_detail: RetryInfo) -> Self {
+        ErrorDetail::RetryInfo(err_detail)
+    }
+}
+
 impl From<BadRequest> for ErrorDetail {
     fn from(err_detail: BadRequest) -> Self {
         ErrorDetail::BadRequest(err_detail)

tonic-types/src/error_details/vec.rs tonic-types/src/richer_error/error_details/vec.rs

@@ -1,8 +1,7 @@
 use prost::{DecodeError, Message};
 use prost_types::Any;
 
-use super::super::pb;
-use super::super::{FromAny, IntoAny};
+use super::super::{pb, FromAny, IntoAny};
 
 /// Used at the `field_violations` field of the [`BadRequest`] struct.
 /// Describes a single bad request field.

tonic-types/src/richer_error/mod.rs

@@ -1,3 +1,7 @@
+mod retry_info;
+
+pub use retry_info::RetryInfo;
+
 mod bad_request;
 
 pub use bad_request::{BadRequest, FieldViolation};

tonic-types/src/std_messages/bad_request.rs tonic-types/src/richer_error/std_messages/bad_request.rs

@@ -0,0 +1,150 @@
+use std::{convert::TryFrom, time};
+
+use prost::{DecodeError, Message};
+use prost_types::Any;
+
+use super::super::{pb, FromAny, IntoAny};
+
+/// Used to encode/decode the `RetryInfo` standard error message described in
+/// [error_details.proto]. Describes when the clients can retry a failed
+/// request.  
+/// Note: When obtained from decoding `RetryInfo` messages, negative
+/// `retry_delay`'s become 0.
+///
+/// [error_details.proto]: https://github.com/googleapis/googleapis/blob/master/google/rpc/error_details.proto
+#[derive(Clone, Debug)]
+pub struct RetryInfo {
+    /// Informs the amout of time that clients should wait before retrying.
+    pub retry_delay: Option<time::Duration>,
+}
+
+impl RetryInfo {
+    /// Type URL of the `RetryInfo` standard error message type.
+    pub const TYPE_URL: &'static str = "type.googleapis.com/google.rpc.RetryInfo";
+
+    /// Should not exceed `prost_types::Duration` range. Limited to
+    /// approximately 10,000 years.
+    pub const MAX_RETRY_DELAY: time::Duration = time::Duration::new(315_576_000_000, 999_999_999);
+
+    /// Creates a new [`RetryInfo`] struct. If `retry_delay` exceeds
+    /// [`RetryInfo::MAX_RETRY_DELAY`], [`RetryInfo::MAX_RETRY_DELAY`] will
+    /// be used instead.
+    pub fn new(retry_delay: Option<time::Duration>) -> Self {
+        let retry_delay = match retry_delay {
+            Some(mut delay) => {
+                if delay > RetryInfo::MAX_RETRY_DELAY {
+                    delay = RetryInfo::MAX_RETRY_DELAY
+                }
+                Some(delay)
+            }
+            None => None,
+        };
+
+        RetryInfo { retry_delay }
+    }
+}
+
+impl RetryInfo {
+    /// Returns `true` if [`RetryInfo`]'s `retry_delay` is set as `None`, and
+    /// `false` if it is not.
+    pub fn is_empty(&self) -> bool {
+        self.retry_delay.is_none()
+    }
+}
+
+impl IntoAny for RetryInfo {
+    fn into_any(self) -> Any {
+        let retry_delay = match self.retry_delay {
+            Some(duration) => {
+                // If duration is too large, uses max `prost_types::Duration`
+                let duration = match prost_types::Duration::try_from(duration) {
+                    Ok(duration) => duration,
+                    Err(_) => prost_types::Duration {
+                        seconds: 315_576_000_000,
+                        nanos: 999_999_999,
+                    },
+                };
+                Some(duration)
+            }
+            None => None,
+        };
+
+        let detail_data = pb::RetryInfo { retry_delay };
+
+        Any {
+            type_url: RetryInfo::TYPE_URL.to_string(),
+            value: detail_data.encode_to_vec(),
+        }
+    }
+}
+
+impl FromAny for RetryInfo {
+    fn from_any(any: Any) -> Result<Self, DecodeError> {
+        let buf: &[u8] = &any.value;
+        let retry_info = pb::RetryInfo::decode(buf)?;
+
+        let retry_delay = match retry_info.retry_delay {
+            Some(duration) => {
+                // Negative retry_delays become 0
+                let duration = time::Duration::try_from(duration).unwrap_or(time::Duration::ZERO);
+                Some(duration)
+            }
+            None => None,
+        };
+
+        let retry_info = RetryInfo { retry_delay };
+
+        Ok(retry_info)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use core::time::Duration;
+
+    use super::super::super::{FromAny, IntoAny};
+    use super::RetryInfo;
+
+    #[test]
+    fn gen_retry_info() {
+        let error_info = RetryInfo::new(Some(Duration::from_secs(u64::MAX)));
+
+        let formatted = format!("{:?}", error_info);
+
+        let expected_filled = "RetryInfo { retry_delay: Some(315576000000.999999999s) }";
+
+        assert!(
+            formatted.eq(expected_filled),
+            "filled RetryInfo differs from expected result"
+        );
+
+        assert!(
+            error_info.is_empty() == false,
+            "filled RetryInfo returns 'false' from .has_retry_delay()"
+        );
+
+        let gen_any = error_info.into_any();
+
+        let formatted = format!("{:?}", gen_any);
+
+        let expected =
+            "Any { type_url: \"type.googleapis.com/google.rpc.RetryInfo\", value: [10, 13, 8, 128, 188, 174, 206, 151, 9, 16, 255, 147, 235, 220, 3] }";
+
+        assert!(
+            formatted.eq(expected),
+            "Any from filled RetryInfo differs from expected result"
+        );
+
+        let br_details = match RetryInfo::from_any(gen_any) {
+            Err(error) => panic!("Error generating RetryInfo from Any: {:?}", error),
+            Ok(from_any) => from_any,
+        };
+
+        let formatted = format!("{:?}", br_details);
+
+        assert!(
+            formatted.eq(expected_filled),
+            "RetryInfo from Any differs from expected result"
+        );
+    }
+}