feat(types): Add gRPC Richer Error Model support (Help) (#1293)

* types: add support for `Help` error message type

Following implementation at flemosr/tonic-richer-error.

* types: add `ResourceInfo` to `gen_status_with_details` test

* types: use `impl Into<Vec<T>>` instead of `Vec<T>` in pub fn's params

* types: comply with clippy

* types: fix names of some tests and vars in `std_messages`
This commit is contained in:
Rafael Lemos
2023-02-23 08:24:19 -03:00
committed by GitHub
parent 7a6b20d8ef
commit d6041a99c2
14 changed files with 403 additions and 49 deletions
+1 -1
View File
@@ -46,7 +46,7 @@ pub use pb::Status;
mod richer_error;
pub use richer_error::{
BadRequest, DebugInfo, ErrorDetail, ErrorDetails, ErrorInfo, FieldViolation,
BadRequest, DebugInfo, ErrorDetail, ErrorDetails, ErrorInfo, FieldViolation, Help, HelpLink,
PreconditionFailure, PreconditionViolation, QuotaFailure, QuotaViolation, RequestInfo,
ResourceInfo, RetryInfo, StatusExt,
};
+113 -10
View File
@@ -1,8 +1,8 @@
use std::{collections::HashMap, time};
use super::std_messages::{
BadRequest, DebugInfo, ErrorInfo, FieldViolation, PreconditionFailure, PreconditionViolation,
QuotaFailure, QuotaViolation, RequestInfo, ResourceInfo, RetryInfo,
BadRequest, DebugInfo, ErrorInfo, FieldViolation, Help, HelpLink, PreconditionFailure,
PreconditionViolation, QuotaFailure, QuotaViolation, RequestInfo, ResourceInfo, RetryInfo,
};
pub(crate) mod vec;
@@ -37,6 +37,9 @@ pub struct ErrorDetails {
/// This field stores [`ResourceInfo`] data, if any.
pub(crate) resource_info: Option<ResourceInfo>,
/// This field stores [`Help`] data, if any.
pub(crate) help: Option<Help>,
}
impl ErrorDetails {
@@ -83,7 +86,10 @@ impl ErrorDetails {
///
/// let err_details = ErrorDetails::with_debug_info(err_stack, "error details");
/// ```
pub fn with_debug_info(stack_entries: Vec<String>, detail: impl Into<String>) -> Self {
pub fn with_debug_info(
stack_entries: impl Into<Vec<String>>,
detail: impl Into<String>,
) -> Self {
ErrorDetails {
debug_info: Some(DebugInfo::new(stack_entries, detail)),
..ErrorDetails::new()
@@ -103,7 +109,7 @@ impl ErrorDetails {
/// QuotaViolation::new("subject 2", "description 2"),
/// ]);
/// ```
pub fn with_quota_failure(violations: Vec<QuotaViolation>) -> Self {
pub fn with_quota_failure(violations: impl Into<Vec<QuotaViolation>>) -> Self {
ErrorDetails {
quota_failure: Some(QuotaFailure::new(violations)),
..ErrorDetails::new()
@@ -176,7 +182,7 @@ impl ErrorDetails {
/// ),
/// ]);
/// ```
pub fn with_precondition_failure(violations: Vec<PreconditionViolation>) -> Self {
pub fn with_precondition_failure(violations: impl Into<Vec<PreconditionViolation>>) -> Self {
ErrorDetails {
precondition_failure: Some(PreconditionFailure::new(violations)),
..ErrorDetails::new()
@@ -226,7 +232,7 @@ impl ErrorDetails {
/// FieldViolation::new("field_2", "description 2"),
/// ]);
/// ```
pub fn with_bad_request(field_violations: Vec<FieldViolation>) -> Self {
pub fn with_bad_request(field_violations: impl Into<Vec<FieldViolation>>) -> Self {
ErrorDetails {
bad_request: Some(BadRequest::new(field_violations)),
..ErrorDetails::new()
@@ -311,6 +317,26 @@ impl ErrorDetails {
}
}
/// Generates an [`ErrorDetails`] struct with [`Help`] details and
/// remaining fields set to `None`.
///
/// # Examples
///
/// ```
/// use tonic_types::{ErrorDetails, HelpLink};
///
/// let err_details = ErrorDetails::with_help(vec![
/// HelpLink::new("description of link a", "resource-a.example.local"),
/// HelpLink::new("description of link b", "resource-b.example.local"),
/// ]);
/// ```
pub fn with_help(links: impl Into<Vec<HelpLink>>) -> Self {
ErrorDetails {
help: Some(Help::new(links)),
..ErrorDetails::new()
}
}
/// Get [`RetryInfo`] details, if any.
pub fn retry_info(&self) -> Option<RetryInfo> {
self.retry_info.clone()
@@ -351,6 +377,11 @@ impl ErrorDetails {
self.resource_info.clone()
}
/// Get [`Help`] details, if any.
pub fn help(&self) -> Option<Help> {
self.help.clone()
}
/// Set [`RetryInfo`] details. Can be chained with other `.set_` and
/// `.add_` [`ErrorDetails`] methods.
///
@@ -385,7 +416,7 @@ impl ErrorDetails {
/// ```
pub fn set_debug_info(
&mut self,
stack_entries: Vec<String>,
stack_entries: impl Into<Vec<String>>,
detail: impl Into<String>,
) -> &mut Self {
self.debug_info = Some(DebugInfo::new(stack_entries, detail));
@@ -407,7 +438,7 @@ impl ErrorDetails {
/// QuotaViolation::new("subject 2", "description 2"),
/// ]);
/// ```
pub fn set_quota_failure(&mut self, violations: Vec<QuotaViolation>) -> &mut Self {
pub fn set_quota_failure(&mut self, violations: impl Into<Vec<QuotaViolation>>) -> &mut Self {
self.quota_failure = Some(QuotaFailure::new(violations));
self
}
@@ -515,7 +546,7 @@ impl ErrorDetails {
/// ```
pub fn set_precondition_failure(
&mut self,
violations: Vec<PreconditionViolation>,
violations: impl Into<Vec<PreconditionViolation>>,
) -> &mut Self {
self.precondition_failure = Some(PreconditionFailure::new(violations));
self
@@ -601,7 +632,7 @@ impl ErrorDetails {
/// FieldViolation::new("field_2", "description 2"),
/// ]);
/// ```
pub fn set_bad_request(&mut self, violations: Vec<FieldViolation>) -> &mut Self {
pub fn set_bad_request(&mut self, violations: impl Into<Vec<FieldViolation>>) -> &mut Self {
self.bad_request = Some(BadRequest::new(violations));
self
}
@@ -706,4 +737,76 @@ impl ErrorDetails {
));
self
}
/// Set [`Help`] details. Can be chained with other `.set_` and `.add_`
/// [`ErrorDetails`] methods.
///
/// # Examples
///
/// ```
/// use tonic_types::{ErrorDetails, HelpLink};
///
/// let mut err_details = ErrorDetails::new();
///
/// err_details.set_help(vec![
/// HelpLink::new("description of link a", "resource-a.example.local"),
/// HelpLink::new("description of link b", "resource-b.example.local"),
/// ]);
/// ```
pub fn set_help(&mut self, links: impl Into<Vec<HelpLink>>) -> &mut Self {
self.help = Some(Help::new(links));
self
}
/// Adds a [`HelpLink`] to [`Help`] details. Sets [`Help`] details if it is
/// not set yet. Can be chained with other `.set_` and `.add_`
/// [`ErrorDetails`] methods.
///
/// # Examples
///
/// ```
/// use tonic_types::ErrorDetails;
///
/// let mut err_details = ErrorDetails::new();
///
/// err_details.add_help_link("description of link", "resource.example.local");
/// ```
pub fn add_help_link(
&mut self,
description: impl Into<String>,
url: impl Into<String>,
) -> &mut Self {
match &mut self.help {
Some(help) => {
help.add_link(description, url);
}
None => {
self.help = Some(Help::with_link(description, url));
}
};
self
}
/// Returns `true` if [`Help`] is set and its `links` vector is not empty,
/// otherwise returns `false`.
///
/// # Examples
///
/// ```
/// use tonic_types::ErrorDetails;
///
/// let mut err_details = ErrorDetails::with_help(vec![]);
///
/// assert_eq!(err_details.has_help_links(), false);
///
/// err_details.add_help_link("description of link", "resource.example.local");
///
/// assert_eq!(err_details.has_help_links(), true);
/// ```
pub fn has_help_links(&self) -> bool {
if let Some(help) = &self.help {
return !help.links.is_empty();
}
false
}
}
@@ -1,6 +1,6 @@
use super::super::std_messages::{
BadRequest, DebugInfo, ErrorInfo, PreconditionFailure, QuotaFailure, RequestInfo, ResourceInfo,
RetryInfo,
BadRequest, DebugInfo, ErrorInfo, Help, PreconditionFailure, QuotaFailure, RequestInfo,
ResourceInfo, RetryInfo,
};
/// Wraps the structs corresponding to the standard error messages, allowing
@@ -31,6 +31,9 @@ pub enum ErrorDetail {
/// Wraps the [`ResourceInfo`] struct.
ResourceInfo(ResourceInfo),
/// Wraps the [`Help`] struct.
Help(Help),
}
impl From<RetryInfo> for ErrorDetail {
@@ -80,3 +83,9 @@ impl From<ResourceInfo> for ErrorDetail {
ErrorDetail::ResourceInfo(err_detail)
}
}
impl From<Help> for ErrorDetail {
fn from(err_detail: Help) -> Self {
ErrorDetail::Help(err_detail)
}
}
+58 -5
View File
@@ -12,8 +12,8 @@ use super::pb;
pub use error_details::{vec::ErrorDetail, ErrorDetails};
pub use std_messages::{
BadRequest, DebugInfo, ErrorInfo, FieldViolation, PreconditionFailure, PreconditionViolation,
QuotaFailure, QuotaViolation, RequestInfo, ResourceInfo, RetryInfo,
BadRequest, DebugInfo, ErrorInfo, FieldViolation, Help, HelpLink, PreconditionFailure,
PreconditionViolation, QuotaFailure, QuotaViolation, RequestInfo, ResourceInfo, RetryInfo,
};
trait IntoAny {
@@ -424,6 +424,28 @@ pub trait StatusExt: crate::sealed::Sealed {
/// }
/// ```
fn get_details_resource_info(&self) -> Option<ResourceInfo>;
/// Get first [`Help`] details found on `tonic::Status`, if any. If some
/// `prost::DecodeError` occurs, returns `None`.
///
/// # Examples
///
/// ```
/// use tonic::{Status, Response};
/// use tonic_types::StatusExt;
///
/// fn handle_request_result<T>(req_result: Result<Response<T>, Status>) {
/// match req_result {
/// Ok(_) => {},
/// Err(status) => {
/// if let Some(help) = status.get_details_help() {
/// // Handle help details
/// }
/// }
/// };
/// }
/// ```
fn get_details_help(&self) -> Option<Help>;
}
impl crate::sealed::Sealed for tonic::Status {}
@@ -471,6 +493,10 @@ impl StatusExt for tonic::Status {
conv_details.push(resource_info.into_any());
}
if let Some(help) = details.help {
conv_details.push(help.into_any());
}
let details = gen_details_bytes(code, &message, conv_details);
tonic::Status::with_details_and_metadata(code, message, details, metadata)
@@ -516,6 +542,9 @@ impl StatusExt for tonic::Status {
ErrorDetail::ResourceInfo(res_info) => {
conv_details.push(res_info.into_any());
}
ErrorDetail::Help(help) => {
conv_details.push(help.into_any());
}
}
}
@@ -568,6 +597,9 @@ impl StatusExt for tonic::Status {
ResourceInfo::TYPE_URL => {
details.resource_info = Some(ResourceInfo::from_any(any)?);
}
Help::TYPE_URL => {
details.help = Some(Help::from_any(any)?);
}
_ => {}
}
}
@@ -610,6 +642,9 @@ impl StatusExt for tonic::Status {
ResourceInfo::TYPE_URL => {
details.push(ResourceInfo::from_any(any)?.into());
}
Help::TYPE_URL => {
details.push(Help::from_any(any)?.into());
}
_ => {}
}
}
@@ -732,6 +767,20 @@ impl StatusExt for tonic::Status {
None
}
fn get_details_help(&self) -> Option<Help> {
let status = pb::Status::decode(self.details()).ok()?;
for any in status.details.into_iter() {
if any.type_url.as_str() == Help::TYPE_URL {
if let Ok(detail) = Help::from_any(any) {
return Some(detail);
}
}
}
None
}
}
#[cfg(test)]
@@ -740,8 +789,8 @@ mod tests {
use tonic::{Code, Status};
use super::{
BadRequest, DebugInfo, ErrorDetails, ErrorInfo, PreconditionFailure, QuotaFailure,
RequestInfo, RetryInfo, StatusExt,
BadRequest, DebugInfo, ErrorDetails, ErrorInfo, Help, PreconditionFailure, QuotaFailure,
RequestInfo, ResourceInfo, RetryInfo, StatusExt,
};
#[test]
@@ -761,7 +810,9 @@ mod tests {
.set_error_info("SOME_INFO", "example.local", metadata.clone())
.add_precondition_failure_violation("TOS", "example.local", "description")
.add_bad_request_violation("field", "description")
.set_request_info("request-id", "some-request-data");
.set_request_info("request-id", "some-request-data")
.set_resource_info("resource-type", "resource-name", "owner", "description")
.add_help_link("link to resource", "resource.example.local");
let fmt_details = format!("{:?}", err_details);
@@ -777,6 +828,8 @@ mod tests {
PreconditionFailure::with_violation("TOS", "example.local", "description").into(),
BadRequest::with_violation("field", "description").into(),
RequestInfo::new("request-id", "some-request-data").into(),
ResourceInfo::new("resource-type", "resource-name", "owner", "description").into(),
Help::with_link("link to resource", "resource.example.local").into(),
];
let fmt_details_vec = format!("{:?}", err_details_vec);
@@ -42,8 +42,10 @@ impl BadRequest {
pub const TYPE_URL: &'static str = "type.googleapis.com/google.rpc.BadRequest";
/// Creates a new [`BadRequest`] struct.
pub fn new(field_violations: Vec<FieldViolation>) -> Self {
BadRequest { field_violations }
pub fn new(field_violations: impl Into<Vec<FieldViolation>>) -> Self {
BadRequest {
field_violations: field_violations.into(),
}
}
/// Creates a new [`BadRequest`] struct with a single [`FieldViolation`] in
@@ -21,9 +21,9 @@ impl DebugInfo {
pub const TYPE_URL: &'static str = "type.googleapis.com/google.rpc.DebugInfo";
/// Creates a new [`DebugInfo`] struct.
pub fn new(stack_entries: Vec<String>, detail: impl Into<String>) -> Self {
pub fn new(stack_entries: impl Into<Vec<String>>, detail: impl Into<String>) -> Self {
DebugInfo {
stack_entries,
stack_entries: stack_entries.into(),
detail: detail.into(),
}
}
@@ -69,15 +69,15 @@ impl IntoAny for ErrorInfo {
impl FromAny for ErrorInfo {
fn from_any(any: Any) -> Result<Self, DecodeError> {
let buf: &[u8] = &any.value;
let debug_info = pb::ErrorInfo::decode(buf)?;
let error_info = pb::ErrorInfo::decode(buf)?;
let debug_info = ErrorInfo {
reason: debug_info.reason,
domain: debug_info.domain,
metadata: debug_info.metadata,
let error_info = ErrorInfo {
reason: error_info.reason,
domain: error_info.domain,
metadata: error_info.metadata,
};
Ok(debug_info)
Ok(error_info)
}
}
@@ -0,0 +1,180 @@
use prost::{DecodeError, Message};
use prost_types::Any;
use super::super::{pb, FromAny, IntoAny};
/// Used at the `links` field of the [`Help`] struct. Describes a URL link.
#[derive(Clone, Debug)]
pub struct HelpLink {
/// Description of what the link offers.
pub description: String,
/// URL of the link.
pub url: String,
}
impl HelpLink {
/// Creates a new [`HelpLink`] struct.
pub fn new(description: impl Into<String>, url: impl Into<String>) -> Self {
HelpLink {
description: description.into(),
url: url.into(),
}
}
}
/// Used to encode/decode the `Help` standard error message described in
/// [error_details.proto]. Provides links to documentation or for performing
/// an out-of-band action.
///
/// [error_details.proto]: https://github.com/googleapis/googleapis/blob/master/google/rpc/error_details.proto
#[derive(Clone, Debug)]
pub struct Help {
/// Links pointing to additional information on how to handle the error.
pub links: Vec<HelpLink>,
}
impl Help {
/// Type URL of the `Help` standard error message type.
pub const TYPE_URL: &'static str = "type.googleapis.com/google.rpc.Help";
/// Creates a new [`Help`] struct.
pub fn new(links: impl Into<Vec<HelpLink>>) -> Self {
Help {
links: links.into(),
}
}
/// Creates a new [`Help`] struct with a single [`HelpLink`] in `links`.
pub fn with_link(description: impl Into<String>, url: impl Into<String>) -> Self {
Help {
links: vec![HelpLink {
description: description.into(),
url: url.into(),
}],
}
}
/// Adds a [`HelpLink`] to [`Help`]'s `links` vector.
pub fn add_link(
&mut self,
description: impl Into<String>,
url: impl Into<String>,
) -> &mut Self {
self.links.append(&mut vec![HelpLink {
description: description.into(),
url: url.into(),
}]);
self
}
/// Returns `true` if [`Help`]'s `links` vector is empty, and `false` if it
/// is not.
pub fn is_empty(&self) -> bool {
self.links.is_empty()
}
}
impl IntoAny for Help {
fn into_any(self) -> Any {
let detail_data = pb::Help {
links: self
.links
.into_iter()
.map(|v| pb::help::Link {
description: v.description,
url: v.url,
})
.collect(),
};
Any {
type_url: Help::TYPE_URL.to_string(),
value: detail_data.encode_to_vec(),
}
}
}
impl FromAny for Help {
fn from_any(any: Any) -> Result<Self, DecodeError> {
let buf: &[u8] = &any.value;
let help = pb::Help::decode(buf)?;
let help = Help {
links: help
.links
.into_iter()
.map(|v| HelpLink {
description: v.description,
url: v.url,
})
.collect(),
};
Ok(help)
}
}
#[cfg(test)]
mod tests {
use super::super::super::{FromAny, IntoAny};
use super::Help;
#[test]
fn gen_help() {
let mut help = Help::new(Vec::new());
let formatted = format!("{:?}", help);
let expected = "Help { links: [] }";
assert!(
formatted.eq(expected),
"empty Help differs from expected result"
);
assert!(
help.is_empty(),
"empty Help returns 'false' from .is_empty()"
);
help.add_link("link to resource a", "resource-a.example.local")
.add_link("link to resource b", "resource-b.example.local");
let formatted = format!("{:?}", help);
let expected_filled = "Help { links: [HelpLink { description: \"link to resource a\", url: \"resource-a.example.local\" }, HelpLink { description: \"link to resource b\", url: \"resource-b.example.local\" }] }";
assert!(
formatted.eq(expected_filled),
"filled Help differs from expected result"
);
assert!(
!help.is_empty(),
"filled Help returns 'true' from .is_empty()"
);
let gen_any = help.into_any();
let formatted = format!("{:?}", gen_any);
let expected = "Any { type_url: \"type.googleapis.com/google.rpc.Help\", value: [10, 46, 10, 18, 108, 105, 110, 107, 32, 116, 111, 32, 114, 101, 115, 111, 117, 114, 99, 101, 32, 97, 18, 24, 114, 101, 115, 111, 117, 114, 99, 101, 45, 97, 46, 101, 120, 97, 109, 112, 108, 101, 46, 108, 111, 99, 97, 108, 10, 46, 10, 18, 108, 105, 110, 107, 32, 116, 111, 32, 114, 101, 115, 111, 117, 114, 99, 101, 32, 98, 18, 24, 114, 101, 115, 111, 117, 114, 99, 101, 45, 98, 46, 101, 120, 97, 109, 112, 108, 101, 46, 108, 111, 99, 97, 108] }";
assert!(
formatted.eq(expected),
"Any from filled Help differs from expected result"
);
let br_details = match Help::from_any(gen_any) {
Err(error) => panic!("Error generating Help from Any: {:?}", error),
Ok(from_any) => from_any,
};
let formatted = format!("{:?}", br_details);
assert!(
formatted.eq(expected_filled),
"Help from Any differs from expected result"
);
}
}
@@ -29,3 +29,7 @@ pub use request_info::RequestInfo;
mod resource_info;
pub use resource_info::ResourceInfo;
mod help;
pub use help::{Help, HelpLink};
@@ -52,8 +52,10 @@ impl PreconditionFailure {
pub const TYPE_URL: &'static str = "type.googleapis.com/google.rpc.PreconditionFailure";
/// Creates a new [`PreconditionFailure`] struct.
pub fn new(violations: Vec<PreconditionViolation>) -> Self {
PreconditionFailure { violations }
pub fn new(violations: impl Into<Vec<PreconditionViolation>>) -> Self {
PreconditionFailure {
violations: violations.into(),
}
}
/// Creates a new [`PreconditionFailure`] struct with a single
@@ -39,8 +39,10 @@ impl QuotaFailure {
pub const TYPE_URL: &'static str = "type.googleapis.com/google.rpc.QuotaFailure";
/// Creates a new [`QuotaFailure`] struct.
pub fn new(violations: Vec<QuotaViolation>) -> Self {
QuotaFailure { violations }
pub fn new(violations: impl Into<Vec<QuotaViolation>>) -> Self {
QuotaFailure {
violations: violations.into(),
}
}
/// Creates a new [`QuotaFailure`] struct with a single [`QuotaViolation`]
@@ -57,12 +57,12 @@ impl FromAny for RequestInfo {
let buf: &[u8] = &any.value;
let req_info = pb::RequestInfo::decode(buf)?;
let debug_info = RequestInfo {
let req_info = RequestInfo {
request_id: req_info.request_id,
serving_data: req_info.serving_data,
};
Ok(debug_info)
Ok(req_info)
}
}
@@ -72,10 +72,10 @@ mod tests {
use super::RequestInfo;
#[test]
fn gen_error_info() {
let error_info = RequestInfo::new("some-id", "some-data");
fn gen_request_info() {
let req_info = RequestInfo::new("some-id", "some-data");
let formatted = format!("{:?}", error_info);
let formatted = format!("{:?}", req_info);
let expected_filled =
"RequestInfo { request_id: \"some-id\", serving_data: \"some-data\" }";
@@ -85,7 +85,7 @@ mod tests {
"filled RequestInfo differs from expected result"
);
let gen_any = error_info.into_any();
let gen_any = req_info.into_any();
let formatted = format!("{:?}", gen_any);
@@ -72,14 +72,14 @@ impl FromAny for ResourceInfo {
let buf: &[u8] = &any.value;
let res_info = pb::ResourceInfo::decode(buf)?;
let debug_info = ResourceInfo {
let res_info = ResourceInfo {
resource_type: res_info.resource_type,
resource_name: res_info.resource_name,
owner: res_info.owner,
description: res_info.description,
};
Ok(debug_info)
Ok(res_info)
}
}
@@ -89,11 +89,10 @@ mod tests {
use super::ResourceInfo;
#[test]
fn gen_error_info() {
let error_info =
ResourceInfo::new("resource-type", "resource-name", "owner", "description");
fn gen_resource_info() {
let res_info = ResourceInfo::new("resource-type", "resource-name", "owner", "description");
let formatted = format!("{:?}", error_info);
let formatted = format!("{:?}", res_info);
let expected_filled = "ResourceInfo { resource_type: \"resource-type\", resource_name: \"resource-name\", owner: \"owner\", description: \"description\" }";
@@ -102,7 +101,7 @@ mod tests {
"filled ResourceInfo differs from expected result"
);
let gen_any = error_info.into_any();
let gen_any = res_info.into_any();
let formatted = format!("{:?}", gen_any);
@@ -105,9 +105,9 @@ mod tests {
#[test]
fn gen_retry_info() {
let error_info = RetryInfo::new(Some(Duration::from_secs(u64::MAX)));
let retry_info = RetryInfo::new(Some(Duration::from_secs(u64::MAX)));
let formatted = format!("{:?}", error_info);
let formatted = format!("{:?}", retry_info);
let expected_filled = "RetryInfo { retry_delay: Some(315576000000.999999999s) }";
@@ -117,11 +117,11 @@ mod tests {
);
assert!(
!error_info.is_empty(),
!retry_info.is_empty(),
"filled RetryInfo returns 'false' from .has_retry_delay()"
);
let gen_any = error_info.into_any();
let gen_any = retry_info.into_any();
let formatted = format!("{:?}", gen_any);