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