error-stack: Putting data in the context struct vs. using attachments?

[AriaFallah]

Hi! I love this library, and one thing I'm struggling to understand is attachments, and when they're useful. I'm hoping the following example can explain my confusion, and then you can hopefully show me what I'm missing.

Contrived Example

Let's say we take the experiment parsing example from the README and change it to have the ExperimentError struct contain a reason

#[derive(Debug)]
struct ExperimentError {
 reason: String
};

impl fmt::Display for ExperimentError {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.write_str("experiment error: could not run experiment because {}", self.reason)
    }
}

then for an example like this

let experiment = parse_experiment(description)
  .attach_printable(format!("experiment {exp_id} could not be parsed"))
  .change_context(ExperimentError)?;

you'd instead write the following

let experiment = parse_experiment(description)
  .change_context_lazy(|| ExperimentError { reason: format!("experiment {exp_id} could not be parsed" })?;

and you don't even need an attachment at all. The only difference as far as I can tell is that the error will render slightly differently. Moreover there seem to be some benefits to doing it this way:

• You make sure there's always a reason captured for the error happening
• It makes it possible to request the specific reason for the experiment error using the provider API (vs. just requesting all attached strings)

Going overboard

This is a bit impractical in its granularity, but anyways with thiserror we could do something like this to take it even further and fully define the entire scope of errors:

#[derive(Error)]
pub enum ExperimentErrorReason {
  #[error("experiment {0} could not be parsed")]
  CouldNotBeParsed(usize),
  // Other errors
}

#[derive(Debug, Error)]
#[error("experiment error: could not run experiment because {reason}")]
struct ExperimentError {
 reason: ExperimentErrorReason
};

let experiment = parse_experiment(description)
  .change_context_lazy(|| ExperimentError { reason: ExperimentErrorReason::CouldNotBeParsed(exp_id) })?;

My Question...

The overarching point I'm trying to demonstrate is that I don't exactly understand why 99% of attachments aren't just a part of the context struct. The only case I can see for attachments over putting stuff into the context struct is attaching stuff that's optional because you don't feel like putting an Option<T> into your struct.

Could you explain if there's something I'm missing here? Maybe some real-world examples from HASH would help demonstrate the utility of attachments better

[indietyp]

Hello, I am sorry for taking so long to respond to your question! I completely missed this thread. My bad 😅

Your question is entirely valid, and thanks for asking. I think "blank" structs with no information and your use-case go hand in hand, but there are some use cases where attachments are beneficial. They are primarily useful in cases where either A) things might change, B) information is unknown during the creation of the context, C) information is shared across multiple errors

I am working on an experimental deserialization library (deer), which heavily uses error-stack. To illustrate the use cases outlined I'll take some snippets of the code

A) Things might change

Let's say we want to create a new data type (u5), which has a bit width of 5 bits. (There is no reason why you would do that, but it is always a good example)

use deer::{
    error::{DeserializeError, ExpectedType, ReceivedValue, ValueError, Variant},
    Deserialize, Deserializer, Document, Reflection, Schema,
};
use error_stack::Report;

#[allow(non_camel_case_types)]
pub struct u5(u8);

impl Reflection for u5 {
    fn schema(_: &mut Document) -> Schema {
        Schema::new("integer")
            .with("maximum", 31)
            .with("minimum", 0)
    }
}

impl<'de> Deserialize<'de> for u5 {
    type Reflection = Self;

    fn deserialize<D: Deserializer<'de>>(de: D) -> error_stack::Result<Self, DeserializeError> {
        match u8::deserialize(de) {
            Ok(value) if value > 31 => Err(Report::new(ValueError.into_error())
                .attach(ReceivedValue::new(value))
                .attach(ExpectedType::new(Self::reflection()))
                .change_context(DeserializeError)),
            Ok(value) => Ok(u5(value)),
            Err(mut error) => {
                for frame in error
                    .frames_mut()
                    .filter_map(|frame| frame.downcast_mut::<ExpectedType>())
                {
                    *frame = ExpectedType::new(Self::reflection());
                }

                Err(error)
            }
        }
    }
}

as you can see here, we can make full use of the existing deserialization logic for u8, but if e.g. we were supplied a String instead (or multiple errors occurred), we can easily change the expected type from u8 to u5, without breaking a sweat and (this is important), without knowing what the underlying error might be. There may be multiple error types that actually make use of ExpectedType, there may be added new ones in the future, but this piece of code does not need to care, it simply just changes their expected value (via the attachment). This keeps code simple, maintainable, and adaptable.

This is of course not applicable to all information, so for information specific to an error that is not expected to change during its lifetime, just using a struct with values is 100% okay and encouraged!

B) Information is unknown

Another example from deer is Location. Every deer error has a location that isn't saved in the error struct. When an error happens in e.g. a specific position of an error we attach Location::Array(n), once we process the error we're able to collect all locations individually into an array, giving us a convenient path to where the error happened, without the deserializer implementation needing to know the exact location!

Let's say we have a json struct like this

[
	...,
	{
		"a": [
			..., 
			{
				"b":  ERROR HERE
			},
			...
		],
		...
	},
	...
]

The json path to the error might be: .[3].a[2].b, in deer, in the array and HashMap deserializer we simply attach the location if we encounter an error, which means the resulting error might look like this (for brevities sake I have omitted some context switches):

graph RL;
	V1["Value Error"]
	L1["Location::Entry(b) | attached in HashMapVisitor"]
	L2["Location::Array(2) | attached in ArrayVisitor"]
	L3["Location::Entry(a) | attached in HashMapVisitor"]
	L4["Location::Array(3) | attached in ArrayVisitor"]

	V1 --> L1
	L1 --> L2
	L2 --> L3
	L3 --> L4

But there is other information that might be helpful, regardless of the error present, like what was the database connection that caused the issue. This might not be available at the creation site, but at a later date, this also saves a lot of boilerplates, instead of making sure that every single error struct has a specific value of a type (which is easy to miss), we can just attach the information when we come across the issue at the application layer without worrying about the underlying error.

C) Information is shared amongst multiple errors

since 0.2, error-stack is not always a stack, but sometimes a tree (internally we sometimes joke about how we could rename error-stack to error-tree instead), so there are some values that might be shared across errors (and boundaries). This goes hand in hand with (A) and (B).

A error-stack error is not always:

graph RL;
	C8 --> A7 --> A6 --> C5 --> A4 --> A3 --> A2 --> C1

but can instead be

graph RL;

	C8 --> A7 --> A6 --> A2 --> C1
	C5 --> A4 --> A3 --> A2

This attachment A2 is therefore "shared" by both the C5 and C8 errors. This gives us new possibilities, like e.g. in deer, we're able to defer certain attachments (like ExpectedType), which are shared by multiple errors until a later point in execution, making it easier to handle, this plays into (A), as we might not know what the actual expected type is, until a later date. This of course has some trade-offs, with struct data we're able to guarantee that a specific value will be present, which we are not able to do using this method.