# 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