Endge

Тема

Переопределение переменных настроек через окружение (env) ​

Приоритет: очень высокий.

В настройках (settings) задаются переменные (vars), которые затем резолвятся в значения и используются в приложении. Потребность: явное и гарантированное переопределение этих переменных через окружение — если в среде (env) задано значение, оно подставляется вместо значения из настроек. Это необходимо для разных сред (dev/test/staging/prod), для секретов и для деплоя без правки доменных настроек. Связь с общей темой конфигурации — Configuration_And_Feature_Flags.

Обоснование ​

В enterprise и в 12-Factor App конфигурация приложения выносится в окружение; секреты и URL по средам не хранятся в коде и не в открытом виде в доменных настройках. Low-Code платформы (OutSystems, Mendix) позволяют переопределять параметры приложения из среды развёртывания. Без явного контракта переопределения vars через env невозможен безопасный деплой в несколько сред и высок риск утечки секретов в настройках домена.

Текущее состояние ​

  • Переменные workspace: definitions задаются в workspace и резолвятся через Endge.workspace.variables.getValue(name) или подстановку {VAR_NAME} через Endge.workspace.variables.resolve().
  • EndgeVars уже имеет приоритет источников:
    1. ENVY (специальный объект/JSON в import.meta.env.ENVY)
    2. Vite env: import.meta.env.VITE_NAME (вместо NAME используется имя переменной без префикса: ENDPOINT_AUTH - VITE_ENDPOINT_AUTH)
    3. Домен: settings.general.vars (currentValue или defaultValue)

То есть технически переопределение через VITE_* и ENVY уже есть, но:

  • Нет явного контракта «любая переменная из settings.vars может быть переопределена через окружение»: поведение размазано по коду и не задокументировано как основная возможность.
  • Нет единого правила именования и префикса: только VITE_ для Vite; при runtime-инъекции env (например, с сервера) контракт не описан.
  • В UI настроек и в документации не отражено, что переменная «переопределяется из env, если задана».
  • При добавлении новых источников (например, runtime env с бэкенда) приоритет и формат должны быть определены один раз и соблюдаться везде.

Требования (To Do, высокий приоритет) ​

1. Явный контракт переопределения ​

  • Зафиксировать: любая переменная из settings.general.vars (и при необходимости из других секций) может быть переопределена через окружение. Если в окружении есть значение для этой переменной — при резолве подставляется оно, а не значение из настроек (currentValue/defaultValue).
  • Документировать контракт в документации платформы и в описании настроек (виджет/раздел «Настройки», описание vars).

2. Правило именования в env ​

  • Определить единое правило: как имя переменной в настройках (name) маппится на ключ в окружении.
    • Сейчас для Vite: name - VITE_${name} (например, API_URL - VITE_API_URL). Зафиксировать это и при необходимости поддержать альтернативный префикс (например, для runtime env с сервера — отдельный префикс или отдельный источник).
  • Учитывать регистр и допустимые символы в именах переменных (чтобы и в настройках, и в env не было расхождений).

3. Приоритет источников ​

  • Сохранить и явно описать порядок: сначала окружение (ENVY, затем Vite env или runtime env), затем домен (settings.vars). Так «среда» всегда перебивает «настройки», что нужно для деплоя и секретов.

4. Отражение в UI и диагностике ​

  • В админке (инспектор настроек, список vars): показывать, что значение переменной «взято из окружения» (например, иконка или пометка «переопределено из env»), чтобы администратор понимал, почему редактирование в настройках не действует.
  • Опционально: в диагностике/логах при резолве можно не логировать значения секретов, но фиксировать факт использования значения из env (по имени переменной).

5. Runtime env (при необходимости) ​

  • Если окружение подставляется не только на сборке (Vite), но и в рантайме (например, конфиг с бэкенда или переменные, инъектируемые при старте приложения), ввести для них явный источник и место в приоритете (например, после ENVY, до VITE_* или после VITE_*), чтобы переопределение через «среду» оставалось предсказуемым.

6. Обратная совместимость ​

  • Текущее поведение EndgeVars (ENVY - VITE_* - домен) оставить; изменения только в виде явного контракта, документации и при необходимости расширения источников (runtime env). Не ломать существующие деплои, где уже используются VITE_* или ENVY.

Риски и ограничения ​

  • Изменение приоритета источников или формата ENVY/VITE_* может сломать существующие деплои; все изменения — обратно совместимые, с расширением контракта (например, добавление runtime env), а не заменой.

Итог ​

  • Ввести и задокументировать понятие переопределения переменных из настроек через окружение как поведение платформы с очень высоким приоритетом.
  • Гарантировать: если в среде (env) задана переменная, соответствующая переменной из настроек, — при резолве используется значение из среды.
  • Зафиксировать правило именования (например, VITE_NAME) и приоритет источников; отразить в UI и при необходимости поддержать runtime env.