Enum ockam_core::errcode::Kind

#[non_exhaustive]
#[repr(u8)]
pub enum Kind {
    Unknown = 0,
    Internal = 1,
    Invalid = 2,
    Unsupported = 3,
    NotFound = 4,
    AlreadyExists = 5,
    ResourceExhausted = 6,
    Misuse = 7,
    Cancelled = 8,
    Shutdown = 9,
    Timeout = 10,
    Conflict = 11,
    Serialization = 12,
    Parse = 13,
    Io = 14,
    Protocol = 15,
    Other = 16,
}

Category indicates “what went wrong”, in abstract terms.

Choosing a Kind

• Kind::Io, Kind::Protocol, and Kind::Other should only be used if there’s no more specific option.

  For example, a network timeout is a type of IO error, however it should use Kind::Timeout rather than Kind::Io.

• Kind::Invalid should be used when the input will never be valid (at least in this version of the software), rather than input which is invalid because of the current system state.

  For example, an unknown identifier should use Kind::NotFound (for example ockam_vault_core’s Secret) rather than Kind::Invalid,

• Kind::Cancelled, Kind::Timeout, and Kind::Shutdown all sound similar, but:

  • Kind::Timeout should be used to map operations which timeout externally, such as network requests. These may succeed if retried.

  • Kind::Shutdown should be used to indicate the operation failed due to the node shutting down.

  • Kind::Cancelled is used when a request to cancel the operation comes in while the operation is in progress.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Unknown = 0

Indicates that there is no way to determine a more specific kind.

Internal = 1

Used for serious internal errors, including panics.

This generally should not be used unless we’d accept a bug report for the error.

Invalid = 2

The input was fundamentally invalid.

For example, this is appropriate to use when:

• A null pointer being passed as input in the FFI.
• A string is used as input which is not UTF-8.
• Parse failures of various kinds, but be sure to include more specific information in the Error payload.

Note that it is not appropriate for input which is invalid only due to the current system state.

Unsupported = 3

The requested operation is not supported/implemented by that component.

For example, this is appropriate for a component (for example, a custom Vault) which do not implement the entire API surface.

NotFound = 4

Some referenced entity was not found.

For example, this may be appropriate for:

• A vault which does not recognize a Secret which it receives.
• FFI that receives an integer handle that does not belong to any known entity.
• Local Address which don’t correspond to any known Worker or Processor.
• Address with a transport of an unknown or unsupported type.

Information about what exactly it is that could not be located should be available on the Error itself.

AlreadyExists = 5

The operation failed because a resource already exists.

For example, this may be appropriate for:

• A ockam node already exists
• A vault state already exists
• An entry in a cddl file that already has an entry for a given key. This would indicate that a resource has been defined multiple times, possibly in different wasys.

Information about what exactly it is that already existed should be available on the Error itself.

ResourceExhausted = 6

Indicates that some resource has been exhausted, or would be exhausted if the request were to be fulfilled.

The resource in question could be memory, open file descriptors, storage, quota, simultaneous in-flight messages or tasks…

Information about which resource it was that was exhausted should be available on the Error itself.

Misuse = 7

An API was misused in some unspecific fashion.

This is mostly intended for FFI and other non-Rust bindings — for example, it would be appropriate to map core::cell::BorrowError to this.

Cancelled = 8

Indicates the operation failed due to a cancellation request.

See the type documentation on the difference between this, Kind::Shutdown and Kind::Timeout.

Shutdown = 9

Indicates that the operation failed due to the node shutting down.

See the type documentation on the difference between this, Kind::Cancelled and Kind::Timeout.

Timeout = 10

Indicates that the operation failed due to an external operation timing out, such as a network request, which may succeed if retried.

See the type documentation on the difference between this, Kind::Shutdown and Kind::Cancelled.

Conflict = 11

Indicates an operation failed due to simultaneous attempts to modify a resource.

Serialization = 12

Indicates an a failure to deserialize a message (or in rare cases, failure to serialize).

Parse = 13

Indicates a parsing error.

Io = 14

Indicates some other I/O error.

Specifics should be available on error payload.

Protocol = 15

Indicates some other I/O error.

Specifics should be available on error payload.

Other = 16

Indicates an error that

Specifics should be available on error payload.

Implementations

impl Kind

pub fn from_u8(n: u8) -> Option<Self>

Attempt to construct a Kind from the numeric value.

Trait Implementations

impl Clone for Kind

fn clone(&self) -> Kind

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Kind

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Kind

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<u8> for Kind

fn from(src: u8) -> Self

Converts to this type from the input type.

impl Hash for Kind

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Kind

fn cmp(&self, other: &Kind) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq for Kind

fn eq(&self, other: &Kind) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Kind

fn partial_cmp(&self, other: &Kind) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for Kind

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Copy for Kind

impl Eq for Kind

impl StructuralPartialEq for Kind