Настройки

Настройки платформы: уровни, на которых их задают, хозяева ключей, окно настроек, языки интерфейса и перечень всех ключей.

Введение

Документ описывает источники значений настроек, хозяев ключей, отображение настроек человеку и устройство языков интерфейса. Значения хранит функция settings, тексты собирает функция i18n, смысл каждого ключа определяет его хозяин. Формат файлов — Форматы файлов, раздел 8, методы — Методы служб платформы, раздел 1.

1 Уровни

Значение ищется от узкого уровня к широкому и берётся с первого уровня, где оно задано. Уровни в таблице 1 перечислены от широкого к узкому.

Таблица 1 — Уровни

Уровня настроек модуля нет: то, что человек задаёт модулю, — параметры узла (Модули, раздел 10).

Ключи core.* на любом уровне, кроме session, записываются в core.json. Ключ со схемой restart: true начинает действовать при следующем запуске; платформа не показывает его применённым сразу.

2 Схема настроек

Каждый хозяин описывает свои настройки в одном файле схемы settings.schema.json рядом со своим кодом (Устройство платформы); программа встраивает его при сборке. Других мест, где записаны умолчание или пределы настройки, нет — ни в коде хозяина, ни в функции настроек, ни в окне (правило 2.2 Правила разработки). Формат файла — Форматы файлов, раздел 8.

Схема делит настройки хозяина на подразделы. У каждого ключа в ней:

• type — string, integer, number (дробное число: доля, миллиметры, температура модели), string[] или color (#RGB / #RRGGBB);
• default — значение по умолчанию;
• default_by — необязательно: умолчание, которое зависит от значения другого ключа того же хозяина. Так цвета оболочки следуют выбранной цветовой схеме;
• restart — нужен ли перезапуск, чтобы значение подействовало;
• для чисел — min и max, для закрытого набора значений — choices.

Тексты настройки хранятся в словарях хозяина, а не в схеме, и именуются по правилу; имена текстов отдельно не записываются (таблица 2).

Таблица 2 — Тексты настройки в словарях

Проверка в make ci не проходит, если у ключа схемы нет хотя бы одного из этих текстов на русском или английском или если пояснение повторяет число своей схемы — предел или умолчание, кроме нуля: такая копия разойдётся со схемой при первом её изменении.

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

Исключение — значения уровня процесса: это свободные ключи для подстановки в параметры узлов (Программа: граф и запуски, раздел 15), схемы у них нет. Записывает их settings.set с уровнем process, а settings.get с process_id возвращает их в записанном виде (Методы служб платформы, раздел 1).

3 Хозяева ключей

Префикс ключа — адрес хозяина (правило 2.4). Функция настроек хранит значения и проверяет их по схеме, но своих ключей у неё нет: смысл каждого ключа определяет его хозяин.

Таблица 3 — Хозяева ключей

Хозяин регистрирует схему при запуске и снова всякий раз, когда функция настроек поднимается заново (событие function.ready): схемы хозяев она держит, только пока работает, и после её перезапуска без повторной регистрации значения человека перестали бы действовать. Хозяин называет settings в своём описании (requires, Устройство платформы, 3.4.1); make ci это проверяет. Хозяин, которому умолчания его схемы безвредны, называет её необязательной (optional) и до её прихода работает на умолчаниях — так устроена функция i18n; графу и функции модулей настройки обязательны: их значения решают, что хранить и сколько ресурсов занять. Регистрировать можно только свою схему: хозяина называет ядро, отправитель вызова (Обмен с ядром, раздел 3), и схема другого хозяина — отказ settings_invalid_owner; в схеме — только ключи со своим префиксом, чужой ключ — отказ settings_invalid. Повторная регистрация того же хозяина заменяет его схему целиком.

Ядро стартует раньше функции настроек и не может её запросить. Поэтому ключи core.* оно читает само: по своей схеме, из core.json и system.json. Если значение в этих файлах не подходит по схеме — недопустимое число или неверный тип, — ядро не стартует и называет файл, ключ, значение и допустимые значения. Так же оно поступает с файлом, который не разбирается.

Функция настроек проверяет по схеме и то, что уже лежит в файлах уровней: файл мог быть изменён вручную. Неподходящее значение она не использует — берёт значение с более широкого уровня — и публикует событие settings.value_invalid с error_code: settings_value_invalid, файлом и ключом; по нему функция наблюдения открывает проблему.

4 Запись и сброс

• Значение проверяется до записи; если оно не подходит, остаётся старое.
• Файл записывается целиком, после записи публикуется событие settings.changed.
• Сброс убирает значение с уровня: ключ удаляется из файла или из памяти сессии, и значение снова берётся с более широких уровней и из схемы. Умолчание в файл не записывается. Ключ убирается из того файла, куда шла его запись на этом уровне: ключ core.* — из core.json, как и записывался.

5 Секреты

Платформа не хранит пароли и ключи доступа. Настройка, в имени которой есть secret, password, token, api_key, apikey или private_key (большие и маленькие буквы не различаются), отклоняется с settings_secret_rejected. Это защита от случайной ошибки, а не распознавание секретов: ключ openai_key проверку пройдёт (Защита, 3.5).

6 Окно настроек

• Раздел «Состояние» расположен первым в колонке окна: работает ли ядро, какие функции на связи, последние ошибки и простые счётчики. Этот раздел не является списком модулей.
• Порядок. Далее следуют крупные разделы (ядро, интерфейс, прочее), внутри них — подразделы. Подразделы по умолчанию свёрнуты.
• Изменение значения. Значение изменяется во вкладке «Правка» панели выбранной настройки (Мастерская, 5.1); клавиша Enter, кнопка «Записать» и переход к другой настройке записывают значение, как уход из поля пульта; значение, которое не проходит проверку схемы, не записывается. Значение из закрытого набора выбирается из списка.
• Справка. У каждой строки есть знак «?», раскрывающий пояснение; пояснение, ключ, умолчание и допустимые значения показывает вкладка «Информация».
• Сброс. Кнопка «Сбросить» во вкладке «Правка» возвращает умолчание настройки, кнопка «Сбросить всё» — умолчания всего раздела.
• Перезапуск. Настройки, требующие перезапуска, помечены.

7 Языки

• В коде только ключи строк, сами тексты — в словарях JSON хозяина текста: подписи окна — у функции ui, названия настроек и тексты ошибок — у хозяина ключа или кода ошибки (правило 2.2). Функция i18n собирает словари, но чужих текстов не хранит.
• Язык интерфейса — настройка i18n.language. Её хозяин — функция i18n; окно настроек записывает её обычным settings.set, как любую другую, переключатель языка мастерской — командой хозяина i18n.language.set, а узнаёт язык мастерская запросом i18n.language.get, ключа настройки не зная; а функция i18n читает её при каждом запросе и собственной копии языка не хранит.
• Словари. Функции объявляют папки своих словарей при знакомстве (locales); папка с сегментом * означает каждую такую папку, которая есть в момент вопроса, поэтому словари, появившиеся во время работы, видны без нового объявления (Обмен с ядром, раздел 4). Ядро отдаёт их список запросом core.locales и добавляет в него свою папку core/kernel/locales; функция i18n читает только эти папки и свою собственную.
• Язык модуля. Модуль узнаёт язык в сообщении init. Функция модулей спрашивает его у хозяина запросом i18n.language.get при каждом запуске модуля; без функции i18n язык в init — null, и модуль говорит на своём языке по умолчанию.
• Отсутствие текста для ключа является проблемой для диагностики, а не отказом: i18n.translate отдаёт сам ключ вместо текста и публикует событие i18n.key_missing с error_code: i18n_key_missing, по которому функция наблюдения открывает одну проблему на ключ.
• Обязательные языки — русский и английский; новый язык — это словари, без кода. Готовых наборов настроек, включаемых целиком, нет: уровни и сброс уже дают начать заново.

8 Перечень ключей

Раздел содержит только ключи и их назначение. Тип, умолчание, допустимые значения и нужен ли перезапуск записаны в одном месте — в файле схемы хозяина, — и в документе не повторяются: изменение умолчания выполняется в одном файле. Проверка в make ci не проходит, если ключ схемы здесь не упомянут или упомянут ключ, которого нет ни в одной схеме.

Ядро — core/kernel/settings.schema.json:

Таблица 4 — Ключи настроек ядра

Ядро читает свои ключи при запуске, поэтому они действуют после перезапуска платформы; два ключа места ядро перечитывает при каждом вопросе о месте, и они действуют сразу.

Мастерская — functions/ui/settings.schema.json:

Таблица 5 — Ключи настроек мастерской

Язык — functions/i18n/settings.schema.json:

Таблица 6 — Ключи настроек языка

Граф — functions/graph/settings.schema.json:

Таблица 7 — Ключи настроек функции графа

Модули — functions/modules/settings.schema.json:

Таблица 8 — Ключи настроек функции модулей

Сколько ждать остановки модуля, задаёт core.process_stop_grace_ms: остановкой OS-процесса занимается ядро, и второго ключа о том же нет.

Пульт — functions/canvas/settings.schema.json, раздел окна настроек «Интерфейс платформы»:

Таблица 9 — Ключи настроек функции пульта

Числа листа действуют со следующего изменения пульта; листы, которые уже есть, от них не меняются. Процесс может иметь свои числа на уровне настроек процесса (Мастерская, 6.3).

Ключи canvas.theme_* — вид пульта, который своего не задал: пульт называет в документе только те ключи темы, которые задал сам, остальные берутся отсюда (Мастерская, 6.5). Раздел схемы canvas.theme — одновременно закрытый перечень ключей темы и описание того, что каждый принимает: документ пульта проверяется по нему же (Форматы файлов, раздел 7).

Журнал — functions/observe/settings.schema.json:

Таблица 10 — Ключи настроек функции наблюдения

Источники — functions/sources/settings.schema.json (Мастерская, 5.6):

Таблица 11 — Ключи настроек функции источников

Вход для программ — functions/gate/settings.schema.json (Методы служб платформы, раздел 5):

Таблица 12 — Ключи настроек функции входа

Помощник — functions/assistant/settings.schema.json (Методы служб платформы, раздел 6):

Таблица 13 — Ключи настроек функции помощника

Профиль — functions/profile/settings.schema.json (Методы служб платформы, раздел 7):

Таблица 14 — Ключи настроек функции профиля