Expand description
OpenMLS Errors
Each module has their own errors it is returning. This module will defines helper macros and functions to define OpenMLS errors.
Error handling
Most function calls in the library return a Result and can therefore surface errors to the library consumer.
Errors can have different sources, depending on their nature. The following list explains the different error sources and how to handle them:
Errors in dependencies
The OpenMLS library relies on external dependencies for cryptographic primitives and storage of cryptographic key material. See the traits in the [User Manual] for more details on the dependencies.
When an unexpected error occurs in one of those dependencies, it is usually surfaced as a LibraryError to the consumer.
Errors induced by wrong API use
Whenever the caller calls an OpenMLS function with invalid input, an error is returned. Examples of wrong input can be: Adding a member twice to a group, interacting with an inactive group, removing inexistent
members from a group, etc. The precise error message depends on the function called, and the error will typically be an enum with explicit variants that state the reason for the error.
Consumers can branch on the variants of the enum and take action accordingly.
Errors induced by processing invalid payload
The library processes external payload in the form of messages sent over a network, or state loaded from disk. In both cases, multi-layered checks need to be done to make sure the payload
is syntactically and semantically correct. The syntax checks typically all happen at the serialization level and get detected early on. Semantic validation is more complex because data needs to be evaluated
in context. You can find more details about validation in the validation chapter of the [User Manual].
These errors are surfaced to the consumer at various stages of the processing, and the processing is aborted for the payload in question. Much like errors induced by wrong API usage, these errors are enums that
contain explicit variants for every error type. Consumers can branch on these variants to take action according to the specific error.
Correctness errors in the library itself
While the library has good test coverage in the form of unit & integration tests, theoretical correctness errors cannot be completely excluded. Should such an error occur, consumers will get
a LibraryError as a return value that contains backtraces indicating where in the code the error occurred and a short string for context. These details are important for debugging the library in such a case.
Consumers should save this information.
All errors derive thiserror::Error as well as
Debug, PartialEq, and Clone.
Structs
- A wrapper struct for an error string. This can be used when no complex error variant is needed.
- Generic error type that indicates unrecoverable errors in the library.