Gel Rust Binding: Errors Crate

This crate contains definitions of errors returned from the database.

• Documentation
• Tokio Client

License

Licensed under either of

• Apache License, Version 2.0, (./LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (./LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

lib.rs:

Error Handling for Gel

All errors that Gel Rust bindings produce are encapsulated into the Error structure. The structure is a bit like Box<dyn Error> or anyhow::Error, except it can only contain Gel error types. Or UserError can be used to encapsulate custom errors (commonly used to return an error from a transaction).

A full list of Gel error types on a single page can be found on the website documentation.

Each error kind is represented as a separate type that implements the ErrorKind trait. But error kinds are used like marker structs; you can use Error::is for error kinds and use them to create instances of the error:

let err = UserError::with_source(io::Error::from(io::ErrorKind::NotFound));
assert!(err.is::<UserError>());

Since errors are hirarchical, Error::is works with any ancestor:

assert!(err.is::<MissingArgumentError>());
assert!(err.is::<QueryArgumentError>());  // implied by the assertion above
assert!(err.is::<InterfaceError>());  // and this one
assert!(err.is::<ClientError>());  // and this one

Error hierarchy doesn't have multiple inheritance (i.e. every error has only single parent). When we match across different parents we use error tags:

assert!(err1.is::<ClientConnectionTimeoutError>());
assert!(err2.is::<TransactionConflictError>());
// Both of these are retried
assert!(err1.has_tag(SHOULD_RETRY));
assert!(err2.has_tag(SHOULD_RETRY));

// But they aren't a part of common hierarchy
assert!(err1.is::<ClientError>());
assert!(!err1.is::<ExecutionError>());
assert!(err2.is::<ExecutionError>());
assert!(!err2.is::<ClientError>());

Errors in Transactions

Special care for errors must be taken in transactions. Generally:

1. Errors from queries should not be ignored, and should be propagagated up to the transaction function.
2. User errors can be encapsulated into UserError via one of the methods:

• ErrorKind::with_source (for any std::error::Error)
• ErrorKind::with_source_box already boxed error
• ErrorKind::with_source_ref for smart wrappers such as anyhow::Error

3. Original query error must be propagated via error chain. It can be in the .source() chain but must not be swallowed, otherwise retrying transaction may work incorrectly.

Nice Error Reporting

Refer to documentation in the gel-tokio crate.