prepare 3.1.0 release (#28)

## [3.1.0] - 2023-10-11
### Added:
- Introduced ldmigration and ldsampling utility packages to support
technology migration use cases.

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: Eli Bishop <eli@launchdarkly.com>
Co-authored-by: LaunchDarklyCI <dev@launchdarkly.com>
Co-authored-by: Ben Woskow <48036130+bwoskow-ld@users.noreply.github.com>
Co-authored-by: Sam Stokes <sstokes@launchdarkly.com>
Co-authored-by: LaunchDarklyReleaseBot <launchdarklyreleasebot@launchdarkly.com>
Co-authored-by: Ember Stevens <ember.stevens@launchdarkly.com>
Co-authored-by: ember-stevens <79482775+ember-stevens@users.noreply.github.com>
Co-authored-by: Casey Waldren <cwaldren@launchdarkly.com>
Co-authored-by: Matthew Wagner <rengawm@gmail.com>
Co-authored-by: ld-repository-standards[bot] <113625520+ld-repository-standards[bot]@users.noreply.github.com>
Co-authored-by: Kane Parkinson <93555788+kparkinson-ld@users.noreply.github.com>
Co-authored-by: Matthew M. Keeler <mkeeler@launchdarkly.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Louis Chan <91093020+louis-launchdarkly@users.noreply.github.com>

Author: 14 people

CODEOWNERS

@@ -0,0 +1,2 @@
+# Repository Maintainers
+* @launchdarkly/team-sdk-go

go.mod

@@ -16,5 +16,5 @@ require (
 	github.com/kr/text v0.2.0 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect
-	gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c // indirect
+	gopkg.in/yaml.v3 v3.0.0 // indirect
 )

go.sum

@@ -26,5 +26,6 @@ golang.org/x/exp v0.0.0-20220823124025-807a23277127/go.mod h1:cyybsKvd6eL0RnXn6p
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
-gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c h1:dUUwHk2QECo/6vqA44rthZ8ie2QXMNeKRTHCNY2nXvo=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.0 h1:hjy8E9ON/egN1tAYqKb61G10WtihqetD4sz2H+8nIeA=
+gopkg.in/yaml.v3 v3.0.0/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

ldmigration/ldmigration_info.go

@@ -0,0 +1,2 @@
+// Package ldmigration contains general types used by LaunchDarkly SDK components to support technology migrations.
+package ldmigration

ldmigration/migration.go

@@ -0,0 +1,112 @@
+package ldmigration
+
+import "fmt"
+
+// ExecutionOrder represents the various execution modes this SDK can operate
+// under while performing migration-assisted reads.
+type ExecutionOrder string
+
+const (
+	// Serial execution ensures the authoritative read will always complete execution before executing the
+	// non-authoritative read.
+	Serial ExecutionOrder = "serial"
+	// Random execution randomly decides if the authoritative read should execute first or second.
+	Random ExecutionOrder = "random"
+	// Concurrent executes both reads in separate go routines, and waits until both calls have finished before
+	// proceeding.
+	Concurrent ExecutionOrder = "concurrent"
+)
+
+// Operation represents a type of migration operation; namely, read or write.
+type Operation string
+
+const (
+	// Read denotes a read-related migration operation.
+	Read Operation = "read"
+	// Write denotes a write-related migration operation.
+	Write Operation = "write"
+)
+
+// ConsistencyCheck records the results of a consistency check and the ratio at
+// which the check was sampled.
+//
+// For example, a sampling ratio of 10 indicts this consistency check was
+// sampled approximately once every ten operations.
+type ConsistencyCheck struct {
+	consistent    bool
+	samplingRatio int
+}
+
+// NewConsistencyCheck creates a new consistency check reflecting the provided values.
+func NewConsistencyCheck(wasConsistent bool, samplingRatio int) *ConsistencyCheck {
+	return &ConsistencyCheck{
+		consistent:    wasConsistent,
+		samplingRatio: samplingRatio,
+	}
+}
+
+// Consistent returns whether or not the check returned a consistent result.
+func (c ConsistencyCheck) Consistent() bool {
+	return c.consistent
+}
+
+// SamplingRatio returns the 1 in x sampling ratio used to determine if the consistency check should be run.
+func (c ConsistencyCheck) SamplingRatio() int {
+	return c.samplingRatio
+}
+
+// Origin represents the source of origin for a migration-related operation.
+type Origin string
+
+const (
+	// Old represents the technology source we are migrating away from.
+	Old Origin = "old"
+	// New represents the technology source we are migrating towards.
+	New Origin = "new"
+)
+
+// Stage denotes one of six possible stages a technology migration could be a
+// part of, progressing through the following order.
+//
+// Off -> DualWrite -> Shadow -> Live -> RampDown -> Complete
+type Stage string
+
+const (
+	// Off - migration hasn't started, "old" is authoritative for reads and writes
+	Off Stage = "off"
+
+	// DualWrite - write to both "old" and "new", "old" is authoritative for reads
+	DualWrite Stage = "dualwrite"
+
+	// Shadow - both "new" and "old" versions run with a preference for "old"
+	Shadow Stage = "shadow"
+
+	// Live - both "new" and "old" versions run with a preference for "new"
+	Live Stage = "live"
+
+	// RampDown - only read from "new", write to "old" and "new"
+	RampDown Stage = "rampdown"
+
+	// Complete - migration is done
+	Complete Stage = "complete"
+)
+
+// ParseStage parses a MigrationStage from a string, or returns an error if the stage is unrecognized.
+func ParseStage(val string) (Stage, error) {
+	switch val {
+	case "off":
+		return Off, nil
+	case "dualwrite":
+		return DualWrite, nil
+	case "shadow":
+		return Shadow, nil
+	case "live":
+		return Live, nil
+	case "rampdown":
+		return RampDown, nil
+	case "complete":
+		return Complete, nil
+	default:
+		return Off, fmt.Errorf("invalid stage %s provided", val)
+	}
+}

ldsampling/package_info.go

@@ -0,0 +1,2 @@
+// Package ldsampling provides functionality related to sampling.
+package ldsampling

ldsampling/sampler.go

@@ -0,0 +1,50 @@
+package ldsampling
+
+import (
+	"math/rand"
+	"time"
+)
+
+// NewSampler creates a *RatioSampler instance that can be used to
+// determine sampling selections.
+//
+// The random number generator used is seeded with the current system time.
+func NewSampler() *RatioSampler {
+	return NewSamplerFromSource(rand.NewSource(time.Now().UnixNano()))
+}
+
+// NewSamplerFromSource creates a *RatioSampler instance similar to
+// NewSampler with the additional benefit of providing the random number
+// source.
+func NewSamplerFromSource(source rand.Source) *RatioSampler {
+	return &RatioSampler{rng: rand.New(source)} //nolint:gosec // doesn't need cryptographic security
+}
+
+// RatioSampler provides a simple interface for determining sample selections.
+//
+// The distribution calculation relies on random number generation, it does not
+// perform any tracking to ensure a strict 1 in x outcome.
+//
+// A non-positive ratio effectively disables sampling, resulting in Sample always
+// returning false. A ratio of 1 will result in every call being true. Any other
+// ratio results in a 1 in x chance of being sampled.
+//
+// As a RatioSampler relies on rand.Source, the sampler is not safe for
+// concurrent use.
+type RatioSampler struct {
+	rng *rand.Rand
+}
+
+// Sample returns a boolean to determine whether or not something should be
+// sampled. It should not be called concurrently.
+func (r *RatioSampler) Sample(ratio int) bool {
+	if ratio <= 0 {
+		return false
+	}
+
+	if ratio == 1 {
+		return true
+	}
+
+	return r.rng.Float64() < 1/float64(ratio)
+}

ldsampling/sampler_test.go

@@ -0,0 +1,34 @@
+package ldsampling
+
+import (
+	"math/rand"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestRatioSampler(t *testing.T) {
+	t.Run("simple sampling", func(t *testing.T) {
+		sampler := NewSampler()
+
+		assert.False(t, sampler.Sample(-1), "negative ratio should sample false")
+		assert.False(t, sampler.Sample(0), "zero ratio should sample false")
+		assert.True(t, sampler.Sample(1), "one ratio should sample true")
+	})
+
+	t.Run("random sampling", func(t *testing.T) {
+		sampler := NewSamplerFromSource(rand.NewSource(1))
+
+		picks := 0
+		for i := 0; i < 1_000; i++ {
+			if sampler.Sample(2) {
+				picks += 1
+			}
+		}
+
+		// This isn't a perfect 1 in 2 ratio, but the sampling is
+		// probabilistic. Since we control the seed, this should be safe for
+		// testing.
+		assert.Equal(t, 508, picks)
+	})
+}