Skip to content

Commit d6041a9

Browse files
authored
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`
1 parent 7a6b20d commit d6041a9

File tree

14 files changed

+403
-49
lines changed

14 files changed

+403
-49
lines changed

tonic-types/src/lib.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ pub use pb::Status;
4646
mod richer_error;
4747

4848
pub use richer_error::{
49-
BadRequest, DebugInfo, ErrorDetail, ErrorDetails, ErrorInfo, FieldViolation,
49+
BadRequest, DebugInfo, ErrorDetail, ErrorDetails, ErrorInfo, FieldViolation, Help, HelpLink,
5050
PreconditionFailure, PreconditionViolation, QuotaFailure, QuotaViolation, RequestInfo,
5151
ResourceInfo, RetryInfo, StatusExt,
5252
};

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

+113-10
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
use std::{collections::HashMap, time};
22

33
use super::std_messages::{
4-
BadRequest, DebugInfo, ErrorInfo, FieldViolation, PreconditionFailure, PreconditionViolation,
5-
QuotaFailure, QuotaViolation, RequestInfo, ResourceInfo, RetryInfo,
4+
BadRequest, DebugInfo, ErrorInfo, FieldViolation, Help, HelpLink, PreconditionFailure,
5+
PreconditionViolation, QuotaFailure, QuotaViolation, RequestInfo, ResourceInfo, RetryInfo,
66
};
77

88
pub(crate) mod vec;
@@ -37,6 +37,9 @@ pub struct ErrorDetails {
3737

3838
/// This field stores [`ResourceInfo`] data, if any.
3939
pub(crate) resource_info: Option<ResourceInfo>,
40+
41+
/// This field stores [`Help`] data, if any.
42+
pub(crate) help: Option<Help>,
4043
}
4144

4245
impl ErrorDetails {
@@ -83,7 +86,10 @@ impl ErrorDetails {
8386
///
8487
/// let err_details = ErrorDetails::with_debug_info(err_stack, "error details");
8588
/// ```
86-
pub fn with_debug_info(stack_entries: Vec<String>, detail: impl Into<String>) -> Self {
89+
pub fn with_debug_info(
90+
stack_entries: impl Into<Vec<String>>,
91+
detail: impl Into<String>,
92+
) -> Self {
8793
ErrorDetails {
8894
debug_info: Some(DebugInfo::new(stack_entries, detail)),
8995
..ErrorDetails::new()
@@ -103,7 +109,7 @@ impl ErrorDetails {
103109
/// QuotaViolation::new("subject 2", "description 2"),
104110
/// ]);
105111
/// ```
106-
pub fn with_quota_failure(violations: Vec<QuotaViolation>) -> Self {
112+
pub fn with_quota_failure(violations: impl Into<Vec<QuotaViolation>>) -> Self {
107113
ErrorDetails {
108114
quota_failure: Some(QuotaFailure::new(violations)),
109115
..ErrorDetails::new()
@@ -176,7 +182,7 @@ impl ErrorDetails {
176182
/// ),
177183
/// ]);
178184
/// ```
179-
pub fn with_precondition_failure(violations: Vec<PreconditionViolation>) -> Self {
185+
pub fn with_precondition_failure(violations: impl Into<Vec<PreconditionViolation>>) -> Self {
180186
ErrorDetails {
181187
precondition_failure: Some(PreconditionFailure::new(violations)),
182188
..ErrorDetails::new()
@@ -226,7 +232,7 @@ impl ErrorDetails {
226232
/// FieldViolation::new("field_2", "description 2"),
227233
/// ]);
228234
/// ```
229-
pub fn with_bad_request(field_violations: Vec<FieldViolation>) -> Self {
235+
pub fn with_bad_request(field_violations: impl Into<Vec<FieldViolation>>) -> Self {
230236
ErrorDetails {
231237
bad_request: Some(BadRequest::new(field_violations)),
232238
..ErrorDetails::new()
@@ -311,6 +317,26 @@ impl ErrorDetails {
311317
}
312318
}
313319

320+
/// Generates an [`ErrorDetails`] struct with [`Help`] details and
321+
/// remaining fields set to `None`.
322+
///
323+
/// # Examples
324+
///
325+
/// ```
326+
/// use tonic_types::{ErrorDetails, HelpLink};
327+
///
328+
/// let err_details = ErrorDetails::with_help(vec![
329+
/// HelpLink::new("description of link a", "resource-a.example.local"),
330+
/// HelpLink::new("description of link b", "resource-b.example.local"),
331+
/// ]);
332+
/// ```
333+
pub fn with_help(links: impl Into<Vec<HelpLink>>) -> Self {
334+
ErrorDetails {
335+
help: Some(Help::new(links)),
336+
..ErrorDetails::new()
337+
}
338+
}
339+
314340
/// Get [`RetryInfo`] details, if any.
315341
pub fn retry_info(&self) -> Option<RetryInfo> {
316342
self.retry_info.clone()
@@ -351,6 +377,11 @@ impl ErrorDetails {
351377
self.resource_info.clone()
352378
}
353379

380+
/// Get [`Help`] details, if any.
381+
pub fn help(&self) -> Option<Help> {
382+
self.help.clone()
383+
}
384+
354385
/// Set [`RetryInfo`] details. Can be chained with other `.set_` and
355386
/// `.add_` [`ErrorDetails`] methods.
356387
///
@@ -385,7 +416,7 @@ impl ErrorDetails {
385416
/// ```
386417
pub fn set_debug_info(
387418
&mut self,
388-
stack_entries: Vec<String>,
419+
stack_entries: impl Into<Vec<String>>,
389420
detail: impl Into<String>,
390421
) -> &mut Self {
391422
self.debug_info = Some(DebugInfo::new(stack_entries, detail));
@@ -407,7 +438,7 @@ impl ErrorDetails {
407438
/// QuotaViolation::new("subject 2", "description 2"),
408439
/// ]);
409440
/// ```
410-
pub fn set_quota_failure(&mut self, violations: Vec<QuotaViolation>) -> &mut Self {
441+
pub fn set_quota_failure(&mut self, violations: impl Into<Vec<QuotaViolation>>) -> &mut Self {
411442
self.quota_failure = Some(QuotaFailure::new(violations));
412443
self
413444
}
@@ -515,7 +546,7 @@ impl ErrorDetails {
515546
/// ```
516547
pub fn set_precondition_failure(
517548
&mut self,
518-
violations: Vec<PreconditionViolation>,
549+
violations: impl Into<Vec<PreconditionViolation>>,
519550
) -> &mut Self {
520551
self.precondition_failure = Some(PreconditionFailure::new(violations));
521552
self
@@ -601,7 +632,7 @@ impl ErrorDetails {
601632
/// FieldViolation::new("field_2", "description 2"),
602633
/// ]);
603634
/// ```
604-
pub fn set_bad_request(&mut self, violations: Vec<FieldViolation>) -> &mut Self {
635+
pub fn set_bad_request(&mut self, violations: impl Into<Vec<FieldViolation>>) -> &mut Self {
605636
self.bad_request = Some(BadRequest::new(violations));
606637
self
607638
}
@@ -706,4 +737,76 @@ impl ErrorDetails {
706737
));
707738
self
708739
}
740+
741+
/// Set [`Help`] details. Can be chained with other `.set_` and `.add_`
742+
/// [`ErrorDetails`] methods.
743+
///
744+
/// # Examples
745+
///
746+
/// ```
747+
/// use tonic_types::{ErrorDetails, HelpLink};
748+
///
749+
/// let mut err_details = ErrorDetails::new();
750+
///
751+
/// err_details.set_help(vec![
752+
/// HelpLink::new("description of link a", "resource-a.example.local"),
753+
/// HelpLink::new("description of link b", "resource-b.example.local"),
754+
/// ]);
755+
/// ```
756+
pub fn set_help(&mut self, links: impl Into<Vec<HelpLink>>) -> &mut Self {
757+
self.help = Some(Help::new(links));
758+
self
759+
}
760+
761+
/// Adds a [`HelpLink`] to [`Help`] details. Sets [`Help`] details if it is
762+
/// not set yet. Can be chained with other `.set_` and `.add_`
763+
/// [`ErrorDetails`] methods.
764+
///
765+
/// # Examples
766+
///
767+
/// ```
768+
/// use tonic_types::ErrorDetails;
769+
///
770+
/// let mut err_details = ErrorDetails::new();
771+
///
772+
/// err_details.add_help_link("description of link", "resource.example.local");
773+
/// ```
774+
pub fn add_help_link(
775+
&mut self,
776+
description: impl Into<String>,
777+
url: impl Into<String>,
778+
) -> &mut Self {
779+
match &mut self.help {
780+
Some(help) => {
781+
help.add_link(description, url);
782+
}
783+
None => {
784+
self.help = Some(Help::with_link(description, url));
785+
}
786+
};
787+
self
788+
}
789+
790+
/// Returns `true` if [`Help`] is set and its `links` vector is not empty,
791+
/// otherwise returns `false`.
792+
///
793+
/// # Examples
794+
///
795+
/// ```
796+
/// use tonic_types::ErrorDetails;
797+
///
798+
/// let mut err_details = ErrorDetails::with_help(vec![]);
799+
///
800+
/// assert_eq!(err_details.has_help_links(), false);
801+
///
802+
/// err_details.add_help_link("description of link", "resource.example.local");
803+
///
804+
/// assert_eq!(err_details.has_help_links(), true);
805+
/// ```
806+
pub fn has_help_links(&self) -> bool {
807+
if let Some(help) = &self.help {
808+
return !help.links.is_empty();
809+
}
810+
false
811+
}
709812
}

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

+11-2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
use super::super::std_messages::{
2-
BadRequest, DebugInfo, ErrorInfo, PreconditionFailure, QuotaFailure, RequestInfo, ResourceInfo,
3-
RetryInfo,
2+
BadRequest, DebugInfo, ErrorInfo, Help, PreconditionFailure, QuotaFailure, RequestInfo,
3+
ResourceInfo, RetryInfo,
44
};
55

66
/// Wraps the structs corresponding to the standard error messages, allowing
@@ -31,6 +31,9 @@ pub enum ErrorDetail {
3131

3232
/// Wraps the [`ResourceInfo`] struct.
3333
ResourceInfo(ResourceInfo),
34+
35+
/// Wraps the [`Help`] struct.
36+
Help(Help),
3437
}
3538

3639
impl From<RetryInfo> for ErrorDetail {
@@ -80,3 +83,9 @@ impl From<ResourceInfo> for ErrorDetail {
8083
ErrorDetail::ResourceInfo(err_detail)
8184
}
8285
}
86+
87+
impl From<Help> for ErrorDetail {
88+
fn from(err_detail: Help) -> Self {
89+
ErrorDetail::Help(err_detail)
90+
}
91+
}

tonic-types/src/richer_error/mod.rs

+58-5
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,8 @@ use super::pb;
1212

1313
pub use error_details::{vec::ErrorDetail, ErrorDetails};
1414
pub use std_messages::{
15-
BadRequest, DebugInfo, ErrorInfo, FieldViolation, PreconditionFailure, PreconditionViolation,
16-
QuotaFailure, QuotaViolation, RequestInfo, ResourceInfo, RetryInfo,
15+
BadRequest, DebugInfo, ErrorInfo, FieldViolation, Help, HelpLink, PreconditionFailure,
16+
PreconditionViolation, QuotaFailure, QuotaViolation, RequestInfo, ResourceInfo, RetryInfo,
1717
};
1818

1919
trait IntoAny {
@@ -424,6 +424,28 @@ pub trait StatusExt: crate::sealed::Sealed {
424424
/// }
425425
/// ```
426426
fn get_details_resource_info(&self) -> Option<ResourceInfo>;
427+
428+
/// Get first [`Help`] details found on `tonic::Status`, if any. If some
429+
/// `prost::DecodeError` occurs, returns `None`.
430+
///
431+
/// # Examples
432+
///
433+
/// ```
434+
/// use tonic::{Status, Response};
435+
/// use tonic_types::StatusExt;
436+
///
437+
/// fn handle_request_result<T>(req_result: Result<Response<T>, Status>) {
438+
/// match req_result {
439+
/// Ok(_) => {},
440+
/// Err(status) => {
441+
/// if let Some(help) = status.get_details_help() {
442+
/// // Handle help details
443+
/// }
444+
/// }
445+
/// };
446+
/// }
447+
/// ```
448+
fn get_details_help(&self) -> Option<Help>;
427449
}
428450

429451
impl crate::sealed::Sealed for tonic::Status {}
@@ -471,6 +493,10 @@ impl StatusExt for tonic::Status {
471493
conv_details.push(resource_info.into_any());
472494
}
473495

496+
if let Some(help) = details.help {
497+
conv_details.push(help.into_any());
498+
}
499+
474500
let details = gen_details_bytes(code, &message, conv_details);
475501

476502
tonic::Status::with_details_and_metadata(code, message, details, metadata)
@@ -516,6 +542,9 @@ impl StatusExt for tonic::Status {
516542
ErrorDetail::ResourceInfo(res_info) => {
517543
conv_details.push(res_info.into_any());
518544
}
545+
ErrorDetail::Help(help) => {
546+
conv_details.push(help.into_any());
547+
}
519548
}
520549
}
521550

@@ -568,6 +597,9 @@ impl StatusExt for tonic::Status {
568597
ResourceInfo::TYPE_URL => {
569598
details.resource_info = Some(ResourceInfo::from_any(any)?);
570599
}
600+
Help::TYPE_URL => {
601+
details.help = Some(Help::from_any(any)?);
602+
}
571603
_ => {}
572604
}
573605
}
@@ -610,6 +642,9 @@ impl StatusExt for tonic::Status {
610642
ResourceInfo::TYPE_URL => {
611643
details.push(ResourceInfo::from_any(any)?.into());
612644
}
645+
Help::TYPE_URL => {
646+
details.push(Help::from_any(any)?.into());
647+
}
613648
_ => {}
614649
}
615650
}
@@ -732,6 +767,20 @@ impl StatusExt for tonic::Status {
732767

733768
None
734769
}
770+
771+
fn get_details_help(&self) -> Option<Help> {
772+
let status = pb::Status::decode(self.details()).ok()?;
773+
774+
for any in status.details.into_iter() {
775+
if any.type_url.as_str() == Help::TYPE_URL {
776+
if let Ok(detail) = Help::from_any(any) {
777+
return Some(detail);
778+
}
779+
}
780+
}
781+
782+
None
783+
}
735784
}
736785

737786
#[cfg(test)]
@@ -740,8 +789,8 @@ mod tests {
740789
use tonic::{Code, Status};
741790

742791
use super::{
743-
BadRequest, DebugInfo, ErrorDetails, ErrorInfo, PreconditionFailure, QuotaFailure,
744-
RequestInfo, RetryInfo, StatusExt,
792+
BadRequest, DebugInfo, ErrorDetails, ErrorInfo, Help, PreconditionFailure, QuotaFailure,
793+
RequestInfo, ResourceInfo, RetryInfo, StatusExt,
745794
};
746795

747796
#[test]
@@ -761,7 +810,9 @@ mod tests {
761810
.set_error_info("SOME_INFO", "example.local", metadata.clone())
762811
.add_precondition_failure_violation("TOS", "example.local", "description")
763812
.add_bad_request_violation("field", "description")
764-
.set_request_info("request-id", "some-request-data");
813+
.set_request_info("request-id", "some-request-data")
814+
.set_resource_info("resource-type", "resource-name", "owner", "description")
815+
.add_help_link("link to resource", "resource.example.local");
765816

766817
let fmt_details = format!("{:?}", err_details);
767818

@@ -777,6 +828,8 @@ mod tests {
777828
PreconditionFailure::with_violation("TOS", "example.local", "description").into(),
778829
BadRequest::with_violation("field", "description").into(),
779830
RequestInfo::new("request-id", "some-request-data").into(),
831+
ResourceInfo::new("resource-type", "resource-name", "owner", "description").into(),
832+
Help::with_link("link to resource", "resource.example.local").into(),
780833
];
781834

782835
let fmt_details_vec = format!("{:?}", err_details_vec);

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

+4-2
Original file line numberDiff line numberDiff line change
@@ -42,8 +42,10 @@ impl BadRequest {
4242
pub const TYPE_URL: &'static str = "type.googleapis.com/google.rpc.BadRequest";
4343

4444
/// Creates a new [`BadRequest`] struct.
45-
pub fn new(field_violations: Vec<FieldViolation>) -> Self {
46-
BadRequest { field_violations }
45+
pub fn new(field_violations: impl Into<Vec<FieldViolation>>) -> Self {
46+
BadRequest {
47+
field_violations: field_violations.into(),
48+
}
4749
}
4850

4951
/// Creates a new [`BadRequest`] struct with a single [`FieldViolation`] in

0 commit comments

Comments
 (0)