INTEGRITY Документация

← Cloudflare Flagship / flagship / sdk

TypeScript Server SDK

FlagshipServerProvider реализует интерфейс серверного провайдера OpenFeature. Провайдер работает в Cloudflare Workers, Node.js и любой серверной среды выполнения JavaScript, поддерживающей Fetch API.

Внутри Cloudflare Worker вы можете передать Flagship привязка напрямую провайдеру. Это позволяет избежать накладных расходов HTTP и является рекомендуемым способом. Вне Workers инициализируйте провайдер с идентификатором приложения и идентификатором аккаунта.

Настройка

Передавайте привязку Flagship напрямую провайдеру. Это рекомендуемый подход внутри 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.");
	},
};

Используйте ID приложения, ID аккаунта и API токен при запуске вне Worker, например в Node.js. Создайте API-токен из вашего аккаунта Cloudflare с разрешением Flagship Evaluate или 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",
});

Параметры настройки

Опция Тип Обязательный Описание
binding Flagship Нет Привязка Flagship из env.FLAGS. Используйте этот вариант внутри Worker для наилучшей производительности. Привязка выполняет аутентификацию автоматически.
appId string Нет Идентификатор приложения Flagship из панели управления Cloudflare. Обязателен, если не используется привязка.
accountId string Нет Идентификатор вашего аккаунта Cloudflare. Обязателен при использовании appId.
authToken string Нет Cloudflare API-токен с разрешением Flagship Evaluate или Flagship App Evaluate. Обязательно, если вы не используете привязку.
fetchOptions RequestInit Нет Пользовательские параметры fetch, применяемые к HTTP-запросам.
timeout number Нет Тайм-аут запроса в миллисекундах. По умолчанию 5000.
retries number Нет Попытки повтора при временных ошибках. По умолчанию 1 и ограничено значением 10.
retryDelay number Нет Задержка между повторными попытками в миллисекундах. По умолчанию 1000 и ограничено значением 30000.
cacheTtl number Нет TTL кэша в миллисекундах. Включает кэширование ответов, если значение больше 0.
cacheMaxSize number Нет Максимальное количество записей в кеше. По умолчанию: 1000 когда cacheTtl задан.

Укажите либо 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.

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