merge prerelease branch

Author: eli-darkly

ldattr/errors.go

@@ -5,6 +5,7 @@ import (
 	"strconv"
 	"strings"
 
+	"github.com/launchdarkly/go-sdk-common/v3/lderrors"
 	"github.com/launchdarkly/go-sdk-common/v3/ldvalue"
 
 	"github.com/launchdarkly/go-jsonstream/v2/jreader"
@@ -81,7 +82,7 @@ type attrRefComponent struct {
 // parameter will consider it invalid.
 func NewRef(referenceString string) Ref {
 	if referenceString == "" || referenceString == "/" {
-		return Ref{err: errAttributeEmpty, rawPath: referenceString}
+		return Ref{err: lderrors.ErrAttributeEmpty{}, rawPath: referenceString}
 	}
 	if referenceString[0] != '/' {
 		// When there is no leading slash, this is a simple attribute reference with no character escaping.
@@ -94,18 +95,18 @@ func NewRef(referenceString string) Ref {
 		if unescaped, ok := unescapePath(path); ok {
 			return Ref{singlePathComponent: unescaped, rawPath: referenceString}
 		}
-		return Ref{err: errAttributeInvalidEscape, rawPath: referenceString}
+		return Ref{err: lderrors.ErrAttributeInvalidEscape{}, rawPath: referenceString}
 	}
 	parts := strings.Split(path, "/")
 	ret := Ref{rawPath: referenceString, components: make([]attrRefComponent, 0, len(parts))}
 	for _, p := range parts {
 		if p == "" {
-			ret.err = errAttributeExtraSlash
+			ret.err = lderrors.ErrAttributeExtraSlash{}
 			return ret
 		}
 		unescaped, ok := unescapePath(p)
 		if !ok {
-			return Ref{err: errAttributeInvalidEscape, rawPath: referenceString}
+			return Ref{err: lderrors.ErrAttributeInvalidEscape{}, rawPath: referenceString}
 		}
 		component := attrRefComponent{name: unescaped}
 		if p[0] >= '0' && p[0] <= '9' {
@@ -129,7 +130,7 @@ func NewRef(referenceString string) Ref {
 // or to ldattr.NewRef("/a~1b").
 func NewLiteralRef(attrName string) Ref {
 	if attrName == "" {
-		return Ref{err: errAttributeEmpty, rawPath: attrName}
+		return Ref{err: lderrors.ErrAttributeEmpty{}, rawPath: attrName}
 	}
 	if attrName[0] != '/' {
 		// When there is no leading slash, this is a simple attribute reference with no character escaping.
@@ -162,13 +163,9 @@ func (a Ref) Equal(other Ref) bool {
 
 // Err returns nil for a valid Ref, or a non-nil error value for an invalid Ref.
 //
-// A Ref can only be invalid for the following reasons:
-//
-// 1. The input string was empty, or consisted only of "/".
-//
-// 2. A slash-delimited string had a double slash causing one component to be empty, such as "/a//b".
-//
-// 3. A slash-delimited string contained a "~" character that was not followed by "0" or "1".
+// A Ref is invalid if the input string is empty, or starts with a slash but is not a valid
+// slash-delimited path, or starts with a slash and contains an invalid escape sequence. For a list of
+// the possible validation errors, see the ErrAttribute___ types in the lderrors package.
 //
 // Otherwise, the Ref is valid, but that does not guarantee that such an attribute exists in any
 // given Context. For instance, NewRef("name") is a valid Ref, but a specific Context might or might
@@ -177,7 +174,7 @@ func (a Ref) Equal(other Ref) bool {
 // See comments on the Ref type for more details of the attribute reference syntax.
 func (a Ref) Err() error {
 	if a.err == nil && a.rawPath == "" {
-		return errAttributeEmpty
+		return lderrors.ErrAttributeEmpty{}
 	}
 	return a.err
 }

ldattr/ref.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"testing"
 
+	"github.com/launchdarkly/go-sdk-common/v3/lderrors"
 	"github.com/launchdarkly/go-sdk-common/v3/ldvalue"
 
 	"github.com/stretchr/testify/assert"
@@ -15,15 +16,15 @@ func TestRefInvalid(t *testing.T) {
 		input         string
 		expectedError error
 	}{
-		{"", errAttributeEmpty},
-		{"/", errAttributeEmpty},
-		{"//", errAttributeExtraSlash},
-		{"/a//b", errAttributeExtraSlash},
-		{"/a/b/", errAttributeExtraSlash},
-		{"/a~x", errAttributeInvalidEscape},
-		{"/a~", errAttributeInvalidEscape},
-		{"/a/b~x", errAttributeInvalidEscape},
-		{"/a/b~", errAttributeInvalidEscape},
+		{"", lderrors.ErrAttributeEmpty{}},
+		{"/", lderrors.ErrAttributeEmpty{}},
+		{"//", lderrors.ErrAttributeExtraSlash{}},
+		{"/a//b", lderrors.ErrAttributeExtraSlash{}},
+		{"/a/b/", lderrors.ErrAttributeExtraSlash{}},
+		{"/a~x", lderrors.ErrAttributeInvalidEscape{}},
+		{"/a~", lderrors.ErrAttributeInvalidEscape{}},
+		{"/a/b~x", lderrors.ErrAttributeInvalidEscape{}},
+		{"/a/b~", lderrors.ErrAttributeInvalidEscape{}},
 	} {
 		t.Run(fmt.Sprintf("input string %q", p.input), func(t *testing.T) {
 			a := NewRef(p.input)
@@ -37,7 +38,7 @@ func TestRefInvalid(t *testing.T) {
 	t.Run("uninitialized", func(t *testing.T) {
 		var a Ref
 		assert.False(t, a.IsDefined())
-		assert.Equal(t, errAttributeEmpty, a.Err())
+		assert.Equal(t, lderrors.ErrAttributeEmpty{}, a.Err())
 		assert.Equal(t, "", a.String())
 		assert.Equal(t, 0, a.Depth())
 	})
@@ -103,7 +104,7 @@ func TestNewLiteralRef(t *testing.T) {
 	assert.Equal(t, 1, a3.Depth())
 
 	a4 := NewLiteralRef("")
-	assert.Equal(t, errAttributeEmpty, a4.Err())
+	assert.Equal(t, lderrors.ErrAttributeEmpty{}, a4.Err())
 }
 
 func TestRefComponents(t *testing.T) {

ldattr/ref_test.go

@@ -1,10 +1,9 @@
 package ldcontext
 
 import (
-	"errors"
-	"fmt"
 	"sort"
-	"strings"
+
+	"github.com/launchdarkly/go-sdk-common/v3/lderrors"
 )
 
 const defaultMultiBuilderCapacity = 3 // arbitrary value based on presumed likely use cases
@@ -53,14 +52,14 @@ func NewMultiBuilder() *MultiBuilder {
 // than a multi-kind context.
 func (m *MultiBuilder) Build() Context {
 	if len(m.contexts) == 0 {
-		return Context{defined: true, err: errContextKindMultiWithNoKinds}
+		return Context{defined: true, err: lderrors.ErrContextKindMultiWithNoKinds{}}
 	}
 
 	if len(m.contexts) == 1 {
 		// Never return a multi-kind context with just one kind; instead return the individual one
 		c := m.contexts[0]
 		if c.Multiple() {
-			return Context{defined: true, err: errContextKindMultiWithinMulti}
+			return Context{defined: true, err: lderrors.ErrContextKindMultiWithinMulti{}}
 		}
 		return c
 	}
@@ -72,14 +71,17 @@ func (m *MultiBuilder) Build() Context {
 	sort.Slice(m.contexts, func(i, j int) bool { return m.contexts[i].Kind() < m.contexts[j].Kind() })
 
 	// Check for conditions that could make a multi-kind context invalid
-	var errs []string
+	var individualErrors map[string]error
 	nestedMulti := false
 	duplicates := false
 	for i, c := range m.contexts {
 		err := c.Err()
 		switch {
 		case err != nil: // one of the individual contexts already had an error
-			errs = append(errs, fmt.Sprintf("(%s) %s", c.Kind(), err.Error()))
+			if individualErrors == nil {
+				individualErrors = make(map[string]error)
+			}
+			individualErrors[string(c.Kind())] = err
 		case c.Multiple(): // multi-kind inside multi-kind is not allowed
 			nestedMulti = true
 		default:
@@ -91,16 +93,19 @@ func (m *MultiBuilder) Build() Context {
 			}
 		}
 	}
-	if nestedMulti {
-		errs = append(errs, errContextKindMultiWithinMulti.Error())
-	}
-	if duplicates {
-		errs = append(errs, errContextKindMultiDuplicates.Error())
+	var err error
+	switch {
+	case nestedMulti:
+		err = lderrors.ErrContextKindMultiWithinMulti{}
+	case duplicates:
+		err = lderrors.ErrContextKindMultiDuplicates{}
+	case len(individualErrors) != 0:
+		err = lderrors.ErrContextPerKindErrors{Errors: individualErrors}
 	}
-	if len(errs) != 0 {
+	if err != nil {
 		return Context{
 			defined: true,
-			err:     errors.New(strings.Join(errs, ", ")),
+			err:     err,
 		}
 	}
 

ldcontext/builder_multi.go

@@ -3,6 +3,7 @@ package ldcontext
 import (
 	"testing"
 
+	"github.com/launchdarkly/go-sdk-common/v3/lderrors"
 	"github.com/stretchr/testify/assert"
 )
 
@@ -57,25 +58,25 @@ func TestMultiBuilderErrors(t *testing.T) {
 	}
 
 	t.Run("empty", func(t *testing.T) {
-		verifyError(t, NewMultiBuilder(), errContextKindMultiWithNoKinds)
+		verifyError(t, NewMultiBuilder(), lderrors.ErrContextKindMultiWithNoKinds{})
 	})
 
 	t.Run("nested multi", func(t *testing.T) {
 		sub1 := NewWithKind("org", "my-key")
 		sub2 := NewMulti(New("user-key"), NewWithKind("org", "other"))
 		b0 := NewMultiBuilder().Add(sub1).Add(sub2)
-		verifyError(t, b0, errContextKindMultiWithinMulti)
+		verifyError(t, b0, lderrors.ErrContextKindMultiWithinMulti{})
 
 		b1 := NewMultiBuilder().Add(sub2)
-		verifyError(t, b1, errContextKindMultiWithinMulti)
+		verifyError(t, b1, lderrors.ErrContextKindMultiWithinMulti{})
 	})
 
 	t.Run("duplicate kind", func(t *testing.T) {
 		sub1 := NewWithKind("org", "my-org-key")
 		sub2 := NewWithKind("user", "my-user-key")
 		sub3 := NewWithKind("org", "other-org-key")
 		b := NewMultiBuilder().Add(sub1).Add(sub2).Add(sub3)
-		verifyError(t, b, errContextKindMultiDuplicates)
+		verifyError(t, b, lderrors.ErrContextKindMultiDuplicates{})
 	})
 
 	t.Run("error in individual contexts", func(t *testing.T) {
@@ -85,7 +86,12 @@ func TestMultiBuilderErrors(t *testing.T) {
 		b := NewMultiBuilder().Add(sub1).Add(sub2).Add(sub3)
 		c0 := b.Build()
 		assert.Error(t, c0.Err())
-		assert.Regexp(t, "\\(kind1\\).*must not be empty, \\(kind3!\\).*disallowed characters", c0.Err().Error())
+		if assert.IsType(t, lderrors.ErrContextPerKindErrors{}, c0.Err()) {
+			e := c0.Err().(lderrors.ErrContextPerKindErrors)
+			assert.Len(t, e.Errors, 2)
+			assert.Equal(t, lderrors.ErrContextKeyEmpty{}, e.Errors["kind1"])
+			assert.Equal(t, lderrors.ErrContextKindInvalidChars{}, e.Errors["kind3!"])
+		}
 		c1, err := b.TryBuild()
 		assert.Equal(t, c0.Err(), c1.Err())
 		assert.Equal(t, c0.Err(), err)

ldcontext/builder_multi_test.go

@@ -5,6 +5,7 @@ import (
 	"net/url"
 
 	"github.com/launchdarkly/go-sdk-common/v3/ldattr"
+	"github.com/launchdarkly/go-sdk-common/v3/lderrors"
 	"github.com/launchdarkly/go-sdk-common/v3/ldvalue"
 )
 
@@ -99,7 +100,7 @@ func (b *Builder) Build() Context {
 		return Context{defined: true, err: err, kind: b.kind}
 	}
 	if b.key == "" && !b.allowEmptyKey {
-		return Context{defined: true, err: errContextKeyEmpty, kind: b.kind}
+		return Context{defined: true, err: lderrors.ErrContextKeyEmpty{}, kind: b.kind}
 	}
 	// We set the kind in the error cases above because that improves error reporting if this
 	// context is used within a multi-kind context.

ldcontext/builder_simple.go

@@ -5,6 +5,7 @@ import (
 	"testing"
 
 	"github.com/launchdarkly/go-sdk-common/v3/ldattr"
+	"github.com/launchdarkly/go-sdk-common/v3/lderrors"
 	"github.com/launchdarkly/go-sdk-common/v3/ldvalue"
 
 	m "github.com/launchdarkly/go-test-helpers/v2/matchers"
@@ -19,12 +20,12 @@ type invalidKindTestParams struct {
 
 func makeInvalidKindTestParams() []invalidKindTestParams {
 	return []invalidKindTestParams{
-		{"kind", errContextKindCannotBeKind},
-		{"multi", errContextKindMultiWithSimpleBuilder},
-		{"örg", errContextKindInvalidChars},
-		{"o~rg", errContextKindInvalidChars},
-		{"😀rg", errContextKindInvalidChars},
-		{"o\trg", errContextKindInvalidChars},
+		{"kind", lderrors.ErrContextKindCannotBeKind{}},
+		{"multi", lderrors.ErrContextKindMultiForSingleKind{}},
+		{"örg", lderrors.ErrContextKindInvalidChars{}},
+		{"o~rg", lderrors.ErrContextKindInvalidChars{}},
+		{"😀rg", lderrors.ErrContextKindInvalidChars{}},
+		{"o\trg", lderrors.ErrContextKindInvalidChars{}},
 	}
 }
 
@@ -68,12 +69,12 @@ func TestBuilderKeyValidation(t *testing.T) {
 
 	c0 := b.Build()
 	assert.True(t, c0.IsDefined())
-	assert.Equal(t, errContextKeyEmpty, c0.Err())
+	assert.Equal(t, lderrors.ErrContextKeyEmpty{}, c0.Err())
 
 	c1, err := b.TryBuild()
 	assert.True(t, c1.IsDefined())
-	assert.Equal(t, errContextKeyEmpty, c1.Err())
-	assert.Equal(t, errContextKeyEmpty, err)
+	assert.Equal(t, lderrors.ErrContextKeyEmpty{}, c1.Err())
+	assert.Equal(t, lderrors.ErrContextKeyEmpty{}, err)
 }
 
 func TestBuilderFullyQualifiedKey(t *testing.T) {

ldcontext/builder_simple_test.go

@@ -5,6 +5,7 @@ import (
 	"sort"
 
 	"github.com/launchdarkly/go-sdk-common/v3/ldattr"
+	"github.com/launchdarkly/go-sdk-common/v3/lderrors"
 	"github.com/launchdarkly/go-sdk-common/v3/ldvalue"
 )
 
@@ -44,14 +45,8 @@ func (c Context) IsDefined() bool {
 //
 // A valid Context is one that can be used in SDK operations. An invalid Context is one that is
 // missing necessary attributes or has invalid attributes, indicating an incorrect usage of the
-// SDK API. The only ways for a Context to be invalid are:
-//
-// - It has a disallowed value for the Kind property. See Builder.Kind().
-// - It is a single-kind Context whose Key is empty.
-// - It is a multi-kind Context that does not have any kinds. See MultiBuilder.
-// - It is a multi-kind Context where the same kind appears more than once.
-// - It is a multi-kind Context where at least one of the nested Contexts had an error.
-// - It is an uninitialized empty Context{} value.
+// SDK API. For a complete list of the ways a Context can be invalid, see the ErrContext___
+// types in the lderrors package.
 //
 // Since in normal usage it is easy for applications to be sure they are using context kinds
 // correctly (so that having to constantly check error return values would be needlessly
@@ -63,7 +58,7 @@ func (c Context) IsDefined() bool {
 // are not sure if you have a valid Context, you can call Err() to check.
 func (c Context) Err() error {
 	if !c.defined && c.err == nil {
-		return errContextUninitialized
+		return lderrors.ErrContextUninitialized{}
 	}
 	return c.err
 }