TypeScript Server SDK

FlagshipServerProvider は、OpenFeature のサーバープロバイダーインターフェースを実装します。プロバイダーは Cloudflare Workers、Node.js、および Fetch API に対応する任意のサーバーサイド JavaScript ランタイムで動作します。

Cloudflare Worker 内では、Flagship の binding をプロバイダーへ直接渡せます。HTTP のオーバーヘッドがなく、推奨の方法です。Workers の外では、アプリ ID とアカウント ID でプロバイダーを初期化します。

セットアップ

Flagship の binding をプロバイダーへ直接渡します。Worker 内ではこの方法を推奨します。

import { OpenFeature } from "@openfeature/server-sdk";
import { FlagshipServerProvider } from "@cloudflare/flagship/server";

export default {
	async fetch(request, env) {
		await OpenFeature.setProviderAndWait(
			new FlagshipServerProvider({ binding: env.FLAGS }),
		);

		const client = OpenFeature.getClient();

		const showNewCheckout = await client.getBooleanValue(
			"new-checkout",
			false,
			{ targetingKey: "user-42", plan: "enterprise" },
		);

		if (showNewCheckout) {
			return new Response("New checkout enabled!");
		}

		return new Response("Standard checkout.");
	},
};

import { OpenFeature } from "@openfeature/server-sdk";
import { FlagshipServerProvider } from "@cloudflare/flagship/server";

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		await OpenFeature.setProviderAndWait(
			new FlagshipServerProvider({ binding: env.FLAGS }),
		);

		const client = OpenFeature.getClient();

		const showNewCheckout = await client.getBooleanValue(
			"new-checkout",
			false,
			{ targetingKey: "user-42", plan: "enterprise" },
		);

		if (showNewCheckout) {
			return new Response("New checkout enabled!");
		}

		return new Response("Standard checkout.");
	},
};

Worker の外（例: Node.js）では、アプリ ID、アカウント ID、API トークンを使います。Cloudflare アカウントから、Flagship Evaluate または Flagship App Evaluate 権限付きの API トークンを発行します。

import { OpenFeature } from "@openfeature/server-sdk";
import { FlagshipServerProvider } from "@cloudflare/flagship/server";

await OpenFeature.setProviderAndWait(
	new FlagshipServerProvider({
		appId: "<APP_ID>",
		accountId: "<ACCOUNT_ID>",
		authToken: "<API_TOKEN>",
	}),
);

const client = OpenFeature.getClient();

const showNewCheckout = await client.getBooleanValue("new-checkout", false, {
	targetingKey: "user-42",
	plan: "enterprise",
});

import { OpenFeature } from "@openfeature/server-sdk";
import { FlagshipServerProvider } from "@cloudflare/flagship/server";

await OpenFeature.setProviderAndWait(
	new FlagshipServerProvider({
		appId: "<APP_ID>",
		accountId: "<ACCOUNT_ID>",
		authToken: "<API_TOKEN>",
	}),
);

const client = OpenFeature.getClient();

const showNewCheckout = await client.getBooleanValue("new-checkout", false, {
	targetingKey: "user-42",
	plan: "enterprise",
});

設定オプション

オプション	型	必須	説明
`binding`	`Flagship`	いいえ	`env.FLAGS` の Flagship binding です。Worker 内ではこちらが最も高速です。認証は binding が自動で扱います。
`appId`	`string`	いいえ	Cloudflare ダッシュボードの Flagship アプリ ID です。binding を使わない場合は必須です。
`accountId`	`string`	いいえ	Cloudflare のアカウント ID です。`appId` を使う場合は必須です。
`authToken`	`string`	いいえ	Flagship Evaluate または Flagship App Evaluate 権限を持つ Cloudflare API トークンです。binding を使わない場合は必須です。
`fetchOptions`	`RequestInit`	いいえ	HTTP リクエストに適用するカスタム fetch オプションです。
`timeout`	`number`	いいえ	リクエストのタイムアウト（ミリ秒）です。デフォルトは `5000` です。
`retries`	`number`	いいえ	一時的なエラー時の再試行回数です。デフォルトは `1`、上限は `10` です。
`retryDelay`	`number`	いいえ	再試行の間隔（ミリ秒）です。デフォルトは `1000`、上限は `30000` です。
`cacheTtl`	`number`	いいえ	キャッシュの TTL（ミリ秒）です。`0` より大きいとレスポンスキャッシュが有効になります。
`cacheMaxSize`	`number`	いいえ	キャッシュ件数の上限です。`cacheTtl` を設定した場合のデフォルトは `1000` です。

binding、または appId、accountId、authToken のいずれかを指定します。

レスポンスキャッシュ

サーバーサイドのレスポンスキャッシュはデフォルトでオフです。同じフラグ、型、評価コンテキストに対する繰り返し評価で直近の結果を再利用したい場合は、cacheTtl で有効にします。

new FlagshipServerProvider({
	appId: "<APP_ID>",
	accountId: "<ACCOUNT_ID>",
	authToken: "<API_TOKEN>",
	cacheTtl: 30_000,
	cacheMaxSize: 1000,
});

同じコンテキストで同じフラグを繰り返し評価する、高トラフィックのサーバーアプリケーションではキャッシュを使います。キャッシュされた値は、TTL が切れるまで古いままになることがあります。アクティブなロールアウト中に変わるフラグでは、TTL を短くしてください。無効化されたフラグとエラーは、プロバイダーはキャッシュしません。

評価コンテキスト

OpenFeature は、評価コンテキストでユーザー属性をフラグプロバイダーへ渡します。targetingKey が主要なユーザー識別子です。

targetingKey とあわせて追加属性を渡し、ターゲティングルールにマッチさせます。たとえば、ルールが参照する plan、country、任意のカスタム属性を含められます。

コンテキスト値は、文字列、数値、真偽値、Date オブジェクトなどのプリミティブを使います。オブジェクトと配列は無効なコンテキストとして拒否されます。

const value = await client.getBooleanValue("new-checkout", false, {
	targetingKey: "user-42",
	plan: "enterprise",
	country: "US",
});

const value = await client.getBooleanValue("new-checkout", false, {
	targetingKey: "user-42",
	plan: "enterprise",
	country: "US",
});

利用できるフック

SDK には、OpenFeature クライアントへ付けられるフックが 2 つあります。

LoggingHook — 評価ごとに構造化情報をログ出力します。
TelemetryHook — オブザーバビリティ向けにタイミングとイベントデータを記録します。

import { LoggingHook, TelemetryHook } from "@cloudflare/flagship/server";

OpenFeature.addHooks(new LoggingHook(), new TelemetryHook());

import { LoggingHook, TelemetryHook } from "@cloudflare/flagship/server";

OpenFeature.addHooks(new LoggingHook(), new TelemetryHook());

別のプロバイダーからの移行

別の OpenFeature 互換プロバイダー（例: LaunchDarkly や Flagsmith）を使っている場合は、プロバイダーの初期化を置き換えるだけで Flagship に切り替えられます。評価の呼び出し側は変更不要です。

// Before
await OpenFeature.setProviderAndWait(
	new LaunchDarklyProvider({ sdkKey: "..." }),
);

// After
await OpenFeature.setProviderAndWait(
	new FlagshipServerProvider({
		appId: "<APP_ID>",
		accountId: "<ACCOUNT_ID>",
		authToken: "<API_TOKEN>",
	}),
);

// Before
await OpenFeature.setProviderAndWait(
	new LaunchDarklyProvider({ sdkKey: "..." }),
);

// After
await OpenFeature.setProviderAndWait(
	new FlagshipServerProvider({
		appId: "<APP_ID>",
		accountId: "<ACCOUNT_ID>",
		authToken: "<API_TOKEN>",
	}),
);