Skip to content

Go SDK

Last updated View as MarkdownAgent setup

The Go SDK provides an OpenFeature-compatible server provider for Go applications. It evaluates flags over HTTP and does not support the Cloudflare Workers binding.

Installation

Install with go get:

go get github.com/cloudflare/flagship/sdks/go

Setup

Configure the provider with your Flagship app ID, Cloudflare account ID, and an API token with Flagship Evaluate or Flagship App Evaluate permission.

package main

import (
	"context"
	"log"

	flagship "github.com/cloudflare/flagship/sdks/go"
	"github.com/open-feature/go-sdk/openfeature"
)

func main() {
	ctx := context.Background()

	provider, err := flagship.NewProvider(flagship.Options{
		AppID:     "<APP_ID>",
		AccountID: "<ACCOUNT_ID>",
		AuthToken: "<API_TOKEN>",
	})
	if err != nil {
		log.Fatal(err)
	}

	if err := openfeature.SetProviderAndWait(provider); err != nil {
		log.Fatal(err)
	}
	defer openfeature.Shutdown()

	client := openfeature.NewDefaultClient()
	evalCtx := openfeature.NewEvaluationContext("user-42", map[string]any{
		"plan": "enterprise",
	})

	enabled, err := client.BooleanValue(ctx, "new-checkout", false, evalCtx)
	if err != nil {
		log.Fatal(err)
	}

	log.Println("new-checkout:", enabled)
}

Flag types

The Go SDK supports all OpenFeature server-side flag types.

enabled, _ := client.BooleanValue(ctx, "new-checkout", false, evalCtx)
variant, _ := client.StringValue(ctx, "homepage-hero", "control", evalCtx)
rate, _ := client.FloatValue(ctx, "sample-rate", 0.1, evalCtx)
limit, _ := client.IntValue(ctx, "upload-limit", 10, evalCtx)
config, _ := client.ObjectValue(ctx, "ui-config", map[string]any{"theme": "light"}, evalCtx)

Use the *ValueDetails methods when you need reason, variant, metadata, or error codes.

Response caching

The provider can cache evaluations to avoid a network round-trip for repeated flag/context pairs. Caching is off by default and enabled by setting CacheTTL:

provider, err := flagship.NewProvider(flagship.Options{
	AppID:        "<APP_ID>",
	AccountID:    "<ACCOUNT_ID>",
	AuthToken:    "<API_TOKEN>",
	CacheTTL:     30 * time.Second, // values may be up to this stale
	CacheMaxSize: 1000,             // LRU-evicted beyond this many entries
})

Each cache entry is keyed by flag key, flag type, and the full evaluation context, so distinct contexts never share a cached value. Cache hits resolve with reason == openfeature.CachedReason.

Disabled flags, errors, and type mismatches are never cached. Because freshness is TTL-based, a flag change in Flagship takes effect after the entry expires.

The cache is per-provider instance, guarded by a mutex for concurrent use, and cleared on Shutdown.

Configuration options

Option Description
AppID Flagship app ID.
AccountID Required with AppID.
BaseURL Base URL override. Defaults to https://api.cloudflare.com.
AuthToken Adds Authorization: Bearer <token> to each request.
Headers Static headers. Explicit Authorization overrides AuthToken.
HeadersFactory Dynamic per-request headers. Values override Headers and AuthToken.
HTTPClient Custom HTTP client.
Timeout Per-attempt timeout. Defaults to 5 seconds.
Retries Retry attempts on transient errors. Defaults to 1 and is capped at 10.
DisableRetries Disables retries when set to true.
RetryDelay Delay between retries. Defaults to 1 second and is capped at 30 seconds.
CacheTTL Enables in-memory response caching when greater than 0. Cached values may be up to this duration stale.
CacheMaxSize Maximum number of cached entries. LRU-evicted beyond this limit. Defaults to 1000 when CacheTTL is set.
Logging Enables debug and error logging. Off by default.
Logger Optional slog-compatible logger. Uses the default slog logger when unset.
Hooks Provider-level OpenFeature hooks.

Evaluation context

From version 0.6.0, context attributes can contain strings, finite numeric values, booleans, nil, maps with string keys, slices, and arrays. The provider recursively normalizes time.Time values to RFC 3339 strings.

The provider sends structured context using POST with a JSON body. Context containing only strings, numbers, booleans, or times uses GET query parameters. Unsupported values, such as other structs, and non-finite numbers return INVALID_CONTEXT through OpenFeature without triggering an HTTP request.

Was this helpful?