← Cloudflare Flagship / flagship / sdk

TypeScript Server SDK

FlagshipServerProvider implementuje rozhraní serverového poskytovatele OpenFeature. Poskytovatel funguje v Cloudflare Workers, Node.js a jakékoli serverové běhové prostředí JavaScriptu, které podporuje Fetch API.

Uvnitř Cloudflare Workeru můžete předat Flagship binding přímo poskytovateli. Tím se vyhnete režii HTTP a jde o doporučený postup. Mimo Workers inicializujte poskytovatele pomocí ID aplikace a ID účtu.

Nastavení

Předejte vazbu Flagship přímo poskytovateli. Jde o doporučený postup uvnitř Workeru.

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.");
	},
};

Použijte ID aplikace, ID účtu a API token, pokud běžíte mimo Worker (například v Node.js). Vygenerujte API token z vašeho účtu Cloudflare s oprávněním Flagship Evaluate nebo Flagship App Evaluate.

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",
});

Možnosti konfigurace

Možnost	Typ	Povinné	Popis
`binding`	`Flagship`	Ne	Binding Flagship z `env.FLAGS`. Pro nejlepší výkon toto použijte uvnitř Workeru. Vazba řeší ověřování automaticky.
`appId`	`string`	Ne	ID aplikace Flagship z Cloudflare dashboardu. Povinné, pokud nepoužíváte binding.
`accountId`	`string`	Ne	ID vašeho účtu Cloudflare. Povinné při použití `appId`.
`authToken`	`string`	Ne	Cloudflare API token s oprávněním Flagship Evaluate nebo Flagship App Evaluate. Vyžadováno, pokud nepoužíváte vazbu.
`fetchOptions`	`RequestInit`	Ne	Vlastní možnosti fetch aplikované na HTTP požadavky.
`timeout`	`number`	Ne	Časový limit požadavku v milisekundách. Výchozí hodnota je `5000`.
`retries`	`number`	Ne	Počet opakování při dočasných chybách. Výchozí hodnota je `1` a je omezeno na `10`.
`retryDelay`	`number`	Ne	Prodleva mezi opakováními v milisekundách. Výchozí hodnota je `1000` a je omezeno na `30000`.
`cacheTtl`	`number`	Ne	TTL cache v milisekundách. Ukládání odpovědí do mezipaměti se zapne, pokud je hodnota vyšší než `0`.
`cacheMaxSize`	`number`	Ne	Maximální počet položek v mezipaměti. Výchozí hodnota je `1000` když `cacheTtl` je nastaven.

Zadejte buď binding nebo appId, accountId, a authToken.

Cachování odpovědí

Serverové ukládání odpovědí do mezipaměti je ve výchozím nastavení vypnuté. Povolte je pomocí cacheTtl pokud chcete, aby opakovaná vyhodnocení stejného příznaku, typu a kontextu vyhodnocení znovu použila nedávný výsledek.

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

Ukládání do mezipaměti použijte u serverových aplikací s vysokým provozem, které opakovaně vyhodnocují stejné flagy pro stejné kontexty. Hodnoty v mezipaměti mohou být zastaralé, dokud nevyprší TTL, proto u flagů, které se během aktivních rolloutů mohou měnit, nastavte krátké TTL. Poskytovatel neukládá do mezipaměti vypnuté flagy ani chyby.

Kontext vyhodnocení

OpenFeature používá kontext vyhodnocení k předání atributů uživatele poskytovateli příznaků. Objekt targetingKey pole je hlavní identifikátor uživatele.

Předejte další atributy společně s targetingKey k porovnání s cílicí pravidla. Můžete například zahrnout plan, country, nebo libovolný vlastní atribut, na který vaše pravidla odkazují.

Používejte primitivní hodnoty kontextu, jako jsou řetězce, čísla, booleovské hodnoty a Date objekty. Poskytovatel odmítá objekty a pole jako neplatný kontext.

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",
});

Dostupné hooky

SDK obsahuje dva hooky, které můžete připojit ke klientovi OpenFeature.

LoggingHook : Zaznamenává strukturované informace pro každé vyhodnocení.
TelemetryHook : Zachycuje časové údaje a data o událostech pro účely observability.

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());

Migrace od jiného poskytovatele

Pokud používáte jiného poskytovatele kompatibilního s OpenFeature (například LaunchDarkly nebo Flagsmith), přejděte na Flagship nahrazením inicializace poskytovatele. Na místech, kde voláte vyhodnocení, nejsou potřeba žádné změny.

// 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>",
	}),
);