Оценка флагов

Контроллер app/КонтролОценки.os, префикс /api, и поток изменений /stream. Все эндпоинты требуют аутентификации; поток отдаётся без неё.

Оценивать флаги по HTTP нужно не всегда: oneflag-sdk забирает снимок один раз и дальше считает значения локально. Эти эндпоинты полезны для клиентов на других языках и для отладки.

Оценить флаг

POST /api/evaluate

Тело

Поле	Тип	Назначение
flagKey	string	Ключ флага, обязательно
environment	string	Окружение; можно задать и параметром env
context	object	Атрибуты пользователя, включая targetingKey
defaultValue	любой	Значение при внештатной ситуации

Ответ 200

{"flagKey":"new-checkout","value":true,"variant":"вкл","reason":"TARGETING_MATCH","errorCode":""}

Поле	Содержимое
value	Значение варианта либо defaultValue
variant	Имя выбранного варианта, пустая строка при отказе
reason	STATIC, TARGETING_MATCH, SPLIT, DISABLED или ERROR
errorCode	Код ошибки OpenFeature, пустая строка при успехе

Отсутствие флага - не ошибка HTTP: ответ 200 с errorCode = FLAG_NOT_FOUND и значением по умолчанию. Флаги не должны ронять вызывающего.

Пустой flagKey или тело не-объект - 400. Несуществующее окружение - 404.

curl -X POST http://localhost:3333/api/evaluate \
  -H "Authorization: Bearer local-sdk-key" \
  -H "Content-Type: application/json" \
  -d '{"flagKey":"new-checkout","environment":"prod","context":{"targetingKey":"user-42","plan":"pro"}}'

Оценить все флаги

POST /api/evaluate/all

Тело

Поле	Тип	Назначение
environment	string	Окружение; можно задать и параметром env
context	object	Атрибуты пользователя

Тело можно не передавать: тогда берётся окружение по умолчанию, а контекст считается пустым.

Ответ 200

{
  "environment": "prod",
  "flags": {
    "new-checkout": { "value": true, "variant": "вкл", "reason": "TARGETING_MATCH" },
    "dark-theme":   { "value": false, "variant": "выкл", "reason": "DISABLED" }
  }
}

Снимок конфигурации

GET /api/snapshot?env=dev

Отдаёт настройки всех флагов окружения без оценки: варианты, правила, процент выкатки. Это то, что забирает SDK при инициализации, чтобы дальше считать значения локально.

Ответ 200

{
  "environment": "dev",
  "flags": {
    "new-checkout": {
      "включен": true,
      "варианты": { "вкл": true, "выкл": false },
      "вариантПоУмолчанию": "вкл",
      "процентВыкатки": 25,
      "правила": [
        { "атрибут": "plan", "оператор": "равно", "значения": ["pro"], "вариант": "вкл" }
      ]
    }
  }
}

Поток изменений

GET /stream

Поток Server-Sent Events: text/event-stream, соединение держится открытым. Один и тот же поток слушают дашборды и SDK.

Событие приходит в формате CloudEvents 1.0, тип - один из com.oneflag.flag.created, com.oneflag.flag.changed, com.oneflag.flag.deleted.

event: com.oneflag.flag.changed
id: 01ARZ3NDEKTSV4RRFFQ69G5FAV
data: {"specversion":"1.0","type":"com.oneflag.flag.changed","source":"/oneflag", ...}

Соединение и keep-alive держит winow. При обрыве клиент переподключается с заголовком Last-Event-ID, поэтому пропущенные события догоняются.

Число открытых подписок видно в GET /stream/info и в метрике oneflag_stream_subscribers.

Ограничение. Поток работает только для клиентов того экземпляра сервиса, который принял изменение. Для нескольких экземпляров общее состояние держит postgresql, но событие в другой экземпляр не уходит.