Seeking Best Practices for Error and Warning Handling in Complex Rust Projects

Start by reading the referenced crates/core/src/error.rs file in rustic_core and compare its current error and warning types with the questions in this issue. A contribution would need a defined documentation scope and agreement on the intended patterns; this issue does not specify a concrete page, example, or acceptance criteria.

Hi @nrc!

I’m reaching out to get some expert advice on the challenges we’re facing with error and warning handling in our Rust-based project, rustic_core. Our project is relatively complex, and we’re struggling to find the right balance between propagating errors (soft- and hard errors), handling warnings, and maintaining good user experience with clear error messages.

Context of Our Problem

1. Error Handling:

   • In our current setup, we primarily rely on returning Result<T, RusticError> to propagate errors. Kind of a god enum approach, where we convert sub errors into that god error for handing it over at our API boundary. However, we often find ourselves in scenarios where multiple errors can occur (e.g., batch operations or validation processes of data collections), and handling only the first error results in lost context.
   • We are considering three primary options:
     1. Returning a single error (Result<T, RusticError>)
     2. Returning a list of errors (Result<T, Vec<RusticError>>)
     3. Returning nested Results (Result<Result<T, Vec<RusticSoftError>>, RusticHardError>)
   • We're also facing cases where we need to continue execution in the presence of some errors but fail fast in others.

2. Warning Handling:

   • We need a consistent way to handle warnings. So far, we’ve identified three potential approaches:
     1. Logging warnings locally and not passing them back to the caller.
     2. Returning a boolean flag (is_warn) to indicate if warnings occurred.
     3. Returning a list of warnings to provide detailed information about all non-critical issues that the caller can process.
   • We’re trying to decide if warnings should be purely for operational visibility (handled via logging), or if the caller should be made aware of warnings explicitly.

3. General Pain Points:

   • We struggle with missing contextual information in error messages, leaving the end-users without actionable guidance.
   • We want to include error codes or links to documentation in error messages for better guidance and debugging.
   • In scenarios like async operations, the logging and error handling become more difficult to manage, especially when errors are collected from multiple spawned tasks.
   • Finally, we want to reconsider how we handle warnings and errors over function boundaries, thinking we may need to simplify or keep more localized handling without propagating too much information upward.

Questions

1. Error Propagation:

   • When should we prefer returning a single error (e.g., Result<T, RusticError>) vs. returning a list of errors (e.g., Result<T, Vec<RusticError>>)? Are there performance or architectural concerns that we should consider when deciding between these two approaches?
   • In complex async operations or batch processing, where multiple errors might occur, what would be the best way to handle error accumulation without losing key context? Is there a common pattern in Rust for handling this elegantly? Like spawning an error handling thread and communicating with it via a channel?

2. Warnings:

   • When handling warnings, would you recommend keeping them local (i.e., logging only) or propagating them back to the caller? Under what circumstances is it better to pass warnings up vs. treating them as internal operational feedback?
   • How would you handle situations where a function should continue executing but may want to indicate that warnings occurred (e.g., via an is_warn boolean flag or a list of warnings)? What is the best approach here to maintain simplicity while giving the caller enough control over decision-making?

3. Async/Concurrency:

   • In async tasks and concurrent operations, how do you typically manage error propagation and structured logging, especially when errors are collected from multiple spawned tasks? How can we ensure we get full visibility into errors without complicating error management?

4. General Best Practices:

   • Are there any best practices or patterns you would recommend for error and warning handling that balance performance, code maintainability, and user experience in Rust-based systems?
   • How can we maintain a simple API for callers while ensuring we capture all relevant issues (both errors and warnings) during complex or long-running operations?
   • We also thought about a nested Result where the outer Result can contain hard errors that lead to aborting the program. While the inner Result would contain a list of errors that were coming up during the processing of data collections. Which is inspired by http://sled.rs/errors

We appreciate any guidance or patterns you’ve found useful in these situations!