Пошук

Flagship Rust SDK — як оцінювати feature flags в асинхронних Rust серверах

·

У нотатці Cloudflare розбирається підхід до роботи з feature flags через новий офіційний Rust SDK для Flagship. Далі — практичний розбір, як інтегрувати його в асинхронний сервер, що вже використовує OpenFeature.

Що саме з'явилося в Flagship для Rust

Flagship отримав офіційний SDK на Rust, який інтегрується з OpenFeature. Це означає, що:

  • можна оцінювати feature flags безпосередньо з async Rust застосунків;
  • застосовуються ті самі таргетингові правила і відсоткові розкати, що й в інших SDK Flagship;
  • провайдер підключається через OpenFeature API, а не через власний кастомний інтерфейс.

Крок 1. Встановити crate cloudflare-flagship

Автори пропонують використовувати офіційний crate cloudflare-flagship з crates.io. Додавання в проєкт відбувається через cargo add:

cargo add cloudflare-flagship

Після цього залежність з'явиться в Cargo.toml, і можна імпортувати типи з цього crate у коді.

Крок 2. Налаштувати FlagshipClientOptions

Для підключення до Flagship SDK потрібні параметри акаунта. У прикладі використовуються:

  • app_id — ідентифікатор застосунку в Flagship;
  • account_id — ідентифікатор акаунта;
  • auth_token — API токен для доступу.

Усе це збирається через builder:

let options = FlagshipClientOptions::builder()
    .app_id("<APP_ID>")
    .account_id("<ACCOUNT_ID>")
    .auth_token("<API_TOKEN>")
    .build()?;

let mut api = OpenFeature::default();
api.set_provider(FlagshipServerProvider::new(options)?).await;
let context = EvaluationContext::default().with_targeting_key("user-42");
let enabled = api
    .create_client()
    .get_bool_value("new-checkout", Some(&context), None)
    .await
    .unwrap_or(false);

У результаті створюється FlagshipClientOptions, який передається в провайдер. Помилки збірки обробляються через ?, тому функція, де розміщений код, має повертати Result.

Крок 3. Реєструвати провайдера в OpenFeature

SDK працює як OpenFeature provider. Послідовність така:

  1. Створюється OpenFeature через OpenFeature::default().
  2. На ньому викликається set_provider(...) з FlagshipServerProvider::new(options)?.
  3. Операція set_provider асинхронна, тому до неї додається .await.

Ця схема дозволяє залишити загальну інтеграцію через OpenFeature, а змінювати бекенд тільки за рахунок іншого провайдера.

Крок 4. Формувати EvaluationContext і читати прапорці

Для таргетингу потрібен контекст користувача. У прикладі використовується тільки targeting key:

  • EvaluationContext::default() створює базовий контекст;
  • with_targeting_key("user-42") задає ідентифікатор користувача для таргетингових правил.

Далі послідовність викликів:

  • api.create_client() — отримати клієнта OpenFeature;
  • get_bool_value("new-checkout", Some(&context), None) — асинхронно оцінити булевий feature flag з ключем new-checkout;
  • .await — дочекатися результату;
  • .unwrap_or(false) — у випадку помилки повернути fallback значення false.

Такий підхід підходить для типового сценарію: за замовчуванням функціональність вимкнена, якщо неможливо отримати коректне значення прапорця.

HTTP проти локальної оцінки прапорців

За умовчанням провайдер оцінює feature flags через HTTP запити до Flagship. Це означає:

  • кожна оцінка залежить від мережі і затримки HTTP;
  • конфігурація прапорців централізована на стороні Flagship.

У SDK окремо виділена опція локальної оцінки. У цьому режимі:

  • визначення прапорців один раз завантажуються;
  • подальші оцінки виконуються в процесі, без мережевого запиту на кожну перевірку;
  • зменшується латентність оцінки, але потрібно слідкувати за оновленням локальних даних.

У матеріалі не детально розписана конфігурація локальної оцінки, тому за конкретними параметрами та методами пропонується звертатися до офіційної документації SDK.

Додаткові можливості SDK: контекст, кеш, логування

Окрім базового сценарію, де передається тільки targeting key, описаний SDK підтримує:

  • структурований evaluation context — можна додавати властивості користувача чи запиту, які потім використовуються в правилах таргетингу;
  • опційний кеш відповідей — зменшує кількість HTTP викликів у випадку частого звернення до тих самих прапорців;
  • хуки для логування й телеметрії — дають змогу підключати власні інструменти обліку, трасування або метрик.

Такі механізми корисні для сервісів з великою кількістю запитів, де зайві мережеві виклики або відсутність прозорого логування можуть стати проблемою.

Системні вимоги: версія Rust і Tokio

SDK висуває дві ключові вимоги до середовища виконання:

  • Rust версії не нижче 1.88 — це важливо враховувати при оновленні існуючих проєктів з більш старою toolchain;
  • наявність Tokio runtime — оскільки виклики до Flagship асинхронні, код передбачає роботу в середовищі Tokio.

Тому перед інтеграцією Flagship SDK потрібно або вже мати застосунок на Tokio, або спланувати міграцію на нього.

Де шукати повну конфігурацію

Для детального налаштування режимів оцінки, кешування, параметрів локальної роботи і інтеграції з OpenFeature автори скеровують до офіційної документації Rust SDK: https://developers.cloudflare.com/flagship/sdk/rust/. Там описані підтримувані опції, а також додаткові приклади використання для різних типів застосунків.

Джерело: Cloudflare Changelog

Пошук

Закрити