Ideas for supporting richer error reporting

[joshlf]

See also: #1659

Currently, our fallible APIs return Options, where all error conditions are reported as None. This is insufficient for a few reasons:

• Some users might want to be able to distinguish the reason for failure (e.g., a size check failed, an alignment check failed).
• With APIs that return Options, there is no distinction in the type system between APIs that have different failure conditions. As a result, reasoning about which error conditions are possible (vs which are statically prevented at compile time) is a matter of reading the documentation on an API rather; the distinction is not visible in the type system.
• Some users want APIs which return Options either because they don't care to distinguish error cases or because they're worried about the performance or binary size implications of richer error reporting.
• When we land TryFromBytes (Support TryFromBytes - conditional conversion analogous to FromBytes #5), some users may want to know which byte offsets or which fields caused a fallible conversion to fail

Generic error types

Have our APIs take a generic error type which can be constructed from the appropriate "underlying" error conditions. For FromBytes conversions, the "underlying" error conditions that some users would want access to would be size and alignment errors. For TryFromBytes, there would be much richer conditions, including the offending byte range, the path to the field that was being validated, etc. See rkyv for some prior art here.

Here's an example for Ref:

pub struct SizeError {
    type_size: usize,
    buffer_size: usize,
}

pub struct AlignError {
    type_align: usize,
    buffer_addr: usize,
}

pub struct ThinError;

impl From<SizeError> for ThinError { ... }
impl From<AlignError> for ThinError { ... }

pub enum SizeAlignError {
    Size(SizeError),
    Align(AlignError),
}

impl From<SizeError> for SizeAlignError { ... }
impl From<AlignError> for SizeAlignError { ... }

impl<B: ByteSlice, T> Ref<B, T> {
    fn new<E: From<SizeError> + From<AlignError>>(bytes: B) -> Result<Ref<B, T>, E> { ... }
}

impl<B: ByteSlice, T: Unaligned> Ref<B, T> {
    fn new_unaligned<E: From<SizeError>>(bytes: B) -> Result<Ref<B, T>, E> { ... }
}

Users who want to ensure that certain error conditions are impossible can write only the error conditions they want to handle:

// This match only needs to handle `SizeError`.
match Ref::new_unaligned::<SizeError>(bytes) {
    Ok(...) => ...,
    Err(SizeError { ... }) => ...,
}

Builder pattern

Create a builder that encodes in the type system which checks have already happened. For each check, provide two methods or functions: one which checks at runtime and returns Option or Result, and one which includes the appropriate type bound (e.g., T: Unaligned and is infallible.

[joshlf]

@djkoloski also mentioned this: https://docs.rs/rancor/0.1.0-pre8/rancor/index.html (bytecheck has been rebased on top of this)