- carry the lab 2 solution over and plan lab 3 (PLAN.md, OpenSpec change instance-id-idempotency) - rename the compose project to mtusi-lab3 and the image to :lab3 - add X-Instance-Id to every response and instance_id to every log record ([app] instance_id, hostname by default) - require Idempotency-Key on POST messages: keys table in Postgres, key and message in one transaction, replay returns the same 201, another body gets 409, TTL from [idempotency] ttl_seconds - send the key from student-tests, k6 scenarios and the skill driver; add idempotency, X-Instance-Id, key race and fault tests Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
13 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 сервис не стартует, в журнале — ошибка проверки настроек