restructured the project to comply community guideline, for others check release note

internal/error/builder.go

@@ -0,0 +1,70 @@
+package error
+
+import (
+	"fmt"
+	"sync"
+)
+
+type Builder struct {
+	*builder
+}
+
+type builder struct {
+	message string
+	errors  []NestedError
+	sync.Mutex
+}
+
+func NewBuilder(format string, args ...any) Builder {
+	return Builder{&builder{message: fmt.Sprintf(format, args...)}}
+}
+
+// adding nil / nil is no-op,
+// you may safely pass expressions returning error to it
+func (b Builder) Add(err NestedError) Builder {
+	if err != nil {
+		b.Lock()
+		// TODO: if err severity is higher than b.severity, update b.severity
+		b.errors = append(b.errors, err)
+		b.Unlock()
+	}
+	return b
+}
+
+func (b Builder) AddE(err error) Builder {
+	return b.Add(From(err))
+}
+
+func (b Builder) Addf(format string, args ...any) Builder {
+	return b.Add(errorf(format, args...))
+}
+
+// Build builds a NestedError based on the errors collected in the Builder.
+//
+// If there are no errors in the Builder, it returns a Nil() NestedError.
+// Otherwise, it returns a NestedError with the message and the errors collected.
+//
+// Returns:
+//   - NestedError: the built NestedError.
+func (b Builder) Build() NestedError {
+	if len(b.errors) == 0 {
+		return nil
+	} else if len(b.errors) == 1 {
+		return b.errors[0]
+	}
+	return Join(b.message, b.errors...)
+}
+
+func (b Builder) To(ptr *NestedError) {
+	if ptr == nil {
+		return
+	} else if *ptr == nil {
+		*ptr = b.Build()
+	} else {
+		(*ptr).With(b.Build())
+	}
+}
+
+func (b Builder) HasError() bool {
+	return len(b.errors) > 0
+}

internal/error/builder_test.go

@@ -0,0 +1,53 @@
+package error
+
+import (
+	"testing"
+
+	. "github.com/yusing/go-proxy/internal/utils/testing"
+)
+
+func TestBuilderEmpty(t *testing.T) {
+	eb := NewBuilder("qwer")
+	ExpectTrue(t, eb.Build() == nil)
+	ExpectTrue(t, eb.Build().NoError())
+	ExpectFalse(t, eb.HasError())
+}
+
+func TestBuilderAddNil(t *testing.T) {
+	eb := NewBuilder("asdf")
+	var err NestedError
+	for range 3 {
+		eb.Add(nil)
+	}
+	for range 3 {
+		eb.Add(err)
+	}
+	ExpectTrue(t, eb.Build() == nil)
+	ExpectTrue(t, eb.Build().NoError())
+	ExpectFalse(t, eb.HasError())
+}
+
+func TestBuilderNested(t *testing.T) {
+	eb := NewBuilder("error occurred")
+	eb.Add(Failure("Action 1").With(Invalid("Inner", "1")).With(Invalid("Inner", "2")))
+	eb.Add(Failure("Action 2").With(Invalid("Inner", "3")))
+
+	got := eb.Build().String()
+	expected1 :=
+		(`error occurred:
+  - Action 1 failed:
+    - invalid Inner: 1
+    - invalid Inner: 2
+  - Action 2 failed:
+    - invalid Inner: 3`)
+	expected2 :=
+		(`error occurred:
+  - Action 1 failed:
+    - invalid Inner: "1"
+    - invalid Inner: "2"
+  - Action 2 failed:
+    - invalid Inner: "3"`)
+	if got != expected1 && got != expected2 {
+		t.Errorf("expected \n%s, got \n%s", expected1, got)
+	}
+}

internal/error/error.go

@@ -0,0 +1,295 @@
+package error
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+)
+
+type (
+	NestedError = *nestedError
+	nestedError struct {
+		subject string
+		err     error
+		extras  []nestedError
+	}
+	jsonNestedError struct {
+		Subject string
+		Err     string
+		Extras  []jsonNestedError
+	}
+)
+
+func From(err error) NestedError {
+	if IsNil(err) {
+		return nil
+	}
+	return &nestedError{err: err}
+}
+
+func FromJSON(data []byte) (NestedError, bool) {
+	var j jsonNestedError
+	if err := json.Unmarshal(data, &j); err != nil {
+		return nil, false
+	}
+	if j.Err == "" {
+		return nil, false
+	}
+	extras := make([]nestedError, len(j.Extras))
+	for i, e := range j.Extras {
+		extra, ok := fromJSONObject(e)
+		if !ok {
+			return nil, false
+		}
+		extras[i] = *extra
+	}
+	return &nestedError{
+		subject: j.Subject,
+		err:     errors.New(j.Err),
+		extras:  extras,
+	}, true
+}
+
+// Check is a helper function that
+// convert (T, error) to (T, NestedError).
+func Check[T any](obj T, err error) (T, NestedError) {
+	return obj, From(err)
+}
+
+func Join(message string, err ...NestedError) NestedError {
+	extras := make([]nestedError, len(err))
+	nErr := 0
+	for i, e := range err {
+		if e == nil {
+			continue
+		}
+		extras[i] = *e
+		nErr += 1
+	}
+	if nErr == 0 {
+		return nil
+	}
+	return &nestedError{
+		err:    errors.New(message),
+		extras: extras,
+	}
+}
+
+func JoinE(message string, err ...error) NestedError {
+	b := NewBuilder(message)
+	for _, e := range err {
+		b.AddE(e)
+	}
+	return b.Build()
+}
+
+func IsNil(err error) bool {
+	return err == nil
+}
+
+func IsNotNil(err error) bool {
+	return err != nil
+}
+
+func (ne NestedError) String() string {
+	var buf strings.Builder
+	ne.writeToSB(&buf, 0, "")
+	return buf.String()
+}
+
+func (ne NestedError) Is(err error) bool {
+	if ne == nil {
+		return err == nil
+	}
+	// return errors.Is(ne.err, err)
+	if errors.Is(ne.err, err) {
+		return true
+	}
+	for _, e := range ne.extras {
+		if e.Is(err) {
+			return true
+		}
+	}
+	return false
+}
+
+func (ne NestedError) IsNot(err error) bool {
+	return !ne.Is(err)
+}
+
+func (ne NestedError) Error() error {
+	if ne == nil {
+		return nil
+	}
+	return ne.buildError(0, "")
+}
+
+func (ne NestedError) With(s any) NestedError {
+	if ne == nil {
+		return ne
+	}
+	var msg string
+	switch ss := s.(type) {
+	case nil:
+		return ne
+	case NestedError:
+		return ne.withError(ss)
+	case error:
+		return ne.withError(From(ss))
+	case string:
+		msg = ss
+	case fmt.Stringer:
+		return ne.appendMsg(ss.String())
+	default:
+		return ne.appendMsg(fmt.Sprint(s))
+	}
+	return ne.withError(From(errors.New(msg)))
+}
+
+func (ne NestedError) Extraf(format string, args ...any) NestedError {
+	return ne.With(errorf(format, args...))
+}
+
+func (ne NestedError) Subject(s any) NestedError {
+	if ne == nil {
+		return ne
+	}
+	var subject string
+	switch ss := s.(type) {
+	case string:
+		subject = ss
+	case fmt.Stringer:
+		subject = ss.String()
+	default:
+		subject = fmt.Sprint(s)
+	}
+	if ne.subject == "" {
+		ne.subject = subject
+	} else {
+		ne.subject = fmt.Sprintf("%s > %s", subject, ne.subject)
+	}
+	return ne
+}
+
+func (ne NestedError) Subjectf(format string, args ...any) NestedError {
+	if ne == nil {
+		return ne
+	}
+	if strings.Contains(format, "%q") {
+		panic("Subjectf format should not contain %q")
+	}
+	if strings.Contains(format, "%w") {
+		panic("Subjectf format should not contain %w")
+	}
+	ne.subject = fmt.Sprintf(format, args...)
+	return ne
+}
+
+func (ne NestedError) JSONObject() jsonNestedError {
+	extras := make([]jsonNestedError, len(ne.extras))
+	for i, e := range ne.extras {
+		extras[i] = e.JSONObject()
+	}
+	return jsonNestedError{
+		Subject: ne.subject,
+		Err:     ne.err.Error(),
+		Extras:  extras,
+	}
+}
+
+func (ne NestedError) JSON() []byte {
+	b, _ := json.MarshalIndent(ne.JSONObject(), "", "  ")
+	return b
+}
+
+func (ne NestedError) NoError() bool {
+	return ne == nil
+}
+
+func (ne NestedError) HasError() bool {
+	return ne != nil
+}
+
+func errorf(format string, args ...any) NestedError {
+	return From(fmt.Errorf(format, args...))
+}
+
+func fromJSONObject(obj jsonNestedError) (NestedError, bool) {
+	data, err := json.Marshal(obj)
+	if err != nil {
+		return nil, false
+	}
+	return FromJSON(data)
+}
+
+func (ne NestedError) withError(err NestedError) NestedError {
+	if ne != nil && err != nil {
+		ne.extras = append(ne.extras, *err)
+	}
+	return ne
+}
+
+func (ne NestedError) appendMsg(msg string) NestedError {
+	if ne == nil {
+		return nil
+	}
+	ne.err = fmt.Errorf("%w %s", ne.err, msg)
+	return ne
+}
+
+func (ne NestedError) writeToSB(sb *strings.Builder, level int, prefix string) {
+	for i := 0; i < level; i++ {
+		sb.WriteString("  ")
+	}
+	sb.WriteString(prefix)
+
+	if ne.NoError() {
+		sb.WriteString("nil")
+		return
+	}
+
+	sb.WriteString(ne.err.Error())
+	if ne.subject != "" {
+		sb.WriteString(fmt.Sprintf(" for %q", ne.subject))
+	}
+	if len(ne.extras) > 0 {
+		sb.WriteRune(':')
+		for _, extra := range ne.extras {
+			sb.WriteRune('\n')
+			extra.writeToSB(sb, level+1, "- ")
+		}
+	}
+}
+
+func (ne NestedError) buildError(level int, prefix string) error {
+	var res error
+	var sb strings.Builder
+
+	for i := 0; i < level; i++ {
+		sb.WriteString("  ")
+	}
+	sb.WriteString(prefix)
+
+	if ne.NoError() {
+		sb.WriteString("nil")
+		return errors.New(sb.String())
+	}
+
+	res = fmt.Errorf("%s%w", sb.String(), ne.err)
+	sb.Reset()
+
+	if ne.subject != "" {
+		sb.WriteString(fmt.Sprintf(" for %q", ne.subject))
+	}
+	if len(ne.extras) > 0 {
+		sb.WriteRune(':')
+		res = fmt.Errorf("%w%s", res, sb.String())
+		for _, extra := range ne.extras {
+			res = errors.Join(res, extra.buildError(level+1, "- "))
+		}
+	} else {
+		res = fmt.Errorf("%w%s", res, sb.String())
+	}
+	return res
+}

internal/error/error_test.go

@@ -0,0 +1,109 @@
+package error_test
+
+import (
+	"errors"
+	"testing"
+
+	. "github.com/yusing/go-proxy/internal/error"
+	. "github.com/yusing/go-proxy/internal/utils/testing"
+)
+
+func TestErrorIs(t *testing.T) {
+	ExpectTrue(t, Failure("foo").Is(ErrFailure))
+	ExpectTrue(t, Failure("foo").With("bar").Is(ErrFailure))
+	ExpectFalse(t, Failure("foo").With("bar").Is(ErrInvalid))
+	ExpectFalse(t, Failure("foo").With("bar").With("baz").Is(ErrInvalid))
+
+	ExpectTrue(t, Invalid("foo", "bar").Is(ErrInvalid))
+	ExpectFalse(t, Invalid("foo", "bar").Is(ErrFailure))
+
+	ExpectFalse(t, Invalid("foo", "bar").Is(nil))
+
+	ExpectTrue(t, errors.Is(Failure("foo").Error(), ErrFailure))
+	ExpectTrue(t, errors.Is(Failure("foo").With(Invalid("bar", "baz")).Error(), ErrInvalid))
+	ExpectTrue(t, errors.Is(Failure("foo").With(Invalid("bar", "baz")).Error(), ErrFailure))
+	ExpectFalse(t, errors.Is(Failure("foo").With(Invalid("bar", "baz")).Error(), ErrNotExists))
+}
+
+func TestErrorNestedIs(t *testing.T) {
+	var err NestedError
+	ExpectTrue(t, err.Is(nil))
+
+	err = Failure("some reason")
+	ExpectTrue(t, err.Is(ErrFailure))
+	ExpectFalse(t, err.Is(ErrDuplicated))
+
+	err.With(Duplicated("something", ""))
+	ExpectTrue(t, err.Is(ErrFailure))
+	ExpectTrue(t, err.Is(ErrDuplicated))
+	ExpectFalse(t, err.Is(ErrInvalid))
+}
+
+func TestIsNil(t *testing.T) {
+	var err NestedError
+	ExpectTrue(t, err.Is(nil))
+	ExpectFalse(t, err.HasError())
+	ExpectTrue(t, err == nil)
+	ExpectTrue(t, err.NoError())
+
+	eb := NewBuilder("")
+	returnNil := func() error {
+		return eb.Build().Error()
+	}
+	ExpectTrue(t, IsNil(returnNil()))
+	ExpectTrue(t, returnNil() == nil)
+
+	ExpectTrue(t, (err.
+		Subject("any").
+		With("something").
+		Extraf("foo %s", "bar")) == nil)
+}
+
+func TestErrorSimple(t *testing.T) {
+	ne := Failure("foo bar")
+	ExpectEqual(t, ne.String(), "foo bar failed")
+	ne = ne.Subject("baz")
+	ExpectEqual(t, ne.String(), "foo bar failed for \"baz\"")
+}
+
+func TestErrorWith(t *testing.T) {
+	ne := Failure("foo").With("bar").With("baz")
+	ExpectEqual(t, ne.String(), "foo failed:\n  - bar\n  - baz")
+}
+
+func TestErrorNested(t *testing.T) {
+	inner := Failure("inner").
+		With("1").
+		With("1")
+	inner2 := Failure("inner2").
+		Subject("action 2").
+		With("2").
+		With("2")
+	inner3 := Failure("inner3").
+		Subject("action 3").
+		With("3").
+		With("3")
+	ne := Failure("foo").
+		With("bar").
+		With("baz").
+		With(inner).
+		With(inner.With(inner2.With(inner3)))
+	want :=
+		`foo failed:
+  - bar
+  - baz
+  - inner failed:
+    - 1
+    - 1
+  - inner failed:
+    - 1
+    - 1
+    - inner2 failed for "action 2":
+      - 2
+      - 2
+      - inner3 failed for "action 3":
+        - 3
+        - 3`
+	ExpectEqual(t, ne.String(), want)
+	ExpectEqual(t, ne.Error().Error(), want)
+}

internal/error/errors.go

@@ -0,0 +1,62 @@
+package error
+
+import (
+	stderrors "errors"
+)
+
+var (
+	ErrFailure     = stderrors.New("failed")
+	ErrInvalid     = stderrors.New("invalid")
+	ErrUnsupported = stderrors.New("unsupported")
+	ErrUnexpected  = stderrors.New("unexpected")
+	ErrNotExists   = stderrors.New("does not exist")
+	ErrMissing     = stderrors.New("missing")
+	ErrDuplicated  = stderrors.New("duplicated")
+	ErrOutOfRange  = stderrors.New("out of range")
+)
+
+const fmtSubjectWhat = "%w %v: %q"
+
+func Failure(what string) NestedError {
+	return errorf("%s %w", what, ErrFailure)
+}
+
+func FailedWhy(what string, why string) NestedError {
+	return Failure(what).With(why)
+}
+
+func FailWith(what string, err any) NestedError {
+	return Failure(what).With(err)
+}
+
+func Invalid(subject, what any) NestedError {
+	return errorf(fmtSubjectWhat, ErrInvalid, subject, what)
+}
+
+func Unsupported(subject, what any) NestedError {
+	return errorf(fmtSubjectWhat, ErrUnsupported, subject, what)
+}
+
+func Unexpected(subject, what any) NestedError {
+	return errorf(fmtSubjectWhat, ErrUnexpected, subject, what)
+}
+
+func UnexpectedError(err error) NestedError {
+	return errorf("%w error: %w", ErrUnexpected, err)
+}
+
+func NotExist(subject, what any) NestedError {
+	return errorf("%v %w: %v", subject, ErrNotExists, what)
+}
+
+func Missing(subject any) NestedError {
+	return errorf("%w %v", ErrMissing, subject)
+}
+
+func Duplicated(subject, what any) NestedError {
+	return errorf("%w %v: %v", ErrDuplicated, subject, what)
+}
+
+func OutOfRange(subject string, value any) NestedError {
+	return errorf("%v %w: %v", subject, ErrOutOfRange, value)
+}