pub struct Status { /* private fields */ }
Expand description
A gRPC status describing the result of an RPC call.
Values can be created using the new
function or one of the specialized
associated functions.
let status1 = Status::new(Code::InvalidArgument, "name is invalid");
let status2 = Status::invalid_argument("name is invalid");
assert_eq!(status1.code(), Code::InvalidArgument);
assert_eq!(status1.code(), status2.code());
Implementations§
source§impl Status
impl Status
sourcepub fn new(code: Code, message: impl Into<String>) -> Status
pub fn new(code: Code, message: impl Into<String>) -> Status
Create a new Status
with the associated code and message.
sourcepub fn cancelled(message: impl Into<String>) -> Status
pub fn cancelled(message: impl Into<String>) -> Status
The operation was cancelled (typically by the caller).
sourcepub fn unknown(message: impl Into<String>) -> Status
pub fn unknown(message: impl Into<String>) -> Status
Unknown error. An example of where this error may be returned is if a
Status
value received from another address space belongs to an error-space
that is not known in this address space. Also errors raised by APIs that
do not return enough error information may be converted to this error.
sourcepub fn invalid_argument(message: impl Into<String>) -> Status
pub fn invalid_argument(message: impl Into<String>) -> Status
Client specified an invalid argument. Note that this differs from
FailedPrecondition
. InvalidArgument
indicates arguments that are
problematic regardless of the state of the system (e.g., a malformed file
name).
sourcepub fn deadline_exceeded(message: impl Into<String>) -> Status
pub fn deadline_exceeded(message: impl Into<String>) -> Status
Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire.
sourcepub fn not_found(message: impl Into<String>) -> Status
pub fn not_found(message: impl Into<String>) -> Status
Some requested entity (e.g., file or directory) was not found.
sourcepub fn already_exists(message: impl Into<String>) -> Status
pub fn already_exists(message: impl Into<String>) -> Status
Some entity that we attempted to create (e.g., file or directory) already exists.
sourcepub fn permission_denied(message: impl Into<String>) -> Status
pub fn permission_denied(message: impl Into<String>) -> Status
The caller does not have permission to execute the specified operation.
PermissionDenied
must not be used for rejections caused by exhausting
some resource (use ResourceExhausted
instead for those errors).
PermissionDenied
must not be used if the caller cannot be identified
(use Unauthenticated
instead for those errors).
sourcepub fn resource_exhausted(message: impl Into<String>) -> Status
pub fn resource_exhausted(message: impl Into<String>) -> Status
Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.
sourcepub fn failed_precondition(message: impl Into<String>) -> Status
pub fn failed_precondition(message: impl Into<String>) -> Status
Operation was rejected because the system is not in a state required for the operation’s execution. For example, directory to be deleted may be non-empty, an rmdir operation is applied to a non-directory, etc.
A litmus test that may help a service implementor in deciding between
FailedPrecondition
, Aborted
, and Unavailable
:
(a) Use Unavailable
if the client can retry just the failing call.
(b) Use Aborted
if the client should retry at a higher-level (e.g.,
restarting a read-modify-write sequence).
(c) Use FailedPrecondition
if the client should not retry until the
system state has been explicitly fixed. E.g., if an “rmdir” fails
because the directory is non-empty, FailedPrecondition
should be
returned since the client should not retry unless they have first
fixed up the directory by deleting files from it.
sourcepub fn aborted(message: impl Into<String>) -> Status
pub fn aborted(message: impl Into<String>) -> Status
The operation was aborted, typically due to a concurrency issue like sequencer check failures, transaction aborts, etc.
See litmus test above for deciding between FailedPrecondition
,
Aborted
, and Unavailable
.
sourcepub fn out_of_range(message: impl Into<String>) -> Status
pub fn out_of_range(message: impl Into<String>) -> Status
Operation was attempted past the valid range. E.g., seeking or reading past end of file.
Unlike InvalidArgument
, this error indicates a problem that may be
fixed if the system state changes. For example, a 32-bit file system will
generate InvalidArgument if asked to read at an offset that is not in the range [0,2^32-1], but it will generate
OutOfRange` if asked to read from
an offset past the current file size.
There is a fair bit of overlap between FailedPrecondition
and
OutOfRange
. We recommend using OutOfRange
(the more specific error)
when it applies so that callers who are iterating through a space can
easily look for an OutOfRange
error to detect when they are done.
sourcepub fn unimplemented(message: impl Into<String>) -> Status
pub fn unimplemented(message: impl Into<String>) -> Status
Operation is not implemented or not supported/enabled in this service.
sourcepub fn internal(message: impl Into<String>) -> Status
pub fn internal(message: impl Into<String>) -> Status
Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken.
The service is currently unavailable. This is a most likely a transient condition and may be corrected by retrying with a back-off.
See litmus test above for deciding between FailedPrecondition
,
Aborted
, and Unavailable
.
sourcepub fn unauthenticated(message: impl Into<String>) -> Status
pub fn unauthenticated(message: impl Into<String>) -> Status
The request does not have valid authentication credentials for the operation.
sourcepub fn from_error(err: Box<dyn Error + Send + Sync + 'static>) -> Status
pub fn from_error(err: Box<dyn Error + Send + Sync + 'static>) -> Status
Create a Status
from various types of Error
.
Inspects the error source chain for recognizable errors, including statuses, HTTP2, and
hyper, and attempts to maps them to a Status
, or else returns an Unknown Status
.
sourcepub fn try_from_error(
err: Box<dyn Error + Send + Sync + 'static>,
) -> Result<Status, Box<dyn Error + Send + Sync + 'static>>
pub fn try_from_error( err: Box<dyn Error + Send + Sync + 'static>, ) -> Result<Status, Box<dyn Error + Send + Sync + 'static>>
Create a Status
from various types of Error
.
Returns the error if a status could not be created.
§Downcast stability
This function does not provide any stability guarantees around how it will downcast errors into status codes.
sourcepub fn from_header_map(header_map: &HeaderMap) -> Option<Status>
pub fn from_header_map(header_map: &HeaderMap) -> Option<Status>
Extract a Status
from a hyper HeaderMap
.
sourcepub fn metadata(&self) -> &MetadataMap
pub fn metadata(&self) -> &MetadataMap
Get a reference to the custom metadata.
sourcepub fn metadata_mut(&mut self) -> &mut MetadataMap
pub fn metadata_mut(&mut self) -> &mut MetadataMap
Get a mutable reference to the custom metadata.
sourcepub fn add_header(&self, header_map: &mut HeaderMap) -> Result<(), Self>
pub fn add_header(&self, header_map: &mut HeaderMap) -> Result<(), Self>
Add headers from this Status
into header_map
.
sourcepub fn with_details(
code: Code,
message: impl Into<String>,
details: Bytes,
) -> Status
pub fn with_details( code: Code, message: impl Into<String>, details: Bytes, ) -> Status
Create a new Status
with the associated code, message, and binary details field.
sourcepub fn with_metadata(
code: Code,
message: impl Into<String>,
metadata: MetadataMap,
) -> Status
pub fn with_metadata( code: Code, message: impl Into<String>, metadata: MetadataMap, ) -> Status
Create a new Status
with the associated code, message, and custom metadata
sourcepub fn with_details_and_metadata(
code: Code,
message: impl Into<String>,
details: Bytes,
metadata: MetadataMap,
) -> Status
pub fn with_details_and_metadata( code: Code, message: impl Into<String>, details: Bytes, metadata: MetadataMap, ) -> Status
Create a new Status
with the associated code, message, binary details field and custom metadata
Trait Implementations§
source§impl Error for Status
impl Error for Status
source§fn source(&self) -> Option<&(dyn Error + 'static)>
fn source(&self) -> Option<&(dyn Error + 'static)>
1.0.0 · source§fn description(&self) -> &str
fn description(&self) -> &str
Auto Trait Implementations§
impl !Freeze for Status
impl !RefUnwindSafe for Status
impl Send for Status
impl Sync for Status
impl Unpin for Status
impl !UnwindSafe for Status
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§impl<T> Instrument for T
impl<T> Instrument for T
source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
source§impl<T> IntoRequest<T> for T
impl<T> IntoRequest<T> for T
source§fn into_request(self) -> Request<T>
fn into_request(self) -> Request<T>
T
in a tonic::Request