Files
mtusi2026lab3/openspec/specs/service-configuration/spec.md
T
ricoromaandClaude Opus 5.5 af4bca08c9 feat: carry lab 2 over and add X-Instance-Id and idempotency keys
- 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>
2026-10-08 19:42:36 +03:00

13 KiB
Raw Blame History

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/ready 200, видят одни и те же данные и пишут карточки чатов в 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 сервис не стартует, в журнале — ошибка проверки настроек