- upload: delete the stored object when ready fails before COMMIT or the pending row is gone (503 instead of 500); unknown COMMIT outcome keeps it - cleaner service (python -m src.cleaner): stale pending rows older than grace (900 s, must exceed 17 s live-upload bound) under FOR UPDATE SKIP LOCKED, object before row, own S3 user with read/delete only - shared session_scope for API and cleaner; early_stop process name - partial index on pending attachments, CREATE INDEX CONCURRENTLY - s3-bootstrap: cleaner user, policy and checks; make env_setup appends missing template variables to an existing .env - failure checks: cleaner on the failure stand, id-list hook actions, five new and three updated tests; driver upload-consistency - sync upload-consistency deltas into main specs (storage-consistency) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
24 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 печататься в
журнал целиком: пароль и строка подключения с паролем в журнал не
попадают.
Размер пула по умолчанию 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/ready200, видят одни и те же данные и пишут карточки чатов в 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_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 сервис не стартует, ошибка называет оба параметра
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 уборщик не стартует, в журнале — ошибка проверки настроек