47 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, у уборщика — пользователя уборщика, у worker — пользователя worker;
- регион;
- срок вызова и срок установки соединения;
- размер пула соединений клиента.
Секреты API, уборщика и worker SHALL иметь по одному источнику — переменной
.env, которую читает и bootstrap S3. Процесс получает свой секрет
мостом или через environment compose. Имя bucket читают и приложение,
и bootstrap, поэтому в .env оно записывается в формате настроек.
Новый .env из make env_setup SHALL получать случайные секреты S3:
административный секрет, секрет API, секрет уборщика, секрет worker и ключ
подписи. В существующий .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, в том числе секреты уборщика и worker, и пароль брокера в
обоих
.envнепустые и различаются
Scenario: Недостающие переменные в существующем .env
- WHEN в существующем
.envнет переменных, которые есть в шаблоне (например, секретов worker и брокера), и выполняется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— сколько незавершённых загрузок или вложений с объектом staging уборщик выбирает одним запросом к PostgreSQL, по умолчанию 100;staging_retention_seconds— срок хранения объекта staging вложенияfailedи объекта staging без метаданных, по умолчанию 86400 (сутки, как у имени skeletonSTAGING_RETENTION_SECONDS).
Значения 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, соответствие имени skeleton
STAGING_RETENTION_SECONDS — ещё и в шапке .env.example.
Scenario: Параметры по умолчанию
- WHEN уборщик запущен без секции
[cleaner]и без переменныхCLEANER__* - THEN запись о его старте называет интервал 60 с, grace 900 с, выборку 100 и срок хранения staging 86400 с
Scenario: Grace не больше границы
- WHEN уборщик запускается с
CLEANER__PENDING_GRACE_SECONDS=17при сроках по умолчанию - THEN уборщик не стартует, код выхода ненулевой, а ошибка называет grace, оба срока и границу 17 с
Scenario: Интервал не число
- WHEN уборщик запускается с
CLEANER__INTERVAL_SECONDS=0,CLEANER__INTERVAL_SECONDS=abcилиCLEANER__STAGING_RETENTION_SECONDS=0 - THEN уборщик не стартует, в журнале — ошибка проверки настроек
Requirement: Параметры загрузок
Ограничения загрузок вложений процесса API (capability attachments,
«Одновременные загрузки реплики», «Срок передачи тела»; capability queue-overload, «Предел
незавершённых заданий») SHALL задаваться в секции [uploads]:
max_concurrent— сколько загрузок процесс обрабатывает одновременно, по умолчанию 4;max_waiting— сколько загрузок может ждать места, по умолчанию 16; 0 — без ожидания, загрузка без места сразу получает 429;wait_timeout_seconds— сколько секунд загрузка ждёт места, по умолчанию 5;body_timeout_seconds— за сколько секунд после того, как загрузка заняла место, должно прийти её тело, по умолчанию 30;max_unfinished_jobs— при каком числе незавершённых заданий стенда загрузка получает 429, по умолчанию 250; 0 — без предела.
max_concurrent SHALL быть целым не меньше 1, max_waiting и max_unfinished_jobs — целыми не
меньше 0, сроки — положительными числами. Иначе сервис MUST NOT
стартовать (требование «Некорректное значение останавливает запуск»).
Значения SHALL одинаково действовать в консоли и в docker. Разовая
подмена SHALL работать через окружение UPLOADS__* без правки файлов.
Запись журнала о старте API SHALL называть все пять значений.
Значения по умолчанию и их обоснование SHALL быть описаны в REPORT.md:
- бюджет памяти реплики: интерпретатор, хэши паролей и места загрузок в лимите контейнера;
- сроки пути загрузки в балансировщике (
load-balancing, «Загрузки через балансировщик»); - предел незавершённых заданий: измеренный потолок worker на худшем классе изображений, срок ожидания и объём staging при заполненном пределе.
Scenario: Параметры загрузок по умолчанию
- WHEN сервис запущен без секции
[uploads]и без переменныхUPLOADS__* - THEN запись журнала о старте называет 4 места, 16 ожидающих, ожидание 5 с, срок тела 30 с и предел 250 незавершённых заданий
Scenario: Подмена параметров загрузок окружением
- WHEN сервис запущен с
UPLOADS__MAX_CONCURRENT=1иUPLOADS__MAX_WAITING=0, а файлы не менялись - THEN вторая одновременная загрузка, пока первая не закончилась, сразу получает 429
Scenario: Неверный параметр загрузок
- WHEN сервис запускается с
UPLOADS__MAX_CONCURRENT=0,UPLOADS__MAX_WAITING=-1,UPLOADS__MAX_UNFINISHED_JOBS=-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;max_objects_per_second— предел скорости прохода: сколько объектов S3 он затрагивает в секунду (capabilitystorage-consistency, «Скорость сверки»), по умолчанию 2000; 0 — без ограничения.
interval_seconds и max_objects_per_second SHALL быть
неотрицательными числами, max_objects_per_second — ещё и конечным (не
inf и не nan), 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 и предел скорости 2000 объектов в секунду
Scenario: Неверный параметр сверки
- WHEN уборщик запускается с
RECONCILER__PAGE_SIZE=5000,RECONCILER__MAX_CHANGES=0,RECONCILER__INTERVAL_SECONDS=-1,RECONCILER__MAX_OBJECTS_PER_SECOND=-1илиRECONCILER__MAX_OBJECTS_PER_SECOND=inf - THEN уборщик не стартует, в журнале — ошибка проверки настроек с именем поля
Requirement: Подключение к брокеру
Параметры брокера SHALL задаваться в секции [broker]:
- адрес и порт;
- пользователь и пароль;
- срок установки соединения;
- срок публикации — от начала публикации пакета заданий до подтверждений брокера, включая установку соединения; по умолчанию 2 с.
Секцию читают relay и worker, реплики API её не используют. Пароль SHALL иметь один
источник — переменную .env, которую читает и контейнер брокера. Новый .env из make env_setup SHALL получать случайный пароль. Пароль MUST NOT попадать в журнал. Сроки SHALL
быть положительными числами, иначе процесс MUST NOT стартовать (требование «Некорректное
значение останавливает запуск»). Разовая подмена SHALL работать через окружение BROKER__*
без правки файлов.
Соответствие имени skeleton BROKER_URL_FILE реальной конфигурации SHALL быть
описано в шапке .env.example и в REPORT.md.
Scenario: Пароль брокера в одном месте
- WHEN в
.envзадан пароль брокера, и стенд поднят на новом volume - THEN брокер, relay и worker в консоли и в docker используют его без правки других файлов
Scenario: Пароль брокера не в журнале
- WHEN relay и worker стартуют и обращаются к брокеру, в том числе при его недоступности
- THEN в журнале нет значения пароля
Scenario: Запись о старте называет брокер
- WHEN relay и worker стартуют
- THEN их записи о старте называют адрес брокера и имя очереди, а срок публикации по умолчанию в записи relay — 2 с
Scenario: Неверный срок публикации
- WHEN relay запускается с
BROKER__PUBLISH_TIMEOUT_SECONDS=0илиabc - THEN relay не стартует, в журнале — ошибка проверки настроек с именем поля
Requirement: Параметры worker
Параметры worker (capability attachment-processing) SHALL задаваться в секции
[worker]:
concurrency— сколько заданий worker обрабатывает одновременно, по умолчанию 2;prefetch— сколько неподтверждённых сообщений выдаёт ему брокер, по умолчанию 2;max_attempts— сколько попыток у задания с последнего replay, по умолчанию 5;job_timeout_seconds— срок одной попытки, по умолчанию 60;lease_margin_seconds— запас аренды сверх срока попытки, по умолчанию 10;retry_base_delay_seconds— основа паузы перед следующей попыткой, по умолчанию 5;retry_max_delay_seconds— верхняя граница паузы, по умолчанию 300;render_timeout_seconds— срок процесса обработки, по умолчанию 40, меньше срока попытки;render_cpu_limit_seconds— лимит CPU процесса обработки в секундах, целое, по умолчанию 15;render_memory_limit_mib— лимит адресного пространства процесса обработки в МиБ, целое, по умолчанию 450;graceful_shutdown_seconds— сколько worker ждёт начатые задания после SIGTERM, по умолчанию 8, не больше 8;reconnect_seconds— пауза между попытками соединиться с брокером и перед возвратом сообщения при отказе PostgreSQL, по умолчанию 2.
concurrency, prefetch, max_attempts, лимиты CPU и памяти SHALL быть целыми не меньше 1,
сроки — положительными конечными числами, retry_max_delay_seconds — не меньше
retry_base_delay_seconds. Иначе worker MUST NOT стартовать: код выхода ненулевой, а ошибка называет
поле. Разовая подмена SHALL работать через окружение WORKER__* без правки файлов. Реплики API
секцию [worker] не используют; relay её тоже не читает. Запись о старте worker SHALL называть
все значения.
Соответствие имён skeleton WORKER_CONCURRENCY, JOB_MAX_ATTEMPTS и
JOB_TIMEOUT_SECONDS этим полям SHALL быть описано в шапке .env.example и в REPORT.md.
Scenario: Параметры worker по умолчанию
- WHEN worker запущен без секции
[worker]и без переменныхWORKER__* - THEN запись о его старте называет конкуренцию 2, prefetch 2, 5 попыток, срок 60 с, запас аренды 10 с, основу паузы 5 с и её предел 300 с, лимиты процесса обработки 40 с, 15 с CPU и 450 МиБ, срок остановки 8 с и паузу соединения 2 с
Scenario: Подмена параметров worker окружением
- WHEN worker запущен с
WORKER__CONCURRENCY=1иWORKER__MAX_ATTEMPTS=2, а файлы не менялись - THEN запись о старте называет эти значения, и одновременно обрабатывается одно задание
Scenario: Неверный параметр worker
- WHEN worker запускается с
WORKER__CONCURRENCY=0,WORKER__PREFETCH=0,WORKER__MAX_ATTEMPTS=abc,WORKER__GRACEFUL_SHUTDOWN_SECONDS=9,WORKER__RENDER_MEMORY_LIMIT_MIB=0илиWORKER__RENDER_TIMEOUT_SECONDS=120при сроке попытки 60 с - THEN worker не стартует, код выхода ненулевой, в журнале — запись с именем поля без значений настроек
Requirement: Параметры relay
Параметры relay (capability job-outbox) SHALL задаваться в секции [relay]:
poll_interval_seconds— пауза между проходами, когда публиковать нечего, по умолчанию 0,25;batch_size— сколько заданий relay берёт за один проход, по умолчанию 100;max_published_backlog— предел опубликованных и не взятых заданий, по умолчанию 1000; 0 — без предела;republish_after_seconds— через сколько секунд отмеченное задание может считаться потерянным, по умолчанию 300;failure_pause_seconds— пауза после отказа брокера или PostgreSQL, по умолчанию 2.
batch_size SHALL быть целым не меньше 1, max_published_backlog — целым не меньше 0, сроки —
положительными конечными числами. Иначе relay MUST NOT стартовать: код выхода ненулевой, а ошибка
называет поле. Разовая подмена SHALL работать через окружение RELAY__* без правки файлов. Реплики API и
worker секцию не используют. Запись о старте relay SHALL называть все значения. Значения по умолчанию и их
обоснование SHALL быть в REPORT.md.
Scenario: Параметры relay по умолчанию
- WHEN relay запущен без секции
[relay]и без переменныхRELAY__* - THEN запись о его старте называет паузу 0,25 с, пакет 100, предел 1000, порог потерянного сообщения 300 с и паузу отказа 2 с
Scenario: Неверный параметр relay
- WHEN relay запускается с
RELAY__BATCH_SIZE=0,RELAY__MAX_PUBLISHED_BACKLOG=-1илиRELAY__POLL_INTERVAL_SECONDS=abc - THEN relay не стартует, код выхода ненулевой, в журнале — запись с именем поля без значений настроек
Requirement: Параметры телеметрии
Телеметрию API, worker и relay (capability observability) SHALL настраивать секция [telemetry]:
enabled— включена ли телеметрия, по умолчанию выключена; рабочий стенд compose включает её в окружении реплик API, worker и relay;otlp_endpoint— адрес OTLP/HTTP Collector (схемаhttpилиhttps, хост и порт, без пути и query), по умолчаниюhttp://127.0.0.1:4318; на стенде — Collector в сети compose;environment— значениеdeployment.environment.name, по умолчаниюlab;trace_sample_ratio— доля корней трасс, выбранных в голове, число от 0 до 1 включительно, по умолчанию 1 — все трассы (observability, «Выбор трасс в голове»);metric_buckets— набор границ histogram:default(по умолчанию) илиcoarse(observability, «Наборы границ histogram»);- интервал отправки метрик, срок одной отправки, размер очереди и пакета SDK и пауза между пакетами — с безопасными значениями по умолчанию; положительные числа, пакет не больше очереди, интервал отправки метрик не больше 30 с — половины срока рядов экспортёра Collector.
Неверное значение MUST останавливать запуск с именем поля (требование «Некорректное значение останавливает запуск»).
Разовая подмена SHALL работать через окружение TELEMETRY__* без правки файлов. Секцию применяют только процессы API,
worker и relay; уборщик, миграции и команда replay телеметрию не запускают при любом её значении.
Переменные OTEL_* стандарта OpenTelemetry настройками сервиса MUST NOT быть, как любые переменные без секции (требование
«Параметры по секциям»): SDK MUST NOT брать из них ни адрес, ни ресурс, ни выключатель, ни выбор трасс, ни параметры
очередей, а процесс с включённой телеметрией, у которого такие переменные есть в окружении, SHALL писать запись warning с
их именами, без значений. Имена skeleton (OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_PROTOCOL,
OTEL_RESOURCE_ATTRIBUTES) и стандартные имена выбора трасс (OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG) сопоставлены
настройкам и постоянным значениям кода в .env.example и REPORT.md.
Запись журнала о старте API, worker и relay SHALL называть, включена ли телеметрия, а при включённой — адрес Collector, окружение, долю выбора трасс, набор границ histogram и интервал отправки метрик.
Scenario: Телеметрия по умолчанию выключена
- WHEN сервис запущен без секции
[telemetry]и без переменныхTELEMETRY__* - THEN запись о старте говорит, что телеметрия выключена, и сервис не обращается к адресу Collector
Scenario: Включение окружением
- WHEN worker запущен с
TELEMETRY__ENABLED=trueиTELEMETRY__OTLP_ENDPOINT, указывающим на Collector, а файлы не менялись - THEN запись о старте называет этот адрес, а трассы, метрики и логи worker приходят в хранилища
Scenario: Телеметрия relay
- WHEN relay запущен на рабочем стенде compose, а затем в консоли
make run_relay - THEN запись о старте relay стенда называет телеметрию включённой, адрес Collector и окружение, а консольного — выключенной
Scenario: Выбор трасс и набор границ окружением
- WHEN API запущен с включённой телеметрией,
TELEMETRY__TRACE_SAMPLE_RATIO=0.1иTELEMETRY__METRIC_BUCKETS=coarse, а файлы не менялись - THEN запись о старте называет долю 0,1, набор
coarseи интервал отправки метрик, а без этих переменных — долю 1 и наборdefault
Scenario: Неверный параметр телеметрии
- WHEN сервис запускается с
TELEMETRY__OTLP_ENDPOINT=collector:4318, с отрицательным интервалом отправки метрик, интервалом 60 с, пакетом больше очереди, долей выбора трасс 1.5, −0.1 илиnanлибо набором границfine - THEN сервис не стартует, в журнале — ошибка проверки настроек с именем поля
Scenario: Переменные OTEL_* не действуют
- WHEN процесс с включённой телеметрией запущен с
OTEL_SDK_DISABLED=true,OTEL_TRACES_SAMPLER=always_offиOTEL_EXPORTER_OTLP_ENDPOINT, указывающим в другое место - THEN сигналы по-прежнему приходят в Collector из
[telemetry], трассы выбираются поtrace_sample_ratio, а в журнале есть записьwarningс именами этих переменных без значений