Go SDK

Go SDK は、Go アプリケーション向けの OpenFeature 互換サーバープロバイダーです。フラグは HTTP 経由で評価します。Cloudflare Workers のバインディングには対応していません。

インストール

go get でインストールします。

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

セットアップ

Flagship のアプリ ID、Cloudflare のアカウント ID、Flagship Evaluate または Flagship App Evaluate 権限を持つ API トークンでプロバイダーを設定します。

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)
}

フラグの型

Go SDK は、OpenFeature のサーバーサイドフラグ型をすべてサポートします。

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)

reason、variant、メタデータ、エラーコードが必要なときは、*ValueDetails メソッドを使います。

レスポンスのキャッシュ

プロバイダーは評価結果をキャッシュし、同じフラグとコンテキストの組み合わせでネットワーク往復を避けられます。キャッシュはデフォルトでオフです。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
})

各キャッシュエントリは、フラグキー、フラグ型、評価コンテキスト全体でキー付けされます。異なるコンテキストがキャッシュ値を共有することはありません。キャッシュヒットは reason == openfeature.CachedReason で解決します。

無効なフラグ、エラー、型の不一致はキャッシュされません。鮮度は TTL ベースのため、Flagship 上のフラグ変更は、エントリの期限切れ後に反映されます。

キャッシュはプロバイダーインスタンスごとです。並行利用向けに mutex で保護され、Shutdown 時にクリアされます。

設定オプション

オプション	説明
`AppID`	Flagship のアプリ ID。
`AccountID`	`AppID` と一緒に必須です。
`BaseURL`	ベース URL の上書きです。デフォルトは `https://api.cloudflare.com` です。
`AuthToken`	各リクエストに `Authorization: Bearer <token>` を付けます。
`Headers`	静的ヘッダーです。明示的な `Authorization` は `AuthToken` より優先されます。
`HeadersFactory`	リクエストごとの動的ヘッダーです。値は `Headers` と `AuthToken` より優先されます。
`HTTPClient`	カスタム HTTP クライアントです。
`Timeout`	試行ごとのタイムアウトです。デフォルトは 5 秒です。
`Retries`	一時的なエラー時の再試行回数です。デフォルトは 1、上限は 10 です。
`DisableRetries`	`true` にすると再試行を無効にします。
`RetryDelay`	再試行の間隔です。デフォルトは 1 秒、上限は 30 秒です。
`CacheTTL`	0 より大きいと、メモリ上のレスポンスキャッシュを有効にします。キャッシュ値はこの期間まで古くなる場合があります。
`CacheMaxSize`	キャッシュエントリの最大数です。この上限を超えると LRU で追い出しされます。`CacheTTL` 設定時のデフォルトは 1000 です。
`Logging`	デバッグとエラーのログを有効にします。デフォルトはオフです。
`Logger`	任意の `slog` 互換ロガーです。未設定時はデフォルトの `slog` ロガーを使います。
`Hooks`	プロバイダーレベルの OpenFeature フックです。

評価コンテキスト

コンテキスト属性は URL クエリパラメーターとして送信されます。対応する値は、文字列、数値型、ブール値、time.Time です。nil の値はスキップされます。マップ、スライス、構造体、その他の複雑な値は、OpenFeature 経由で INVALID_CONTEXT を返し、HTTP リクエストは発生しません。