Files
mtusi2026lab6/openspec/specs/service-configuration/spec.md
T
2026-11-15 06:17:06 +03:00

47 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, у уборщика — пользователя уборщика, у 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_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 — сколько незавершённых загрузок или вложений с объектом staging уборщик выбирает одним запросом к PostgreSQL, по умолчанию 100;
  • staging_retention_seconds — срок хранения объекта staging вложения failed и объекта staging без метаданных, по умолчанию 86400 (сутки, как у имени skeleton STAGING_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 он затрагивает в секунду (capability storage-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 с именами этих переменных без значений