GitHub - Unleash/unleash-go-sdk: Unleash client SDK for Go

The official Unleash SDK for Go. This SDK lets you evaluate feature flags in your Go services and applications.

Unleash is an open-source feature management platform. You can use this SDK with Unleash Enterprise or Unleash Open Source.

For complete documentation, see the Go SDK reference.

Requirements

Go 1.23 or later (tested up to 1.26)

Installation

Install the SDK module with go get:

go get github.com/Unleash/unleash-go-sdk/v6@latest

Quick start

The following example initializes the SDK and checks a feature flag:

package main

import (
	"net/http"

	unleash "github.com/Unleash/unleash-go-sdk/v6"
)

func main() {
	err := unleash.Initialize(
		unleash.WithAppName("my-go-service"),
		unleash.WithUrl("https://<your-unleash-instance>/api/"),
		unleash.WithCustomHeaders(http.Header{"Authorization": {"<your-backend-token>"}}),
	)

	if err != nil {
		panic(err)
	}

	defer unleash.Close()

	// Block until the SDK has fetched flag data from Unleash.
	// In production, consider using bootstrapping or event listeners instead.
	unleash.WaitForReady()

	enabled := unleash.IsEnabled("my-feature", unleash.FeatureOptions{})
	if enabled {
		// new behavior
	}

	variant := unleash.GetVariant("checkout-experiment", unleash.VariantOptions{})
	if variant.Name == "blue" {
		// blue variant behavior
	} else if variant.Name == "green" {
		// green variant behavior
	}
}

Contributing

Local development

Clone the repository and the client specification test data. The client specification defines a shared contract that all Unleash SDKs test against.

git clone https://github.com/Unleash/unleash-go-sdk.git
cd unleash-go-sdk
mkdir -p testdata
git clone https://github.com/Unleash/client-specification.git testdata/client-specification

To test a local application against your development copy of the SDK, add a replace directive to the application's go.mod:

replace github.com/Unleash/unleash-go-sdk/v6 => ../unleash-go-sdk/

Running tests

Use make to run the test suite:

make          # vet + tests
make test-race # tests with the race detector

Benchmarking

Run the feature flag evaluation benchmark:

go test -run=^$ -bench=BenchmarkFeatureToggleEvaluation -benchtime=10s

Example output on a MacBook Pro (M1 Pro, 2021) with 16 GB RAM:

goos: darwin
goarch: arm64
pkg: github.com/Unleash/unleash-go-sdk/v6
BenchmarkFeatureToggleEvaluation-8 Final Estimated Operations Per Day: 101.131 billion (1.011315e+11)
13635154 854.3 ns/op
PASS
ok github.com/Unleash/unleash-go-sdk/v6 13.388s

854.3 ns/op translates to roughly 101 billion evaluations per day on a single CPU core.

Code style and formatting

Use the following make targets to format and lint your code:

make fmt          # format code
make fmt-check    # check formatting without writing
make strict-check # vet + golint

Releasing

Update clientVersion in client.go.
Create a release in GitHub with a semantic version tag.

License

Apache-2.0