HAProxy as the single entry point, API replicas without published ports, resource limits and per-service secrets, restart and stop-one hooks, replica tests in student-tests. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
8.6 KiB
Spec Delta
MODIFIED Requirements
Requirement: Запуск через compose
make run_docker SHALL собирать образ и поднимать стенд через
docker compose: PostgreSQL, Valkey, одноразовый сервис миграций,
API_REPLICAS реплик API (capability load-balancing) и балансировщик
(LB). Реплики API SHALL стартовать после готовности PostgreSQL и Valkey
и успешных миграций. Миграции SHALL выполняться один раз за запуск
отдельным сервисом, а не репликами. Перед этим цель SHALL создавать
недостающие .env и config.toml из шаблонов (make env_setup) и
MUST NOT перезаписывать существующие. make stop SHALL останавливать
сервисы, make down — удалять контейнеры, сохраняя volume, make logs
— показывать журнал всех реплик API.
Scenario: Штатный запуск
- WHEN в свежем clone выполнен
make run_docker - THEN сервис отвечает через LB на
http://localhost:8080/health/ready, работают две реплики API, иmake student_testпроходит
Scenario: Миграции один раз
- WHEN выполнен
make run_dockerс двумя репликами - THEN журнал сервиса миграций содержит один прогон, а в журналах реплик API нет запуска миграций
Requirement: Порты из .env
Порты стенда и консольного запуска SHALL браться из одного .env:
- внутренний порт API —
APP__PORT: параметр приложения[app] portв формате настроек. Его слушает каждая реплика, на нём работают healthcheck и проверки LB, на нём же LB принимает запросы внутри своего контейнера; - внешний порт стенда —
APP_OUT_PORT: порт LB на127.0.0.1хоста, приложение его не читает; - порт PostgreSQL внутри сети compose —
POSTGRES_PORT, его слушает сам сервер и использует API в docker; - внешний порт PostgreSQL —
POSTGRES_OUT_PORT: порт на127.0.0.1хоста для запуска в консоли; - порт Valkey внутри сети compose —
VALKEY_PORT, внешний —VALKEY_OUT_PORTна127.0.0.1для запуска в консоли.
Если переменная порта API не задана, SHALL действовать 8080. Параметры
приложения в .env SHALL записываться в формате настроек
(SECTION__FIELD). Имя без секции допускается только для переменных,
которые приложение не читает. Адреса и порты PostgreSQL и Valkey MUST
NOT быть записаны в compose литералами.
Scenario: Другой внешний порт
- WHEN в
.envзаданоAPP_OUT_PORT=8090, и выполненmake run_docker - THEN API доступно через LB на
localhost:8090, а внутри контейнеров реплики слушаютAPP__PORT
Scenario: Другой внутренний порт
- WHEN в
.envзаданоAPP__PORT=9090 - THEN реплики внутри контейнеров слушают 9090 и становятся
healthy, LB проверяет их на 9090, а API доступно наlocalhost:$APP_OUT_PORT
Scenario: Другой порт Postgres
- WHEN в
.envзаданыPOSTGRES_PORT=5544иPOSTGRES_OUT_PORT=5545, а compose не правился - THEN
make run_dockerподнимает стенд,/health/readyотвечает 200, аmake run_devподключается к Postgres на127.0.0.1:5545
Scenario: Другой порт Valkey
- WHEN в
.envзаданы другиеVALKEY_PORTиVALKEY_OUT_PORT, а compose не правился - THEN
make run_dockerиmake run_devподключаются к Valkey на новых портах, и кэш работает
Requirement: Публикация только на localhost
Порты LB, PostgreSQL и Valkey SHALL публиковаться в compose только на
127.0.0.1 хоста. Адрес публикации SHALL быть записан литералом, а не
переменной. Реплики API MUST NOT публиковать порты на хосте: к ним
ходят только LB и контейнеры сети compose. Учебный стенд MUST NOT быть
доступен с других машин сети.
Scenario: Адрес публикации
- WHEN для запущенных контейнеров LB, API, Postgres и Valkey
выполняется
docker port - THEN порты LB, Postgres и Valkey опубликованы на
127.0.0.1, а не на0.0.0.0, а у контейнеров API опубликованных портов нет
Requirement: Данные переживают рестарт стенда
Данные PostgreSQL SHALL храниться в именованном volume. Скрипт
scripts/restart.sh SHALL перезапускать LB, все реплики API и все
используемые хранилища — PostgreSQL и Valkey. Volume, схема и данные
SHALL сохраняться: без удаления volume, очистки и повторного
наполнения. Число реплик после рестарта SHALL оставаться прежним.
Скрипт SHALL быть исполняемым, завершаться с кодом 0 только после
перезапуска, укладываться в 90 с и MUST NOT печатать секреты.
Публичная проверка make test-persistence ACTION_SCRIPT=scripts/restart.sh SHALL проходить через LB.
Scenario: Рестарт hook-ом
- WHEN пользователь вошёл, отправил сообщение, затем выполнен
scripts/restart.sh - THEN контейнеры LB, всех реплик API, Postgres и Valkey
перезапущены: те же ID и новое время старта в
docker inspect. После готовности запрос с прежним токеном через LB получает 200 и видит своё сообщение
Scenario: Публичная проверка сохранности
- WHEN на запущенном стенде выполняется
make test-persistence ACTION_SCRIPT=scripts/restart.sh - THEN команда завершается с кодом 0 и печатает
PASS
ADDED Requirements
Requirement: Лимиты ресурсов и секреты по сервисам
Каждый сервис стенда SHALL иметь лимиты CPU и памяти: LB, реплики API,
сервис миграций, PostgreSQL и Valkey. Сумма лимитов и расчёт
соединений PostgreSQL для заявленного числа реплик SHALL быть описаны
в REPORT.md. Секреты SHALL передаваться только тем сервисам, которым
они нужны:
- пароль PostgreSQL — PostgreSQL, репликам API и сервису миграций;
- пароль Valkey — Valkey и репликам API;
- LB MUST NOT получать ни одного секрета.
Scenario: Лимиты у всех контейнеров
- WHEN для каждого контейнера запущенного стенда выполняется
docker inspect(HostConfig.NanoCpus,HostConfig.Memory) - THEN у LB, каждой реплики API, сервиса миграций, PostgreSQL и Valkey оба значения больше нуля
Scenario: Секреты по сервисам
- WHEN проверяющий смотрит окружение сервисов в
docker compose config - THEN у LB нет ни одного пароля, у сервиса миграций нет пароля Valkey, а пароль Valkey есть только у Valkey и реплик API