Initial open source release of go-errors.

Author: seeruk

.editorconfig

@@ -0,0 +1,16 @@
+; indicate this is the root of the project
+root = true
+
+[*]
+charset = utf-8
+end_of_line = LF
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[Makefile]
+indent_style = tab
+
+[*.go]
+indent_style = tab

.gitignore

@@ -0,0 +1,6 @@
+# Test binary, build with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+*.svg

NOTES.md

@@ -0,0 +1,34 @@
+# Notes
+
+## Output
+
+Errors are only used in a few places:
+
+* Programmatically, i.e. checking the kind of an error. No output.
+* In logs, i.e. when they have bubbled up through the application.
+* Output to the user, i.e. how a web application might respond, or perhaps more likely with Go, in 
+an API response.
+
+Programmatically, we don't really have any issues. We are only looking for an error kind. This is a 
+simple comparison through the stack.
+
+In logs, we are by far more likely to use a message, a stack trace, and also log the fields of all
+errors as structured log fields. This part is fine really, we'll have all of the information we need
+and it should work fine in Kibana too. The message is a little bit pointless, but might make it 
+easier to filter for certain top-level errors. By providing fields as a generic map, it also means
+we have a consistent format for submitting structured errors as logs, no matter what information is
+in the error.
+
+Finally, errors that are output to the user. So, most of the time we can probably get away with some
+kind of generic "an internal error occurred, contact someone @ wherever" kind of messages. What
+about those times where we might want a more structured error format? Really we're talking about two
+distinct concepts; errors, and error responses. Given that we have fields on errors, we should be
+able to use that to build error responses if we need to. We can base our expectations surrounding
+the fields that should be present on an error on the kind of error that is encountered. In other 
+words, we could make an error kind like `deals: submission validation`, and along with that kind of 
+error, always make sure we set a certain set of fields. For structs that need to be attached as 
+fields we can still make use of the fields.
+
+This does introduce another issue; what if we don't want to log all fields? Well then in that case,
+they could always be removed. If we can expect certain fields to be there, we can expect them and 
+then remove them too. Simple really.

README.md

@@ -0,0 +1,25 @@
+# go-errors
+
+This package aims to provide flexible general-purpose error handling functionality, with the 
+following specific features in mind:
+
+* **Error wrapping**: Allowing an error's cause to be preserved along with additional information.
+* **Stack tracing**: Allowing the path taken to return an error to be easily identified.
+* **Structured fields**: Allowing errors to be logged with additional contextual information.
+
+This library has built upon the mistakes we've made and lessons we've learnt with regards to error
+handling at Icelolly whilst working on our internal APIs. This library was inspired by approaches 
+found elsewhere in the community, most notably the approach found in [Upspin][1].
+
+## Example
+
+An example of usage can be found in the `example/` directory. It showcases creating errors, wrapping
+them, handling different kinds of errors, and dealing with things like logging.
+
+## See More
+
+* https://github.com/upspin/upspin/tree/master/errors
+* https://middlemost.com/failure-is-your-domain/
+
+
+[1]: https://github.com/upspin/upspin/blob/master/errors/errors.go#L23

errors.go

@@ -0,0 +1,300 @@
+package errors
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"runtime"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+// Kind is simply a string, but it allows New to function the way it does, and limits what can be
+// passed as the kind of an error to things defined as actual error kinds.
+type Kind string
+
+// Error is a general-purpose error type, providing much more contextual information and utility
+// when compared to the built-in error interface.
+type Error struct {
+	// Kind can be used as a sort of pseudo-type that check on. It's a useful mechanism for avoiding
+	// "sentinel" errors, or for checking an error's type. Kind is defined as a string so that error
+	// kinds can be defined in other packages.
+	Kind Kind
+
+	// Message is a human-readable, user-friendly string. Unlike caller, Message is really intended
+	// to be user-facing, i.e. safe to send to the front-end.
+	Message string
+
+	// Cause is the previous error. The error that triggered this error. If it is nil, then the root
+	// cause is this Error instance. If Cause is not nil, but also not of type Error, then the root
+	// cause is the error in Cause.
+	Cause error
+
+	// Fields is a general-purpose map for storing key/value information. Useful for providing
+	// additional structured information in logs.
+	Fields map[string]interface{}
+
+	// caller is the function that was called when this error occurred. Useful for identifying where
+	// an error occurred, or providing information to developers (i.e. this should not be revealed
+	// or used in responses / sent to the front-end). This may be something as simple as the method
+	// name being called, or perhaps include more information to do with parameters.
+	caller string
+
+	// Stack location information.
+	file string
+	line int
+}
+
+// Error satisfies the standard library's error interface. It returns a message that should be
+// useful as part of logs, as that's where this method will likely be used most, including the
+// caller, and the message, for the whole stack.
+func (e *Error) Error() string {
+	return e.format(false)
+}
+
+// Format allows this error to be formatted differently, depending on the needs of the developer.
+// The different formatting options made available are:
+//
+// %v:  Standard formatting: shows callers, and shows messages, for the whole stack.
+// %+v: Verbose formatting: shows callers, and shows messages, for the whole stack, with file and
+//      line, information, across multiple lines.
+func (e *Error) Format(s fmt.State, c rune) {
+	if c == 'v' && s.Flag('+') {
+		io.WriteString(s, e.format(true))
+		return
+	}
+
+	io.WriteString(s, e.format(false))
+}
+
+// WithFields appends a set of key/value pairs to the error's field list.
+func (e *Error) WithFields(kvs ...interface{}) *Error {
+	kvc := len(kvs)
+
+	if kvc%2 != 0 {
+		Fatal(New(fmt.Sprintf(
+			"errors: invalid argument count for WithFields, expected even number of fields, got %d",
+			kvc,
+		)))
+	}
+
+	if e.Fields == nil {
+		e.Fields = make(map[string]interface{})
+	}
+
+	for i := 0; i < kvc; i = i + 2 {
+		key, ok := kvs[i].(string)
+		if !ok {
+			Fatal(New(fmt.Sprintf("errors: invalid type for key passed to WithFields at index %d", i)))
+		}
+
+		e.Fields[key] = kvs[i+1]
+	}
+
+	return e
+}
+
+// WithField appends a key/value pair to the error's field list.
+func (e *Error) WithField(fieldKey string, fieldValue interface{}) *Error {
+	if e.Fields == nil {
+		e.Fields = make(map[string]interface{})
+	}
+
+	e.Fields[fieldKey] = fieldValue
+
+	return e
+}
+
+// format returns this error, and all previous errors, as a string. The result can be represented as
+// a multi-line stack-trace by setting `asStack` to true.
+func (e *Error) format(asStack bool) string {
+	// Buffer is shared between recursive calls to avoid some unnecessary re-allocations.
+	buf := bytes.Buffer{}
+
+	e.formatAccumulator(&buf, asStack, false)
+
+	return buf.String()
+}
+
+// formatAccumulator is a recursive error formatting function.
+func (e *Error) formatAccumulator(buf *bytes.Buffer, asStack, isCause bool) {
+	if asStack && !isCause {
+		buf.WriteString("Error")
+	}
+
+	if e.caller != "" {
+		pad(buf, ": ")
+		buf.WriteString("[")
+		buf.WriteString(e.caller)
+		buf.WriteString("]")
+	}
+
+	if e.Message != "" {
+		pad(buf, ": ")
+		buf.WriteString(e.Message)
+	}
+
+	if e.Kind != "" {
+		pad(buf, " ")
+		buf.WriteString("(")
+		buf.WriteString(string(e.Kind))
+		buf.WriteString(")")
+	}
+
+	if asStack {
+		buf.WriteString("\n")
+		buf.WriteString("    ")
+		buf.WriteString("File: \"")
+		buf.WriteString(e.file)
+		buf.WriteString("\", line ")
+		buf.WriteString(strconv.Itoa(e.line))
+		buf.WriteString("\n")
+
+		if len(e.Fields) > 0 {
+			buf.WriteString("    ")
+			buf.WriteString("With fields:\n")
+
+			fieldKeys := make([]string, 0, len(e.Fields))
+			for k := range e.Fields {
+				fieldKeys = append(fieldKeys, k)
+			}
+
+			sort.Strings(fieldKeys)
+
+			for _, k := range fieldKeys {
+				buf.WriteString("    ")
+				buf.WriteString("- \"")
+				buf.WriteString(k)
+				buf.WriteString("\": ")
+				buf.WriteString(fmt.Sprintf("%v", e.Fields[k]))
+				buf.WriteString("\n")
+			}
+		}
+	}
+
+	if e.Cause != nil {
+		if !asStack {
+		} else {
+			buf.WriteString("Caused by")
+		}
+
+		switch cause := e.Cause.(type) {
+		case *Error:
+			cause.formatAccumulator(buf, asStack, true)
+		case error:
+			pad(buf, ": ")
+			buf.WriteString(cause.Error())
+		}
+	}
+}
+
+// pad takes a buffer and if it's not empty, writes the given padding string to it.
+func pad(buf *bytes.Buffer, pad string) {
+	if buf.Len() > 0 {
+		buf.WriteString(pad)
+	}
+}
+
+// New returns a new error. New accepts a variadic list of arguments, but at least one argument must
+// be specified, otherwise New will panic. New will also panic if an unexpected type is given to it.
+// Each field that can be set on an *Error is of a different type, meaning we can switch on the type
+// of each argument, and still know which field to set on the error, leaving New as a very flexible
+// function that is also not overly verbose to call.
+//
+// Example usage:
+//
+//    // Create the initial error, maybe this would be returned from some function.
+//    err := errors.New(ErrKindTimeout, "client: HTTP request timed out")
+//    // Wrap an existing error. It can be a regular error too. Also, set a field.
+//    err = errors.New(err, "accom: fetch failed", errors.WithField("tti_code", ttiCode))
+//
+// As you can see, this usage is flexible, and includes the ability to construct pretty much any
+// kind of error your application should need.
+func New(args ...interface{}) *Error {
+	err := newError(args...)
+
+	updateLocation(err)
+	updateCaller(err)
+
+	return err
+}
+
+// newError creates a new *Error instance, returning it as an *Error, so that we can operate on it
+// internally without having to cast back to *Error.
+func newError(args ...interface{}) *Error {
+	if len(args) == 0 {
+		panic("errors: call to errors.New with no arguments")
+	}
+
+	err := &Error{}
+	for _, arg := range args {
+		switch v := arg.(type) {
+		case Kind:
+			err.Kind = v
+		case string:
+			err.Message = v
+		case *Error:
+			// Can't dereference a nil pointer, so bail early. This is a developer error.
+			if v == nil {
+				panic("errors: attempted to wrap nil *Error")
+			}
+
+			// Make a shallow copy of the value, so that we don't change the original error.
+			cv := *v
+			err.Cause = &cv
+		case error:
+			err.Cause = v
+		case map[string]interface{}:
+			err.Fields = v
+		default:
+			panic(fmt.Sprintf("errors: bad call to errors.New: unknown type %T, value %v", arg, arg))
+		}
+	}
+
+	return err
+}
+
+// Wrap constructs an error the same way that New does, the only difference being that if the given
+// cause is nil, this function will return nil. This makes it quite handy in return lines at the end
+// of functions. Wrap conveys it's meaning a little more than New does when you are wrapping other
+// errors.
+func Wrap(cause error, args ...interface{}) *Error {
+	if cause == nil {
+		return nil
+	}
+
+	// Add the cause to the end of args so that it is definitely set as the cause.
+	args = append(args, cause)
+	err := newError(args...)
+
+	// We have to set these again, as they'll be at the wrong depth now.
+	updateLocation(err)
+	updateCaller(err)
+
+	return err
+}
+
+// updateCaller takes an error and sets the calling function information on it. Safe to use in error
+// constructors, but no deeper.
+func updateCaller(err *Error) {
+	fpcs := make([]uintptr, 1)
+	ptr := runtime.Callers(3, fpcs)
+	if ptr == 0 {
+		return
+	}
+
+	fun := runtime.FuncForPC(fpcs[0] - 1)
+	if fun != nil {
+		funcName := strings.Split(fun.Name(), "/")
+		err.caller = funcName[len(funcName)-1]
+	}
+}
+
+// updateLocation takes an error and sets file and line information on it. Safe to use in error
+// constructors, but no deeper.
+func updateLocation(err *Error) {
+	_, file, line, _ := runtime.Caller(2)
+	err.file = file
+	err.line = line
+}