unleash-go-sdk

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

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

License

Apache-2.0