A drop-in replacement for Go errors, with some added sugar! Unwrap user-friendly messages, HTTP status code, easy wrapping with multiple error types.

Overview

errors gopher

Build Status codecov Go Report Card Maintainability

Errors

Errors package is a drop-in replacement of the built-in Go errors package with no external dependencies. It lets you create errors of 11 different types which should handle most of the use cases. Some of them are a bit too specific for web applications, but useful nonetheless. Following are the primary features of this package:

  1. Multiple (11) error types
  2. User friendly message
  3. File & line number prefixed to errors
  4. HTTP status code and user friendly message (wrapped messages are concatenated) for all error types
  5. Helper functions to generate each error type
  6. Helper function to get error Type, error type as int, check if error type is wrapped anywhere in chain

In case of nested errors, the messages & errors are also looped through the full chain of errors.

Prerequisites

Go 1.13+

Available error types

  1. TypeInternal - is the error type for when there is an internal system error. e.g. Database errors
  2. TypeValidation - is the error type for when there is a validation error. e.g. invalid email address
  3. TypeInputBody - is the error type for when the input data is invalid. e.g. invalid JSON
  4. TypeDuplicate - is the error type for when there's duplicate content. e.g. user with email already exists (when trying to register a new user)
  5. TypeUnauthenticated - is the error type when trying to access an authenticated API without authentication
  6. TypeUnauthorized - is the error type for when there's an unauthorized access attempt
  7. TypeEmpty - is the error type for when an expected non-empty resource, is empty
  8. TypeNotFound - is the error type for an expected resource is not found. e.g. user ID not found
  9. TypeMaximumAttempts - is the error type for attempting the same action more than an allowed threshold
  10. TypeSubscriptionExpired - is the error type for when a user's 'paid' account has expired
  11. TypeDownstreamDependencyTimedout - is the error type for when a request to a downstream dependent service times out

Helper functions are available for all the error types. Each of them have 2 helper functions, one which accepts only a string, and the other which accepts an original error as well as a user friendly message.

All the dedicated error type functions are documented here. Names are consistent with the error type, e.g. errors.Internal(string) and errors.InternalErr(error, string)

User friendly messages

More often than not, when writing APIs, we'd want to respond with an easier to undersand user friendly message. Instead of returning the raw error. And log the raw error.

There are helper functions for all the error types, when in need of setting a friendly message, there are helper functions have a suffix 'Err'. All such helper functions accept the original error and a string.

package main
import(
    "fmt"
    "github.com/bnkamalesh/errors"
)

func Bar() error {
    return fmt.Errorf("hello %s", "world!")
}

func Foo() error {
    err := Bar()
    if err != nil {
        return errors.InternalErr(err, "bar is not happy")
    }
    return nil
}

func main() {
    err := Foo()
    fmt.Println(err)
    _,msg,_ := errors.HTTPStatusCodeMessage(err)
    fmt.Println(msg)
}

File & line number prefixed to errors

A common annoyance with Go errors which most people are aware of is, figuring out the origin of the error, especially when there are nested function calls. Ever since error annotation was introduced in Go, a lot of people have tried using it to trace out an errors origin by giving function names, contextual message etc in it. e.g. fmt.Errorf("database query returned error %w", err). This errors package, whenever you call the Go error interface's Error() string function, it'll print the error prefixed by the filepath and line number. It'd look like ../Users/JohnDoe/apps/main.go:50 hello world where 'hello world' is the error message.

HTTP status code & message

The function errors.HTTPStatusCodeMessage(error) (int, string, bool) returns the HTTP status code, message, and a boolean value. The boolean is true, if the error is of type *Error from this package. If error is nested with multiple errors, it loops through all the levels and returns a single concatenated message. This is illustrated in the 'How to use?' section

How to use?

Before that, over the years I have tried error with stack trace, annotation, custom error package with error codes etc. Finally, I think this package gives the best of all worlds, for most generic usecases.

A sample was already shown in the user friendly message section, following one would show a few more scenarios.

package main

import (
	"fmt"
	"net/http"
	"time"

	"github.com/bnkamalesh/errors"
	"github.com/bnkamalesh/webgo/v4"
	"github.com/bnkamalesh/webgo/v4/middleware"
)

func bar() error {
	return fmt.Errorf("%s %s", "sinking", "bar")
}

func bar2() error {
	err := bar()
	if err != nil {
		return errors.InternalErr(err, "bar2 was deceived by bar1 :(")
	}
	return nil
}

func foo() error {
	err := bar2()
	if err != nil {
		return errors.InternalErr(err, "we lost bar2!")
	}
	return nil
}

func handler(w http.ResponseWriter, r *http.Request) {
	err := foo()
	if err != nil {
		// log the error on your server for troubleshooting
		fmt.Println(err.Error())
		// respond to request with friendly msg
		status, msg, _ := errors.HTTPStatusCodeMessage(err)
		webgo.SendError(w, msg, status)
		return
	}

	webgo.R200(w, "yay!")
}

func routes() []*webgo.Route {
	return []*webgo.Route{
		&webgo.Route{
			Name:    "home",
			Method:  http.MethodGet,
			Pattern: "/",
			Handlers: []http.HandlerFunc{
				handler,
			},
		},
	}
}

func main() {
	router := webgo.NewRouter(&webgo.Config{
		Host:         "",
		Port:         "8080",
		ReadTimeout:  15 * time.Second,
		WriteTimeout: 60 * time.Second,
	}, routes())

	router.UseOnSpecialHandlers(middleware.AccessLog)
	router.Use(middleware.AccessLog)
	router.Start()
}

webgo was used to illustrate the usage of the function, errors.HTTPStatusCodeMessage. It returns the appropriate http status code, user friendly message stored within, and a boolean value. Boolean value is true if the returned error of type *Error. Since we get the status code and message separately, when using any web framework, you can set values according to the respective framework's native functions. In case of Webgo, it wraps errors in a struct of its own. Otherwise, you could directly respond to the HTTP request by calling errors.WriteHTTP(error,http.ResponseWriter).

Once the app is running, you can check the response by opening http://localhost:8080 on your browser. Or on terminal

$ curl http://localhost:8080
{"errors":"we lost bar2!. bar2 was deceived by bar1 :(","status":500} // output

And the fmt.Println(err.Error()) generated output on stdout would be:

/Users/username/go/src/errorscheck/main.go:28 /Users/username/go/src/errorscheck/main.go:20 sinking bar

Benchmark

Benchmark run on:

Screenshot 2020-07-18 at 6 25 22 PM

Results

$ go version
go version go1.14.4 darwin/amd64
$ go test -bench=.
goos: darwin
goarch: amd64
pkg: github.com/bnkamalesh/errors
Benchmark_Internal-8                            	 1874256	       639 ns/op	     368 B/op	       5 allocs/op
Benchmark_InternalErr-8                         	 1612707	       755 ns/op	     368 B/op	       5 allocs/op
Benchmark_InternalGetError-8                    	 1700966	       706 ns/op	     464 B/op	       6 allocs/op
Benchmark_InternalGetErrorWithNestedError-8     	 1458368	       823 ns/op	     464 B/op	       6 allocs/op
Benchmark_InternalGetMessage-8                  	 1866562	       643 ns/op	     368 B/op	       5 allocs/op
Benchmark_InternalGetMessageWithNestedError-8   	 1656597	       770 ns/op	     400 B/op	       6 allocs/op
Benchmark_HTTPStatusCodeMessage-8               	26003678	        46.1 ns/op	      16 B/op	       1 allocs/op
BenchmarkHasType-8                              	84689433	        14.2 ns/op	       0 B/op	       0 allocs/op
PASS
ok  	github.com/bnkamalesh/errors	14.478s

Contributing

More error types, customization etc; PRs & issues are welcome!

The gopher

The gopher used here was created using Gopherize.me. Show some love to Go errors like our gopher lady here!

You might also like...
The Emperor takes care of all errors personally
The Emperor takes care of all errors personally

The Emperor takes care of all errors personally. Go's philosophy encourages to gracefully handle errors whenever possible, but some times recovering f

eris provides a better way to handle, trace, and log errors in Go 🎆

eris Package eris provides a better way to handle, trace, and log errors in Go. go get github.com/rotisserie/eris Why you'll want to switch to eris Us

Golang errors with stack trace and source fragments.
Golang errors with stack trace and source fragments.

Golang Errors with Stack Trace and Source Fragments Tired of uninformative error output? Probably this will be more convenient: Example package main

Hierarchical errors reporting done right in Golang

Hierarchical errors made right Hate seeing error: exit status 128 in the output of programs without actual explanation what is going wrong? Or, maybe,

Go tool to wrap and fix errors with the new %w verb directive
Go tool to wrap and fix errors with the new %w verb directive

errwrap Wrap and fix Go errors with the new %w verb directive. This tool analyzes fmt.Errorf() calls and reports calls that contain a verb directive t

Golang errors with stacktrace and context

merry Add context to errors, including automatic stack capture, cause chains, HTTP status code, user messages, and arbitrary values. The package is la

harvest Go errors with ease

Pears Harvest Go Errors with Ease Introduction Pears helps reduce the boilerplate and ensure correctness for common error-handling scenarios: Panic re

SupErr -- Go stdlib errors with super powers

superr SupErr -- Go stdlib errors with super powers. Pronounced super with a French accent :D Build a stack of errors compatible with Go stdlib and er

Package semerr helps to work with errors in Golang.
Package semerr helps to work with errors in Golang.

semerr Package semerr helps to work with errors in Golang. Const error An error that can be defined as const. var errMutable error = errors.New("mutab

Comments
  • [minor] `Stacktrace(err error) string` - returns a prettified stacktr…

    [minor] `Stacktrace(err error) string` - returns a prettified stacktr…

    [minor] Stacktrace(err error) string - returns a prettified stacktrace of the error [minor] StacktraceCustomFormat(msgformat string, traceFormat string, err error) string - supports using custom format [minor] RuntimeFrames(err error) - returns runtime.Frames of the error, based on combined (if nested) program counters of the error [minor] ProgramCounters(err error) []uintptr - returns combined (if nested) program counters of the error [minor] fmt.Formatter interface implementation

    opened by bnkamalesh 0
Releases(v0.9.0)
  • v0.9.0(Dec 13, 2021)

    [minor] Stacktrace(err error) string - returns a prettified stacktrace of the error [minor] StacktraceCustomFormat(msgformat string, traceFormat string, err error) string - supports using custom format [minor] RuntimeFrames(err error) - returns runtime.Frames of the error, based on combined (if nested) program counters of the error [minor] ProgramCounters(err error) []uintptr - returns combined (if nested) program counters of the error [minor] fmt.Formatter interface implementation [minor] HTTP status code and message support [minor] File & line number prefixed to errors [minor] Helper methods for different error types [minor] Helper methods with formatting support for all error types

    Source code(tar.gz)
    Source code(zip)
Owner
Kamaleshwar
Let's fix this planet, one line of code at a time.
Kamaleshwar
Wrap contains a method for wrapping one Go error with another.

Note: this code is still in alpha stage. It works but it may change subtly in the near future, depending on what comes out of golang/go#52607. Wrap.Wi

Nate Finch 4 Jun 27, 2022
Wraps the normal error and provides an error that is easy to use with net/http.

Go HTTP Error Wraps the normal error and provides an error that is easy to use with net/http. Install go get -u github.com/cateiru/go-http-error Usage

Yuto Watanabe 0 Dec 20, 2021
Common juju errors and functions to annotate errors. Based on juju/errgo

errors import "github.com/juju/errors" The juju/errors provides an easy way to annotate errors without losing the original error context. The exporte

Juju 1.3k Sep 28, 2022
Linter for errors.Is and errors.As

erris erris is a program for checking that errors are compared or type asserted using go1.13 errors.Is and errors.As functions. Install go get -u gith

Roman Budnikov 51 Mar 3, 2022
An errors package optimized for the pkg/errors package

errors An errors package optimized for the pkg/errors package Use Download and install go get github.com/dobyte/errors API // New Wrapping for errors.

Fuxiao 3 Mar 2, 2022
A Go (golang) package for representing a list of errors as a single error.

go-multierror go-multierror is a package for Go that provides a mechanism for representing a list of error values as a single error. This allows a fun

HashiCorp 1.7k Sep 25, 2022
Errors - A lib for handling error gracefully in Go

?? Errors Errors 是一个用于优雅地处理 Go 中错误的库。 Read me in English ??‍ 功能特性 优雅地处理 error,嗯,

水不要鱼 1 Jan 17, 2022
This structured Error package wraps errors with context and other info

RErr package This structured Error package wraps errors with context and other info. It can be used to enrich logging, for example with a structured l

Rohan Allison 0 Jan 21, 2022
Go error library with error portability over the network

cockroachdb/errors: Go errors with network portability This library aims to be used as a drop-in replacement to github.com/pkg/errors and Go's standar

CockroachDB 1.4k Sep 23, 2022
Error interface wrappers for Google's errdetails protobuf types, because they're handy as heck and I want to use them more

Error interface wrappers for Google's errdetails protobuf types, because they're handy as heck and I want to use them more

Claudia Hardman 1 Nov 18, 2021