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>
150 lines
8.6 KiB
Markdown
150 lines
8.6 KiB
Markdown
# 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
|