Crate tonic_types
source ·Expand description
A collection of useful protobuf types that can be used with tonic
.
This crate also introduces the StatusExt
trait and implements it in
tonic::Status
, allowing the implementation of the
gRPC Richer Error Model with tonic
in a convenient way.
§Usage
Useful protobuf types are available through the pb
module. They can be
imported and worked with directly.
The StatusExt
trait adds associated functions to tonic::Status
that
can be used on the server side to create a status with error details, which
can then be returned to gRPC clients. Moreover, the trait also adds methods
to tonic::Status
that can be used by a tonic client to extract error
details, and handle them with ease.
§Getting Started
[dependencies]
tonic = <tonic-version>
tonic-types = <tonic-types-version>
§Examples
The examples bellow cover a basic use case of the gRPC Richer Error Model. More complete server and client implementations are provided in the Richer Error example, located in the main repo examples directory.
§Server Side: Generating tonic::Status
with an ErrorDetails
struct
use tonic::{Code, Status};
use tonic_types::{ErrorDetails, StatusExt};
// ...
// Inside a gRPC server endpoint that returns `Result<Response<T>, Status>`
// Create empty `ErrorDetails` struct
let mut err_details = ErrorDetails::new();
// Add error details conditionally
if some_condition {
err_details.add_bad_request_violation(
"field_a",
"description of why the field_a is invalid"
);
}
if other_condition {
err_details.add_bad_request_violation(
"field_b",
"description of why the field_b is invalid",
);
}
// Check if any error details were set and return error status if so
if err_details.has_bad_request_violations() {
// Add additional error details if necessary
err_details
.add_help_link("description of link", "https://resource.example.local")
.set_localized_message("en-US", "message for the user");
let status = Status::with_error_details(
Code::InvalidArgument,
"bad request",
err_details,
);
return Err(status);
}
// Handle valid request
// ...
§Client Side: Extracting an ErrorDetails
struct from tonic::Status
use tonic::{Response, Status};
use tonic_types::StatusExt;
// ...
// Where `req_result` was returned by a gRPC client endpoint method
fn handle_request_result<T>(req_result: Result<Response<T>, Status>) {
match req_result {
Ok(response) => {
// Handle successful response
},
Err(status) => {
let err_details = status.get_error_details();
if let Some(bad_request) = err_details.bad_request() {
// Handle bad_request details
}
if let Some(help) = err_details.help() {
// Handle help details
}
if let Some(localized_message) = err_details.localized_message() {
// Handle localized_message details
}
}
};
}
§Working with different error message types
Multiple examples are provided at the ErrorDetails
doc. Instructions
about how to use the fields of the standard error message types correctly
are provided at error_details.proto.
§Alternative tonic::Status
associated functions and methods
In the StatusExt
doc, an alternative way of interacting with
tonic::Status
is presented, using vectors of error details structs
wrapped with the ErrorDetail
enum. This approach can provide more
control over the vector of standard error messages that will be generated or
that was received, if necessary. To see how to adopt this approach, please
check the StatusExt::with_error_details_vec
and
StatusExt::get_error_details_vec
docs, and also the main repo’s
Richer Error example directory.
Besides that, multiple examples with alternative error details extraction
methods are provided in the StatusExt
doc, which can be specially
useful if only one type of standard error message is being handled by the
client. For example, using StatusExt::get_details_bad_request
is a
more direct way of extracting a BadRequest
error message from
tonic::Status
.
Re-exports§
pub use pb::Status;
Modules§
- Useful protobuf types
Structs§
- Used to encode/decode the
BadRequest
standard error message described in error_details.proto. Describes violations in a client request. Focuses on the syntactic aspects of the request. - Used to encode/decode the
DebugInfo
standard error message described in error_details.proto. Describes additional debugging info. - Groups the standard error messages structs. Provides associated functions and methods to setup and edit each error message independently. Used when extracting error details from
tonic::Status
, and when creating atonic::Status
with error details. - Used to encode/decode the
ErrorInfo
standard error message described in error_details.proto. Describes the cause of the error with structured details. - Used at the
field_violations
field of theBadRequest
struct. Describes a single bad request field. - 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. - Used at the
links
field of theHelp
struct. Describes a URL link. - Used to encode/decode the
LocalizedMessage
standard error message described in error_details.proto. Provides a localized error message that is safe to return to the user. - Used to encode/decode the
PreconditionFailure
standard error message described in error_details.proto. Describes what preconditions have failed. - Used at the
violations
field of thePreconditionFailure
struct. Describes a single precondition failure. - Used to encode/decode the
QuotaFailure
standard error message described in error_details.proto. Describes how a quota check failed. - Used at the
violations
field of theQuotaFailure
struct. Describes a single quota violation. - Used to encode/decode the
RequestInfo
standard error message described in error_details.proto. Contains metadata about the request that clients can attach when providing feedback. - Used to encode/decode the
ResourceInfo
standard error message described in error_details.proto. Describes the resource that is being accessed. - 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 decodingRetryInfo
messages, negativeretry_delay
’s become 0.
Enums§
- Wraps the structs corresponding to the standard error messages, allowing the implementation and handling of vectors containing any of them.
Traits§
- Used to implement associated functions and methods on
pb::Status
, that allow the extraction of standard error details. This trait is sealed and not meant to be implemented outside oftonic-types
. - Used to implement associated functions and methods on
tonic::Status
, that allow the addition and extraction of standard error details. This trait is sealed and not meant to be implemented outside oftonic-types
.