RFC-015: Error Handling

[IWANABETHATGUY]

• Feature Name: Error handling
• Start Date: 2022-08-12
• Rspack Issue: Error handling  #526

Summary

High level design of rspack error handling.

Motivation

Instead of panicing when suffering an error, we want to display more human-readable diagnostics to users. This is for better user experience and developer debugging experience.

For the design of error handling, we want it to be:

1. Panic free (As much as possible), we don't panic when user gives a bad input. instead, we suggest users verify the configuration and the code they wrote.

2. Traceable (Let errors could be located quickly), referring to files that are not in the filesystem, see the different behavior of webpack and rspack:

   Directory Tree

   ├── a.sass
   ├── index.js
   └── webpack.config.js

   Webpack

   ERROR in ./index.js 2:0-21
   Module not found: Error: Can't resolve './aaaaa.css' in '/Users/xxx/webpack/cssExtract'
   resolve './aaaaa.css' in '/Users/xxx/webpack/cssExtract'
     using description file: /Users/xxx/webpack/cssExtract/package.json (relative path: .)
       Field 'browser' doesn't contain a valid alias configuration
       using description file: /Users/xxx/webpack/cssExtract/package.json (relative path: ./aaaaa.css)
         no extension
           Field 'browser' doesn't contain a valid alias configuration
           /Users/xxx/webpack/cssExtract/aaaaa.css doesn't exist
         .js
           Field 'browser' doesn't contain a valid alias configuration
           /Users/xxx/webpack/cssExtract/aaaaa.css.js doesn't exist
         .json
           Field 'browser' doesn't contain a valid alias configuration
           /Users/xxx/webpack/cssExtract/aaaaa.css.json doesn't exist
         .wasm
           Field 'browser' doesn't contain a valid alias configuration
           /Users/xxx/webpack/cssExtract/aaaaa.css.wasm doesn't exist
         as directory
           /Users/xxx/webpack/cssExtract/aaaaa.css doesn't exist

   Rspack

   "/Users/xxx/rspack/crates/rspack_plugin_css/tests/fixtures/webpack/default-options"
   CompilerOptions { entry: {"main": EntryItem { path: "/Users/xxx/rspack/crates/rspack_plugin_css/tests/fixtures/webpack/default-options/index.js" }}, context: "/Users/xxx/rspack/crates/rspack_plugin_css/tests/fixtures/webpack/default-options", dev_server: DevServerOptions { hmr: false }, output: OutputOptions { path: "/Users/xxx/rspack/crates/rspack_plugin_css/tests/fixtures/webpack/default-options/dist", public_path: PublicPath { content: String("/") }, asset_module_filename: Filename { template: "assets/[name][ext]" }, unique_name: "__rspack_runtime__", filename: Filename { template: "[name][ext]" }, chunk_filename: Filename { template: "[id][ext]" } }, target: Target(Web), resolve: Resolve { extensions: [".tsx", ".jsx", ".ts", ".js", ".json"], alias: [], prefer_relative: false, symlinks: true, main_files: ["index"], main_fields: ["main"], browser_field: true, condition_names: {} }, plugins: [] }
   thread 'main' panicked at 'failed to compile in fixtrue "/Users/xxx/rspack/crates/rspack_plugin_css/tests/fixtures/webpack/default-options"', crates/rspack_plugin_css/examples/main.rs:15:25
   note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
   thread 'tokio-runtime-worker' panicked at 'called `Result::unwrap()` on an `Err` value: SendError(DependencyReference(Dependency { importer: Some("/Users/xxx/rspack/crates/rspack_plugin_css/tests/fixtures/webpack/default-options/index.js"), detail: ModuleDependency { specifier: "./style.css", kind: Import } }, "/Users/xxx/rspack/crates/rspack_plugin_css/tests/fixtures/webpack/default-options/style.css"))', crates/rspack_core/src/normal_module_factory.rs:113:8
   

3. Categorizable (The diagnostic information is grouped into different categories to allow users and developers to quickly locate the location of the code in question)：

   For now we will probably classify them in two dimensions (more dimensions may be added in the future)

   1. Severity

      For example, Error, Warning, etc. This allows user to customize the level of error displayed.

   2. Module

      For example, different plugins and loaders. This makes it easy for users to quickly locate where the error may have occurred.

   By combining these two dimensions we could also show only a certain level of error, making it easier for user to focus on solving a particular problem.

Guide-level explanation

Glossary

Diagnostic

An abstraction of the different levels of information, Diagnostic may be an error that cannot be recovered or may be a practice that is not recommended（for example:cycle dependency)

Severity

Different levels of diagnosis e.g. Error, Warning, Suggestion.

Progressive Error Handling Implementation

1. Eliminate all unwrap or explicit panicing where possible, use Result instead. Adding a helper function for error emitting and display.
2. Reshape all errors to be as traceable as possible Error (Message: String, start: usize, end: usize) . and use the corresponding Error Reporter for error reporting.
3. Categorize errors by different dimensions.

Rationale and alternatives

Based on research into rustc and webpack (see Prior art for details)

The principle is to use a Context that runs through the whole program, the core data provides the errorEmit function (using an array to carry all the error messages) that function mainly handles errors that don't crash the program, the rest of the errors are handled by the language-related error logic, e.g. (Webpack will throw new Error, rustc use Result )

We have two alternative implementations of this.

Implementation One

Similar to Webpack we also add an errors field to Compilation

#[derive(Debug)]
pub struct Compilation {
  pub options: Arc<CompilerOptions>,
  entries: HashMap<String, EntryItem>,
  pub(crate) visited_module_id: VisitedModuleIdentity,
  pub module_graph: ModuleGraph,
  pub chunk_graph: ChunkGraph,
  pub runtime: Runtime,
  pub entrypoints: HashMap<String, Entrypoint>,
  pub assets: CompilationAssets,
  
+  pub diagnostics: Vec<Diagnostic>
}

After that, we need to change the signature of the call that takes Compilation as an argument to Arc<Mutex<Compilation>>

pub trait Module: Debug + Send + Sync {
  fn module_type(&self) -> ModuleType;

  fn source_types(&self, _module: &ModuleGraphModule, _compilation: &Compilation) -> &[SourceType];

  fn render(
    &self,
    requested_source_type: SourceType,
    module: &ModuleGraphModule,
-    compilation: &Compilation,
+    compilation: Arc<Mutex<Compilation>>,
  ) -> Result<Option<ModuleRenderResult>>;

  fn dependencies(&mut self) -> Vec<ModuleDependency> {
    vec![]
  }
}

Because potential errors can occur in any function call, for updating Compilation.diagnostics, we may need to add an extra argument to a lot of function calls.

Cons

1. More invasive to the current implementation, the code repository would require a lot of modification.
2. There will also be a slight performance impact due to the introduction of Mutex.

Implementation two

see #549,

Pros

1. Less invasive compared to implementation one.
2. Lock free, performance gain.

Prior art

Webpack

webpack uses two different types of error handling, one for errors that are not recoverable or affect the execution of the program which uses throw new Error to interrupt the process. Another type of error that does not affect the execution of the build process directly pushes errors to Compilation.errors.

For the implementation of the second type of error handing:

1. Some plugins have their own array of errors , which would merge into the error array of Compilation in a specific hook.See the Module's error merging as an example https://github.com/webpack/webpack/blob/9fcaa243573005d6fdece9a3f8d89a0e8b399613/lib/Compilation.js#L2731-L2740
2. Some plugins push errors directly into the errors array of parameter compilation https://github.com/webpack/webpack/blob/9fcaa243573005d6fdece9a3f8d89a0e8b399613/lib/DllReferencePlugin.js#L133-L149

After the build process is finished, Errors and Warnings are passed to Stats for final processing https://github.com/webpack/webpack/blob/9fcaa243573005d6fdece9a3f8d89a0e8b399613/lib/Stats.js#L68-L81

The final output will pipe into stdio or stderror.

rustc

https://rustc-dev-guide.rust-lang.org/diagnostics.html?highlight=Errors#error-messages, According to rustc-dev-guide，https://rustc-dev-guide.rust-lang.org/diagnostics.html?highlight=Errors#error-messages:~:text=Session%20and%20ParseSess%20have%20methods%20(or%20fields%20with%20methods)%20that%20allow%20reporting%20errors.%20These%20methods%20usually%20have%20names%20like%20span_err%20or%20struct_span_err%20or%20span_warn%2C%20etc...%20There%20are%20lots%20of%20them%3B%20they%20emit%20different%20types%20of%20%22errors%22%2C%20such%20as%20warnings%2C%20errors%2C%20fatal%20errors%2C%20suggestions%2C%20etc. We know that rustc mainly uses Session
structures to report errors, and that Sessions are mounted on the GlobalContext throughout the compilation process.

Let's take the example of rust TypeError, https://rustc-dev-guide.rust-lang.org/ty.html#type-errors， When rustc needs to emit a type_error it will call TyCtxt::ty_error or TyCtxt::ty_error_with_message. When calling ty_error_with_message it will use Session to register one delay_span_bug and finally call delay_span_bug of session.handler, which will createg a Diagnostic first, after that call self.emit_diagnostic, finally call self.emitter.emit_diagnostic https://github.com/rust-lang/rust/blob/b998821e4c51c44a9ebee395c91323c374236bbb/compiler/rustc_errors/src/emitter.rs#L614-L638, through a number of transformation operations https://github.com/rust-lang/rust/blob/b998821e4c51c44a9ebee395c91323c374236bbb/compiler/rustc_errors/src/annotate_snippet_emitter_writer.rs#L21 pipe the result to stderr

Unresolved questions

• Which Error Reporter should we use?

  Some alternative options:

  • https://crates.io/crates/codespan-reporting
  • https://crates.io/crates/ariadne
  • https://crates.io/crates/miette

• How to unify error handing in rust side and node side.

  1. Handing all errors in rust side, transport errors via serde
  2. Handing all errors in node binding side, transport errors via serde
  3. Handling of individual errors, uniform error format， make a node binding for error reporting (unify the display of errors)

Future possibilities

1. Provide a unique Error Number for each type of error as rustc and typescript did.

   rustc

   error[E0282]: type annotations needed
    --> crates/rspack_plugin_css/examples/main.rs:7:7
     |
   7 |   let options = TestOptions::from_fixture(&cur_dir).into();
     |       ^^^^^^^
   8 |
   9 |   println!("{:?}", *options);

   tsc

   test.ts:1:5 - error TS2322: Type 'number' is not assignable to type 'string'.
   
   1 let a : string = 3;
         ~

   Pros：

   • More detailed explanations could be provided for each error number
     For the above wrong rust code snippet, we can find specific explanations on the official website of rust https://doc.rust-lang.org/error-index.html#E0282

   Cons：

   • Higher maintenance costs