The library errors provides type safe constructs to annotate Golang errors with the context and handle opaque errors without the boilerplate.
The library is inspired by the post -- Assert Golang Errors For Behavior: Everything You Need To Know Before Making Robust and Scalable Error Handling and its recommendation to deal with opaque errors -- failure does not have global catastrophic impacts but local functionality is impaired, execution of current control flow is terminated and incorrect results are returned.
Opaque errors is a classical scenario of error handling in Golang, which is advertised by the majority of online publications. The code block knows that an error occurred. It does not have the ability to inspect error details, it only knows about the successful or unsuccessful completion of the called function. This error bubbles along the call stack until it is handler by the application.
func foo() (*Bar, error) {
val, err := db.dynamo.GetItem(ctx, req)
if err != nil {
return nil, err
}
// continue happy path
}The debugging of opaque error handling becomes a difficult job because it violates annotate errors with the context recommendation. The Go Programming Language recommends inclusion of the context to the error path using fmt.Errorf.
func foo() (*Bar, error) {
val, err := db.dynamo.GetItem(ctx, req)
if err != nil {
return nil, fmt.Errorf("[foo] dynamodb i/o failed: %w", err)
}
// continue happy path
}In the context of a large application, fmt.Errorf("[foo] dynamodb i/o failed: %w", err) would be repeated a gazillion times for each service call to dynamo, any refactoring of the error text or context structure becomes a tedious job - the type system would not help at all because fmt.Errorf is not type safe.
Usage of this library to define a type safe wrapping of errors is the better approach to annotate error context:
// produces an error message
// [foo] dynamodb i/o failed: original error
const errDynamoIO = faults.Type("dynamodb i/o failed")
func foo() (*Bar, error) {
val, err := db.dynamo.GetItem(ctx, req)
if err != nil {
return nil, errDynamoIO.New(err)
}
// continue happy path
}The latest version of the library is available at main branch of this repository. All development, including new features and bug fixes, take place on the main branch using forking and pull requests as described in contribution guidelines. The stable version is available via Golang modules.
import "github.com/fogfish/faults"
const (
// create basic error context
errSomeA = faults.Type("something is failed")
// create error context with arguments
errSomeB = faults.Type("something is failed %s")
// create "fast" error context, would not annotate error with call stack
errSomeC = faults.Fast("something is failed")
// create error context with type safe arguments
errSomeD = faults.Safe1[int]("something %d is failed")
errSomeE = faults.Safe2[int, string]("something %d is failed %s")
)The library uses the runtime package to discover function context and inject it into the error. If you are developing a highly loaded system, usage of runtime package might cause about 75% of the loss of the error path capacity. Therefore, the library support a "fast" variant of the type faults.Fast, which omits usage of runtime package internally.
The library is MIT licensed and accepts contributions via GitHub pull requests:
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Added some feature') - Push to the branch (
git push origin my-new-feature) - Create new Pull Request
The build and testing process requires Go version 1.18 or later.
build and test library.
git clone https://github.com/fogfish/faults
cd errors
go test
go test -run=^$ -bench=. -cpu 1 -benchtime=1sThe commit message helps us to write a good release note, speed-up review process. The message should address two question what changed and why. The project follows the template defined by chapter Contributing to a Project of Git book.
If you experience any issues with the library, please let us know via GitHub issues. We appreciate detailed and accurate reports that help us to identity and replicate the issue.
