Delta specs synced into graceful-shutdown, load-balancing, load-benchmark and service-configuration; the change moves to openspec/changes/archive/2026-10-11-graceful-failover/. PLAN.md marks the change archived and AGENTS.md notes what was handed to rolling-update. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
15 KiB
service-configuration Specification
Purpose
Как оператор настраивает сервис: источники значений и их приоритет, имена параметров по секциям, запуск без файлов конфигурации и режимы запуска console / docker.
Requirements
Requirement: Источники настроек и приоритет
Сервис SHALL читать настройки из переменных окружения процесса, файла
.env, файла config.toml и встроенных значений по умолчанию, в этом
порядке убывания приоритета. Отсутствующий файл SHALL пропускаться без
ошибки.
Scenario: Окружение важнее файла
- WHEN
[app] log_levelвconfig.tomlравенDEBUG, а процесс запущен сAPP__LOG_LEVEL=WARNING - THEN действует уровень
WARNING
Scenario: Запуск без файлов
- WHEN в каталоге нет ни
.env, ниconfig.toml - THEN сервис стартует на значениях по умолчанию и слушает порт 8080
Requirement: Параметры по секциям
Каждый параметр SHALL принадлежать секции: в config.toml — таблица
[section], в окружении — имя SECTION__FIELD без учёта регистра.
Переменные без префикса секции MUST NOT влиять на сервис.
Scenario: Имя с секцией
- WHEN процесс запущен с
APP__PORT=9090 - THEN сервис слушает порт 9090
Scenario: Имя без секции
- WHEN процесс запущен с
APP_PORT=9090и безAPP__PORT - THEN сервис слушает порт по умолчанию
Requirement: Некорректное значение останавливает запуск
Значение, которое не приводится к типу параметра, SHALL останавливать запуск с сообщением, где названо поле. Сервис MUST NOT молча подставлять значение по умолчанию вместо некорректного.
Scenario: Порт не число
- WHEN процесс запущен с
APP__PORT=abc - THEN запуск завершается ошибкой, в выводе упомянут
port
Requirement: Режимы запуска
Режим SHALL задаваться параметром APP__RUN_MODE со значениями
console и docker, по умолчанию console. В режиме console сервис
SHALL слушать только 127.0.0.1 и перезапускаться при изменении
исходного кода. В режиме docker сервис SHALL слушать 0.0.0.0 без
автоперезапуска.
Scenario: Console по умолчанию
- WHEN сервис запущен командой
python -m srcбезAPP__RUN_MODE - THEN он доступен на
127.0.0.1:8080и недоступен с других интерфейсов
Scenario: Docker
- WHEN сервис запущен с
APP__RUN_MODE=docker - THEN он слушает
0.0.0.0:8080
Requirement: Файлы с локальными значениями не в git
config.toml и .env SHALL игнорироваться git. В репозитории SHALL
храниться шаблон config_example.toml без секретов.
Scenario: Проверка ignore
- WHEN в корне создан
config.toml - THEN
git statusего не показывает, аconfig_example.tomlотслеживается
Requirement: Подключение к PostgreSQL
Параметры подключения SHALL задаваться в секции [database]: адрес,
порт, пользователь, пароль, имя базы, размер пула и таймауты. Пароль
SHALL иметь один источник — POSTGRES_PASSWORD в .env, который
читает и контейнер Postgres. Значения параметров MUST NOT печататься в
журнал целиком: пароль и строка подключения с паролем в журнал не
попадают.
Scenario: Пароль в одном месте
- WHEN в
.envменяетсяPOSTGRES_PASSWORD, и стенд пересоздаётся на новом volume - THEN и Postgres, и сервис в консоли и в docker используют новый пароль без правки других файлов
Scenario: Пароль не в журнале
- WHEN сервис стартует и подключается к Postgres
- THEN в журнале нет значения пароля
Requirement: Консоль и docker без правки конфигурации
Переключение между запуском в консоли и в docker MUST NOT требовать
правки .env, config.toml или compose, в том числе
комментирования и раскомментирования блоков. В консоли сервис SHALL
подключаться к PostgreSQL и Valkey по адресам публикации на хосте из
.env, в docker — по адресам и портам внутри сети compose, которые
compose передаёт в окружение контейнера из переменных .env.
Scenario: Консоль, затем docker
- WHEN выполнен
make run_dev, затем он остановлен и выполненmake run_docker, а файлы конфигурации между запусками не менялись - THEN оба запуска доходят до
/health/ready200, видят одни и те же данные и пишут карточки чатов в Valkey
Requirement: Подключение к Valkey
Адрес, порт и пароль Valkey SHALL задаваться в секции [cache], таймаут
клиента, время пропуска кэша после отказа, срок записей и размер пула —
тоже. Пароль SHALL иметь один источник — VALKEY_PASSWORD в .env,
который читает и контейнер Valkey. Новый .env из make env_setup
SHALL получать случайный пароль. Пароль MUST NOT попадать в журнал.
Scenario: Пароль Valkey в одном месте
- WHEN в
.envменяетсяVALKEY_PASSWORD, и стенд пересоздаётся - THEN Valkey и сервис в консоли и в docker используют новый пароль без правки других файлов
Scenario: Пароль Valkey не в журнале
- WHEN сервис стартует и обращается к Valkey, в том числе при его недоступности
- THEN в журнале нет значения пароля
Requirement: Срок жизни сессии
Срок жизни сессии SHALL задаваться параметром приложения
[auth] session_ttl_seconds в config.toml и одинаково действовать в
консоли и в docker. Без параметра срок SHALL быть 3600 с. Разовая
подмена SHALL работать через окружение AUTH__SESSION_TTL_SECONDS без
правки файлов. Значение SHALL быть целым положительным числом секунд,
иначе сервис MUST NOT стартовать (требование «Некорректное значение
останавливает запуск»). Соответствие контрактному имени
SESSION_TTL_SECONDS SHALL быть описано в REPORT.md.
Scenario: Срок из config.toml
- WHEN в
config.tomlзадано[auth] session_ttl_seconds = 600, и сервис запущен черезmake run_devилиmake run_docker - THEN
expires_atновой сессии на 600 с позже момента входа
Scenario: Срок по умолчанию
- WHEN параметр в
config.tomlне задан - THEN
expires_atновой сессии на 3600 с позже момента входа
Scenario: Короткий срок из окружения
- WHEN сервис запущен с
AUTH__SESSION_TTL_SECONDS=2в окружении, а файлы не менялись - THEN
expires_atновой сессии на 2 с позже момента входа
Scenario: Срок не число
- WHEN сервис запускается с
AUTH__SESSION_TTL_SECONDS=abcили0 - THEN сервис не стартует, в журнале — ошибка проверки настроек
Requirement: Идентификатор экземпляра
Значение X-Instance-Id и поля instance_id журнала SHALL браться из
параметра [app] instance_id. Если параметр не задан, SHALL
использоваться hostname процесса, определённый один раз при старте. В
контейнере compose это короткий ID контейнера. Значение SHALL состоять
из 1–64 символов A–Z, a–z, 0–9, ., _, -. Другое значение
SHALL останавливать запуск (требование «Некорректное значение
останавливает запуск»). У реплик значение должно различаться, поэтому
оно MUST NOT задаваться в общих для реплик источниках: в config.toml
и его шаблоне, в .env, в окружении и hostname сервиса API в
compose.
Scenario: Hostname по умолчанию
- WHEN контейнер API запущен через compose без
APP__INSTANCE_ID - THEN
X-Instance-Idравен hostname контейнера — началу его ID изdocker compose ps -q api
Scenario: Явное значение
- WHEN сервис запущен с
APP__INSTANCE_ID=api-a - THEN ответы содержат
X-Instance-Id: api-a, а записи журнала —instance_id=api-a
Scenario: Недопустимое значение
- WHEN сервис запускается с
APP__INSTANCE_ID="api a" - THEN сервис не стартует, в выводе упомянут
instance_id
Requirement: Срок ключа идемпотентности
Срок ключа идемпотентности SHALL задаваться параметром приложения
[idempotency] ttl_seconds в config.toml и одинаково действовать в
консоли и в docker. Без параметра срок SHALL быть 86400 с. Разовая
подмена SHALL работать через окружение IDEMPOTENCY__TTL_SECONDS без
правки файлов. Значение SHALL быть целым положительным числом секунд,
иначе сервис MUST NOT стартовать. Срок меньше 86400 с нарушает
контракт и SHALL применяться только в проверках. Соответствие имени
skeleton IDEMPOTENCY_TTL_SECONDS SHALL быть описано в REPORT.md.
Scenario: Срок ключа по умолчанию
- WHEN параметр в
config.tomlне задан - THEN ключ остаётся занятым 86400 с: в пределах этого срока повтор с другим телом получает 409
Scenario: Короткий срок ключа из окружения
- WHEN сервис запущен с
IDEMPOTENCY__TTL_SECONDS=2в окружении, а файлы не менялись - THEN через 2 с после отправки ключ снова свободен
Scenario: Срок ключа не число
- WHEN сервис запускается с
IDEMPOTENCY__TTL_SECONDS=abcили0 - THEN сервис не стартует, в журнале — ошибка проверки настроек
Requirement: Таймауты соединений за балансировщиком
Параметры приложения SHALL задавать два срока простоя соединений:
[app] keep_alive_seconds— сколько секунд реплика держит простаивающее keep-alive соединение HTTP; по умолчанию 60;[database] idle_in_transaction_timeout_ms— сколько миллисекунд PostgreSQL ждёт следующую команду в открытой транзакции соединения приложения, прежде чем прервать его; по умолчанию 10000, 0 — без ограничения.
Оба SHALL одинаково действовать в консоли и в docker. Разовая подмена
SHALL работать через окружение (APP__KEEP_ALIVE_SECONDS,
DATABASE__IDLE_IN_TRANSACTION_TIMEOUT_MS) без правки файлов.
keep_alive_seconds SHALL быть целым положительным числом.
idle_in_transaction_timeout_ms SHALL быть нулём или целым числом
больше [database] request_timeout_seconds в миллисекундах: иначе
PostgreSQL прерывал бы транзакции живых запросов. При нарушении сервис
MUST NOT стартовать. Как эти сроки согласованы с балансировщиком и
сроком запроса, SHALL быть описано в REPORT.md.
Scenario: Сроки по умолчанию
- WHEN параметры в
config.tomlне заданы - THEN реплика держит простаивающее соединение 60 с, а соединения
приложения с PostgreSQL получают
idle_in_transaction_session_timeout10 с
Scenario: Срок не число
- WHEN сервис запускается с
APP__KEEP_ALIVE_SECONDS=0илиDATABASE__IDLE_IN_TRANSACTION_TIMEOUT_MS=abc - THEN сервис не стартует, в журнале — ошибка проверки настроек
Scenario: Срок простоя транзакции не больше срока запроса
- WHEN сервис запускается с
DATABASE__IDLE_IN_TRANSACTION_TIMEOUT_MS=5000приrequest_timeout_seconds6 - THEN сервис не стартует, ошибка называет оба параметра