initial state

Author: PeterIvanov

builder.go

@@ -0,0 +1,167 @@
+package errorx
+
+import (
+	"fmt"
+	"strconv"
+)
+
+// Utility to compose an error from type
+// Typically, a direct usage is not required: either Type methods of helpers like Decorate is sufficient
+// Only use builder if no neater alternative is available
+type ErrorBuilder struct {
+	errorType     *Type
+	message       string
+	cause         error
+	underlying    []error
+	mode          callStackBuildMode
+	isTransparent bool
+}
+
+// Created error builder from an existing error type
+func NewErrorBuilder(t *Type) *ErrorBuilder {
+	getMode := func() callStackBuildMode {
+		if t.modifiers.CollectStackTrace() {
+			return stackTraceCollect
+		} else {
+			return stackTraceOmit
+		}
+	}
+
+	return &ErrorBuilder{
+		errorType:     t,
+		mode:          getMode(),
+		isTransparent: t.modifiers.Transparent(),
+	}
+}
+
+// Provide an original cause for error
+// For non-errorx errors, a stack trace is collected
+// Otherwise, it is inherited by default, as error wrapping is typically performed 'en passe'
+// Note that even if an original error explicitly omitted the stack trace, it could be added on wrap
+func (eb *ErrorBuilder) WithCause(err error) *ErrorBuilder {
+	eb.cause = err
+	if Cast(err) != nil {
+		eb.mode = stackTraceBorrow
+	}
+
+	return eb
+}
+
+// Transparent wrap hides the current error type from the type checks and exposes the error type of the cause instead
+// The same holds true for traits, and the dynamic properties are visible from both cause and transparent wrapper
+// Note that if the cause error is non-errorx, transparency will still hold, type check against wrapper will still fail
+func (eb *ErrorBuilder) Transparent() *ErrorBuilder {
+	if eb.cause == nil {
+		panic("wrong builder usage: wrap modifier without non-nil cause")
+	}
+
+	eb.isTransparent = true
+	return eb
+}
+
+// Collect the current stack trace along with the original one, and use both in formatting
+// If the original error does not hold a stack trace for whatever reason, it will be collected it this point
+// This is typically a way to handle an error received from another goroutine - say, a worker pool
+// When stack traces overlap, formatting makes a conservative attempt not to repeat itself,
+// preserving the *original* stack trace in its entirety
+func (eb *ErrorBuilder) EnhanceStackTrace() *ErrorBuilder {
+	if eb.cause == nil {
+		panic("wrong builder usage: wrap modifier without non-nil cause")
+	}
+
+	if Cast(eb.cause) != nil {
+		eb.mode = stackTraceEnhance
+	} else {
+		eb.mode = stackTraceCollect
+	}
+
+	return eb
+}
+
+// Adds multiple additional (hidden, suppressed) related errors to be used exclusively in error output
+// Note that these errors make no other effect whatsoever: their traits, types, properties etc. are lost
+func (eb *ErrorBuilder) withUnderlyingErrors(errs ...error) *ErrorBuilder {
+	eb.underlying = append(eb.underlying, errs...)
+	return eb
+}
+
+// Provides a message for an error in flexible format, to simplify its usages
+// Without args, leaves the original message intact, so a message may be generated or provided externally
+// With args, a formatting is performed, and it is therefore expected a format string to be constant
+func (eb *ErrorBuilder) WithConditionallyFormattedMessage(message string, args ...interface{}) *ErrorBuilder {
+	if len(args) == 0 {
+		eb.message = message
+	} else {
+		eb.message = fmt.Sprintf(message, args...)
+	}
+
+	return eb
+}
+
+// Returns an error with specified params
+func (eb *ErrorBuilder) Create() *Error {
+	return &Error{
+		errorType:   eb.errorType,
+		message:     eb.message,
+		cause:       eb.cause,
+		underlying:  eb.underlying,
+		transparent: eb.isTransparent,
+		stackTrace:  eb.assembleStackTrace(),
+	}
+}
+
+type callStackBuildMode int
+
+const (
+	stackTraceCollect callStackBuildMode = 1
+	stackTraceBorrow  callStackBuildMode = 2
+	stackTraceEnhance callStackBuildMode = 3
+	stackTraceOmit    callStackBuildMode = 4
+)
+
+func (eb *ErrorBuilder) assembleStackTrace() *stackTrace {
+	switch eb.mode {
+	case stackTraceCollect:
+		return eb.collectOriginalStackTrace()
+	case stackTraceBorrow:
+		return eb.borrowStackTraceFromCause()
+	case stackTraceEnhance:
+		return eb.combineStackTraceWithCause()
+	case stackTraceOmit:
+		return nil
+	default:
+		panic("unknown mode " + strconv.Itoa(int(eb.mode)))
+	}
+}
+
+func (eb *ErrorBuilder) collectOriginalStackTrace() *stackTrace {
+	return collectStackTrace()
+}
+
+func (eb *ErrorBuilder) borrowStackTraceFromCause() *stackTrace {
+	originalStackTrace := eb.extractStackTraceFromCause(eb.cause)
+	if originalStackTrace != nil {
+		return originalStackTrace
+	} else {
+		return collectStackTrace()
+	}
+}
+
+func (eb *ErrorBuilder) combineStackTraceWithCause() *stackTrace {
+	currentStackTrace := collectStackTrace()
+
+	originalStackTrace := eb.extractStackTraceFromCause(eb.cause)
+	if originalStackTrace != nil {
+		currentStackTrace.enhanceWithCause(originalStackTrace)
+	}
+
+	return currentStackTrace
+}
+
+func (eb *ErrorBuilder) extractStackTraceFromCause(cause error) *stackTrace {
+	if typedCause := Cast(cause); typedCause != nil {
+		return typedCause.stackTrace
+	}
+
+	return nil
+}

builder_test.go

@@ -0,0 +1,22 @@
+package errorx
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestBuilderTransparency(t *testing.T) {
+	t.Run("Raw", func(t *testing.T) {
+		err := NewErrorBuilder(testType).WithCause(errors.New("bad thing")).Transparent().Create()
+		require.False(t, err.IsOfType(testType))
+		require.NotEqual(t, testType, err.Type())
+	})
+
+	t.Run("RawWithModifier", func(t *testing.T) {
+		err := NewErrorBuilder(testTypeTransparent).WithCause(errors.New("bad thing")).Create()
+		require.False(t, err.IsOfType(testType))
+		require.NotEqual(t, testType, err.Type())
+	})
+}

common.go

@@ -0,0 +1,24 @@
+package errorx
+
+var (
+	// General purpose errors to be used universally
+	// These errors should typically be used in opaque manner, implying no handing in user code
+	// When handling is required, it is best to use custom error types with both standard and custom traits
+	CommonErrors = NewNamespace("common")
+
+	IllegalArgument      = CommonErrors.NewType("illegal_argument")
+	IllegalState         = CommonErrors.NewType("illegal_state")
+	IllegalFormat        = CommonErrors.NewType("illegal_format")
+	InitializationFailed = CommonErrors.NewType("initialization_failed")
+	DataUnavailable      = CommonErrors.NewType("data_unavailable")
+	UnsupportedOperation = CommonErrors.NewType("unsupported_operation")
+	RejectedOperation    = CommonErrors.NewType("rejected_operation")
+	Interrupted          = CommonErrors.NewType("interrupted")
+	AssertionFailed      = CommonErrors.NewType("assertion_failed")
+	InternalError        = CommonErrors.NewType("internal_error")
+	ExternalError        = CommonErrors.NewType("external_error")
+	ConcurrentUpdate     = CommonErrors.NewType("concurrent_update")
+	TimeoutElapsed       = CommonErrors.NewType("timeout", Timeout())
+	NotImplemented       = UnsupportedOperation.NewSubtype("not_implemented")
+	UnsupportedVersion   = UnsupportedOperation.NewSubtype("version")
+)