Публичный интерфейс библиотеки `oneflag-sdk`

Классы

Сводка методов

Единица	Метод	Возвращает
`OneFlagProvider`	`Инициализировать(Контекст = Неопределено)`	-
`OneFlagProvider`	`Завершить()`	-
`OneFlagProvider`	`Состояние()`	`Строка`
`OneFlagProvider`	`Метаданные()`	`Структура`
`OneFlagProvider`	`ОбновитьСнимок()`	`Булево`
`OneFlagProvider`	`ЖивоеОбновлениеРаботает()`	`Булево`
`OneFlagProvider`	`КлючиФлагов()`	`Массив`
`OneFlagProvider`	`ПоследняяОшибка()`	`Строка`
`OneFlagProvider`	`ОбновленийПолучено`	`Число`
`OneFlagProvider`	`ВычислитьЛогическое(Ключ, ЗначениеПоУмолчанию, Контекст)`	`ResolutionDetails`
`OneFlagProvider`	`ВычислитьСтроку(Ключ, ЗначениеПоУмолчанию, Контекст)`	`ResolutionDetails`
`OneFlagProvider`	`ВычислитьЧисло(Ключ, ЗначениеПоУмолчанию, Контекст)`	`ResolutionDetails`
`OneFlagProvider`	`ВычислитьОбъект(Ключ, ЗначениеПоУмолчанию, Контекст)`	`ResolutionDetails`
`FlagEvaluator`	`ОценитьПоСнимку(Ключ, Настройка, Контекст, ЗначениеПоУмолчанию)`	`Соответствие`

Методы контракта провайдера (Вычислить..., Метаданные) вызывает клиент OpenFeature - напрямую они не нужны.

Обмен с сервером

Запрос	Когда
`GET /api/snapshot?env=<окружение>`	При инициализации и при каждом обновлении снимка
`GET /stream`	Один раз после успешной инициализации, читается до закрытия

Запрос снимка уходит с заголовками Authorization: Bearer <ключ SDK> и Accept: application/json. Поток подключается без заголовка авторизации. Снимок обновляется по событиям потока, чей тип начинается с com.oneflag.flag..

Класс `FlagEvaluator`

Правила разрешения значения флага по элементу снимка конфигурации. Состояния не хранит, поэтому один экземпляр обслуживает любое число оценок.

Тот же класс используется сервером OneFlag. Общий код исключает расхождение между тем, что показывает дашборд, и тем, что видит приложение.

Исходник: src/Классы/FlagEvaluator.os

Конструктор

bsl

Новый FlagEvaluator()

Параметров нет.

ОценитьПоСнимку

bsl

Функция ОценитьПоСнимку(Знач Ключ, Знач Настройка, Знач Контекст = Неопределено,
	Знач ЗначениеПоУмолчанию = Неопределено) Экспорт

Разрешает значение флага по его настройке в окружении.

Параметры

Параметр	Тип	Назначение
`Ключ`	`Строка`	Ключ флага. Участвует в хешировании процентной выкатки
`Настройка`	`Соответствие`	Элемент снимка конфигурации
`Контекст`	`Соответствие`	Атрибуты пользователя, включая `targetingKey`
`ЗначениеПоУмолчанию`	`Произвольный`	Значение при внештатной ситуации

Поля Настройка:

Поле	Тип	Назначение
`включен`	`Булево`	Флаг включён в окружении
`варианты`	`Соответствие`	Имя варианта → значение
`вариантПоУмолчанию`	`Строка`	Вариант, когда правила не сработали
`процентВыкатки`	`Число`	Доля аудитории, 100 по умолчанию
`правила`	`Массив`	Правила таргетинга, проверяются по порядку

Возвращаемое значение

Соответствие с полями:

Поле	Тип	Содержимое
`значение`	`Произвольный`	Значение варианта либо `ЗначениеПоУмолчанию`
`вариант`	`Строка`	Имя выбранного варианта, пустая строка при отказе
`причина`	`Строка`	`STATIC`, `TARGETING_MATCH`, `SPLIT`, `DISABLED` или `ERROR`
`кодОшибки`	`Строка`	Код ошибки OpenFeature, пустая строка при успехе

Порядок разрешения

Настройка не передана - ERROR с кодом FLAG_NOT_FOUND;
включен не равно Истина - значение по умолчанию, причина DISABLED;
сработало правило таргетинга - вариант правила, причина TARGETING_MATCH;
процентВыкатки не меньше 100 - вариант по умолчанию, причина STATIC;
в контексте нет непустого targetingKey - ERROR с кодом TARGETING_KEY_MISSING;
пользователь не попал в выкатку - значение по умолчанию, причина SPLIT;
иначе вариант по умолчанию, причина SPLIT.

Без targetingKey процентная выкатка была бы случайной при каждом вызове, поэтому она не выполняется, а не выбирает наугад. Попадание считается через bucketer от пары «ключ флага + ключ таргетинга»: один и тот же пользователь всегда попадает в тот же бакет, поэтому при увеличении процента никто не выключается обратно.

Если варианты отсутствуют или названного варианта в них нет - ERROR с кодом PARSE_ERROR.

Правило таргетинга

json

{ "атрибут": "plan", "оператор": "равно", "значения": ["pro"], "вариант": "вкл" }

Поле	Назначение
`атрибут`	Имя атрибута контекста. Отсутствующий атрибут правило пропускает
`оператор`	См. таблицу ниже. По умолчанию `равно`
`значения`	Массив эталонов. Пустой массив правило не выбирает
`вариант`	Имя варианта при срабатывании

Правила проверяются по порядку, срабатывает первое подошедшее.

Операторы

Оператор	Условие
`равно`	Значение атрибута совпадает с одним из эталонов
`не равно`	Значение атрибута не совпадает ни с одним эталоном
`содержит`	Эталон входит в значение как подстрока
`начинается с`	Значение начинается с эталона
`заканчивается на`	Значение заканчивается эталоном
`больше`, `меньше`	Числовое сравнение
`версия равна`, `версия больше`, `версия меньше`	Сравнение по semver
`версия в диапазоне`	Вхождение в диапазон semver

Нечисловое значение числовые операторы не выбирают, а не роняют оценку. То же с версиями: значение или эталон, которые версией не разбираются, правило не выбирает.

Диапазон принимает форму >=1.2.0, ^1.2.3, ~1.2, 1.2.x или составную >=1.0.0 <2.0.0. Составной диапазон собирается по частям: Версии.ВерсияВДиапазоне читает из строки только первое условие и молча отбрасывает остальные, из-за чего 5.0.0 прошла бы проверку >=1.0.0 <2.0.0. Пустой эталон диапазона считается ошибкой настройки и правило не выбирает, хотя semver трактовал бы его как *.

bsl

Оценщик = Новый FlagEvaluator();

Настройка = Новый Соответствие();
Настройка.Вставить("включен", Истина);
Настройка.Вставить("варианты", Новый Соответствие());
Настройка["варианты"].Вставить("вкл", Истина);
Настройка["варианты"].Вставить("выкл", Ложь);
Настройка.Вставить("вариантПоУмолчанию", "выкл");
Настройка.Вставить("процентВыкатки", 100);

Контекст = Новый Соответствие();
Контекст.Вставить("targetingKey", "user-42");

Оценка = Оценщик.ОценитьПоСнимку("new-checkout", Настройка, Контекст, Ложь);

Сообщить(Оценка["значение"]);   // Ложь
Сообщить(Оценка["вариант"]);    // выкл
Сообщить(Оценка["причина"]);    // STATIC

Класс `OneFlagProvider`

Провайдер OpenFeature поверх сервера OneFlag. Хранит снимок конфигурации окружения и вычисляет значения флагов локально, а свежесть снимка поддерживает потоком изменений.

Исходник: src/Классы/OneFlagProvider.os

Конструктор

bsl

Новый OneFlagProvider(Знач Адрес, Знач Ключ, Знач Окружение = "dev", Знач Настройки = Неопределено)

Параметр	Тип	Назначение
`Адрес`	`Строка`	Базовый адрес сервера, например `http://localhost:3333`. Завершающие слеши отбрасываются
`Ключ`	`Строка`	Ключ SDK, уходит в заголовке `Authorization`
`Окружение`	`Строка`	Ключ окружения. По умолчанию `dev`
`Настройки`	`Структура`, `Соответствие`	Необязательные параметры устойчивости

Поля Настройки:

Параметр	По умолчанию	Описание
`ПовторовЗагрузки`	`3`	Сколько раз повторить неудачный запрос снимка
`ЗадержкаПовтора`	`500`	Пауза между попытками, мс
`ТаймаутЗапроса`	`10`	Таймаут HTTP-запроса, с

Повторы нужны, потому что первая неудача редко означает недоступный сервер: чаще это гонка при старте, когда приложение поднялось раньше сервиса флагов. Реализованы через resilience.

Исключения

Условие	Сообщение
Пустой адрес	`OneFlag: не задан адрес сервера`

Свойства

Свойство	Тип	Назначение
`ОбновленийПолучено`	`Число`	Сколько раз конфигурация обновлялась по потоку

Жизненный цикл

Метод	Возвращает	Назначение
`Инициализировать`	-	Загружает снимок и подписывается на изменения
`Завершить`	-	Останавливает чтение потока и закрывает соединение
`Состояние`	`Строка`	`NOT_READY`, `READY` или `ERROR`
`Метаданные`	`Структура`	Структура с полем `Имя` = `OneFlagProvider`

Инициализировать

bsl

Процедура Инициализировать(Знач Контекст = Неопределено) Экспорт

Загружает снимок и, если он получен, подписывается на поток изменений. Вызывается клиентом OpenFeature при УстановитьПровайдер.

Результат загрузки	Состояние	Поток
Снимок получен	`READY`	Подписка выполняется
Снимок не получен	`ERROR`	Подписки нет

Неудача подписки на поток состояние не меняет: снимок уже загружен, и без потока провайдер продолжит отдавать значения из него.

Завершить

bsl

Процедура Завершить() Экспорт

Останавливает цикл чтения потока, закрывает соединение и переводит провайдера в NOT_READY. Разорванное соединение ошибкой не считается.

Состояние

bsl

Функция Состояние() Экспорт

Возвращаемое значение

Строка - NOT_READY до инициализации и после Завершить, READY при успешной загрузке снимка, ERROR при неудаче.

В состоянии NOT_READY любая оценка возвращает значение по умолчанию с кодом ошибки PROVIDER_NOT_READY.

Работа со снимком

Метод	Возвращает	Назначение
`ОбновитьСнимок`	`Булево`	Принудительно перечитывает конфигурацию
`ЖивоеОбновлениеРаботает`	`Булево`	Читается ли поток изменений
`КлючиФлагов`	`Массив`	Ключи известных флагов
`ПоследняяОшибка`	`Строка`	Описание последнего сбоя связи

ОбновитьСнимок

bsl

Функция ОбновитьСнимок() Экспорт

Забирает свежий снимок конфигурации с повторами по настройкам устойчивости.

Возвращаемое значение

Булево - Истина, если снимок обновлён.

При неудаче прежний снимок остаётся в силе, а описание сбоя попадает в ПоследняяОшибка(). Замена снимка выполняется под семафором, поэтому одновременная оценка флага видит либо старый снимок целиком, либо новый.

ЖивоеОбновлениеРаботает

bsl

Функция ЖивоеОбновлениеРаботает() Экспорт

Возвращаемое значение

Булево - Истина, если фоновое задание читает поток изменений.

Значение Ложь при Состояние() = "READY" означает рабочий, но деградировавший режим: значения берутся из снимка, изменения на сервере до приложения не доходят. Обновить конфигурацию в этом режиме можно только ОбновитьСнимок().

КлючиФлагов

bsl

Функция КлючиФлагов() Экспорт

Возвращаемое значение

Массив из Строка - ключи всех флагов текущего снимка.

ПоследняяОшибка

bsl

Функция ПоследняяОшибка() Экспорт

Возвращаемое значение

Строка - краткое представление последней ошибки связи, пустая строка после успешного обновления.

Контракт провайдера OpenFeature

bsl

Функция ВычислитьЛогическое(Знач Ключ, Знач ЗначениеПоУмолчанию, Знач Контекст) Экспорт
Функция ВычислитьСтроку(Знач Ключ, Знач ЗначениеПоУмолчанию, Знач Контекст) Экспорт
Функция ВычислитьЧисло(Знач Ключ, Знач ЗначениеПоУмолчанию, Знач Контекст) Экспорт
Функция ВычислитьОбъект(Знач Ключ, Знач ЗначениеПоУмолчанию, Знач Контекст) Экспорт

Вызываются клиентом OpenFeature. Возвращают ResolutionDetails.

Коды ошибок:

Код	Когда
`PROVIDER_NOT_READY`	Провайдер не инициализирован
`FLAG_NOT_FOUND`	Ключа нет в снимке окружения
`TYPE_MISMATCH`	Тип значения флага не совпал с типом метода
`TARGETING_KEY_MISSING`	Задана процентная выкатка, но в контексте нет `targetingKey`
`PARSE_ERROR`	В настройке нет вариантов или назван несуществующий вариант

ВычислитьОбъект тип не проверяет: у объекта ожидаемого типа платформы нет.

bsl

Провайдер = Новый OneFlagProvider("http://localhost:3333", "local-sdk-key", "prod");
OpenFeature.УстановитьПровайдер(Провайдер);

Клиент = OpenFeature.ПолучитьКлиента();
Детали = Клиент.ПолучитьЛогическоеСДеталями("new-checkout", Ложь,
	Новый EvaluationContext("user-42", Новый Структура("plan", "pro")));

Сообщить(Детали.Значение);   // Истина
Сообщить(Детали.Причина);    // TARGETING_MATCH
Сообщить(Детали.Вариант);    // вкл

Публичный интерфейс библиотеки oneflag-sdk ​

Классы ​

Сводка методов ​

Обмен с сервером ​

Класс FlagEvaluator ​

Конструктор ​

ОценитьПоСнимку ​

Порядок разрешения ​

Правило таргетинга ​

Операторы ​

Класс OneFlagProvider ​

Конструктор ​

Свойства ​

Жизненный цикл ​

Инициализировать ​

Завершить ​

Состояние ​

Работа со снимком ​

ОбновитьСнимок ​

ЖивоеОбновлениеРаботает ​

КлючиФлагов ​

ПоследняяОшибка ​

Контракт провайдера OpenFeature ​

Публичный интерфейс библиотеки `oneflag-sdk`

Классы

Сводка методов

Обмен с сервером

Класс `FlagEvaluator`

Конструктор

ОценитьПоСнимку

Порядок разрешения

Правило таргетинга

Операторы

Класс `OneFlagProvider`

Конструктор

Свойства

Жизненный цикл

Инициализировать

Завершить

Состояние

Работа со снимком

ОбновитьСнимок

ЖивоеОбновлениеРаботает

КлючиФлагов

ПоследняяОшибка

Контракт провайдера OpenFeature