Refactor error handling and recategorize errors

[fxamacker]

Changes

This PR improves error handling and error passing between Atree, Cadence, and FVM.

• Categorize errors into FatalError, ExternalError, and UserError.
• Implement Unwrap() for FatalError, ExternalError, and UserError.
• Add tests for error categorization, etc.

Closes #285 Updates https://github.com/onflow/cadence/issues/1255

Details

Errors are categorized as early as feasible. Changes only affect the error paths (avoids affecting the happy paths).

Here, the word "pluggable" describes interfaces or callback functions that might be implemented by packages external to Atree.

Basically, when Atree:

• Creates an error: create either FatalError or UserError.
• Receives error from known packages: wrap the error in FatalError or UserError.
• Receives error from pluggable interfaces or callback functions: wrap the error as ExternalError only if it is not categorized already.
• Receives error from its own functions: there's no need to categorize error because it's already categorized, so just wrap the error with more context if needed.

Pluggable interfaces:

• Ledger
• BaseStorage
• SlabStorage
• TypeInfo
• Value
• Storable
• DigesterBuilder
• Digester

Pluggable callback functions:

• StorableDecoder
• TypeInfoDecoder
• ValueComparator
• StorableComparator
• HashInputProvider
• ArrayElementProvider
• MapElementProvider
• ArrayIterationFunc
• MapEntryIterationFunc
• MapElementIterationFunc

  ---

• [x] Targeted PR against main branch
• [x] Linked to Github issue with discussion and accepted design OR link to spec that describes this work
• [x] Code follows the standards mentioned here
• [x] Updated relevant documentation
• [x] Re-reviewed Files changed in the Github PR explorer
• [x] Added appropriate labels

[codecov-commenter]

Codecov Report

Merging #295 (8db5046) into main (c836704) will decrease coverage by 4.44%. The diff coverage is 15.74%.

@@            Coverage Diff             @@
##             main     #295      +/-   ##
==========================================
- Coverage   69.05%   64.62%   -4.44%     
==========================================
  Files          14       14              
  Lines        7314     7991     +677     
==========================================
+ Hits         5051     5164     +113     
- Misses       1629     2152     +523     
- Partials      634      675      +41     

Impacted Files	Coverage Δ
array_debug.go	51.65% <0.00%> (-2.52%)	:arrow_down:
encode.go	79.36% <0.00%> (-1.29%)	:arrow_down:
hash.go	69.86% <0.00%> (-1.97%)	:arrow_down:
map_debug.go	51.67% <0.00%> (-3.84%)	:arrow_down:
array.go	69.86% <14.28%> (-6.29%)	:arrow_down:
map.go	66.79% <14.81%> (-4.89%)	:arrow_down:
basicarray.go	49.78% <15.15%> (-3.77%)	:arrow_down:
storage.go	74.52% <15.47%> (-4.90%)	:arrow_down:
storable_slab.go	45.45% <25.00%> (-4.55%)	:arrow_down:
storable.go	54.41% <30.43%> (-11.17%)	:arrow_down:
... and 1 more

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[fxamacker]

go test -cover reports 81.3% but Codecov is ~16% lower than what is reported by Go tooling.