Crate conjure_error 

Runtime support for Conjure error types.

In a networked service, the error objects that are propagated through its codebase are responsible for two things:

• Collecting useful information that a developer can use to diagnose whatever problem caused the error.
• Controlling how the error is presented to the client.

Services implemented using Conjure’s frameworks use the Error type defined in this crate as the single error type throughout the codebase. Errors store:

• Developer facing:
  • Error::cause - the underlying cause of the error. This can be a type implementing the Rust std::error::Error trait, or just a str or String containing a description of what happened. When an Error is logged, the cause (and its chain of sources via std::error::Error::source) are included as a parameter. The log-safety of that cause information is identified by the choice of constructor of the Error.
  • Error::safe_params and Error::unsafe_params - key-value pairs that can be added to the error to provide context. When an Error is logged, these are included in the service log’s parameters. When a service Error is created, all of the parameters of its associated Conjure error are automatically included as params, with ErrorType::safe_args used to partition the parameters between safe and unsafe. Additional params can be added via Error::with_safe_param and Error::with_unsafe_param.
  • Error::backtraces - a sequence of backtraces to annotate the error with the state of the function call stack. A backtrace is automatically taken when the Error is created, and additional backtraces can be added with the Error::with_backtrace method. This can be used when, for example, an Error transfers from one thread to another. When an Error is logged, its backtraces will be included in the stacktrace field.
• Client facing:
  • Error::kind - how the error should be reported to the client. There are currently three kinds:
    • ErrorKind::Service - a standard service error. These are constructed from a type implementing Serialize and ErrorType. The value is expected to serialize as a struct, with the struct’s fields being the parameters of the error. Errors defined in Conjure APIs will generate types implementing these traits. This will generate an HTTP response following the Conjure wire spec. Service errors are created with the Error::service, Error::service_safe, Error::internal, and Error::internal_safe functions.
    • ErrorKind::Throttle - an indication that the client is making too many requests and should throttle itself. This will generate a 429 Too Many Requests HTTP response. Throttle errors are created with the Error::throttle, Error::throttle_safe, Error::throttle_for, and Error::throttle_for_safe functions.
    • ErrorKind::Unavailable - an indication that the server is unable to handle the request. This will generate a 503 Service Unavailable HTTP response. Unavailable errors are created with the Error::unavailable and Error::unavailable_safe functions.

Examples

Mapping a std::error::Error returned by a stdlib API into a generic internal service error:

use conjure_error::Error;
use std::fs::File;

let file = File::open("var/data/database.csv").map_err(Error::internal_safe)?;

Doing the same, but including the filename as an extra parameter:

use conjure_error::Error;
use std::fs::File;

let filename = "var/data/database.csv";
let file = File::open(filename).map_err(|e| {
    Error::internal_safe(e).with_safe_param("filename", filename)
})?;

Returning a specific Conjure error when there is no existing error cause:

types:
  definitions:
    errors:
      ObjectNotFound:
        namespace: MyService
        code: INVALID_ARGUMENT
        safe-args:
          objectRid: rid

use conjure_error::Error;
use my_service_api::errors::ObjectNotFound;

if !object_was_found {
    return Err(Error::service_safe("failed to find object", ObjectNotFound::new(object_rid)));
}

Modules

conflict

error_code

failed_precondition

internal

invalid_argument

not_found

permission_denied

request_entity_too_large

serializable_error

timeout

Structs

Backtrace

A backtrace associated with an Error.

Conflict

A generic CONFLICT error.

Error

A standard error type for network services.

FailedPrecondition

A generic FAILED_PRECONDITION error.

Internal

A generic INTERNAL error.

InvalidArgument

A generic INVALID_ARGUMENT error.

NotFound

A generic NOT_FOUND error.

Params

A collection of error parameters, either safe or unsafe.

ParamsIter

An iterator over the parameters of an error.

PermissionDenied

A generic PERMISSION_DENIED error.

RequestEntityTooLarge

A generic REQUEST_ENTITY_TOO_LARGE error.

SerializableError

The JSON-serializable representation of an error.

ThrottleError

Information about a throttle error.

Timeout

A generic TIMEOUT error.

UnavailableError

Information about an unavailable error.

WithInstanceId

An ErrorType which wraps another and overrides its instance ID.

Enums

ErrorCode

The broad category of a Conjure error.

ErrorKind

Information about the specific type of an Error.

Traits

ErrorType

A trait implemented by Conjure error types.

Functions

encode

Encodes a Conjure error into its serialized form.

stringify_parameters

Re-serializes the parameters of a SerializableError in the legacy stringified format.