DRAFT: Feature: Error Manager (WIP) - [merged] #699

Closed benloh closed 1 year ago

In GitLab by @daveseah on Jul 19, 2022, 17:06

Merges dev-next-gui-errhelp -> dev-next

WORK IN PROGRESS

WHAT IS THE ERROR MANAGER

The Error Manager is a module that is being designed to centralize capture, processing, and reporting of errors across GEMSTEP.

The Error Manager technically does the following:

handle crashes - instead of crashing in the browser invisibly, we can show or mitigate the error
attribution - since there are a lot of different sources of errors, we want to categorize them by system
attaching to operations - since errors can occur during any part of an operation/workflow task, we want to be able to infer the context where a particular error occurred
automated logging - keep track of errors in the order they are reported
universally accessible module api - dependency-less and importable by any code in the system so errors can be easily reported

With the above in place, we can do stuff like this:

providing error state info - specific 'appcontext' (e.g. Main, ScriptEditor) can subscribe to the error manager so it can display issues that arise during use
automated help - by combining 'operation' and 'attribution' information with 'appcontext', we can infer what user-initiated actions caused an error and then suggest how to fix it
research log - the error manager can become another source of logged information for researchers

DEVELOPMENT APPROACH

Because error management can significantly change workflow in unexpected ways, we're developing it in a separate branch: dev-next-gui-errhelp. This branch will track against the active branch used by the research team (dev-next-gui at the time of this writing), merging in changes as they are made. This should result in an alternate branch that researchers can try out; if there is a consensus that it's ready for use, we can merge it quickly.

This is a fairly complicated subject because of the number of error sources, their specific meaning, and context of operation; we are implementing a kind of 1980s style "expert system" using ad-hoc techniques. On the technical side, there is also inserting the additional code to check for errors programmatically, and handling cascading errors where an error may originate in one area and then cause a number of cascading failures in parallel. Determining which error is the "root cause" that should be reported to the user.

Right now we are just trying to catch them all; afterwards we can concentrate on providing the first-pass user experience:

handles bad scripts in a way that doesn't crash the system silently
reports errors in the script by line number and position, with "understandable" instructions that also help build understanding of the GEMSTEP simulation engine model.
provides a categorization system for errors by operation, system, type, and number
provides a timestamped log of captured errors
provides a way for researchers to easily change the reported error text

This work will require a lot of coordination between the GUI, system, and research team to communicate what errors they are seeing and how they believe they should be handled.

INITIAL TECHNICAL DESIGN

copied from !245

reporting errors from code

First import ERROR from 'modules/error-mgr' in the module you're adding to the error reporting system.

Your code can use try/catch with this format:

try {
  const script_tokens = TRANSPILER.TextToScript(suspiciousText);
  const program = TRANSPILER.CompileScript(script_tokens);
} catch (caught) {
  ERROR(`error detected`,{
    source:'compiler',
    where: 'name-of-module, function',
    data: { suspiciousText },
    caught
  }
}

The ERROR method logs the error and contextual information, and rethrows the passed caught error object back up the chain IF "system wide error handling" is enabled by the SYSTEM_ENABLE flag defined in the modules/error-mgr source. If this flag is off, the error is just logged by the error is not rethrown so things can sort of run further, but it's unlikely it will do so cleanly.

After an error is logged, the system waits for 1500 milliseconds before throwing an overlay up on the browser window telling you that an error has occurred, and what to do about it.

checking error status (WIP)

For modules that care whether an error has happened or not, use code that look like this:

import { ERR_MGR } from 'modules/error-mgr'

function mySpecialCode() {
  // stuff that could make errors happen in here
}

if (!ERR_MGR) mySpecialCode();
else try {
  mySpecialCode()
} catch (caught) {
  ERR_MGR(`an error occurred`, {   
    source:'compiler',
    where: 'name-of-module, function',
    data: { suspiciousText },
    caught
  }
}

This awkward syntax is used to make two versions of the code that is run with the try/catch wrapper. ERR_MGR will be valid if SYSTEM_ENABLE is set true in modules/error-mgr, undefined if not. This isn't a great solution, so we'll see what we can do to make it more streamlined.

CONDITIONS CURRENTLY CHECKED AND TRAPPED

Here are the current cases that the error manager is now trying to detect during operation

[x] wrap ManifestLoader JSON.parse() with try/catch and report to ERROR manager (malformed JSON in gemprj)
[x] wrap ProjectLoader JSON.parse() with try/catch and report to ERROR manager (missing gemprj fields)
[x] wrap ValidateStatement with try/catch for generic crash, forward bad VSDToken errors through ERROR manager
[x] wrap Tokenize with try/catch forward to ERROR manager (mismatched blocks)
[x] wrap Evaluate with try/catch forward to ERROR manager (bad expression)
[x] wrap users of CompileBlueprint with try/catch and forward to ERROR manager (non-compiling syntactically-correct GEMSCRIPT)
[x] wrap users of CompileScript with try/catch and forward to ERROR manager (error in round script)
[x] wrap initScript compile code with try/catch and forward to ERROR manager (error in bpdef init script)

In GitLab by @daveseah on Jul 19, 2022, 17:06

changed target branch from dev to dev-next-gui

In GitLab by @daveseah on Jul 20, 2022, 13:37

added 2 commits

e0939ca4 - gui-errhelp: main needs to check ERR_MGR flag properly
31d2fd1a - gui-errhelp: PROGRAM INIT is now default

Compare with previous version

In GitLab by @daveseah on Jul 20, 2022, 14:23

added 1 commit

6528a6cc - dev-next-gui-errhelp: remove bundler warning if program-out already is set to same out

Compare with previous version

In GitLab by @daveseah on Jul 27, 2022, 10:56

changed target branch from dev-next-gui to dev-next

In GitLab by @daveseah on Jul 27, 2022, 17:40

added 75 commits

6528a6cc...21f980ca - 74 commits from branch dev-next
ad292fde - Merge branch 'dev-next' into dev-next-gui-errhelp

Compare with previous version

theRAPTLab / gsgo