Files
mtusi2026lab4/openspec/specs/service-configuration/spec.md
T

30 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 печататься в журнал целиком: пароль и строка подключения с паролем в журнал не попадают.

Размер пула по умолчанию SHALL быть 10 соединений на процесс (pool_size). Переполнение пула (max_overflow) по умолчанию SHALL быть 0: соединений сверх размера пула процесс не открывает. Те же значения SHALL стоять в шаблоне config_example.toml. Разовая подмена SHALL работать через окружение (DATABASE__POOL_SIZE, DATABASE__MAX_OVERFLOW) без правки файлов. Наибольшее число соединений стенда — число реплик × (pool_size + max_overflow) плюс подключения миграций и обслуживания. Оно MUST NOT превышать max_connections PostgreSQL, а расчёт для заявленного числа реплик SHALL быть в REPORT.md.

Scenario: Пароль в одном месте

  • WHEN в .env меняется POSTGRES_PASSWORD, и стенд пересоздаётся на новом volume
  • THEN и Postgres, и сервис в консоли и в docker используют новый пароль без правки других файлов

Scenario: Пароль не в журнале

  • WHEN сервис стартует и подключается к Postgres
  • THEN в журнале нет значения пароля

Scenario: Пул по умолчанию

  • WHEN сервис запущен без config.toml или с config.toml из шаблона, а окружение параметры пула не задаёт
  • THEN пул процесса — 10 соединений без переполнения

Requirement: Консоль и docker без правки конфигурации

Переключение между запуском в консоли и в docker MUST NOT требовать правки .env, config.toml или compose, в том числе комментирования и раскомментирования блоков. В консоли сервис SHALL подключаться к PostgreSQL, Valkey и S3 по адресам публикации на хосте из .env, в docker — по адресам и портам внутри сети compose, которые compose передаёт в окружение контейнера из переменных .env.

Scenario: Консоль, затем docker

  • WHEN выполнен make run_dev, затем он остановлен и выполнен make run_docker, а файлы конфигурации между запусками не менялись
  • THEN оба запуска доходят до /health/ready 200, видят одни и те же данные и пишут карточки чатов в Valkey, а запись о старте называет S3 стенда: в консоли — адрес публикации на хосте, в docker — адрес в сети compose

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: Подключение к S3

Параметры S3 SHALL задаваться в секции [s3]:

  • адрес и порт;
  • имя bucket;
  • ключи пользователя S3 процесса: у реплик API — пользователя API, у уборщика — пользователя уборщика;
  • регион;
  • срок вызова и срок установки соединения;
  • размер пула соединений клиента.

Секреты API и уборщика SHALL иметь по одному источнику — переменной .env, которую читает и bootstrap S3. Процесс получает свой секрет мостом или через environment compose. Имя bucket читают и приложение, и bootstrap, поэтому в .env оно записывается в формате настроек. Новый .env из make env_setup SHALL получать случайные секреты S3: административный секрет, секрет API, секрет уборщика и ключ подписи. В существующий .env make env_setup SHALL дописывать переменные шаблона, которых в нём нет: секреты — случайными значениями, остальные — значениями шаблона. Существующие строки он MUST NOT менять, а в вывод SHALL печатать только имена дописанных переменных, без значений. Секреты S3 MUST NOT попадать в журнал.

Имя bucket SHALL соответствовать правилам имён bucket S3: 3–63 символа, строчные латинские буквы, цифры, . и -, первый и последний символ — буква или цифра. Сроки SHALL быть положительными числами. Иначе сервис MUST NOT стартовать (требование «Некорректное значение останавливает запуск»).

Соответствие имён skeleton S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_ACCESS_KEY_ID_FILE и S3_SECRET_ACCESS_KEY_FILE реальной конфигурации SHALL быть описано в REPORT.md.

Scenario: Секрет API в одном месте

  • WHEN в .env меняется секрет API S3, и стенд поднимается заново
  • THEN bootstrap приводит к нему пользователя API, а сервис в консоли и в docker использует новый секрет без правки других файлов

Scenario: Секреты в новом .env

  • WHEN make env_setup дважды выполняется в каталоге без .env, и между запусками .env удаляется
  • THEN секреты S3, в том числе секрет уборщика, в обоих .env непустые и различаются

Scenario: Недостающие переменные в существующем .env

  • WHEN в существующем .env нет переменных, которые есть в шаблоне (например, секретов уборщика), и выполняется make env_setup
  • THEN эти переменные дописаны в конец .env, секреты среди них непустые, прежние строки не изменились, а вывод называет только имена дописанных переменных; повторный запуск ничего не дописывает

Scenario: Секреты S3 не в журнале

  • WHEN сервис стартует и обращается к S3, в том числе с неверным секретом
  • THEN в журнале нет ни секретов S3, ни ключей доступа

Scenario: Недопустимое имя bucket

  • WHEN сервис запускается с S3__BUCKET=Bad_Bucket
  • THEN сервис не стартует, а в выводе упомянут bucket

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_timeout 10 с

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_seconds 6
  • THEN сервис не стартует, ошибка называет оба параметра

Requirement: Лимиты вложений — константы контракта

Лимиты вложения — 10 485 760 байт на тело и 40 000 000 пикселей — SHALL быть константами приложения, а не настройками: их задаёт контракт, и они одинаковы на всех установках. Ни окружение, ни .env, ни config.toml MUST NOT их менять. Соответствие имён skeleton MAX_UPLOAD_BYTES и MAX_IMAGE_PIXELS этим константам SHALL быть описано в REPORT.md.

Scenario: Окружение не меняет лимит

  • WHEN сервис запущен с MAX_UPLOAD_BYTES=1 и MAX_IMAGE_PIXELS=1 в окружении, и участник загружает sample.png
  • THEN ответ 201: лимиты остались контрактными

Requirement: Параметры уборщика

Параметры уборщика незавершённых загрузок (capability storage-consistency) SHALL задаваться в секции [cleaner]:

  • interval_seconds — пауза между проходами, по умолчанию 60;
  • pending_grace_seconds — grace period, по умолчанию 900;
  • batch_size — сколько незавершённых загрузок уборщик выбирает одним запросом к PostgreSQL, по умолчанию 100.

Значения SHALL быть положительными, batch_size — целым. Иначе уборщик MUST NOT стартовать (требование «Некорректное значение останавливает запуск»).

Grace SHALL быть больше границы живой загрузки — суммы сроков её шагов после записи метаданных: 2 × [database] request_timeout_seconds + [s3] timeout_seconds, по настройкам процесса уборщика (17 с по умолчанию). Иначе уборщик MUST NOT стартовать: код выхода ненулевой, а ошибка называет grace, оба срока и границу.

Сравнение grace с границей SHALL выполнять только уборщик при своём старте: реплики API секцию [cleaner] не используют и от этой проверки не зависят. Разовая подмена SHALL работать через окружение CLEANER__* без правки файлов. Значения по умолчанию и обоснование grace SHALL быть описаны в REPORT.md.

Scenario: Параметры по умолчанию

  • WHEN уборщик запущен без секции [cleaner] и без переменных CLEANER__*
  • THEN запись о его старте называет интервал 60 с, grace 900 с и выборку 100

Scenario: Grace не больше границы

  • WHEN уборщик запускается с CLEANER__PENDING_GRACE_SECONDS=17 при сроках по умолчанию
  • THEN уборщик не стартует, код выхода ненулевой, а ошибка называет grace, оба срока и границу 17 с

Scenario: Интервал не число

  • WHEN уборщик запускается с CLEANER__INTERVAL_SECONDS=0 или CLEANER__INTERVAL_SECONDS=abc
  • THEN уборщик не стартует, в журнале — ошибка проверки настроек

Requirement: Параметры загрузок

Ограничения загрузок вложений процесса API (capability attachments, «Одновременные загрузки реплики», «Срок передачи тела») SHALL задаваться в секции [uploads]:

  • max_concurrent — сколько загрузок процесс обрабатывает одновременно, по умолчанию 4;
  • max_waiting — сколько загрузок может ждать места, по умолчанию 16; 0 — без ожидания, загрузка без места сразу получает 429;
  • wait_timeout_seconds — сколько секунд загрузка ждёт места, по умолчанию 5;
  • body_timeout_seconds — за сколько секунд после того, как загрузка заняла место, должно прийти её тело, по умолчанию 30.

max_concurrent SHALL быть целым не меньше 1, max_waiting — целым не меньше 0, сроки — положительными числами. Иначе сервис MUST NOT стартовать (требование «Некорректное значение останавливает запуск»). Значения SHALL одинаково действовать в консоли и в docker. Разовая подмена SHALL работать через окружение UPLOADS__* без правки файлов. Запись журнала о старте API SHALL называть все четыре значения.

Значения по умолчанию и их обоснование SHALL быть описаны в REPORT.md:

  • бюджет памяти реплики: интерпретатор, хэши паролей и места загрузок в лимите контейнера;
  • сроки пути загрузки в балансировщике (load-balancing, «Загрузки через балансировщик»).

Scenario: Параметры загрузок по умолчанию

  • WHEN сервис запущен без секции [uploads] и без переменных UPLOADS__*
  • THEN запись журнала о старте называет 4 места, 16 ожидающих, ожидание 5 с и срок тела 30 с

Scenario: Подмена параметров загрузок окружением

  • WHEN сервис запущен с UPLOADS__MAX_CONCURRENT=1 и UPLOADS__MAX_WAITING=0, а файлы не менялись
  • THEN вторая одновременная загрузка, пока первая не закончилась, сразу получает 429

Scenario: Неверный параметр загрузок

  • WHEN сервис запускается с UPLOADS__MAX_CONCURRENT=0, UPLOADS__MAX_WAITING=-1 или UPLOADS__BODY_TIMEOUT_SECONDS=abc
  • THEN сервис не стартует, в журнале — ошибка проверки настроек с именем поля

Requirement: Параметры сверки

Параметры сверки bucket и БД (capability storage-consistency) SHALL задаваться в секции [reconciler]:

  • interval_seconds — пауза между плановыми сверками процесса уборщика, по умолчанию 3600; 0 — без плановой сверки;
  • page_size — сколько ключей сверка берёт одной страницей списка S3 и сколько строк одним запросом к PostgreSQL, по умолчанию 1000, не больше 1000;
  • max_changes — предел изменений за проход, по умолчанию 100.

interval_seconds SHALL быть неотрицательным числом, page_size и max_changes — целыми не меньше 1. Иначе уборщик MUST NOT стартовать (требование «Некорректное значение останавливает запуск»).

Отдельного grace у сверки нет: она берёт [cleaner] pending_grace_seconds и его проверку границы живой загрузки (требование «Параметры уборщика»). Разовая подмена SHALL работать через окружение RECONCILER__* без правки файлов. Разовый проход SHALL принимать предел изменений и аргументом команды. Значения по умолчанию и их обоснование SHALL быть описаны в REPORT.md. Реплики API секцию [reconciler] не используют.

Scenario: Параметры сверки по умолчанию

  • WHEN уборщик запущен без секции [reconciler] и без переменных RECONCILER__*
  • THEN запись о его старте называет интервал сверки 3600 с, страницу 1000 и предел изменений 100

Scenario: Неверный параметр сверки

  • WHEN уборщик запускается с RECONCILER__PAGE_SIZE=5000, RECONCILER__MAX_CHANGES=0 или RECONCILER__INTERVAL_SECONDS=-1
  • THEN уборщик не стартует, в журнале — ошибка проверки настроек с именем поля