feat: Create errors package

errors/defraError.go

@@ -0,0 +1,90 @@
+// Copyright 2022 Democratized Data Foundation
+//
+// Use of this software is governed by the Business Source License
+// included in the file licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with
+// the Business Source License, use of this software will be governed
+// by the Apache License, Version 2.0, included in the file
+// licenses/APL.txt.
+
+package errors
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"strings"
+)
+
+const StackKey string = "Stack"
+
+var (
+	_ error         = (*defraError)(nil)
+	_ fmt.Formatter = (*defraError)(nil)
+)
+
+type defraError struct {
+	message    string
+	inner      error
+	stacktrace string
+	kvs        []KV
+}
+
+func (e *defraError) Error() string {
+	builder := strings.Builder{}
+	builder.WriteString(e.message)
+	if len(e.kvs) > 0 {
+		builder.WriteString(".")
+	}
+
+	for i, kv := range e.kvs {
+		builder.WriteString(" ")
+		builder.WriteString(kv.key)
+		builder.WriteString(": ")
+		builder.WriteString(fmt.Sprint(kv.value))
+		if i < len(e.kvs)-1 {
+			builder.WriteString(",")
+		}
+	}
+
+	return builder.String()
+}
+
+func (e *defraError) Is(other error) bool {
+	switch otherTyped := other.(type) { //nolint:errorlint
+	case *defraError:
+		return e.message == otherTyped.message
+	default:
+		otherString := other.Error()
+		return e.message == otherString || e.Error() == otherString || errors.Is(e.inner, other)
+	}
+}
+
+func (e *defraError) Unwrap() error {
+	return e.inner
+}
+
+// Format writes the error into the given state.
+//
+// Currently the following runes are supported: `v[+]` (+ also writes out the stacktrace), `s`, `q`.
+func (e *defraError) Format(f fmt.State, verb rune) {
+	errorString := e.Error()
+	switch verb {
+	case 'v':
+		_, _ = io.WriteString(f, errorString)
+
+		if f.Flag('+') {
+			if len(errorString) > 0 && errorString[len(errorString)-1] != '.' {
+				_, _ = io.WriteString(f, ".")
+			}
+
+			_, _ = io.WriteString(f, " "+StackKey+": ")
+			_, _ = io.WriteString(f, e.stacktrace)
+		}
+	case 's':
+		_, _ = io.WriteString(f, errorString)
+	case 'q':
+		_, _ = fmt.Fprintf(f, "%q", errorString)
+	}
+}

errors/errors.go

@@ -0,0 +1,79 @@
+// Copyright 2022 Democratized Data Foundation
+//
+// Use of this software is governed by the Business Source License
+// included in the file licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with
+// the Business Source License, use of this software will be governed
+// by the Apache License, Version 2.0, included in the file
+// licenses/APL.txt.
+
+package errors
+
+import (
+	"bytes"
+	"runtime"
+
+	goErrors "github.com/go-errors/errors"
+)
+
+// todo: make this configurable:
+// https://github.com/sourcenetwork/defradb/issues/733
+const MaxStackDepth int = 50
+
+type KV struct {
+	key   string
+	value interface{}
+}
+
+func NewKV(key string, value interface{}) KV {
+	return KV{
+		key:   key,
+		value: value,
+	}
+}
+
+// New creates a new Defra error, suffixing any key-value
+// pairs provided.
+//
+// A stacktrace will be yielded if formatting with a `+`, e.g `fmt.Sprintf("%+v", err)`.
+func New(message string, keyvals ...KV) error {
+	return newError(message, keyvals...)
+}
+
+// Wrap creates a new error of the given message that contains
+// the given inner error, suffixing any key-value pairs provided.
+func Wrap(message string, inner error, keyvals ...KV) error {
+	err := newError(message, keyvals...)
+	err.inner = inner
+	return err
+}
+
+func newError(message string, keyvals ...KV) *defraError {
+	return withStackTrace(message, keyvals...)
+}
+
+func withStackTrace(message string, keyvals ...KV) *defraError {
+	stackBuffer := make([]uintptr, MaxStackDepth)
+	// Skip the first X frames as they are part of this library (and dependencies) and are
+	// best hidden.
+	length := runtime.Callers(4, stackBuffer[:])
+	stack := stackBuffer[:length]
+	stackText := toString(stack)
+
+	return &defraError{
+		message:    message,
+		stacktrace: stackText,
+		kvs:        keyvals,
+	}
+}
+
+func toString(stack []uintptr) string {
+	buf := bytes.Buffer{}
+
+	for _, pc := range stack {
+		frame := goErrors.NewStackFrame(pc)
+		buf.WriteString(frame.String())
+	}
+	return buf.String()
+}

errors/errors_test.go

@@ -0,0 +1,168 @@
+// Copyright 2022 Democratized Data Foundation
+//
+// Use of this software is governed by the Business Source License
+// included in the file licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with
+// the Business Source License, use of this software will be governed
+// by the Apache License, Version 2.0, included in the file
+// licenses/APL.txt.
+
+package errors
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestErrorIs(t *testing.T) {
+	const errorMessage string = "gndjdhs"
+
+	err := New(errorMessage)
+
+	assert.ErrorIs(t, err, errors.New(errorMessage))
+}
+
+func TestErrorIsDefraError(t *testing.T) {
+	const errorMessage string = "gndjdhs"
+
+	err := New(errorMessage)
+
+	assert.ErrorIs(t, err, New(errorMessage))
+}
+
+func TestErrorWrap(t *testing.T) {
+	const errorMessage1 string = "gndjdhs"
+	const errorMessage2 string = "nhdfbgshna"
+
+	err1 := New(errorMessage1)
+	err2 := Wrap(errorMessage2, err1)
+
+	assert.ErrorIs(t, err2, errors.New(errorMessage1))
+}
+
+func TestErrorUnwrap(t *testing.T) {
+	const errorMessage1 string = "gndjdhs"
+	const errorMessage2 string = "nhdfbgshna"
+
+	err1 := New(errorMessage1)
+	err2 := Wrap(errorMessage2, err1)
+
+	unwrapped := errors.Unwrap(err2)
+
+	assert.ErrorIs(t, unwrapped, errors.New(errorMessage1))
+}
+
+func TestErrorAs(t *testing.T) {
+	const errorMessage1 string = "gndjdhs"
+	const errorMessage2 string = "nhdfbgshna"
+
+	err1 := New(errorMessage1)
+	err2 := fmt.Errorf("%s: %w", errorMessage2, err1)
+
+	target := &defraError{}
+	isErr1 := errors.As(err2, &target)
+
+	assert.True(t, isErr1)
+	assert.ErrorIs(t, target, errors.New(errorMessage1))
+}
+
+func TestErrorFmts(t *testing.T) {
+	const errorMessage string = "gndjdhs"
+
+	err := New(errorMessage)
+	result := fmt.Sprintf("%s", err)
+
+	assert.Equal(t, errorMessage, result)
+}
+
+func TestErrorFmtq(t *testing.T) {
+	const errorMessage string = "gndjdhs"
+
+	err := New(errorMessage)
+	result := fmt.Sprintf("%q", err)
+
+	assert.Equal(t, "\""+errorMessage+"\"", result)
+}
+
+func TestErrorFmtvWithoutStacktrace(t *testing.T) {
+	const errorMessage string = "gndjdhs"
+
+	err := New(errorMessage)
+	result := fmt.Sprintf("%v", err)
+
+	assert.Equal(t, errorMessage, result)
+}
+
+func TestErrorFmtsWithKvp(t *testing.T) {
+	const errorMessage string = "gndjdhs"
+
+	err := New(errorMessage, NewKV("Kv1", 1))
+	result := fmt.Sprintf("%s", err)
+
+	assert.Equal(t, errorMessage+". Kv1: 1", result)
+}
+
+func TestErrorFmtsWithManyKvps(t *testing.T) {
+	const errorMessage string = "gndjdhs"
+
+	err := New(errorMessage, NewKV("Kv1", 1), NewKV("Kv2", "2"))
+	result := fmt.Sprintf("%s", err)
+
+	assert.Equal(t, errorMessage+". Kv1: 1, Kv2: 2", result)
+}
+
+func TestErrorFmtvWithStacktrace(t *testing.T) {
+	const errorMessage string = "gndjdhs"
+
+	err := New(errorMessage)
+	result := fmt.Sprintf("%+v", err)
+
+	/*
+		The Go test flag `-race` messes with the stacktrace causing this function's frame to be ommited from
+		the stacktrace, as our CI runs with the `-race` flag, these assertions need to be disabled.
+
+		// Assert that the first line starts with the error message and contains this [test] function's stacktrace-line -
+		// including file, line number, and function reference. An exact string match should not be used as the stacktrace
+		// is machine dependent.
+		assert.Regexp(t, fmt.Sprintf("^%s\\. Stack: .*\\/defradb\\/errors\\/errors_test\\.go:[0-9]+ \\([a-zA-Z0-9]*\\)", errorMessage), result)
+		// Assert that the error contains this function's name, and a print-out of the generating line.
+		assert.Regexp(t, "TestErrorFmtvWithStacktrace: err := Error\\(errorMessage\\)", result)
+	*/
+
+	// As noted above, we cannot assert that this function's stack frame is included in the trace,
+	// however we should still assert that the error message is present.
+	assert.Regexp(t, fmt.Sprintf("^%s\\. Stack: ", errorMessage), result)
+
+	// Assert that the next line of the stacktrace is also present.
+	assert.Regexp(t, ".*\\/testing/testing.go:[0-9]+ \\([a-zA-Z0-9]*\\)", result)
+}
+
+func TestErrorFmtvWithStacktraceAndKvps(t *testing.T) {
+	const errorMessage string = "gndjdhs"
+
+	err := New(errorMessage, NewKV("Kv1", 1), NewKV("Kv2", "2"))
+	result := fmt.Sprintf("%+v", err)
+
+	/*
+		The Go test flag `-race` messes with the stacktrace causing this function's frame to be ommited from
+		the stacktrace, as our CI runs with the `-race` flag, these assertions need to be disabled.
+
+		// Assert that the first line starts with the error message and contains this [test] function's stacktrace-line -
+		// including file, line number, and function reference. An exact string match should not be used as the stacktrace
+		// is machine dependent.
+		assert.Regexp(t, fmt.Sprintf("^%s\\. Kv1: 1, Kv2: 2\\. Stack: .*\\/defradb\\/errors\\/errors_test\\.go:[0-9]+ \\([a-zA-Z0-9]*\\)", errorMessage), result)
+		// Assert that the error contains this function's name, and a print-out of the generating line.
+		assert.Regexp(t, "TestErrorFmtvWithStacktraceAndKvps: err := Error\\(errorMessage\\)", result)
+	*/
+
+	// As noted above, we cannot assert that this function's stack frame is included in the trace,
+	// however we should still assert that the error message is present.
+	assert.Regexp(t, fmt.Sprintf("^%s\\. Kv1: 1, Kv2: 2\\. Stack: ", errorMessage), result)
+
+	// Assert that the next line of the stacktrace is also present.
+	assert.Regexp(t, ".*\\/testing/testing.go:[0-9]+ \\([a-zA-Z0-9]*\\)", result)
+}

go.mod

@@ -9,6 +9,7 @@ require (
 	github.com/fxamacker/cbor/v2 v2.4.0
 	github.com/go-chi/chi/v5 v5.0.7
 	github.com/go-chi/cors v1.2.1
+	github.com/go-errors/errors v1.0.1
 	github.com/gogo/protobuf v1.3.2
 	github.com/graphql-go/graphql v0.8.0
 	github.com/hsanjuan/ipfs-lite v1.4.1

go.sum

@@ -265,7 +265,10 @@ github.com/go-chi/chi/v5 v5.0.7/go.mod h1:DslCQbL2OYiznFReuXYUmQ2hGd1aDpCnlMNITL
 github.com/go-chi/cors v1.2.1 h1:xEC8UT3Rlp2QuWNEr4Fs/c2EAGVKBwy/1vHx3bppil4=
 github.com/go-chi/cors v1.2.1/go.mod h1:sSbTewc+6wYHBBCW7ytsFSn836hqM7JxpglAy2Vzc58=
 github.com/go-delve/delve v1.5.0/go.mod h1:c6b3a1Gry6x8a4LGCe/CWzrocrfaHvkUxCj3k4bvSUQ=
+github.com/go-errors/errors v1.0.1 h1:LUHzmkK3GUKUrL/1gfBUxAHzcev3apQlezX/+O7ma6w=
 github.com/go-errors/errors v1.0.1/go.mod h1:f4zRHt4oKfwPJE5k8C9vpYG+aDHdBFUsgrm6/TyX73Q=
+github.com/go-errors/errors v1.4.2 h1:J6MZopCL4uSllY1OfXM374weqZFFItUbrImctkmUxIA=
+github.com/go-errors/errors v1.4.2/go.mod h1:sIVyrIiJhuEF+Pj9Ebtd6P/rEYROXFi3BopGUQ5a5Og=
 github.com/go-gl/glfw v0.0.0-20190409004039-e6da0acd62b1/go.mod h1:vR7hzQXu2zJy9AVAgeJqvqgH9Q5CA+iKCZ2gyEVpxRU=
 github.com/go-gl/glfw/v3.3/glfw v0.0.0-20191125211704-12ad95a8df72/go.mod h1:tQ2UAYgL5IevRw8kRxooKSPJfGvJ9fJQFa0TUsXzTg8=
 github.com/go-gl/glfw/v3.3/glfw v0.0.0-20200222043503-6f7a984d4dc4/go.mod h1:tQ2UAYgL5IevRw8kRxooKSPJfGvJ9fJQFa0TUsXzTg8=