feat: put API replicas behind HAProxy
HAProxy 3.4 is the only published entry point; api runs as API_REPLICAS replicas without ports, found through Docker DNS and checked on /health/ready. Retries only on connection failure, LB errors in the contract error format, resource limits and per-service secrets. Adds scripts/stop-one.sh, LB-aware restart.sh, make replicas / instances / lb_stats and replica tests driven by EXPECT_REPLICAS. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
+72
-33
@@ -11,8 +11,9 @@ paths:
|
||||
Задание — `README.md` лабы 3, роли — `contracts/infrastructure.json`,
|
||||
семантика `X-Instance-Id` и `Idempotency-Key` — `api-contract.md`.
|
||||
Общие правила compose, пинов и volumes — `docker.md`; здесь то, что
|
||||
добавляет лаба 3. Стартовые значения и почему HAProxy — `PLAN.md`,
|
||||
«Ключевые решения»; окончательные — design change `replicas-lb`.
|
||||
добавляет лаба 3. Почему HAProxy — `PLAN.md`, «Ключевые решения»;
|
||||
числа и их обоснование — design change `replicas-lb` (архив
|
||||
`openspec/changes/archive/`), спек `load-balancing`.
|
||||
|
||||
```
|
||||
клиент → 127.0.0.1:APP_OUT_PORT → haproxy → api × API_REPLICAS → postgres (данные, сессии, ключи)
|
||||
@@ -23,14 +24,19 @@ paths:
|
||||
## Сервисы compose
|
||||
|
||||
- **`haproxy`** — единственный сервис с портом наружу:
|
||||
`127.0.0.1:${APP_OUT_PORT:-8080}`. Образ закреплён тегом с
|
||||
патч-версией и digest индекса (`docker.md`). Конфиг —
|
||||
`127.0.0.1:${APP_OUT_PORT:-8080}:${APP__PORT:-8080}` (внутри LB
|
||||
слушает тот же `APP__PORT`, что реплики). Образ закреплён тегом с
|
||||
патч-версией и digest индекса (`docker.md`), сейчас 3.4 LTS. Конфиг —
|
||||
`infra/haproxy/haproxy.cfg`, монтируется read-only длинной записью с
|
||||
`create_host_path: false`. Секретов LB не получает. Лимиты CPU/RAM.
|
||||
`create_host_path: false`. Окружение — только `API_PORT`, секретов LB
|
||||
не получает. `depends_on: api` (`service_started`): `make stop` гасит
|
||||
LB раньше реплик. Healthcheck — `bash` с `/dev/tcp` на
|
||||
`/lb/ready` (curl в образе нет): `healthy` значит «есть готовая
|
||||
реплика». Лимиты CPU/RAM.
|
||||
- **`api`** — `deploy.replicas: ${API_REPLICAS:-2}`, без `ports`,
|
||||
без `container_name`: оба мешают масштабированию одного сервиса
|
||||
(рубрика «4»). Разовая подмена — `docker compose up -d --scale
|
||||
api=N`. Лимиты CPU/RAM у каждой реплики, `stop_grace_period: 10s`,
|
||||
(рубрика «4»). Разовая подмена — `make replicas API_REPLICAS=N`.
|
||||
Лимиты CPU/RAM у каждой реплики, `stop_grace_period: 10s`,
|
||||
`restart: unless-stopped`.
|
||||
- **`migrate`** — как в лабе 2: один раз до реплик, реплики ждут
|
||||
`service_completed_successfully` (`migrations.md`).
|
||||
@@ -40,11 +46,17 @@ paths:
|
||||
|
||||
## HAProxy
|
||||
|
||||
- Имена прокси разные: `frontend entry`, `backend api`, `frontend
|
||||
monitor`. С HAProxy 3.3 frontend и backend с одним именем — ошибка
|
||||
конфигурации. Проверка конфига — `haproxy -c` в закреплённом образе
|
||||
с `API_PORT`.
|
||||
- Реплики находятся через DNS Docker, а не списком адресов:
|
||||
`resolvers` на `127.0.0.11:53` и `server-template api- <N> api:<порт>
|
||||
check resolvers docker init-addr none`. Новая и пропавшая реплика
|
||||
видны без перезагрузки LB. `<N>` — запас слотов не меньше
|
||||
максимального числа реплик в сериях трека 1.
|
||||
видны без перезагрузки LB (`hold` 1 с). `<N>` — запас слотов не
|
||||
меньше максимального числа реплик в сериях трека 1 (сейчас 8). Слоты
|
||||
HAProxy (`api-1`, `api-2`) не совпадают с именами контейнеров
|
||||
compose: слот получает адрес из DNS.
|
||||
- Проверка готовности — активная: `option httpchk GET /health/ready`,
|
||||
`http-check expect status 200`, `inter`/`fall`/`rise` и
|
||||
`timeout check` явно. `/health/live` для LB не годится: живой
|
||||
@@ -53,17 +65,26 @@ paths:
|
||||
запрещён (README, п. 3), а разные `X-Instance-Id` у запросов одной
|
||||
сессии — проверка уровня 3.
|
||||
- Повтор запроса в LB — только `retry-on conn-failure` с `retries` и
|
||||
`option redispatch`. Запрос до реплики не дошёл, поэтому повтор
|
||||
безопасен для любого метода. `response-timeout`, `empty-response`,
|
||||
`5xx` не повторяются: `POST /chats` и `POST /users` не идемпотентны
|
||||
(`api-contract.md`). `POST` сообщения клиент повторяет сам, с тем же
|
||||
ключом.
|
||||
`option redispatch 1` (каждый повтор — на другую реплику). Запрос до
|
||||
реплики не дошёл, поэтому повтор безопасен для любого метода.
|
||||
`response-timeout`, `empty-response`, `5xx` не повторяются: `POST
|
||||
/chats` и `POST /users` не идемпотентны (`api-contract.md`). `POST`
|
||||
сообщения клиент повторяет сам, с тем же ключом.
|
||||
- `X-Request-Id` и `X-Instance-Id` ставит API, LB их не переписывает.
|
||||
Ответы, которые сгенерировал сам HAProxy (502/503/504), желательно
|
||||
отдавать в формате ошибки контракта через `http-error`; контракт
|
||||
разрешает им не иметь `X-Instance-Id`.
|
||||
- Статистика (stats-сокет или страница) — для трека 1 и диагностики,
|
||||
только внутри сети compose, наружу не публикуется.
|
||||
Ответы, которые сгенерировал сам HAProxy (502/503/504), отдаются в
|
||||
формате ошибки контракта через `http-error … lf-string` с `code`
|
||||
`unavailable` (в перечислении кодов контракта нет отдельных для 502 и
|
||||
504); `request_id` — `%[unique-id]`, он же в заголовке
|
||||
`X-Request-Id`. `X-Instance-Id` у них нет — контракт это допускает.
|
||||
- Статистика — страница `/stats` и `/stats;csv` (`stats show-legends`:
|
||||
адрес слота) во `frontend monitor` на `:8404`, там же `monitor-uri
|
||||
/lb/ready` (503, если готовых реплик нет). Только внутри сети
|
||||
compose, наружу не публикуется; оператору — `make lb_stats` (CSV
|
||||
читается изнутри контейнера LB).
|
||||
- Журнал — `log stdout`, `option httplog` + `option dontlog-normal`:
|
||||
успешные запросы не пишутся, ошибки, повторы (`+N` в поле retries),
|
||||
перенаправления и смена состояния реплик — пишутся. `nbthread` равен
|
||||
лимиту CPU контейнера LB.
|
||||
|
||||
## Цепочка таймаутов
|
||||
|
||||
@@ -72,10 +93,10 @@ paths:
|
||||
|
||||
- время обнаружения отказа ≈ `inter × fall + timeout check` ≤ 10 с
|
||||
(рубрика «3»: «не позднее 10 секунд»). В `REPORT.md` — и формула, и
|
||||
замер;
|
||||
замер (замер — change `graceful-failover`);
|
||||
- `timeout connect` × (`retries` + 1) < 2 с: таймаут клиента в
|
||||
`tests/resilience.py` — 2 с, и повтор на живую реплику должен успеть
|
||||
раньше;
|
||||
раньше. Поэтому `timeout connect` 500 мс, а не 1 с, и `redispatch 1`;
|
||||
- `timeout server` > `[database] request_timeout_seconds` + запас на
|
||||
KDF входа, иначе LB рвал бы ответ, который API ещё отдаст;
|
||||
- таймаут проверки внутри `/health/ready` < `timeout check` HAProxy
|
||||
@@ -89,25 +110,43 @@ Hook для `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`
|
||||
(`tests/README.md`), по образцу `scripts/stop-one.example.sh`.
|
||||
|
||||
- `#!/bin/sh`, `set -eu`, исполняемый бит в git. Возврат 0 не позже
|
||||
чем через 10 с. Остановленная реплика остаётся остановленной,
|
||||
восстановление — отдельной командой (`docker start <id>` или
|
||||
`docker compose up -d`), её печатает `REPORT.md`.
|
||||
чем через 10 с: `docker stop --timeout 9` (uvicorn сам завершается
|
||||
за ≤ 8 с). Остановленная реплика остаётся остановленной,
|
||||
восстановление — отдельной командой `make replicas` (те же
|
||||
контейнеры, те же ID), её печатает `REPORT.md`.
|
||||
- `TARGET_INSTANCE_ID` — `X-Instance-Id` реплики, то есть короткий ID
|
||||
контейнера. Скрипт проверяет формат и то, что это контейнер сервиса
|
||||
`api` **этого** проекта (`docker compose ps -q api`). Иначе — отказ
|
||||
с ненулевым кодом: Postgres, Valkey, LB и чужие контейнеры он не
|
||||
трогает никогда. Volumes не удаляет.
|
||||
контейнера: только hex, 12–64 символа. Скрипт ищет его префиксом
|
||||
среди работающих реплик сервиса `api` **этого** проекта (`docker
|
||||
compose ps -q api`). Иначе — отказ с ненулевым кодом: Postgres,
|
||||
Valkey, LB и чужие контейнеры он не трогает никогда. Volumes не
|
||||
удаляет.
|
||||
- Режим — `STOP_MODE=stop` (по умолчанию, `docker stop`: SIGTERM и
|
||||
graceful) или `kill` (`docker kill`: отказ процесса без graceful).
|
||||
Проверить, что `restart: unless-stopped` не поднимает реплику после
|
||||
`kill`: тест требует, чтобы её не было среди последних ответов.
|
||||
`restart: unless-stopped` не поднимает реплику ни после `stop`, ни
|
||||
после `kill` (проверено на Docker 29.8: `exited`, `RestartCount` 0
|
||||
через 15 с), поэтому `docker stop -t 0` вместо `kill` не нужен.
|
||||
- `STOP_ONE_LOG=<файл>` — необязательная строка «время,
|
||||
`TARGET_INSTANCE_ID`, полный ID контейнера, режим»: тест скрывает
|
||||
вывод hook, но передаёт ему своё окружение. Так evidence показывает,
|
||||
какой ID выбрал тест и какой контейнер остановлен.
|
||||
- Секретов и окружения не печатает: вывод hook тест скрывает, но он
|
||||
остаётся в терминале при ручном запуске.
|
||||
- Доказательство на защите и в `evidence/failover/` — какой контейнер
|
||||
остановлен: `docker compose ps` до и после, ID совпадает с
|
||||
`TARGET_INSTANCE_ID`. Одного заголовка мало (README, «Сценарий
|
||||
защиты», п. 3). Повторить для каждой реплики, восстанавливая
|
||||
предыдущую.
|
||||
`TARGET_INSTANCE_ID` (строка `STOP_ONE_LOG`). Одного заголовка мало
|
||||
(README, «Сценарий защиты», п. 3). Повторить для каждой реплики,
|
||||
восстанавливая предыдущую (`make replicas`).
|
||||
|
||||
## Свои цели Makefile
|
||||
|
||||
- `make replicas` — `up -d --no-deps --no-recreate --wait --scale
|
||||
api=$(API_REPLICAS) api`: запускает остановленные реплики с теми же ID
|
||||
и доводит их число до `API_REPLICAS` (разово — аргументом make).
|
||||
- `make instances` — `driver.py instances` скилла `run-mtusi-messenger`:
|
||||
вход одним синтетическим пользователем и серия `GET /users/me` с одним
|
||||
токеном, `X-Instance-Id` каждого ответа (шаг 1 сценария защиты).
|
||||
- `make lb_stats` — занятые слоты HAProxy: адрес, состояние проверки,
|
||||
запросы, ошибки соединения, повторы, перенаправления.
|
||||
|
||||
## Поочерёдная замена: `scripts/rolling-update.sh`
|
||||
|
||||
|
||||
@@ -59,6 +59,15 @@ paths:
|
||||
базовый замер снимается заново. Профили лабы 2 (`full`, `restore*`)
|
||||
продолжают работать и после перехода на N реплик.
|
||||
|
||||
До `graceful-failover` override `bench/bench.compose.yml` держит один
|
||||
API: у `api` `deploy.replicas: 1` и `container_name` (k6 ходит к нему
|
||||
по имени), `haproxy` не запускается (`up -d --no-deps api`), его порт
|
||||
сброшен. Лимиты `api`, `postgres` и `valkey` — в форме
|
||||
`deploy.resources.limits` с теми же `BENCH_*` (основной compose задаёт
|
||||
лимиты так же, и `cpus` / `mem_limit` рядом с ними compose не
|
||||
принимает); `memswap_limit` — на уровне сервиса. `NanoCpus` и `Memory`
|
||||
контейнеров при этом те же, метки сравнимы.
|
||||
|
||||
Стенд — свой проект compose `mtusi-bench`: тот же `docker-compose.yml`
|
||||
с override `bench/bench.compose.yml` (по образцу `make failure_checks`),
|
||||
подстановки — `bench/bench.env`, а не `.env` рабочего стенда. Пароли
|
||||
|
||||
+15
-9
@@ -106,14 +106,19 @@ git ls-files -z -co --exclude-standard | tar --null -T - -cf - | docker build -t
|
||||
`container_name`**, реплик `${API_REPLICAS:-2}`, наружу только LB
|
||||
(`balancer.md`). До лабы 3 порт был
|
||||
`"127.0.0.1:${APP_OUT_PORT:-8080}:${APP__PORT:-8080}"`; теперь эта
|
||||
строка — у сервиса `haproxy`. `environment` — якорь `x-app-env`:
|
||||
`APP__RUN_MODE: docker`, `APP__PORT`, `DATABASE__*` из переменных
|
||||
`POSTGRES_*`, `CACHE__*` из `VALKEY_*` (`settings.md`, «Консоль и
|
||||
docker»). У `migrate` — только Postgres-часть: пароль Valkey ему не
|
||||
нужен (секреты только там, где нужны, рубрика «4»). Healthcheck
|
||||
образа проверяет `APP__PORT`; `stop_grace_period: 10s`;
|
||||
`restart: unless-stopped`; лимиты CPU/RAM. Имена переменных в
|
||||
`.env` — `settings.md`, «Имена в `.env`».
|
||||
строка — у сервиса `haproxy`. `environment` собирается из якорей:
|
||||
`x-db-env` (`APP__RUN_MODE: docker`, `DATABASE__*` из переменных
|
||||
`POSTGRES_*`) и `x-cache-env` (`CACHE__*` из `VALKEY_*`), у `api`
|
||||
— оба через `<<: [*db-env, *cache-env]` плюс `APP__PORT`
|
||||
(`settings.md`, «Консоль и docker»). У `migrate` — только
|
||||
`x-db-env`: пароль Valkey ему не нужен; `haproxy` получает только
|
||||
`API_PORT` (секреты только там, где нужны, рубрика «4»).
|
||||
Healthcheck образа проверяет `APP__PORT`; `stop_grace_period: 10s`;
|
||||
`restart: unless-stopped`; лимиты CPU/RAM
|
||||
(`deploy.resources.limits`) у всех сервисов — override стендов
|
||||
(`bench/`) задаёт лимиты в той же форме: `cpus` / `mem_limit` рядом с
|
||||
ними compose не принимает. Имена переменных в `.env` — `settings.md`,
|
||||
«Имена в `.env`».
|
||||
- Литералов адреса и порта Postgres в compose нет: `POSTGRES_HOST`
|
||||
становится алиасом сервиса в сети, `POSTGRES_PORT` — портом самого
|
||||
сервера через `PGPORT` (его же берут `pg_isready` и `psql` в
|
||||
@@ -210,7 +215,8 @@ Hook для `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
|
||||
--wait postgres valkey` (те же контейнеры, ожидание healthcheck) →
|
||||
`start api haproxy`. `start api` запускает и зависимость `migrate`:
|
||||
повторный прогон миграций — no-op. Число реплик не меняется: `start`
|
||||
поднимает те же контейнеры, а не масштабирует.
|
||||
поднимает те же контейнеры, а не масштабирует (реплику, остановленную
|
||||
`stop-one.sh`, тоже).
|
||||
- `#!/bin/sh`, `set -eu`, исполняемый бит в git (`chmod +x`,
|
||||
`git update-index --chmod=+x`). Возвращает 0 только после действия,
|
||||
укладывается в 90 с. Готовность ждёт сам тест. Секреты не печатает.
|
||||
|
||||
@@ -66,10 +66,11 @@ timeout_graceful_shutdown=..., log_config=None, access_log=False)`.
|
||||
Valkey из compose, затем `APP__RUN_MODE=console uv run python -m
|
||||
src`;
|
||||
- `run_docker: env_setup` (недостающие `.env` и `config.toml` из
|
||||
шаблонов, затем `DOCKER_BUILDKIT=1 $(DC) build` и `$(DC) up -d`),
|
||||
шаблонов, затем `DOCKER_BUILDKIT=1 $(DC) build` и `$(DC) up -d`:
|
||||
хранилища → migrate → `api` × `API_REPLICAS` → haproxy),
|
||||
к нему `stop`, `down` (volume остаётся), `logs`
|
||||
(`$(DC) logs -f --no-log-prefix api`: без префикса `api-1 |`
|
||||
каждая строка — JSON);
|
||||
каждая строка — JSON, реплику называет поле `instance_id`);
|
||||
- `lint` (`ruff format .` + `ruff check --fix .`, дважды),
|
||||
`env_setup` (шаблоны `.env` и `config.toml`, в новый `.env` —
|
||||
случайные `POSTGRES_PASSWORD` и `VALKEY_PASSWORD`; существующий
|
||||
@@ -86,9 +87,17 @@ timeout_graceful_shutdown=..., log_config=None, access_log=False)`.
|
||||
`yes`). Volume — именованный `postgres_data` в compose; `wipe_data`
|
||||
пересоздаёт и Valkey, то есть чистит кэш.
|
||||
- Valkey: `start_cache` (`$(DC) up -d --wait valkey`), `stop_cache`.
|
||||
- Реплики за HAProxy (с лабы 3, `balancer.md`): `replicas` (вернуть
|
||||
остановленные и выставить число, `API_REPLICAS ?= 2` после `-include
|
||||
.env`), `instances` (распределение одной сессии по `X-Instance-Id`),
|
||||
`lb_stats` (слоты HAProxy).
|
||||
- `student_test` передаёт pytest `EXPECT_REPLICAS` (по умолчанию
|
||||
`API_REPLICAS`): сколько реплик за `BASE_URL` ждут тесты реплик.
|
||||
Против одного процесса — `EXPECT_REPLICAS=1` (`student-tests.md`).
|
||||
- `test_isolated: env_setup start_db start_cache` — образ на временной
|
||||
базе (`student-tests.md`); Valkey общий с рабочим стендом, ключи кэша
|
||||
разделены именем базы. Скрипт запускается `$(PYTHON)`, а не
|
||||
разделены именем базы. Один контейнер API без LB: скрипт зовёт `make
|
||||
student_test EXPECT_REPLICAS=1`. Скрипт запускается `$(PYTHON)`, а не
|
||||
`uv run`: uv повторно пересылает SIGINT, и Ctrl+C обрывал уборку.
|
||||
- `failure_checks: env_setup` — проверки отказов на отдельном стенде,
|
||||
проект compose `<рабочий>-failures` (`student-tests.md`). От
|
||||
|
||||
@@ -149,10 +149,12 @@ Postgres и Valkey приходят мостами из `POSTGRES_PASSWORD` и
|
||||
|
||||
Skeleton lab3 добавил ещё два имени:
|
||||
|
||||
- `API_REPLICAS` читает только compose (`deploy.replicas` сервиса
|
||||
`api`), приложение — нет. Поэтому имя остаётся как есть, без секции:
|
||||
строка в `.env.example` и `${API_REPLICAS:-2}` в compose. Разовая
|
||||
подмена — `docker compose up --scale api=N`;
|
||||
- `API_REPLICAS` читают compose (`deploy.replicas` сервиса `api`) и
|
||||
Makefile (`make replicas`, `EXPECT_REPLICAS` тестов), приложение —
|
||||
нет. Поэтому имя остаётся как есть, без секции: строка в
|
||||
`.env.example`, `${API_REPLICAS:-2}` в compose и `API_REPLICAS ?= 2`
|
||||
в Makefile — без строки в `.env` действует 2. Разовая подмена —
|
||||
`make replicas API_REPLICAS=N`;
|
||||
- `IDEMPOTENCY_TTL_SECONDS` читает только приложение. Это
|
||||
`[idempotency] ttl_seconds` в `config.toml` (по умолчанию 86400 —
|
||||
24 ч по контракту), соответствие — в `REPORT.md`, как
|
||||
|
||||
@@ -45,13 +45,30 @@ paths:
|
||||
и срок ключа — проверки отказов (`test_failures.py`);
|
||||
- гонка одного ключа (уровень 4, `test_race.py`): N потоков за
|
||||
`threading.Barrier` шлют одно тело с одним ключом. Все ответы 201 с
|
||||
одним `id`, в истории ровно одно сообщение. С change `replicas-lb`
|
||||
через LB тест ещё требует ≥2 разных `X-Instance-Id` среди ответов:
|
||||
иначе «через разные реплики» не доказано. Против одного процесса
|
||||
(`make test_isolated`, console) эта часть пропускается с явной
|
||||
причиной, а не считается пройденной;
|
||||
- распределение по репликам: запросы одной сессии через LB отвечают
|
||||
≥2 разными `X-Instance-Id` без повторного входа.
|
||||
одним `id`, в истории ровно одно сообщение (`test_same_key_at_once`,
|
||||
любой стенд). Через LB `test_same_key_through_replicas` ещё требует
|
||||
пару пересекающихся по времени запросов с разными `X-Instance-Id`:
|
||||
иначе «одновременно через разные реплики» не доказано;
|
||||
- тесты реплик (нужны ≥ 2 реплики за `BASE_URL`, фикстура
|
||||
`replicas`):
|
||||
- `test_load_balancing.py` — одна сессия на разных репликах, запись
|
||||
видна через другую реплику (спек `load-balancing` вне сверки
|
||||
покрытия: сценарий — в докстринге);
|
||||
- `test_idempotency.py::test_replay_on_other_replica` — повтор с
|
||||
ключом через другую реплику, 409 от разных реплик;
|
||||
- `test_race.py::test_same_key_through_replicas`.
|
||||
|
||||
Сколько реплик за `BASE_URL`, набор узнаёт из `EXPECT_REPLICAS`, а не
|
||||
угадывает по ответам: иначе сломанный LB давал бы пропуск вместо
|
||||
падения. `make student_test` берёт его из `API_REPLICAS` (2), `make
|
||||
test_isolated` и `driver.py student` против своего процесса передают
|
||||
1. При 1 тесты реплик пропускаются с причиной «one API process» (её
|
||||
печатает `-rsP` в `addopts`), при ≥ 2 и одном увиденном значении —
|
||||
падают с числом увиденных (`assert_replicas` в `contract.py`);
|
||||
- «Одно значение на процесс» (`test_api_conventions.py`) — две
|
||||
одинаковые серии по 18 запросов: против одного процесса одно
|
||||
значение, через LB каждое значение повторяется, и вторая серия не
|
||||
приносит новых. Опирается на round-robin LB.
|
||||
|
||||
Проверки отказов реплик (остановка, kill, rolling update) — не pytest,
|
||||
а `make test-failover` и сценарии `balancer.md`: им нужен стенд с LB и
|
||||
@@ -79,11 +96,12 @@ paths:
|
||||
стенда (ключи кэша разделены именем базы), публичный smoke и весь
|
||||
набор против отдельного контейнера, затем уборка при любом исходе.
|
||||
Его вывод — evidence набора против контейнера. Это один контейнер
|
||||
API без LB: тесты, которым нужны ≥2 реплики, здесь пропускаются.
|
||||
`make student_test` — против любого запущенного стенда (`BASE_URL`),
|
||||
он оставляет данные в рабочей базе. Против стенда compose лабы 3
|
||||
(`BASE_URL` = HAProxy) выполняются и тесты реплик; их вывод — второй
|
||||
файл evidence.
|
||||
API без LB (`EXPECT_REPLICAS=1`): тесты, которым нужны ≥2 реплики,
|
||||
здесь пропускаются. `make student_test` — против любого запущенного
|
||||
стенда (`BASE_URL`), он оставляет данные в рабочей базе. Против
|
||||
стенда compose лабы 3 (`BASE_URL` = HAProxy) выполняются и тесты
|
||||
реплик; их вывод — второй файл evidence
|
||||
(`evidence/tests/student-test-lb.md`).
|
||||
- Проверкам, которым нужен особый стенд (TTL 2 с, остановленные или
|
||||
замороженные Postgres и Valkey, сбой БД посреди транзакции), обычный
|
||||
прогон не подходит. Это **проверки отказов**: маркер `fault`, модуль
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: run-mtusi-messenger
|
||||
description: Запустить, остановить, прогнать и подёргать API мессенджера MTUSI (FastAPI, PostgreSQL, Valkey; лаба 3, пока один API без балансировщика) — на хосте или в Docker. Use when asked to run / start / stop the server or the container, run the smoke test, `make test`, `make student_test` or `make test_isolated`, check that an API change works on a live server, send a request to an endpoint, reproduce a bug over HTTP, check the container, or call services directly without HTTP.
|
||||
description: Запустить, остановить, прогнать и подёргать API мессенджера MTUSI (FastAPI, PostgreSQL, Valkey; лаба 3 — HAProxy перед репликами API) — на хосте или в Docker. Use when asked to run / start / stop the server or the stand, run the smoke test, `make test`, `make student_test`, `make test_isolated`, `make test-persistence` or `make test-failover`, stop or restore an API replica, show X-Instance-Id distribution, check that an API change works on a live server, send a request to an endpoint, reproduce a bug over HTTP, check the containers, or call services directly without HTTP.
|
||||
---
|
||||
|
||||
REST API мессенджера (пользователи, чаты, сообщения) — сервер на
|
||||
@@ -10,20 +10,22 @@ FastAPI/uvicorn, данные в PostgreSQL из compose, карточки ча
|
||||
накатывает миграции и поднимает Valkey (`make upgrade start_cache`),
|
||||
запускает свой экземпляр сервера в фоне, гоняет сценарий по HTTP,
|
||||
публичный smoke и собственные тесты, шлёт одиночные запросы и
|
||||
останавливает сервер. Против контейнера
|
||||
(`make run_docker`) работают те же команды драйвера, кроме
|
||||
`start`/`stop`. Только стандартная библиотека Python.
|
||||
останавливает сервер. Против стенда compose (`make run_docker`:
|
||||
HAProxy на `APP_OUT_PORT` перед репликами API) работают те же команды
|
||||
драйвера, кроме `start`/`stop`, плюс `instances` — распределение одной
|
||||
сессии по репликам. Только стандартная библиотека Python.
|
||||
|
||||
Все пути — от корня репозитория. Проверено на macOS (arm64), uv 0.12,
|
||||
Python 3.12 из `.python-version`, Docker Desktop 29.8.
|
||||
|
||||
**Лаба 3** (`AGENTS.md`, «Переходное состояние»). Каждый ответ API
|
||||
несёт `X-Instance-Id` (hostname процесса), `POST` сообщения требует
|
||||
**Лаба 3.** Каждый ответ API несёт `X-Instance-Id` (hostname процесса,
|
||||
в compose — короткий ID контейнера), `POST` сообщения требует
|
||||
`Idempotency-Key`: повтор с тем же ключом и телом — тот же 201 и то же
|
||||
сообщение, другое тело — 409, без ключа — 400. Проект compose —
|
||||
`mtusi-lab3`, своя база. Балансировщика и реплик пока нет: один API на
|
||||
`APP_OUT_PORT`. После change `replicas-lb` раздел «Run: контейнер»
|
||||
переписать под HAProxy и реплики.
|
||||
`mtusi-lab3`, своя база. Стенд: HAProxy — единственная точка входа на
|
||||
`127.0.0.1:APP_OUT_PORT`, за ним `API_REPLICAS` (по умолчанию 2) реплик
|
||||
`api` без портов на хосте. Консольный `driver.py start` — один процесс
|
||||
без балансировщика: тесты реплик против него пропускаются.
|
||||
|
||||
Аутентификация лабы 2: регистрация с `password`, вход
|
||||
`POST /api/v1/auth/sessions` по `Authorization: Basic`, дальше —
|
||||
@@ -69,7 +71,8 @@ python3 $D req GET /api/v1/users/me --token <token из ответа выше>
|
||||
python3 $D req POST /api/v1/chats/<chat>/messages --token <token> --data '{"text":"hi"}'
|
||||
# печатает idempotency-key; повтор той же отправки — тот же запрос с --key <ключ>
|
||||
python3 $D smoke # публичный tests/smoke.py против этого порта
|
||||
python3 $D student # make student_test BASE_URL=http://localhost:<port> — ~15 с
|
||||
python3 $D student # make student_test BASE_URL=http://localhost:<port> — ~20 с
|
||||
python3 $D --port 8080 instances # стенд через LB: X-Instance-Id 12 запросов одной сессии
|
||||
python3 $D stop
|
||||
```
|
||||
|
||||
@@ -80,7 +83,8 @@ python3 $D stop
|
||||
| `flow` | сквозной сценарий; `[FAIL]` в строке и код 1 при провале; в конце печатает id alice/bob/eve/chat и синтетический токен alice |
|
||||
| `req METHOD PATH [--token T \| --basic USER:PASS] [--data JSON] [--key K \| --no-key]` | один запрос: статус, `x-request-id`, `x-instance-id`, `www-authenticate` у 401, тело; код 2 при статусе ≥ 400. `POST …/messages` без `--key` получает новый `Idempotency-Key` (он печатается), `--no-key` — без заголовка |
|
||||
| `smoke` | `tests/smoke.py --base-url http://localhost:<port>` |
|
||||
| `student` | `make student_test BASE_URL=http://localhost:<port>` (pytest по `student-tests/`); код 1, если каталога нет |
|
||||
| `student` | `make student_test BASE_URL=http://localhost:<port>` (pytest по `student-tests/`); против своего процесса (есть pid-файл) — с `EXPECT_REPLICAS=1`, тесты реплик пропускаются с причиной; код 1, если каталога нет |
|
||||
| `instances [--count N]` | вход одним синтетическим пользователем, N (12) × `GET /api/v1/users/me` с одним токеном: `X-Instance-Id` каждого ответа и число ответов каждой реплики; токен не печатается. Его зовёт `make instances` |
|
||||
| `stop` | SIGTERM всей группе; ждёт, пока порт освободится. Чужой сервер и контейнер не трогает |
|
||||
| `all` | всё подряд (`student` — если есть `student-tests/`), `stop` в `finally` |
|
||||
|
||||
@@ -91,29 +95,43 @@ python3 $D stop
|
||||
- `make test BASE_URL=http://localhost:18080` работает так же, как
|
||||
`driver.py smoke`.
|
||||
|
||||
## Run: контейнер (compose)
|
||||
## Run: стенд compose (HAProxy + реплики)
|
||||
|
||||
Проект `mtusi-lab3`, образ `mtusi-messenger:lab3`, compose-сервисы `postgres`, `valkey`,
|
||||
`migrate` (одноразовые миграции) и `api`. Внешний порт — аргументом
|
||||
make, чтобы не столкнуться с 8080:
|
||||
Проект `mtusi-lab3`, образ `mtusi-messenger:lab3`, compose-сервисы
|
||||
`postgres`, `valkey`, `migrate` (одноразовые миграции), `api` ×
|
||||
`API_REPLICAS` (по умолчанию 2, без портов на хосте) и `haproxy` —
|
||||
единственный порт API на хосте, `127.0.0.1:APP_OUT_PORT` (8080).
|
||||
Конфиг LB — `infra/haproxy/haproxy.cfg`, правила — `balancer.md`.
|
||||
|
||||
```bash
|
||||
make run_docker APP_OUT_PORT=18090 # build + up -d: postgres, valkey → migrate → api
|
||||
docker compose ps -a --format '{{.Name}} {{.Ports}} {{.Status}}'
|
||||
python3 $D --port 18090 flow # те же проверки против контейнера
|
||||
docker compose logs --no-log-prefix api | tail -5 # JSON-строки, без -f
|
||||
make run_docker # build + up -d: postgres, valkey → migrate → api × 2 → haproxy
|
||||
docker compose ps -a --format '{{.Name}} {{.ID}} {{.Ports}} {{.Status}}'
|
||||
make instances # ≥2 X-Instance-Id одной сессии через LB (шаг 1 защиты)
|
||||
make lb_stats # слоты HAProxy: адрес, UP/DOWN, запросы, повторы, перенаправления
|
||||
python3 $D --port 8080 flow # те же проверки через LB
|
||||
make test && make student_test # smoke и весь набор через LB, тесты реплик выполняются
|
||||
docker compose logs --no-log-prefix api | tail -5 # JSON всех реплик, реплика — поле instance_id; без -f
|
||||
docker compose logs --no-log-prefix haproxy | tail # LB: ошибки, повторы (+N), смена состояния реплик
|
||||
docker compose exec valkey sh -c 'valkey-cli -p "$VALKEY_PORT" --scan --pattern "messenger:*" | head'
|
||||
# ключи кэша; пароль — из VALKEYCLI_AUTH контейнера
|
||||
scripts/restart.sh # рестарт API, Postgres и Valkey: данные и токены остаются, кэш пуст
|
||||
scripts/restart.sh # рестарт LB, всех реплик, Postgres и Valkey: данные и токены остаются, кэш пуст
|
||||
make test-persistence ACTION_SCRIPT=scripts/restart.sh # то же публичной проверкой
|
||||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh # остановка реплики, обслужившей тест; ~20 с
|
||||
STOP_MODE=kill STOP_ONE_LOG=/tmp/stop-one.log make test-failover ACTION_SCRIPT=scripts/stop-one.sh
|
||||
# kill вместо graceful; журнал: какой TARGET_INSTANCE_ID и контейнер
|
||||
TARGET_INSTANCE_ID=<x-instance-id> scripts/stop-one.sh # остановить одну реплику руками
|
||||
make replicas # вернуть остановленные реплики (те же ID), ждать healthy
|
||||
make replicas API_REPLICAS=3 # разово 3 реплики; LB видит новую за 1–3 с без правки конфига
|
||||
make down # удалить контейнеры, volume с данными остаётся
|
||||
make wipe_data # удалить и данные: только после ввода yes
|
||||
```
|
||||
|
||||
`make run_docker` сам создаёт недостающие `.env` и `config.toml`
|
||||
(`env_setup`) и монтирует `config.toml` только для чтения. Готовность —
|
||||
`docker inspect -f '{{.State.Health.Status}}' $(docker compose ps -q api)`
|
||||
→ `healthy`.
|
||||
`healthy` у `haproxy` (`docker compose ps haproxy`): LB отвечает на
|
||||
`/lb/ready` 200, пока есть хотя бы одна готовая реплика. Между прогонами
|
||||
`make test-failover` — `make replicas`: иначе следующий прогон увидит
|
||||
одну реплику и упадёт на `less than two API instances observed`.
|
||||
|
||||
## Direct invocation (без HTTP)
|
||||
|
||||
@@ -188,10 +206,24 @@ make lint # ruff; затрагивает и dr
|
||||
|
||||
## Gotchas
|
||||
|
||||
- **На 8080 обычно уже работает `make run_dev` пользователя.** Поэтому
|
||||
драйвер по умолчанию на 18080. `driver.py --port 8080 stop` чужой
|
||||
сервер не убьёт (нет pid-файла → `left running`, код 1) — и не надо:
|
||||
это процесс пользователя.
|
||||
- **На 8080 обычно уже работает стенд `make run_docker` (HAProxy) или
|
||||
`make run_dev` пользователя.** Поэтому драйвер по умолчанию на 18080.
|
||||
`driver.py --port 8080 stop` чужой сервер не убьёт (нет pid-файла →
|
||||
`left running`, код 1) — и не надо: это процесс пользователя.
|
||||
- **`make student_test` против одного процесса без `EXPECT_REPLICAS=1`
|
||||
падает на тестах реплик** (`saw 1 X-Instance-Id ... EXPECT_REPLICAS=2`):
|
||||
по умолчанию набор ждёт `API_REPLICAS` реплик за `BASE_URL`. Против
|
||||
`make run_dev` — `make student_test EXPECT_REPLICAS=1`; `driver.py
|
||||
student` и `make test_isolated` передают его сами.
|
||||
- **Порт отдельной реплики на хосте не опубликован.** Запрос мимо LB —
|
||||
только изнутри сети: `docker compose exec --index 2 api python -c
|
||||
"import urllib.request as u; print(u.urlopen('http://127.0.0.1:8080/health/ready').headers['X-Instance-Id'])"`.
|
||||
`docker compose exec api` без `--index` берёт первую реплику; если она
|
||||
остановлена `stop-one.sh`, команда падает.
|
||||
- **Номера слотов HAProxy (`api-1`, `api-2` в `make lb_stats`) не
|
||||
совпадают с именами контейнеров** (`mtusi-lab3-api-1`): слот получает
|
||||
адрес из DNS. Связь — по адресу: `docker inspect -f '{{range
|
||||
.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' <id>`.
|
||||
- **Экземпляр драйвера пишет в ту же рабочую базу**, что `make run_dev` и
|
||||
`make run_docker`: тестовые пользователи и чаты там остаются. Чистый
|
||||
прогон — `make test_isolated` (временная база `test_<db>`), чистый
|
||||
@@ -215,11 +247,12 @@ make lint # ruff; затрагивает и dr
|
||||
`start` передаёт `APP__PORT=<port>` в окружении, а окружение важнее
|
||||
`.env`. `APP_OUT_PORT` приложение не читает — это порт публикации
|
||||
контейнера.
|
||||
- **`driver.py stop` контейнер не останавливает** (`not ours (no pid
|
||||
- **`driver.py stop` стенд не останавливает** (`not ours (no pid
|
||||
file)`, код 1) — это правильно, гасить его `make down`. `status` для
|
||||
контейнера показывает один PID — процесс Docker Desktop, а не uvicorn.
|
||||
стенда показывает один PID — процесс Docker Desktop, а не HAProxy.
|
||||
- **`make logs` висит** (`logs -f`) — агенту нужен
|
||||
`docker compose logs --no-log-prefix api` без `-f`.
|
||||
`docker compose logs --no-log-prefix api` без `-f`. Строки всех
|
||||
реплик перемешаны, реплику называет поле `instance_id`.
|
||||
- **`req` без `--token` на защищённом пути даёт 401 `unauthorized`** с
|
||||
`www-authenticate: Bearer realm="messenger"` — это не сломанный
|
||||
сервер, а контракт: аутентификация раньше доступа. Токен — из ответа
|
||||
@@ -234,9 +267,10 @@ make lint # ruff; затрагивает и dr
|
||||
409 — штатный для FastAPI (`api-contract.md`). Ключ в журнал сервера не
|
||||
пишется: повтор виден по `"replayed": true` и `message_id`.
|
||||
- **`X-Instance-Id` в консоли — hostname машины**, в контейнере —
|
||||
короткий ID контейнера (`docker compose ps -q api`). Другое значение —
|
||||
`APP__INSTANCE_ID=... python3 $D start`; в `config.toml` и `.env` его
|
||||
не задавать.
|
||||
короткий ID контейнера (начало `docker compose ps -q api`, по нему
|
||||
`scripts/stop-one.sh` находит реплику). Другое значение —
|
||||
`APP__INSTANCE_ID=... python3 $D start`; в `config.toml`, `.env` и
|
||||
compose его не задавать: у реплик значение должно различаться.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
@@ -247,6 +281,11 @@ make lint # ruff; затрагивает и dr
|
||||
- **`make upgrade failed` в `start`** — не запущен Docker или занят порт
|
||||
Postgres `POSTGRES_OUT_PORT` (5433): `docker ps`, `lsof -nP
|
||||
-iTCP:5433 -sTCP:LISTEN`.
|
||||
- **Через LB 503 `No API replica is available` без `X-Instance-Id`** —
|
||||
ответ самого HAProxy: готовых реплик нет (все остановлены или ещё не
|
||||
прошли 2 проверки `/health/ready`). `make lb_stats`, затем `make
|
||||
replicas`. Ответ 502/504 от LB — реплика оборвала ответ или не уложилась
|
||||
в 10 с.
|
||||
- **`/health/ready` отвечает 503, `/health/live` — 200** — Postgres
|
||||
недоступен: `docker compose ps postgres`, `make start_db`. Запросы к
|
||||
API в это время получают 503 `unavailable`, после возврата Postgres
|
||||
|
||||
@@ -17,15 +17,19 @@
|
||||
получает новый Idempotency-Key (печатается для повтора)
|
||||
smoke публичный tests/smoke.py против этого порта
|
||||
student собственные тесты student-tests/ (make student_test) против
|
||||
этого порта
|
||||
этого порта; против своего процесса — с EXPECT_REPLICAS=1
|
||||
instances [--count N] распределение одной сессии по репликам: вход
|
||||
одним синтетическим пользователем, N × GET /users/me с одним
|
||||
токеном, X-Instance-Id каждого ответа и итог по репликам
|
||||
stop остановить свой экземпляр на порту
|
||||
all start → flow → smoke → student (если есть student-tests/) → stop
|
||||
|
||||
Порт по умолчанию 18080, а не 8080: на 8080 обычно висит `make run_dev`
|
||||
пользователя, и его процесс трогать не надо. Экземпляр драйвера пишет в
|
||||
ту же рабочую базу Postgres, что и `make run_dev`. flow, req, smoke и
|
||||
student работают с любым сервером на порту, в том числе с контейнером
|
||||
(`make run_docker APP_OUT_PORT=<port>`).
|
||||
Порт по умолчанию 18080, а не 8080: на 8080 обычно работает стенд
|
||||
`make run_docker` (HAProxy перед репликами API) или `make run_dev`
|
||||
пользователя, и их процессы трогать не надо. Экземпляр драйвера пишет в
|
||||
ту же рабочую базу Postgres. flow, req, smoke, student и instances
|
||||
работают с любым сервером на порту, в том числе со стендом через
|
||||
балансировщик (`--port 8080`).
|
||||
"""
|
||||
|
||||
import argparse
|
||||
@@ -40,6 +44,7 @@ import time
|
||||
import urllib.error
|
||||
import urllib.request
|
||||
import uuid
|
||||
from collections import Counter
|
||||
from pathlib import Path
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[3]
|
||||
@@ -537,10 +542,57 @@ def cmd_student(port: int) -> int:
|
||||
if not (ROOT / "student-tests").is_dir():
|
||||
print("no student-tests/ in this checkout")
|
||||
return 1
|
||||
return subprocess.call(
|
||||
["make", "student_test", f"BASE_URL=http://localhost:{port}"],
|
||||
cwd=ROOT,
|
||||
command = ["make", "student_test", f"BASE_URL=http://localhost:{port}"]
|
||||
_, pid_path = paths(port)
|
||||
if pid_path.exists():
|
||||
# на порту свой процесс драйвера: один API без балансировщика,
|
||||
# тесты реплик пропускаются с причиной
|
||||
command.append("EXPECT_REPLICAS=1")
|
||||
return subprocess.call(command, cwd=ROOT)
|
||||
|
||||
|
||||
def cmd_instances(port: int, count: int) -> int:
|
||||
"""Распределение одной сессии по репликам: один вход, `count`
|
||||
запросов `GET /users/me` с одним токеном. Токен не печатается."""
|
||||
tag = uuid.uuid4().hex[:8]
|
||||
username, password = f"lb_{tag}", f"Pw-lb-{uuid.uuid4().hex}"
|
||||
body = {
|
||||
"username": username,
|
||||
"display_name": "LB demo",
|
||||
"password": password,
|
||||
}
|
||||
status, _, _ = call(port, "POST", USERS, body=body)
|
||||
if status != 201:
|
||||
print(f"register: {status}")
|
||||
return 1
|
||||
status, _, session = call(
|
||||
port,
|
||||
"POST",
|
||||
SESSIONS,
|
||||
authorization=basic(username, password),
|
||||
)
|
||||
if status != 201 or not isinstance(session, dict):
|
||||
print(f"login: {status}")
|
||||
return 1
|
||||
token = session["token"]
|
||||
counts: Counter[str] = Counter()
|
||||
failures = 0
|
||||
for number in range(1, count + 1):
|
||||
status, hdrs, payload = call(port, "GET", f"{USERS}/me", token=token)
|
||||
instance = hdrs.get("x-instance-id", "-")
|
||||
ok = status == 200 and isinstance(payload, dict)
|
||||
ok = ok and payload.get("username") == username
|
||||
failures += not ok
|
||||
print(
|
||||
f"{number:>3} GET /api/v1/users/me {status} "
|
||||
f"x-instance-id: {instance}" + ("" if ok else " UNEXPECTED"),
|
||||
)
|
||||
counts[instance] += 1
|
||||
print(f"user {username}: one login, {count} requests with one token")
|
||||
for instance, served in counts.most_common():
|
||||
print(f" {instance}: {served}")
|
||||
print(f"instances: {len(counts)}")
|
||||
return 1 if failures else 0
|
||||
|
||||
|
||||
def main() -> int:
|
||||
@@ -549,6 +601,8 @@ def main() -> int:
|
||||
sub = parser.add_subparsers(dest="cmd", required=True)
|
||||
for name in ("start", "stop", "status", "flow", "smoke", "student", "all"):
|
||||
sub.add_parser(name)
|
||||
instances = sub.add_parser("instances")
|
||||
instances.add_argument("--count", type=int, default=12)
|
||||
req = sub.add_parser("req")
|
||||
req.add_argument("method")
|
||||
req.add_argument("path")
|
||||
@@ -580,6 +634,8 @@ def main() -> int:
|
||||
return flow_rc or smoke_rc or student_rc
|
||||
if args.cmd == "req":
|
||||
return cmd_req(port, args)
|
||||
if args.cmd == "instances":
|
||||
return cmd_instances(port, args.count)
|
||||
handlers = {
|
||||
"start": cmd_start,
|
||||
"stop": cmd_stop,
|
||||
|
||||
+6
-2
@@ -14,9 +14,13 @@
|
||||
# порт сервиса ([app] port): на нём слушает приложение, его же
|
||||
# публикует compose, на нём же healthcheck
|
||||
APP__PORT=8080
|
||||
# порт на 127.0.0.1 хоста, куда публикуется сервис; приложение его
|
||||
# не читает
|
||||
# порт на 127.0.0.1 хоста, куда публикуется балансировщик HAProxy —
|
||||
# единственная точка входа; приложение его не читает
|
||||
APP_OUT_PORT=8080
|
||||
# число реплик сервиса api за балансировщиком (имя skeleton); читают
|
||||
# compose (deploy.replicas) и Makefile, приложение — нет. Разовая
|
||||
# подмена — make replicas API_REPLICAS=N
|
||||
API_REPLICAS=2
|
||||
|
||||
# PostgreSQL. POSTGRES_USER, POSTGRES_PASSWORD и POSTGRES_DB читает и
|
||||
# образ postgres; пароль задаётся только при первом создании volume.
|
||||
|
||||
@@ -10,8 +10,9 @@ REST API мессенджера (пользователи, чаты, истор
|
||||
commit `c6ad34d`): PostgreSQL как источник истины, вход по Basic →
|
||||
Bearer-сессия, Valkey — кэш карточек чатов, трек 2 лабы 2 (план запроса
|
||||
и восстановление) в `bench/`. Change `instance-id-idempotency` добавил
|
||||
`X-Instance-Id` и `Idempotency-Key`; балансировщик и реплики — следующие
|
||||
changes (`PLAN.md`). Переход на lab2 завершён changes OpenSpec, они в
|
||||
`X-Instance-Id` и `Idempotency-Key`, `replicas-lb` — HAProxy перед
|
||||
двумя репликами API, лимиты, `scripts/stop-one.sh`; дальше — changes
|
||||
из `PLAN.md`. Переход на lab2 завершён changes OpenSpec, они в
|
||||
`openspec/changes/archive/`. Стек:
|
||||
Python 3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog
|
||||
(JSON в stdout), redis-py (клиент Valkey).
|
||||
@@ -99,18 +100,16 @@ Python 3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog
|
||||
Лаба 3 закрыта не целиком. Этот файл и `.claude/rules/` описывают
|
||||
целевое состояние лабы 3, поэтому стенд с ними пока расходится. План
|
||||
работ, решения и трек «5» — `PLAN.md`. Стенд — проект compose
|
||||
`mtusi-lab3` со своей базой; `X-Instance-Id` и `Idempotency-Key` уже
|
||||
работают, публичный smoke лабы 3 проходит на одном процессе.
|
||||
`mtusi-lab3` со своей базой: HAProxy перед двумя репликами `api`
|
||||
(change `replicas-lb`); `make test`, `make test-persistence` и `make
|
||||
test-failover` проходят через LB.
|
||||
|
||||
- Одна реплика `api` с опубликованным портом, LB нет; `scripts/restart.sh`
|
||||
перезапускает только api, Postgres и Valkey; `scripts/stop-one.sh`
|
||||
нет — `make test-failover` пока не запустить (change `replicas-lb`).
|
||||
- Тест «Одно значение на процесс» (`test_api_conventions.py`) верен
|
||||
только против одного процесса; гонка одного ключа ещё не требует
|
||||
ответов ≥2 реплик (`student-tests.md`) — оба переписывает
|
||||
`replicas-lb`.
|
||||
- Скилл `run-mtusi-messenger` и `bench/` — стенд с одним API;
|
||||
`REPORT.md` заполнен только для идемпотентности и `X-Instance-Id`.
|
||||
- `bench/` — стенд с одним API без LB; переход на HAProxy + N реплик,
|
||||
профиль `failover` и замер времени обнаружения отказа — change
|
||||
`graceful-failover`. Цепочка таймаутов задана, но не замерена.
|
||||
- `scripts/rolling-update.sh` нет (change `rolling-update`).
|
||||
- `REPORT.md` заполнен для идемпотентности, `X-Instance-Id` и реплик за
|
||||
LB; трек «5» и уровень «4» по failover и rolling update — впереди.
|
||||
|
||||
Закрытый пункт убрать отсюда, закрытый переход — удалить раздел.
|
||||
|
||||
@@ -257,20 +256,23 @@ Python 3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog
|
||||
| `make test [BASE_URL=...]` | публичный smoke против запущенного сервера |
|
||||
| `make load` | нагрузка из `tests/load.py`; параметры — `tests/README.md` |
|
||||
| `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | сохранность: создаёт данные и сессию, вызывает restart hook, проверяет те же данные прежним токеном (`tests/README.md`) |
|
||||
| `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | отказ одной API-реплики: 15 с записи параллельно hook, восстановление записи ≤10 с, без дублей (`tests/README.md`); `scripts/stop-one.sh` ещё не написан |
|
||||
| `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | отказ одной API-реплики через LB: 15 с записи параллельно hook, восстановление записи ≤10 с, без дублей (`tests/README.md`). `STOP_MODE=kill` — без graceful, `STOP_ONE_LOG=<файл>` — какой `TARGET_INSTANCE_ID` и контейнер остановлен. Между прогонами — `make replicas` |
|
||||
| `make run_dev` | `make upgrade` (Postgres из compose и миграции) и `make start_cache`, затем `APP__RUN_MODE=console uv run python -m src`: 127.0.0.1:8080, reload |
|
||||
| `make lint` | `ruff format` + `ruff check --fix`, дважды: так нужно из-за COM812; `tests/` и `scripts/` skeleton исключены в `[tool.ruff]` |
|
||||
| `make env_setup` | `.env.example` → `.env` со случайными `POSTGRES_PASSWORD` и `VALKEY_PASSWORD`, `config_example.toml` → `config.toml`; существующие файлы не перезаписывает (новые строки шаблона переносятся руками) |
|
||||
| `make run_docker` | `make env_setup` (только недостающие файлы) + `docker compose build` + `up -d`: postgres, valkey → migrate → api; `config.toml` и `infra/valkey/valkey.conf` монтируются read-only |
|
||||
| `make run_docker` | `make env_setup` (только недостающие файлы) + `docker compose build` + `up -d`: postgres, valkey → migrate → api × `API_REPLICAS` (2) → haproxy на `127.0.0.1:APP_OUT_PORT`; `config.toml`, `infra/valkey/valkey.conf` и `infra/haproxy/haproxy.cfg` монтируются read-only |
|
||||
| `make stop` / `make down` | остановить / удалить контейнеры compose; volume с данными остаётся |
|
||||
| `make logs` | журнал API, каждая строка — JSON (`--no-log-prefix`) |
|
||||
| `make logs` | журнал всех реплик API, каждая строка — JSON (`--no-log-prefix`), реплика — поле `instance_id` |
|
||||
| `make replicas [API_REPLICAS=N]` | вернуть остановленные реплики (те же ID) и выставить их число, ждать `healthy` (`balancer.md`) |
|
||||
| `make instances` | вход одним синтетическим пользователем, 12 × `GET /users/me` через LB: `X-Instance-Id` каждого ответа и итог по репликам |
|
||||
| `make lb_stats` | слоты HAProxy: адрес, состояние проверки, запросы, повторы, перенаправления (CSV статистики изнутри контейнера LB) |
|
||||
| `make start_db` / `make stop_db` | Postgres стенда: `up -d --wait postgres` / `stop postgres` |
|
||||
| `make start_cache` / `make stop_cache` | Valkey стенда: `up -d --wait valkey` / `stop valkey`; volume нет, кэш после рестарта пуст |
|
||||
| `make upgrade` | `start_db` + `uv run alembic upgrade head` с хоста (`127.0.0.1:POSTGRES_OUT_PORT`) |
|
||||
| `make revision` | `upgrade` + `alembic revision --autogenerate`, сообщение спрашивает `read -p` |
|
||||
| `make wipe_data` | `down -v` — удалить данные стенда (и кэш); только после ввода `yes` |
|
||||
| `make test_isolated [KEEP_TEST_DB=1]` | образ на временной базе `test_<db>` с Valkey стенда (ключи разделены именем базы): сборка, миграции, отдельный контейнер API на `TEST_APP_PORT`, `make test` + `make student_test`, уборка при любом исходе (`student-tests.md`) |
|
||||
| `make student_test [BASE_URL=...]` | собственные тесты `student-tests/` (pytest) против запущенного сервера, кроме проверок отказов (`-m 'not fault'`); сервер недоступен — код 2 и одна строка с адресом |
|
||||
| `make test_isolated [KEEP_TEST_DB=1]` | образ на временной базе `test_<db>` с Valkey стенда (ключи разделены именем базы): сборка, миграции, отдельный контейнер API на `TEST_APP_PORT`, `make test` + `make student_test EXPECT_REPLICAS=1` (тесты реплик пропускаются с причиной), уборка при любом исходе (`student-tests.md`) |
|
||||
| `make student_test [BASE_URL=...] [EXPECT_REPLICAS=...]` | собственные тесты `student-tests/` (pytest) против запущенного сервера, кроме проверок отказов (`-m 'not fault'`); `EXPECT_REPLICAS` (по умолчанию `API_REPLICAS`) — сколько реплик за `BASE_URL`, против одного процесса — 1; сервер недоступен — код 2 и одна строка с адресом |
|
||||
| `make failure_checks [FAULT_ARGS=...]` | проверки отказов (`pytest -m fault`, ~45 с) на отдельном стенде: проект `<рабочий>-failures` со своими Postgres и Valkey, обычный и «тесный» API (срок 2 с, пул 1), hook `student-tests/fault_hook.py`; стенд и его volume удаляются при любом исходе, рабочий не трогается (`student-tests.md`) |
|
||||
| `make bench [BENCH_LABEL=...]` | полная матрица 10k / 100k / 500k читаемого чата плюс 100 000 сообщений в 1 110 фоновых чатах разного размера (~35 мин, оценка по `bench_quick`) на своём проекте compose `mtusi-bench` (API, Postgres, Valkey с лимитами, без портов хоста и без `.env` рабочего стенда); на каждый размер — свежий стенд, `VACUUM (ANALYZE)`, планы запроса истории (`auto_explain`) по уровням чатов с вариантами индекса и запроса, в конце — пробы стоимости записи по вариантам. Результаты в `evidence/bench/<метка>/`, занятая метка — отказ. Перед запуском — подготовка хоста (`bench.md`) |
|
||||
| `make bench_quick` | самопроверка стенда на 1k / 5k / 10k и 3 500 фоновых сообщений (~3 мин), метка `quick-<время>`, в git не идёт |
|
||||
@@ -326,10 +328,11 @@ src/
|
||||
utc.py # utcnow() (aware UTC), формат RFC 3339 с Z
|
||||
cursor.py # непрозрачный keyset-курсор: кодирование и разбор
|
||||
student-tests/ # black-box тесты по HTTP (уровень 4): make student_test
|
||||
conftest.py # BASE_URL, проверка доступности, фикстуры alice/bob/eve/chat и stand/tight_api, сбор маркеров spec, стоп без hook
|
||||
conftest.py # BASE_URL, EXPECT_REPLICAS и фикстура replicas (пропуск против одного процесса), проверка доступности, фикстуры alice/bob/eve/chat и stand/tight_api, сбор маркеров spec, стоп без hook
|
||||
api_client.py # Api поверх httpx; Actor.headers() — единственное место идентификации; post_message/send_message — с Idempotency-Key
|
||||
contract.py # тела по схемам contracts/openapi.json, форматы id и created_at, X-Instance-Id, assert_error
|
||||
test_idempotency.py # спек idempotency: ключ, повтор, 409, область, порядок кодов (гонка — test_race.py, отказы — test_failures.py)
|
||||
contract.py # тела по схемам contracts/openapi.json, форматы id и created_at, X-Instance-Id, assert_error, assert_replicas
|
||||
test_idempotency.py # спек idempotency: ключ, повтор, 409, область, порядок кодов, повтор через другую реплику (гонка — test_race.py, отказы — test_failures.py)
|
||||
test_load_balancing.py # спек load-balancing (вне сверки покрытия): одна сессия на разных репликах, запись видна через другую реплику
|
||||
spec_coverage.py # исключения (сценарии, которые не проверить по HTTP) и сверка покрытия
|
||||
test_rubric.py, test_race.py # обязательные сценарии и гонки уровня 4
|
||||
test_<capability>.py # сценарии основных спеков, маркер @pytest.mark.spec
|
||||
@@ -337,10 +340,10 @@ student-tests/ # black-box тесты по HTTP (уровень 4)
|
||||
run_isolated.py # make test_isolated: образ на временной базе test_<db> (stdlib)
|
||||
run_failures.py # make failure_checks: стенд <рабочий>-failures, два API, pytest -m fault, уборка (stdlib)
|
||||
fault_hook.py # hook стенда отказов: stop/start/pause/unpause, кэш, триггеры сбоя участников и сообщений (stdlib)
|
||||
failures.compose.yml # override стенда отказов: без публикации портов
|
||||
failures.compose.yml # override стенда отказов: без публикации портов (Postgres, Valkey, LB)
|
||||
bench/ # нагрузочный стенд на API + Postgres + Valkey: make bench / make bench_quick
|
||||
run.py # оркестратор: стенд compose, фоновые чаты и расписание наполнения, матрица, обслуживание БД, планы и варианты, пробы записи, backup и восстановление во второе хранилище со сверкой, метрики, runs.csv / summary.md / meta.json
|
||||
bench.compose.yml # override стенда mtusi-bench: имена, лимиты BENCH_*, без портов и config.toml, auto_explain
|
||||
bench.compose.yml # override стенда mtusi-bench: имена, одна реплика api без LB, лимиты BENCH_* (deploy.resources), без портов и config.toml, auto_explain
|
||||
bench.env # подстановки compose стенда вместо .env рабочего стенда (без паролей)
|
||||
k6/ # сценарии k6: prepare (вход по Basic, фоновые чаты), prefill (по расписанию), cursors, plan_cursors (страницы плана фоновых чатов), explain, read, tail, write, after_backup и restore_check (этап восстановления); lib.js — Bearer, messageHeaders (новый Idempotency-Key на отправку) и хелперы
|
||||
compare.py # make bench_compare: дельта двух меток, уровень шума, эффект или шум
|
||||
@@ -348,19 +351,22 @@ bench/ # нагрузочный стенд на API + Post
|
||||
migrations/, alembic.ini # ревизии alembic, async env.py; применяет одноразовый сервис compose
|
||||
infra/ # конфигурации сервисов стенда; README.md — skeleton
|
||||
valkey/valkey.conf # лимит памяти и LRU, persistence выключен
|
||||
haproxy/haproxy.cfg # (лаба 3) LB: реплики через DNS Docker, проверки /health/ready, повтор только на conn-failure
|
||||
scripts/restart.sh # restart hook для make test-persistence, по restart.example.sh: api, postgres, valkey; (лаба 3) и LB
|
||||
scripts/stop-one.sh # (лаба 3) failover hook для make test-failover: TARGET_INSTANCE_ID → контейнер api, stop или kill
|
||||
haproxy/haproxy.cfg # LB: реплики через DNS Docker (8 слотов), проверки /health/ready, цепочка таймаутов, повтор только на conn-failure, ответы LB в формате контракта, мониторинг :8404
|
||||
scripts/restart.sh # restart hook для make test-persistence, по restart.example.sh: LB, все реплики api, postgres, valkey
|
||||
scripts/stop-one.sh # failover hook для make test-failover: TARGET_INSTANCE_ID → реплика api этого проекта, STOP_MODE stop или kill, STOP_ONE_LOG
|
||||
scripts/rolling-update.sh # (лаба 3) поочерёдная замена реплик новым образом
|
||||
Dockerfile # builder (uv sync --locked) → runtime: .venv + src + миграции, UID 10001, healthcheck
|
||||
docker-compose.yml # проект mtusi-lab3: postgres, valkey, migrate, api; адреса и порты из .env, volume postgres_data; (лаба 3) haproxy, api × API_REPLICAS без портов, лимиты
|
||||
docker-compose.yml # проект mtusi-lab3: postgres, valkey, migrate, api × API_REPLICAS без портов, haproxy — единственный порт API; адреса и порты из .env, volume postgres_data, лимиты у всех, окружение по сервисам
|
||||
.dockerignore
|
||||
config_example.toml, .env.example
|
||||
evidence/storage/ # отказы БД, пул, statement_timeout, рестарт, порты Postgres, свежий clone
|
||||
evidence/migrations/ # миграции с нуля и повторно, ошибка миграции
|
||||
evidence/auth/ # пароли и токены в БД, срок сессии, TTL из конфига
|
||||
evidence/cache/ # попадания в кэш, отказ Valkey, FLUSHALL и рестарт
|
||||
evidence/tests/ # выводы make test_isolated, make student_test и make failure_checks для REPORT.md
|
||||
evidence/tests/ # выводы make test_isolated, make student_test (через LB) и make failure_checks для REPORT.md
|
||||
evidence/idempotency/ # повтор, 409, гонка, таблица ключей, X-Instance-Id
|
||||
evidence/replicas/ # стенд с LB: порты, лимиты, окружение, распределение, ответы LB, test-persistence
|
||||
evidence/failover/ # make test-failover для каждой реплики (stop и kill), отказы stop-one.sh
|
||||
evidence/bench/<метка>/ # результаты make bench / bench_restore: паспорт, прогоны, наполнение, сводка (планы, стоимость записи, восстановление), планы explain-<размер>.txt, сырые итоги k6
|
||||
evidence/compare/ # таблицы make bench_compare: <до>__<после>.md
|
||||
KNOWN_ISSUES.md # найденные попутно дефекты, не исправленные без просьбы
|
||||
@@ -368,8 +374,7 @@ KNOWN_ISSUES.md # найденные попутно дефекты,
|
||||
|
||||
`evidence/` перенесён без содержимого лабы 2 (оно осталось в
|
||||
репозитории `mtusi2026lab2-safronov`). Каталоги выше появляются заново
|
||||
по мере changes; новые для лабы 3 — `evidence/replicas/`,
|
||||
`evidence/idempotency/`, `evidence/failover/`, `evidence/rollout/`.
|
||||
по мере changes; для лабы 3 ещё появится `evidence/rollout/`.
|
||||
|
||||
## Архитектура в двух словах
|
||||
|
||||
|
||||
@@ -61,9 +61,15 @@ env_setup:
|
||||
-include .env
|
||||
APP__PORT ?= 8080
|
||||
APP_OUT_PORT ?= 8080
|
||||
# число реплик api за HAProxy — то же, что deploy.replicas в compose
|
||||
API_REPLICAS ?= 2
|
||||
# сколько реплик за BASE_URL ждут тесты реплик student-tests: против
|
||||
# стенда с LB — API_REPLICAS, против одного процесса — 1 (их пропуск)
|
||||
EXPECT_REPLICAS ?= $(API_REPLICAS)
|
||||
DC=docker compose
|
||||
|
||||
# стенд: postgres, valkey -> migrate -> api. env_setup создаёт
|
||||
# стенд: postgres, valkey -> migrate -> api × API_REPLICAS -> haproxy
|
||||
# (единственный порт API на хосте — у haproxy). env_setup создаёт
|
||||
# недостающие .env и config.toml из шаблонов: без config.toml compose не
|
||||
# запустится (bind с create_host_path: false), без паролей — тоже
|
||||
.PHONY: run_docker
|
||||
@@ -80,7 +86,8 @@ stop:
|
||||
down:
|
||||
$(DC) down
|
||||
|
||||
# без префикса "api-1 |": каждая строка — JSON
|
||||
# журнал всех реплик api без префикса "api-1 |": каждая строка — JSON,
|
||||
# реплику называет поле instance_id
|
||||
.PHONY: logs
|
||||
logs:
|
||||
$(DC) logs -f --no-log-prefix api
|
||||
@@ -137,6 +144,44 @@ stop_cache:
|
||||
$(DC) stop valkey
|
||||
|
||||
|
||||
# -------------------------
|
||||
# Реплики за балансировщиком (HAProxy)
|
||||
# -------------------------
|
||||
|
||||
# вернуть остановленные реплики (scripts/stop-one.sh) и выставить их
|
||||
# число: остановленные контейнеры запускаются с теми же ID, недостающие
|
||||
# создаются, лишние удаляются; ждёт healthcheck реплик. Разовая подмена —
|
||||
# make replicas API_REPLICAS=3, следующий make run_docker вернёт число
|
||||
# из .env
|
||||
.PHONY: replicas
|
||||
replicas:
|
||||
$(DC) up -d --no-deps --no-recreate --wait --scale api=$(API_REPLICAS) api
|
||||
|
||||
# распределение запросов одной сессии через LB: вход одним синтетическим
|
||||
# пользователем, серия GET /users/me с одним токеном, X-Instance-Id каждого
|
||||
# ответа и число ответов каждой реплики
|
||||
.PHONY: instances
|
||||
instances:
|
||||
$(PYTHON) .claude/skills/run-mtusi-messenger/driver.py --port $(APP_OUT_PORT) instances
|
||||
|
||||
# состояние реплик глазами HAProxy: занятые слоты, адрес, статус проверки,
|
||||
# соединения, запросы, ошибки соединения, повторы и перенаправления. CSV
|
||||
# статистики читается изнутри контейнера LB: порт 8404 наружу не
|
||||
# опубликован, curl в образе нет, bash есть
|
||||
LB_STATS_FIELDS = svname addr status check_status scur stot econ wretr wredis hrsp_5xx
|
||||
.PHONY: lb_stats
|
||||
lb_stats:
|
||||
@$(DC) exec -T haproxy bash -c 'exec 3<>/dev/tcp/127.0.0.1/8404 && printf "GET /stats;csv HTTP/1.0\r\n\r\n" >&3 && cat <&3' \
|
||||
| awk -F, -v fields="$(LB_STATS_FIELDS)" ' \
|
||||
/^# pxname/ { sub(/^# /, ""); for (i = 1; i <= NF; i++) col[$$i] = i; \
|
||||
n = split(fields, f, " "); for (j = 1; j <= n; j++) printf "%s\t", f[j]; print ""; next } \
|
||||
$$1 != "api" { next } \
|
||||
$$2 != "BACKEND" && $$(col["addr"]) == "" && $$(col["status"]) == "MAINT (resolution)" { free++; next } \
|
||||
{ for (j = 1; j <= n; j++) { v = $$(col[f[j]]); printf "%s\t", (v == "" ? "-" : v) }; print "" } \
|
||||
END { printf "free slots: %d\n", free }' \
|
||||
| column -t -s "$$(printf '\t')"
|
||||
|
||||
|
||||
# -------------------------
|
||||
# Load benchmark
|
||||
# -------------------------
|
||||
@@ -197,10 +242,13 @@ bench_ab:
|
||||
# Common targets
|
||||
# -------------------------
|
||||
|
||||
# собственные black-box тесты против запущенного сервера (BASE_URL)
|
||||
# собственные black-box тесты против запущенного сервера (BASE_URL).
|
||||
# EXPECT_REPLICAS — сколько реплик за BASE_URL: по умолчанию API_REPLICAS
|
||||
# (стенд с LB); против одного процесса — EXPECT_REPLICAS=1, и тесты
|
||||
# реплик пропускаются с причиной
|
||||
.PHONY: student_test
|
||||
student_test:
|
||||
BASE_URL=$(BASE_URL) uv run pytest
|
||||
BASE_URL=$(BASE_URL) EXPECT_REPLICAS=$(EXPECT_REPLICAS) uv run pytest
|
||||
|
||||
# образ на временной базе test_<POSTGRES_DB>: сборка, миграции, отдельный
|
||||
# контейнер api на 127.0.0.1:TEST_APP_PORT, make test и make student_test,
|
||||
|
||||
+27
-7
@@ -4,6 +4,11 @@
|
||||
# bench/bench.env, а не из .env рабочего стенда; пароли и BENCH_* передаёт
|
||||
# run.py (поля Profile), без них стенд не поднимается. Решения 1, 2, 5 design
|
||||
# change bench-postgres; что не меняется между метками — .claude/rules/bench.md.
|
||||
# До change graceful-failover стенд — один API без балансировщика: сервис
|
||||
# haproxy не запускается (run.py поднимает api с --no-deps), у api одна
|
||||
# реплика. Лимиты — в форме deploy.resources.limits, как в основном файле:
|
||||
# compose не принимает cpus/mem_limit рядом с deploy-лимитами; значения
|
||||
# (NanoCpus, Memory) у контейнеров те же, что раньше.
|
||||
services:
|
||||
postgres:
|
||||
container_name: mtusi-bench-postgres
|
||||
@@ -13,16 +18,22 @@ services:
|
||||
# включает его только на этапе плана, между прогонами
|
||||
command: ["postgres", "-c", "shared_preload_libraries=auto_explain"]
|
||||
ports: !reset []
|
||||
cpus: ${BENCH_DB_CPUS:?run make bench}
|
||||
mem_limit: ${BENCH_DB_MEMORY:?run make bench}
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: ${BENCH_DB_CPUS:?run make bench}
|
||||
memory: ${BENCH_DB_MEMORY:?run make bench}
|
||||
memswap_limit: ${BENCH_DB_MEMORY:?run make bench}
|
||||
|
||||
valkey:
|
||||
container_name: mtusi-bench-valkey
|
||||
restart: "no"
|
||||
ports: !reset []
|
||||
cpus: ${BENCH_CACHE_CPUS:?run make bench}
|
||||
mem_limit: ${BENCH_CACHE_MEMORY:?run make bench}
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: ${BENCH_CACHE_CPUS:?run make bench}
|
||||
memory: ${BENCH_CACHE_MEMORY:?run make bench}
|
||||
memswap_limit: ${BENCH_CACHE_MEMORY:?run make bench}
|
||||
|
||||
migrate:
|
||||
@@ -31,10 +42,11 @@ services:
|
||||
volumes: !reset []
|
||||
|
||||
api:
|
||||
# один контейнер: k6 обращается к нему по имени (container_name вместе
|
||||
# с deploy.replicas > 1 compose не принимает)
|
||||
container_name: mtusi-bench-api
|
||||
image: mtusi-messenger:bench
|
||||
restart: "no"
|
||||
ports: !reset []
|
||||
volumes: !reset []
|
||||
# проверка раз в несколько секунд — лишний CPU внутри лимита API
|
||||
healthcheck:
|
||||
@@ -43,10 +55,18 @@ services:
|
||||
# размер 500k с наполнением идёт ~25 мин; на медленном хосте срок
|
||||
# 3600 с по умолчанию мог бы истечь посреди прогона и дать 401
|
||||
AUTH__SESSION_TTL_SECONDS: ${BENCH_SESSION_TTL_SECONDS:?run make bench}
|
||||
cpus: ${BENCH_APP_CPUS:?run make bench}
|
||||
mem_limit: ${BENCH_APP_MEMORY:?run make bench}
|
||||
deploy:
|
||||
replicas: 1
|
||||
resources:
|
||||
limits:
|
||||
cpus: ${BENCH_APP_CPUS:?run make bench}
|
||||
memory: ${BENCH_APP_MEMORY:?run make bench}
|
||||
memswap_limit: ${BENCH_APP_MEMORY:?run make bench}
|
||||
|
||||
haproxy:
|
||||
# не запускается, но порт рабочего стенда не занимает и по ошибке
|
||||
ports: !reset []
|
||||
|
||||
networks:
|
||||
default:
|
||||
# k6 подключается к сети стенда по имени (docker run --network)
|
||||
|
||||
+85
-13
@@ -1,19 +1,23 @@
|
||||
# Стенд лабы 3: PostgreSQL, Valkey (кэш), одноразовые миграции и API.
|
||||
# Правила — .claude/rules/docker.md. Значения — из .env (шаблон
|
||||
# .env.example); литералы только у адреса публикации 127.0.0.1 и у режима
|
||||
# docker. Имя проекта меняется в каждой лабе: от него зависят имена
|
||||
# volumes, и стенд не должен подключаться к данным прошлой лабы.
|
||||
# Стенд лабы 3: HAProxy — единственная точка входа, за ним API ×
|
||||
# API_REPLICAS; PostgreSQL, Valkey (кэш) и одноразовые миграции.
|
||||
# Правила — .claude/rules/docker.md и balancer.md. Значения — из .env
|
||||
# (шаблон .env.example); литералы только у адреса публикации 127.0.0.1 и
|
||||
# у режима docker. Имя проекта меняется в каждой лабе: от него зависят
|
||||
# имена volumes, и стенд не должен подключаться к данным прошлой лабы.
|
||||
name: mtusi-lab3
|
||||
|
||||
# окружение приложения: одно для api и migrate, чтобы они не разъехались
|
||||
x-app-env: &app-env
|
||||
# окружение по сервисам: секреты получают только те, кому они нужны.
|
||||
# PostgreSQL — api и migrate
|
||||
x-db-env: &db-env
|
||||
APP__RUN_MODE: docker
|
||||
APP__PORT: ${APP__PORT:-8080}
|
||||
DATABASE__HOST: ${POSTGRES_HOST:-postgres}
|
||||
DATABASE__PORT: ${POSTGRES_PORT:-5432}
|
||||
DATABASE__USER: ${POSTGRES_USER:?POSTGRES_USER is not set, run make env_setup}
|
||||
DATABASE__PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is empty, run make env_setup}
|
||||
DATABASE__NAME: ${POSTGRES_DB:?POSTGRES_DB is not set, run make env_setup}
|
||||
|
||||
# Valkey — только api
|
||||
x-cache-env: &cache-env
|
||||
CACHE__HOST: ${VALKEY_HOST:-valkey}
|
||||
CACHE__PORT: ${VALKEY_PORT:-6379}
|
||||
CACHE__PASSWORD: ${VALKEY_PASSWORD:?VALKEY_PASSWORD is empty, copy Valkey lines from .env.example}
|
||||
@@ -60,6 +64,13 @@ services:
|
||||
retries: 10
|
||||
start_period: 30s
|
||||
start_interval: 1s
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
# соединения реплик: API_REPLICAS × (pool_size + max_overflow)
|
||||
# + migrate ≤ max_connections (100), расчёт — REPORT.md
|
||||
cpus: "2.0"
|
||||
memory: 1G
|
||||
|
||||
# кэш карточек чатов: без volume, persistence выключен в valkey.conf —
|
||||
# после рестарта кэш пуст, данные остаются в PostgreSQL
|
||||
@@ -100,28 +111,44 @@ services:
|
||||
retries: 10
|
||||
start_period: 10s
|
||||
start_interval: 1s
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
# maxmemory 64mb в valkey.conf плюс накладные
|
||||
cpus: "0.5"
|
||||
memory: 128M
|
||||
|
||||
# миграции — один раз до реплик, сами реплики их не запускают
|
||||
migrate:
|
||||
# образ собирает сервис api (make run_docker, make test_isolated)
|
||||
image: mtusi-messenger:lab3
|
||||
pull_policy: never
|
||||
command: ["alembic", "upgrade", "head"]
|
||||
restart: "no"
|
||||
environment: *app-env
|
||||
# только PostgreSQL: пароль Valkey миграциям не нужен
|
||||
environment: *db-env
|
||||
volumes:
|
||||
- *config-toml
|
||||
depends_on:
|
||||
postgres:
|
||||
condition: service_healthy
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: "0.5"
|
||||
memory: 256M
|
||||
|
||||
# реплики API: порты не публикуются, фиксированного имени контейнера
|
||||
# нет (мешало бы масштабированию) — запросы идут только через haproxy; X-Instance-Id — hostname, то есть
|
||||
# короткий ID контейнера. Разовая подмена числа — make replicas
|
||||
# API_REPLICAS=N
|
||||
api:
|
||||
build: .
|
||||
image: mtusi-messenger:lab3
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
# только localhost: стенд учебный
|
||||
- "127.0.0.1:${APP_OUT_PORT:-8080}:${APP__PORT:-8080}"
|
||||
environment: *app-env
|
||||
environment:
|
||||
<<: [*db-env, *cache-env]
|
||||
APP__PORT: ${APP__PORT:-8080}
|
||||
volumes:
|
||||
- *config-toml
|
||||
depends_on:
|
||||
@@ -134,6 +161,51 @@ services:
|
||||
condition: service_completed_successfully
|
||||
# healthcheck — из образа; SIGKILL не раньше, чем через 10 с
|
||||
stop_grace_period: 10s
|
||||
deploy:
|
||||
replicas: ${API_REPLICAS:-2}
|
||||
resources:
|
||||
limits:
|
||||
# один процесс — один event loop: больше 1 CPU не использует;
|
||||
# Argon2id 4 × 64 MiB + интерпретатор ≈ 350 МБ
|
||||
cpus: "1.0"
|
||||
memory: 512M
|
||||
|
||||
# единственная точка входа: реплики находит через DNS Docker, проверяет
|
||||
# /health/ready; конфиг — infra/haproxy/haproxy.cfg. Секретов не получает
|
||||
haproxy:
|
||||
image: haproxy:3.4.6-trixie@sha256:e273915691a8eab3f105bf3e39fd4c29a4ecf334e33421903b5589d25e14db26
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
# порт реплик и самого LB внутри сети: тот же APP__PORT
|
||||
API_PORT: ${APP__PORT:-8080}
|
||||
ports:
|
||||
# только localhost: стенд учебный; API на хосте доступно только так
|
||||
- "127.0.0.1:${APP_OUT_PORT:-8080}:${APP__PORT:-8080}"
|
||||
volumes:
|
||||
- type: bind
|
||||
source: ./infra/haproxy/haproxy.cfg
|
||||
target: /usr/local/etc/haproxy/haproxy.cfg
|
||||
read_only: true
|
||||
bind:
|
||||
create_host_path: false
|
||||
# make stop гасит LB раньше реплик, make run_docker поднимает после них
|
||||
depends_on:
|
||||
- api
|
||||
healthcheck:
|
||||
# healthy — через LB можно обслужить запрос: /lb/ready отвечает 200,
|
||||
# пока есть хотя бы одна готовая реплика. curl в образе нет, bash есть
|
||||
test: ["CMD", "bash", "-c", "exec 3<>/dev/tcp/127.0.0.1/8404 && printf 'GET /lb/ready HTTP/1.0\\r\\n\\r\\n' >&3 && head -n 1 <&3 | grep -q ' 200 '"]
|
||||
interval: 5s
|
||||
timeout: 3s
|
||||
retries: 3
|
||||
start_period: 10s
|
||||
start_interval: 1s
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
# nbthread 1 в haproxy.cfg
|
||||
cpus: "1.0"
|
||||
memory: 256M
|
||||
|
||||
volumes:
|
||||
postgres_data:
|
||||
|
||||
@@ -0,0 +1,95 @@
|
||||
# Балансировщик стенда лабы 3: единственная точка входа перед репликами
|
||||
# сервиса api. Правила — .claude/rules/balancer.md, решения — design
|
||||
# change replicas-lb (решения 1–5). Порт приходит переменной окружения
|
||||
# API_PORT (= APP__PORT из .env); секретов LB не получает.
|
||||
|
||||
global
|
||||
# журнал — в stdout контейнера (docker compose logs haproxy)
|
||||
log stdout format raw local0 info
|
||||
maxconn 4096
|
||||
# один поток на лимит 1 CPU: иначе HAProxy создал бы поток на каждый
|
||||
# CPU ВМ и делил между ними одну квоту
|
||||
nbthread 1
|
||||
|
||||
# DNS Docker: имя сервиса api отвечает адресами всех работающих реплик.
|
||||
# Пропавший адрес уходит из слота, новый появляется за 1–2 с без
|
||||
# перезагрузки LB
|
||||
resolvers docker
|
||||
nameserver dns 127.0.0.11:53
|
||||
accepted_payload_size 8192
|
||||
resolve_retries 3
|
||||
timeout resolve 1s
|
||||
timeout retry 1s
|
||||
hold valid 1s
|
||||
hold obsolete 1s
|
||||
hold nx 1s
|
||||
hold other 1s
|
||||
hold refused 1s
|
||||
hold timeout 1s
|
||||
|
||||
defaults
|
||||
mode http
|
||||
log global
|
||||
option httplog
|
||||
# обычные успешные запросы не пишутся; ошибки, таймауты, повторы,
|
||||
# перенаправления и смена состояния реплик — пишутся
|
||||
option dontlog-normal
|
||||
# timeout connect × (retries + 1) = 0,5 × 3 = 1,5 с < 2 с таймаута
|
||||
# клиента tests/resilience.py: перенаправление успевает раньше
|
||||
timeout connect 500ms
|
||||
retries 2
|
||||
# каждый повтор — на другую реплику, а не на ту же
|
||||
option redispatch 1
|
||||
# повтор только если соединение не установлено: запрос до реплики не
|
||||
# дошёл, повтор безопасен для любого метода. Ответ, который реплика
|
||||
# уже начала, не повторяется: POST /users и POST /chats не
|
||||
# идемпотентны, отправку сообщения повторяет клиент с тем же ключом
|
||||
retry-on conn-failure
|
||||
# больше [database] request_timeout_seconds (6 с) и KDF входа
|
||||
timeout server 10s
|
||||
timeout client 30s
|
||||
timeout http-request 10s
|
||||
timeout http-keep-alive 10s
|
||||
# больше таймаута проверки внутри /health/ready (2 с); обнаружение
|
||||
# отказа ≈ inter × fall + timeout check = 1 × 2 + 3 = 5 с ≤ 10 с
|
||||
timeout check 3s
|
||||
# request_id ответов, которые создаёт сам LB
|
||||
unique-id-format lb-%{+X}o%ci%cp%Ts%rt%pid
|
||||
# ответы самого LB — в формате ошибки контракта; в перечислении кодов
|
||||
# контракта нет отдельных кодов для 502 и 504, ближайший — unavailable.
|
||||
# X-Instance-Id у них нет: контракт это допускает
|
||||
http-error status 502 content-type application/json lf-string '{"error":{"code":"unavailable","message":"API replica closed the connection","request_id":"%[unique-id]"}}' hdr X-Request-Id "%[unique-id]"
|
||||
http-error status 503 content-type application/json lf-string '{"error":{"code":"unavailable","message":"No API replica is available","request_id":"%[unique-id]"}}' hdr X-Request-Id "%[unique-id]"
|
||||
http-error status 504 content-type application/json lf-string '{"error":{"code":"unavailable","message":"API replica did not respond in time","request_id":"%[unique-id]"}}' hdr X-Request-Id "%[unique-id]"
|
||||
|
||||
# точка входа клиентов: на хосте — 127.0.0.1:APP_OUT_PORT (compose)
|
||||
frontend entry
|
||||
bind "*:${API_PORT}"
|
||||
default_backend api
|
||||
|
||||
backend api
|
||||
# по очереди, без cookie и stick-table: sticky session запрещён
|
||||
balance roundrobin
|
||||
# активная проверка готовности: /health/live для LB не годится,
|
||||
# живой процесс без PostgreSQL запросы не обслуживает
|
||||
option httpchk
|
||||
http-check send meth GET uri /health/ready
|
||||
http-check expect status 200
|
||||
# реплика исключается после 2 неудачных проверок подряд и
|
||||
# возвращается после 2 успешных; проверка раз в секунду
|
||||
default-server check inter 1s fall 2 rise 2 resolvers docker init-addr none resolve-prefer ipv4
|
||||
# 8 слотов — максимум реплик в сериях трека 1; лишние слоты в MAINT,
|
||||
# девятую реплику LB не увидит
|
||||
server-template api- 8 "api:${API_PORT}"
|
||||
|
||||
# мониторинг внутри сети compose, наружу не публикуется:
|
||||
# /lb/ready — healthcheck контейнера LB (200, пока есть готовая реплика),
|
||||
# /stats и /stats;csv — состояние и счётчики каждой реплики (make lb_stats)
|
||||
frontend monitor
|
||||
bind :8404
|
||||
monitor-uri /lb/ready
|
||||
monitor fail if { nbsrv(api) lt 1 }
|
||||
stats enable
|
||||
stats uri /stats
|
||||
# адрес реплики в статистике (поле addr): только внутри сети
|
||||
stats show-legends
|
||||
@@ -11,7 +11,7 @@ evidence, потом коммит evidence и отчёта (бриф основ
|
||||
|
||||
## 1. Балансировщик и compose
|
||||
|
||||
- [ ] 1.1 `infra/haproxy/haproxy.cfg` по решениям 1–5:
|
||||
- [x] 1.1 `infra/haproxy/haproxy.cfg` по решениям 1–5:
|
||||
- `resolvers docker`;
|
||||
- `frontend entry` на `"*:${API_PORT}"`;
|
||||
- `backend api` с `server-template api- 8`, проверками
|
||||
@@ -24,7 +24,7 @@ evidence, потом коммит evidence и отчёта (бриф основ
|
||||
|
||||
Проверка: `haproxy -c` в образе `haproxy:3.4.6-trixie@sha256:…`
|
||||
с `API_PORT=8080` — `Configuration file is valid`.
|
||||
- [ ] 1.2 `docker-compose.yml` по решению 6:
|
||||
- [x] 1.2 `docker-compose.yml` по решению 6:
|
||||
- сервис `haproxy`: пин тега и digest, конфиг только на чтение,
|
||||
порт `127.0.0.1:${APP_OUT_PORT}:${APP__PORT}`, healthcheck через
|
||||
`/lb/ready`, `depends_on: api`;
|
||||
@@ -40,7 +40,7 @@ evidence, потом коммит evidence и отчёта (бриф основ
|
||||
- в `docker compose config` у `haproxy` нет `PASSWORD`, у `migrate`
|
||||
нет `CACHE__`;
|
||||
- `grep -n container_name docker-compose.yml` пуст.
|
||||
- [ ] 1.3 Поднять стенд на новом compose: `make run_docker`. Volume
|
||||
- [x] 1.3 Поднять стенд на новом compose: `make run_docker`. Volume
|
||||
тот же, `make wipe_data` не нужен.
|
||||
|
||||
Проверка:
|
||||
@@ -53,12 +53,12 @@ evidence, потом коммит evidence и отчёта (бриф основ
|
||||
|
||||
## 2. Hook-скрипты и цели Makefile
|
||||
|
||||
- [ ] 2.1 `scripts/restart.sh` по решению 8: LB и все реплики, порядок
|
||||
- [x] 2.1 `scripts/restart.sh` по решению 8: LB и все реплики, порядок
|
||||
`docker.md`. Проверка:
|
||||
- `make test-persistence ACTION_SCRIPT=scripts/restart.sh` —
|
||||
`PASS`;
|
||||
- `StartedAt` LB, обеих реплик, Postgres и Valkey новые, ID те же.
|
||||
- [ ] 2.2 Новый `scripts/stop-one.sh` по решению 7 и образцу
|
||||
- [x] 2.2 Новый `scripts/stop-one.sh` по решению 7 и образцу
|
||||
`scripts/stop-one.example.sh`:
|
||||
- формат `TARGET_INSTANCE_ID`, поиск среди `docker compose ps -q
|
||||
api`;
|
||||
@@ -72,7 +72,7 @@ evidence, потом коммит evidence и отчёта (бриф основ
|
||||
- пустой, не-hex, ID Postgres / Valkey / LB, неизвестный ID —
|
||||
ненулевой код, ни один контейнер не остановлен;
|
||||
- после `kill` реплика через 15 с всё ещё `exited`.
|
||||
- [ ] 2.3 Свои цели `Makefile` по решению 9: `API_REPLICAS ?= 2`,
|
||||
- [x] 2.3 Свои цели `Makefile` по решению 9: `API_REPLICAS ?= 2`,
|
||||
`EXPECT_REPLICAS`, `replicas`, `instances`, `lb_stats`,
|
||||
`EXPECT_REPLICAS` у `student_test`. Цели skeleton не трогать.
|
||||
|
||||
@@ -85,16 +85,16 @@ evidence, потом коммит evidence и отчёта (бриф основ
|
||||
|
||||
## 3. Тесты реплик
|
||||
|
||||
- [ ] 3.1 `conftest.py` и `contract.py` по решению 10:
|
||||
- [x] 3.1 `conftest.py` и `contract.py` по решению 10:
|
||||
`EXPECT_REPLICAS`, фикстура `replicas` с пропуском и причиной,
|
||||
помощник `assert_replicas`. Проверка: `make lint`.
|
||||
- [ ] 3.2 Новый `test_load_balancing.py`: «Одна сессия на разных
|
||||
- [x] 3.2 Новый `test_load_balancing.py`: «Одна сессия на разных
|
||||
репликах», «Запись видна через другую реплику». Сценарии — в
|
||||
докстрингах, не маркерами. Проверка:
|
||||
- против LB (`make student_test`) оба проходят, печатают увиденные
|
||||
`X-Instance-Id`;
|
||||
- с `EXPECT_REPLICAS=1` — `SKIPPED` с причиной.
|
||||
- [ ] 3.3 `test_idempotency.py` «Повтор через другую реплику» и
|
||||
- [x] 3.3 `test_idempotency.py` «Повтор через другую реплику» и
|
||||
`test_race.py` «Гонка одного ключа через реплики», маркеры `spec`
|
||||
`idempotency` (решение 10). Докстринг прежней «Гонки одного ключа»
|
||||
— без ссылки на будущий change.
|
||||
@@ -106,10 +106,10 @@ evidence, потом коммит evidence и отчёта (бриф основ
|
||||
временно `balance first` в конфиге LB (весь трафик на первую
|
||||
реплику) — тест гонки и тест повтора падают с числом увиденных
|
||||
реплик. Конфиг вернуть, LB перезапустить.
|
||||
- [ ] 3.4 «Одно значение на процесс» в `test_api_conventions.py` по
|
||||
- [x] 3.4 «Одно значение на процесс» в `test_api_conventions.py` по
|
||||
решению 10. Проверка: проходит против LB и против одного процесса
|
||||
(`make test_isolated`).
|
||||
- [ ] 3.5 `/opsx:sync`, как в change `instance-id-idempotency`:
|
||||
- [x] 3.5 `/opsx:sync`, как в change `instance-id-idempotency`:
|
||||
сверка покрытия читает основные спеки, и без sync маркеры новых
|
||||
сценариев `idempotency` указывали бы на неизвестные сценарии.
|
||||
Archive потом выполняется с «Sync anyway». Проверка:
|
||||
@@ -121,18 +121,18 @@ evidence, потом коммит evidence и отчёта (бриф основ
|
||||
|
||||
## 4. Свои стенды и скилл
|
||||
|
||||
- [ ] 4.1 `student-tests/run_isolated.py`: `EXPECT_REPLICAS=1` у `make
|
||||
- [x] 4.1 `student-tests/run_isolated.py`: `EXPECT_REPLICAS=1` у `make
|
||||
student_test`. `student-tests/failures.compose.yml`: сброс портов
|
||||
`haproxy`, без `api` (решение 12). Проверка:
|
||||
- `make test_isolated` — код 0, тесты реплик `SKIPPED` с причиной;
|
||||
- `make failure_checks` — код 0, рабочий стенд не тронут
|
||||
(`StartedAt` LB и реплик прежние).
|
||||
- [ ] 4.2 `bench/bench.compose.yml` по решению 12: одна реплика,
|
||||
- [x] 4.2 `bench/bench.compose.yml` по решению 12: одна реплика,
|
||||
лимиты в форме `deploy.resources.limits`. Проверка:
|
||||
- `make bench_quick` и `make bench_restore_quick` — код 0;
|
||||
- в паспорте те же лимиты API, Postgres и Valkey, что в прежней
|
||||
метке `quick-*`.
|
||||
- [ ] 4.3 Скилл `run-mtusi-messenger` по решению 11: `instances` и
|
||||
- [x] 4.3 Скилл `run-mtusi-messenger` по решению 11: `instances` и
|
||||
`EXPECT_REPLICAS=1` в `driver.py`, `SKILL.md`. Проверка:
|
||||
- `python3 .claude/skills/run-mtusi-messenger/driver.py all` — код
|
||||
0, тесты реплик пропущены с причиной;
|
||||
@@ -141,7 +141,7 @@ evidence, потом коммит evidence и отчёта (бриф основ
|
||||
|
||||
## 5. Документы и общая проверка
|
||||
|
||||
- [ ] 5.1 Правила и инструкции под решения:
|
||||
- [x] 5.1 Правила и инструкции под решения:
|
||||
- `balancer.md`: цепочка таймаутов (`timeout check` 3 с,
|
||||
`timeout connect` 500 мс, `redispatch 1`), `STOP_ONE_LOG`,
|
||||
`make replicas` / `lb_stats` / `instances`, ответы LB в формате
|
||||
|
||||
@@ -81,8 +81,13 @@ Unicode code points.
|
||||
|
||||
#### Scenario: Одно значение на процесс
|
||||
|
||||
- **WHEN** клиент выполняет серию разных запросов к одному процессу API
|
||||
- **THEN** все ответы содержат одно и то же значение `X-Instance-Id`
|
||||
- **WHEN** клиент дважды подряд выполняет одну и ту же серию разных
|
||||
запросов — к одному процессу API или через балансировщик к
|
||||
нескольким репликам
|
||||
- **THEN** против одного процесса все ответы содержат одно значение
|
||||
`X-Instance-Id`; через балансировщик каждое значение встречается
|
||||
больше чем в одном ответе, а во второй серии нет значений, которых не
|
||||
было в первой
|
||||
|
||||
### Requirement: Единый формат ошибки
|
||||
|
||||
|
||||
@@ -12,25 +12,37 @@ Valkey, одноразовыми миграциями и API (`make run_docker`)
|
||||
### Requirement: Запуск через compose
|
||||
|
||||
`make run_docker` SHALL собирать образ и поднимать стенд через
|
||||
`docker compose`: PostgreSQL, Valkey, одноразовый сервис миграций и API.
|
||||
API SHALL стартовать после готовности PostgreSQL и Valkey и успешных
|
||||
миграций. Перед этим цель SHALL создавать недостающие `.env` и
|
||||
`config.toml` из шаблонов (`make env_setup`) и MUST NOT перезаписывать
|
||||
существующие. `make stop` SHALL останавливать сервисы, `make down` —
|
||||
удалять контейнеры, сохраняя volume, `make logs` — показывать журнал API.
|
||||
`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** сервис отвечает на `http://localhost:8080/health/ready`, и
|
||||
- **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;
|
||||
- внешний порт API — `APP_OUT_PORT`: порт на `127.0.0.1` хоста,
|
||||
формате настроек. Его слушает каждая реплика, на нём работают
|
||||
healthcheck и проверки LB, на нём же LB принимает запросы внутри
|
||||
своего контейнера;
|
||||
- внешний порт стенда — `APP_OUT_PORT`: порт LB на `127.0.0.1` хоста,
|
||||
приложение его не читает;
|
||||
- порт PostgreSQL внутри сети compose — `POSTGRES_PORT`, его слушает
|
||||
сам сервер и использует API в docker;
|
||||
@@ -49,14 +61,15 @@ NOT быть записаны в compose литералами.
|
||||
|
||||
- **WHEN** в `.env` задано `APP_OUT_PORT=8090`, и выполнен
|
||||
`make run_docker`
|
||||
- **THEN** API доступно на `localhost:8090`, а внутри контейнера
|
||||
сервис слушает `APP__PORT`
|
||||
- **THEN** API доступно через LB на `localhost:8090`, а внутри
|
||||
контейнеров реплики слушают `APP__PORT`
|
||||
|
||||
#### Scenario: Другой внутренний порт
|
||||
|
||||
- **WHEN** в `.env` задано `APP__PORT=9090`
|
||||
- **THEN** сервис внутри контейнера слушает 9090, контейнер становится
|
||||
`healthy`, а API доступно на `localhost:$APP_OUT_PORT`
|
||||
- **THEN** реплики внутри контейнеров слушают 9090 и становятся
|
||||
`healthy`, LB проверяет их на 9090, а API доступно на
|
||||
`localhost:$APP_OUT_PORT`
|
||||
|
||||
#### Scenario: Другой порт Postgres
|
||||
|
||||
@@ -89,15 +102,18 @@ NOT быть записаны в compose литералами.
|
||||
|
||||
### Requirement: Публикация только на localhost
|
||||
|
||||
Порты API, PostgreSQL и Valkey SHALL публиковаться в compose только на
|
||||
Порты LB, PostgreSQL и Valkey SHALL публиковаться в compose только на
|
||||
`127.0.0.1` хоста. Адрес публикации SHALL быть записан литералом, а не
|
||||
переменной. Учебный стенд MUST NOT быть доступен с других машин сети.
|
||||
переменной. Реплики API MUST NOT публиковать порты на хосте: к ним
|
||||
ходят только LB и контейнеры сети compose. Учебный стенд MUST NOT быть
|
||||
доступен с других машин сети.
|
||||
|
||||
#### Scenario: Адрес публикации
|
||||
|
||||
- **WHEN** для запущенных контейнеров API, Postgres и Valkey выполняется
|
||||
`docker port`
|
||||
- **THEN** порты опубликованы на `127.0.0.1`, а не на `0.0.0.0`
|
||||
- **WHEN** для запущенных контейнеров LB, API, Postgres и Valkey
|
||||
выполняется `docker port`
|
||||
- **THEN** порты LB, Postgres и Valkey опубликованы на `127.0.0.1`, а
|
||||
не на `0.0.0.0`, а у контейнеров API опубликованных портов нет
|
||||
|
||||
### Requirement: Конфигурация на старте
|
||||
|
||||
@@ -129,21 +145,23 @@ compose, и приложению, SHALL передаваться через `env
|
||||
### Requirement: Данные переживают рестарт стенда
|
||||
|
||||
Данные PostgreSQL SHALL храниться в именованном volume. Скрипт
|
||||
`scripts/restart.sh` SHALL перезапускать API и все используемые
|
||||
хранилища — PostgreSQL и Valkey, — сохраняя volume, схему и данные: без
|
||||
удаления volume, очистки и повторного наполнения. Скрипт SHALL быть
|
||||
исполняемым, завершаться с кодом 0 только после перезапуска,
|
||||
укладываться в 90 с и MUST NOT печатать секреты. Публичная проверка
|
||||
`make test-persistence ACTION_SCRIPT=scripts/restart.sh` SHALL
|
||||
проходить.
|
||||
`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** контейнеры API, Postgres и Valkey перезапущены (новое время
|
||||
старта в `docker inspect`), а после готовности запрос с прежним
|
||||
токеном получает 200 и видит своё сообщение
|
||||
- **THEN** контейнеры LB, всех реплик API, Postgres и Valkey
|
||||
перезапущены: те же ID и новое время старта в `docker inspect`. После
|
||||
готовности запрос с прежним токеном через LB получает 200 и видит
|
||||
своё сообщение
|
||||
|
||||
#### Scenario: Публичная проверка сохранности
|
||||
|
||||
@@ -194,3 +212,29 @@ MUST NOT затрагивать ресурсы проектов прошлых
|
||||
- **THEN** стенд создаёт и затем удаляет только
|
||||
`mtusi-lab3_postgres_data`, а `mtusi-lab2_postgres_data` остаётся с
|
||||
прежней датой создания
|
||||
|
||||
### 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
|
||||
|
||||
@@ -161,6 +161,15 @@ SHALL быть 201 с одним и тем же `Message`.
|
||||
- **THEN** все ответы 201 с одинаковым `id`, а в истории чата ровно
|
||||
одно такое сообщение
|
||||
|
||||
#### Scenario: Гонка одного ключа через реплики
|
||||
|
||||
- **WHEN** 10 клиентов по отдельным соединениям одновременно
|
||||
отправляют одно тело с одним ключом через балансировщик, и среди
|
||||
ответов есть два пересекающихся по времени запроса, которые
|
||||
обслужили реплики с разными `X-Instance-Id`
|
||||
- **THEN** все ответы 201 с одинаковым `Message`, а в истории чата
|
||||
ровно одно такое сообщение
|
||||
|
||||
### Requirement: Ключ фиксируется только вместе с сообщением
|
||||
|
||||
Ключ SHALL сохраняться только вместе с сообщением, в одной транзакции.
|
||||
@@ -213,3 +222,11 @@ MUST NOT занимать ключ: повтор с тем же ключом SHA
|
||||
- **WHEN** сообщение отправлено с ключом K, и процесс API
|
||||
перезапущен
|
||||
- **THEN** повтор с K и тем же телом даёт 201 с тем же `Message`
|
||||
|
||||
#### Scenario: Повтор через другую реплику
|
||||
|
||||
- **WHEN** сообщение отправлено с ключом K через балансировщик, а
|
||||
повтор с K и тем же телом обслужила реплика с другим
|
||||
`X-Instance-Id`
|
||||
- **THEN** повтор даёт 201 с тем же `Message`, а другое тело с K на
|
||||
любой реплике — 409
|
||||
|
||||
@@ -0,0 +1,229 @@
|
||||
# load-balancing Specification
|
||||
|
||||
## Purpose
|
||||
|
||||
Работа API за балансировщиком: одна точка входа, несколько
|
||||
взаимозаменяемых реплик без привязки клиента, проверка их готовности,
|
||||
безопасные повторы и сохранение чтения и записи при отказе любой одной
|
||||
реплики.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Единая точка входа
|
||||
|
||||
Стенд SHALL принимать запросы клиентов в одной точке — балансировщике
|
||||
(LB), опубликованном на `127.0.0.1:${APP_OUT_PORT}`. Реплики API MUST
|
||||
NOT публиковать порты на хосте и MUST NOT иметь фиксированного имени
|
||||
контейнера. Ответы реплик SHALL проходить через LB без замены
|
||||
заголовков `X-Request-Id` и `X-Instance-Id` и тела.
|
||||
|
||||
#### Scenario: Порт только у балансировщика
|
||||
|
||||
- **WHEN** стенд запущен `make run_docker`, и выполнен
|
||||
`docker compose ps`
|
||||
- **THEN** у контейнеров `api` нет опубликованных портов, у них нет
|
||||
заданного `container_name`, а API на хосте доступно только через
|
||||
порт LB на `127.0.0.1`
|
||||
|
||||
### Requirement: Взаимозаменяемые реплики
|
||||
|
||||
Сервис API SHALL запускаться в числе реплик `API_REPLICAS`, по
|
||||
умолчанию 2. Это значение читает только compose. Реплики SHALL быть
|
||||
одинаковыми: один образ, одна конфигурация, общие PostgreSQL и Valkey.
|
||||
В памяти процесса MUST NOT быть состояния, от которого зависит
|
||||
корректность ответа. Изменение числа реплик MUST NOT требовать правки
|
||||
конфигурации LB. LB SHALL обслуживать до 8 реплик.
|
||||
|
||||
#### Scenario: Две реплики по умолчанию
|
||||
|
||||
- **WHEN** выполнен `make run_docker` без `API_REPLICAS` в `.env`
|
||||
- **THEN** работают два контейнера `api` с разными `X-Instance-Id`, и
|
||||
оба получают запросы через LB
|
||||
|
||||
#### Scenario: Масштабирование без правки балансировщика
|
||||
|
||||
- **WHEN** выполнен `make replicas API_REPLICAS=3`, а конфигурация LB
|
||||
не менялась
|
||||
- **THEN** не позже чем через 10 с запросы через LB обслуживают три
|
||||
разных `X-Instance-Id`
|
||||
|
||||
### Requirement: Распределение без привязки клиента
|
||||
|
||||
LB SHALL распределять запросы по готовым репликам по очереди, независимо
|
||||
от соединения, сессии и cookie клиента. Привязка клиента к реплике
|
||||
(sticky session) MUST NOT использоваться. Запросы одной сессии SHALL
|
||||
обслуживаться разными репликами без повторного входа. Подтверждённое
|
||||
сообщение SHALL быть видно следующему чтению через любую реплику.
|
||||
|
||||
#### Scenario: Одна сессия на разных репликах
|
||||
|
||||
- **WHEN** пользователь вошёл один раз и выполняет 20 запросов
|
||||
`GET /api/v1/users/me` с одним токеном через LB
|
||||
- **THEN** все ответы 200 с этим пользователем, а `X-Instance-Id`
|
||||
принимает не меньше двух разных значений
|
||||
|
||||
#### Scenario: Запись видна через другую реплику
|
||||
|
||||
- **WHEN** сообщение отправлено через LB, затем история чата
|
||||
читается несколько раз подряд
|
||||
- **THEN** каждое чтение содержит это сообщение, в том числе чтения
|
||||
с другим `X-Instance-Id`, чем у отправки
|
||||
|
||||
#### Scenario: Распределение видно оператору
|
||||
|
||||
- **WHEN** выполнен `make instances`
|
||||
- **THEN** команда входит одним синтетическим пользователем, выполняет
|
||||
серию запросов с одним токеном и печатает `X-Instance-Id` каждого
|
||||
ответа и число ответов каждой реплики
|
||||
|
||||
### Requirement: Проверка готовности реплик
|
||||
|
||||
LB SHALL активно проверять каждую реплику запросом
|
||||
`GET /health/ready`. Период, число неудач до исключения, число
|
||||
успехов до возврата и таймаут проверки SHALL быть заданы явно.
|
||||
Реплика, которая не проходит проверки, SHALL исключаться из
|
||||
распределения: она остановлена, не отвечает или отвечает 503. Вернувшаяся
|
||||
реплика SHALL включаться без перезапуска LB. Время обнаружения отказа
|
||||
по проверкам MUST NOT превышать 10 с. Таймаут проверки внутри
|
||||
`/health/ready` SHALL быть меньше таймаута проверки LB.
|
||||
|
||||
#### Scenario: Остановленная реплика исключена
|
||||
|
||||
- **WHEN** одна из двух реплик остановлена
|
||||
- **THEN** не позже чем через 10 с статистика LB показывает её не в
|
||||
состоянии `UP`, и запросы через LB обслуживает только оставшаяся
|
||||
|
||||
#### Scenario: Вернувшаяся реплика включена
|
||||
|
||||
- **WHEN** остановленная реплика запущена снова
|
||||
- **THEN** не позже чем через 10 с после её готовности статистика LB
|
||||
показывает её `UP`, и запросы снова распределяются по обеим
|
||||
|
||||
### Requirement: Повтор только при отказе соединения
|
||||
|
||||
LB SHALL повторять запрос на другой реплике, только если соединение с
|
||||
репликой не установлено, то есть запрос до неё не дошёл. Такой повтор
|
||||
безопасен для любого метода. Запрос, который реплика уже получила, MUST
|
||||
NOT повторяться LB: ни по таймауту ответа, ни по обрыву ответа, ни по
|
||||
ответу 5xx. Причина — `POST /users` и `POST /chats` не идемпотентны.
|
||||
Отправку сообщения повторяет клиент, с тем же `Idempotency-Key`.
|
||||
Произведение таймаута соединения LB на число попыток SHALL быть меньше
|
||||
2 с: перенаправление должно успеть раньше таймаута клиента публичной
|
||||
проверки.
|
||||
|
||||
#### Scenario: Отказ соединения перенаправлен
|
||||
|
||||
- **WHEN** реплика закрыла приёмный сокет (`docker stop`), а LB ещё
|
||||
не исключил её по проверкам
|
||||
- **THEN** запрос, направленный на неё, LB передаёт другой реплике, и
|
||||
клиент получает ответ API, а не ошибку LB
|
||||
|
||||
#### Scenario: Оборванный ответ не повторяется
|
||||
|
||||
- **WHEN** процесс реплики убит (`docker kill`), пока она обрабатывает
|
||||
запрос
|
||||
- **THEN** клиент получает ошибку LB, а журнал LB показывает, что
|
||||
запрос на другую реплику не повторялся
|
||||
|
||||
### Requirement: Ошибки балансировщика в формате контракта
|
||||
|
||||
Ответы, которые создаёт сам LB, SHALL иметь статус 502, 503 или 504 и
|
||||
тело в формате ошибки контракта с `code` `unavailable`. Такие ответы
|
||||
возникают, когда нет готовых реплик, ответ реплики оборвался или не
|
||||
пришёл вовремя. `request_id` тела SHALL совпадать с заголовком
|
||||
`X-Request-Id`, который ставит LB. `X-Instance-Id` у таких ответов
|
||||
может отсутствовать.
|
||||
|
||||
#### Scenario: Нет готовых реплик
|
||||
|
||||
- **WHEN** все реплики API остановлены, и клиент запрашивает
|
||||
`/health/ready` через LB
|
||||
- **THEN** ответ 503 с телом `{"error": {"code": "unavailable", ...}}`,
|
||||
`request_id` равен `X-Request-Id`, а других полей в теле нет
|
||||
|
||||
### Requirement: Отказ одной реплики
|
||||
|
||||
При остановке любой одной реплики из двух и более новые чтения и
|
||||
записи через LB SHALL проходить снова не позже чем через 10 с от
|
||||
начала остановки. Подтверждённые сообщения SHALL оставаться
|
||||
доступными. Повтор неподтверждённой отправки с тем же ключом MUST NOT
|
||||
создавать дубль. Ошибки переходного периода допустимы и SHALL
|
||||
учитываться. Публичная проверка `make test-failover
|
||||
ACTION_SCRIPT=scripts/stop-one.sh` SHALL проходить для каждой реплики,
|
||||
если предыдущая перед этим восстановлена.
|
||||
|
||||
#### Scenario: Штатная остановка каждой реплики
|
||||
|
||||
- **WHEN** `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`
|
||||
выполнен, затем реплики восстановлены, и проверка повторена так,
|
||||
чтобы остановленной оказалась другая реплика
|
||||
- **THEN** оба прогона печатают `PASS`, первая успешная запись после
|
||||
начала остановки — не позже 10 с, дублей нет
|
||||
|
||||
#### Scenario: Отказ процесса без graceful
|
||||
|
||||
- **WHEN** та же проверка выполнена с `STOP_MODE=kill`
|
||||
- **THEN** она печатает `PASS`: оборванные запросы учтены как
|
||||
неудачные попытки, повтор с тем же ключом не создаёт дубль
|
||||
|
||||
### Requirement: Failover hook
|
||||
|
||||
`scripts/stop-one.sh` SHALL останавливать ровно одну работающую
|
||||
реплику API этого проекта compose — ту, чей контейнер соответствует
|
||||
`TARGET_INSTANCE_ID` (значению `X-Instance-Id`). Скрипт SHALL
|
||||
возвращать 0 не позже чем через 10 с. Режим задаёт `STOP_MODE`:
|
||||
`stop` (по умолчанию, SIGTERM и graceful) или `kill` (SIGKILL).
|
||||
|
||||
Остановленная реплика SHALL оставаться остановленной, несмотря на
|
||||
политику перезапуска контейнера. Восстановление — отдельной командой
|
||||
`make replicas`.
|
||||
|
||||
Если значение не соответствует ни одной работающей реплике API этого
|
||||
проекта, скрипт SHALL завершаться с ненулевым кодом и ничего не
|
||||
останавливать. PostgreSQL, Valkey, LB, контейнеры других проектов и
|
||||
volumes скрипт MUST NOT трогать. Секреты он MUST NOT печатать.
|
||||
|
||||
#### Scenario: Остановка по instance id
|
||||
|
||||
- **WHEN** `scripts/stop-one.sh` выполнен с `TARGET_INSTANCE_ID`,
|
||||
равным `X-Instance-Id` одной из реплик
|
||||
- **THEN** скрипт вернул 0 быстрее 10 с, `docker compose ps -a`
|
||||
показывает остановленным контейнер, ID которого начинается с
|
||||
`TARGET_INSTANCE_ID`, а остальные контейнеры стенда работают с
|
||||
прежним временем старта
|
||||
|
||||
#### Scenario: Чужой или неизвестный id
|
||||
|
||||
- **WHEN** `TARGET_INSTANCE_ID` пуст, имеет недопустимый формат,
|
||||
указывает на контейнер PostgreSQL, Valkey или LB этого стенда либо не
|
||||
соответствует ни одному контейнеру
|
||||
- **THEN** скрипт завершается с ненулевым кодом, и ни один контейнер
|
||||
не остановлен
|
||||
|
||||
#### Scenario: Реплика не поднимается сама
|
||||
|
||||
- **WHEN** реплика остановлена скриптом в режиме `stop` или `kill`,
|
||||
и прошло 15 с
|
||||
- **THEN** контейнер всё ещё остановлен, и его `X-Instance-Id` не
|
||||
встречается в ответах через LB
|
||||
|
||||
#### Scenario: Восстановление реплик
|
||||
|
||||
- **WHEN** после остановки реплики выполнен `make replicas`
|
||||
- **THEN** работают `API_REPLICAS` реплик, остановленный контейнер
|
||||
запущен снова с тем же ID, и не позже чем через 10 с LB снова
|
||||
распределяет запросы по всем репликам
|
||||
|
||||
### Requirement: Статистика балансировщика внутри сети
|
||||
|
||||
LB SHALL отдавать статистику по каждой реплике: состояние проверки,
|
||||
число запросов, повторы, очередь. Статистика SHALL быть доступна только
|
||||
внутри сети compose; на хост она MUST NOT публиковаться. Оператор SHALL
|
||||
получать её одной командой `make lb_stats`.
|
||||
|
||||
#### Scenario: Состояние реплик
|
||||
|
||||
- **WHEN** стенд запущен, и выполнен `make lb_stats`
|
||||
- **THEN** команда печатает по строке на каждый занятый слот реплики с
|
||||
её адресом и состоянием проверки, а порт статистики не опубликован на
|
||||
хосте
|
||||
@@ -153,6 +153,47 @@ MUST завершаться ошибкой с указанием этой ком
|
||||
- **THEN** все ответы 201 с одним `id`, а в истории ровно одно такое
|
||||
сообщение
|
||||
|
||||
### Requirement: Тесты реплик через балансировщик
|
||||
|
||||
Набор SHALL содержать тесты, которым нужны две и больше реплики за
|
||||
`BASE_URL`:
|
||||
- распределение одной сессии по репликам и чтение записи через другую
|
||||
реплику (capability `load-balancing`);
|
||||
- повтор с тем же ключом через другую реплику и гонка одного ключа с
|
||||
ответами разных реплик, пересекающимися по времени (capability
|
||||
`idempotency`).
|
||||
|
||||
Сколько реплик ожидается за `BASE_URL`, набор SHALL узнавать из
|
||||
переменной `EXPECT_REPLICAS`, а не угадывать по ответам. `make
|
||||
student_test` SHALL брать её из `API_REPLICAS` (по умолчанию 2), `make
|
||||
test_isolated` и прогон драйвера против своего процесса в консоли SHALL
|
||||
передавать 1. При `EXPECT_REPLICAS` = 1 тесты реплик SHALL
|
||||
пропускаться с причиной, которая называет режим одного процесса. Они
|
||||
MUST NOT считаться пройденными. При `EXPECT_REPLICAS` ≥ 2 тест SHALL
|
||||
падать, если ответы дали меньше двух разных `X-Instance-Id`, и
|
||||
сообщение SHALL называть число увиденных значений.
|
||||
|
||||
#### Scenario: Против стенда с балансировщиком
|
||||
|
||||
- **WHEN** стенд запущен `make run_docker`, и выполнен `make
|
||||
student_test`
|
||||
- **THEN** тесты реплик выполняются и проходят, а их вывод показывает
|
||||
увиденные `X-Instance-Id`
|
||||
|
||||
#### Scenario: Против одного процесса
|
||||
|
||||
- **WHEN** выполнен `make test_isolated` или `make student_test
|
||||
EXPECT_REPLICAS=1` против одного процесса API
|
||||
- **THEN** тесты реплик помечены пропущенными с причиной «один
|
||||
процесс», остальные тесты проходят, и код выхода 0
|
||||
|
||||
#### Scenario: Реплик меньше ожидаемого
|
||||
|
||||
- **WHEN** `make student_test` с `EXPECT_REPLICAS=2` запущен против
|
||||
одного процесса API
|
||||
- **THEN** тесты реплик падают с сообщением, что увидено одно значение
|
||||
`X-Instance-Id`, а не пропускаются
|
||||
|
||||
### Requirement: Покрытие сценариев основных спеков
|
||||
|
||||
Для каждого сценария основных спеков `api-conventions`,
|
||||
@@ -195,11 +236,13 @@ student_test` этот тест не выполняет; итог сверки S
|
||||
|
||||
### Requirement: Результат прогона сохраняется
|
||||
|
||||
Вывод прогона против контейнера (`make test_isolated`) и вывод `make
|
||||
Вывод прогона против контейнера (`make test_isolated`), вывод `make
|
||||
student_test` против стенда с балансировщиком и вывод `make
|
||||
failure_checks` SHALL сохраняться в `evidence/` с командой, датой,
|
||||
commit, адресом стенда и итогом. `REPORT.md` SHALL ссылаться на них в
|
||||
строках уровня «4»: собственные тесты, 100 сообщений от 10 клиентов и
|
||||
автоматические проверки истечения сессии и недоступности БД и Valkey.
|
||||
строках уровня «4»: собственные тесты, 100 сообщений от 10 клиентов,
|
||||
гонка одного ключа через реплики и автоматические проверки истечения
|
||||
сессии и недоступности БД и Valkey.
|
||||
|
||||
#### Scenario: Доказательство в отчёте
|
||||
|
||||
@@ -218,19 +261,22 @@ Valkey, собрать образ, создать базу заново, при
|
||||
опубликовать его на `127.0.0.1:TEST_APP_PORT` из `.env`, дождаться
|
||||
готовности, выполнить публичный smoke (`make test`) и весь набор
|
||||
(`make student_test`) против этого контейнера, затем остановить и
|
||||
удалить контейнер и удалить базу. Код выхода SHALL быть ненулевым, если
|
||||
не прошёл smoke, набор или уборка. Рабочая база и рабочий контейнер API
|
||||
MUST NOT затрагиваться, а карточки чатов тестового прогона в Valkey
|
||||
отделены от рабочих именем базы в ключе (capability `chat-cache`).
|
||||
Параллельный запуск двух прогонов не поддерживается.
|
||||
удалить контейнер и удалить базу. Это один процесс API без
|
||||
балансировщика: набор SHALL запускаться с `EXPECT_REPLICAS=1`, и тесты
|
||||
реплик пропускаются с причиной. Код выхода SHALL быть ненулевым, если
|
||||
не прошёл smoke, набор или уборка. Рабочая база и рабочие контейнеры
|
||||
стенда MUST NOT затрагиваться, а карточки чатов тестового прогона в
|
||||
Valkey отделены от рабочих именем базы в ключе (capability
|
||||
`chat-cache`). Параллельный запуск двух прогонов не поддерживается.
|
||||
|
||||
#### Scenario: Успешный прогон
|
||||
|
||||
- **WHEN** в рабочей базе есть данные, рабочий стенд запущен, и
|
||||
выполнен `make test_isolated`
|
||||
- **THEN** smoke и набор прошли, код выхода 0, ни базы `test_<db>`, ни
|
||||
тестового контейнера после команды нет, число строк в таблицах
|
||||
рабочей базы не изменилось, а рабочий API продолжает отвечать
|
||||
- **THEN** smoke и набор прошли, тесты реплик пропущены с причиной,
|
||||
код выхода 0, ни базы `test_<db>`, ни тестового контейнера после
|
||||
команды нет, число строк в таблицах рабочей базы не изменилось, а
|
||||
рабочий стенд продолжает отвечать через балансировщик
|
||||
|
||||
#### Scenario: Упавшие тесты
|
||||
|
||||
|
||||
+3
-2
@@ -70,8 +70,9 @@ testpaths = ["student-tests"]
|
||||
# каталог с дефисом не пакет: хелперы импортируются как модули
|
||||
pythonpath = ["student-tests"]
|
||||
# проверки отказов (маркер fault) — только make failure_checks: там
|
||||
# pytest -m fault перекрывает этот -m
|
||||
addopts = "-v -rP --strict-markers -m 'not fault'"
|
||||
# pytest -m fault перекрывает этот -m. -rsP: вывод прошедших тестов и
|
||||
# причины пропуска (тесты реплик против одного процесса)
|
||||
addopts = "-v -rsP --strict-markers -m 'not fault'"
|
||||
markers = [
|
||||
"spec(capability, scenario): сценарий основного спека, который проверяет тест",
|
||||
"fault: проверка отказа хранилища; нужен стенд make failure_checks и его hook",
|
||||
|
||||
+11
-8
@@ -2,16 +2,19 @@
|
||||
set -eu
|
||||
# Restart hook для make test-persistence (tests/README.md) по образцу
|
||||
# scripts/restart.example.sh; правила — .claude/rules/docker.md.
|
||||
# Перезапускает API и все хранилища стенда (на лабе 2 — Postgres и
|
||||
# Valkey) с сохранением volume, схемы и данных: без down -v, FLUSHALL и
|
||||
# повторного наполнения. Кэш Valkey после рестарта пуст: persistence у
|
||||
# него выключен, данные — в Postgres. start api запускает и его
|
||||
# зависимость migrate: повторный прогон миграций ничего не меняет.
|
||||
# Готовность API ждёт сам тест. Секреты не печатает.
|
||||
# Перезапускает балансировщик, все реплики API и все хранилища стенда
|
||||
# (Postgres и Valkey) с сохранением volume, схемы и данных: без down -v,
|
||||
# FLUSHALL и повторного наполнения. Кэш Valkey после рестарта пуст:
|
||||
# persistence у него выключен, данные — в Postgres.
|
||||
# LB гасится первым и поднимается последним. start поднимает те же
|
||||
# контейнеры всех реплик: число реплик не меняется (реплика, остановленная
|
||||
# stop-one.sh, тоже запускается). start api запускает и его зависимость
|
||||
# migrate: повторный прогон миграций ничего не меняет.
|
||||
# Готовность через LB ждёт сам тест. Секреты не печатает.
|
||||
cd "$(dirname "$0")/.."
|
||||
|
||||
docker compose stop api
|
||||
docker compose stop haproxy api
|
||||
docker compose restart postgres valkey
|
||||
# те же контейнеры: --wait только дожидается их healthcheck
|
||||
docker compose up -d --wait postgres valkey
|
||||
docker compose start api
|
||||
docker compose start api haproxy
|
||||
|
||||
Executable
+73
@@ -0,0 +1,73 @@
|
||||
#!/bin/sh
|
||||
set -eu
|
||||
# Failover hook для make test-failover (tests/README.md) по образцу
|
||||
# scripts/stop-one.example.sh; правила — .claude/rules/balancer.md,
|
||||
# решения — design change replicas-lb, решение 7.
|
||||
# TARGET_INSTANCE_ID — X-Instance-Id реплики, то есть начало ID её
|
||||
# контейнера (hostname в compose). Скрипт останавливает ровно одну
|
||||
# работающую реплику сервиса api этого проекта и оставляет её
|
||||
# остановленной: restart: unless-stopped не поднимает контейнер ни после
|
||||
# docker stop, ни после docker kill. Postgres, Valkey, LB, чужие контейнеры
|
||||
# и volumes не трогает. Восстановление — make replicas.
|
||||
# STOP_MODE=stop (по умолчанию) — docker stop: SIGTERM и graceful;
|
||||
# STOP_MODE=kill — docker kill: SIGKILL, отказ процесса без graceful;
|
||||
# STOP_ONE_LOG=<файл> — дописать строку «время, TARGET_INSTANCE_ID,
|
||||
# полный ID контейнера, режим» (доказательство: тест скрывает вывод hook).
|
||||
# Секретов и окружения не печатает.
|
||||
: "${TARGET_INSTANCE_ID:?test provides target API instance alias}"
|
||||
mode="${STOP_MODE:-stop}"
|
||||
|
||||
case "$mode" in
|
||||
stop | kill) ;;
|
||||
*)
|
||||
echo "stop-one: STOP_MODE must be stop or kill" >&2
|
||||
exit 2
|
||||
;;
|
||||
esac
|
||||
|
||||
# hostname контейнера — его ID в hex, от 12 символов
|
||||
case "$TARGET_INSTANCE_ID" in
|
||||
*[!0-9a-f]*)
|
||||
echo "stop-one: TARGET_INSTANCE_ID is not a container id" >&2
|
||||
exit 2
|
||||
;;
|
||||
esac
|
||||
if [ "${#TARGET_INSTANCE_ID}" -lt 12 ] || [ "${#TARGET_INSTANCE_ID}" -gt 64 ]; then
|
||||
echo "stop-one: TARGET_INSTANCE_ID is not a container id" >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
cd "$(dirname "$0")/.."
|
||||
|
||||
# только работающие реплики сервиса api этого проекта, полные ID
|
||||
match=""
|
||||
for id in $(docker compose ps -q --no-trunc api); do
|
||||
case "$id" in
|
||||
"$TARGET_INSTANCE_ID"*)
|
||||
if [ -n "$match" ]; then
|
||||
echo "stop-one: TARGET_INSTANCE_ID matches several replicas" >&2
|
||||
exit 3
|
||||
fi
|
||||
match="$id"
|
||||
;;
|
||||
esac
|
||||
done
|
||||
if [ -z "$match" ]; then
|
||||
echo "stop-one: no running api replica of this project matches TARGET_INSTANCE_ID" >&2
|
||||
exit 3
|
||||
fi
|
||||
|
||||
if [ "$mode" = stop ]; then
|
||||
# uvicorn завершается сам не позже 8 с (graceful_shutdown_seconds);
|
||||
# 9 с гарантируют возврат hook раньше 10 с и для зависшего процесса
|
||||
docker stop --timeout 9 "$match" >/dev/null
|
||||
else
|
||||
docker kill "$match" >/dev/null
|
||||
fi
|
||||
|
||||
if [ -n "${STOP_ONE_LOG:-}" ]; then
|
||||
printf '%s TARGET_INSTANCE_ID=%s container=%s mode=%s\n' \
|
||||
"$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$TARGET_INSTANCE_ID" "$match" "$mode" \
|
||||
>>"$STOP_ONE_LOG"
|
||||
fi
|
||||
echo "stop-one: stopped api container $(printf '%.12s' "$match") (mode $mode)" >&2
|
||||
@@ -12,6 +12,11 @@ from api_client import Actor, Api
|
||||
from spec_coverage import COLLECTED, Collected
|
||||
|
||||
BASE_URL = os.environ.get("BASE_URL", "http://localhost:8080").rstrip("/")
|
||||
# сколько реплик API за BASE_URL: стенд с LB — API_REPLICAS (make
|
||||
# student_test), один процесс — 1 (make test_isolated, драйвер в консоли).
|
||||
# Режим задаётся явно, а не угадывается по ответам: иначе сломанный LB
|
||||
# давал бы пропуск вместо падения
|
||||
EXPECT_REPLICAS = int(os.environ.get("EXPECT_REPLICAS", "2"))
|
||||
# hook стенда отказов и «тесный» API задаёт make failure_checks
|
||||
FAULT_HOOK = os.environ.get("FAULT_HOOK", "")
|
||||
FAULT_TIGHT_BASE_URL = os.environ.get("FAULT_TIGHT_BASE_URL", "").rstrip("/")
|
||||
@@ -79,6 +84,26 @@ def base_url() -> str:
|
||||
return BASE_URL
|
||||
|
||||
|
||||
@pytest.fixture(scope="session")
|
||||
def expect_replicas() -> int:
|
||||
return EXPECT_REPLICAS
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def replicas() -> int:
|
||||
"""Тест реплик: нужны ≥ 2 реплики за балансировщиком.
|
||||
|
||||
Против одного процесса тест пропускается с причиной, а не считается
|
||||
пройденным.
|
||||
"""
|
||||
if EXPECT_REPLICAS < 2:
|
||||
pytest.skip(
|
||||
f"one API process (EXPECT_REPLICAS={EXPECT_REPLICAS}): "
|
||||
"replica checks need the stand with the load balancer",
|
||||
)
|
||||
return EXPECT_REPLICAS
|
||||
|
||||
|
||||
@pytest.fixture(scope="session")
|
||||
def api() -> Iterator[Api]:
|
||||
with Api(BASE_URL) as client:
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
|
||||
import json
|
||||
import re
|
||||
from collections.abc import Iterable
|
||||
from datetime import datetime, timedelta
|
||||
from functools import cache
|
||||
from pathlib import Path
|
||||
@@ -165,6 +166,20 @@ def assert_instance_id(resp: httpx.Response) -> str:
|
||||
return instance_id
|
||||
|
||||
|
||||
def assert_replicas(values: Iterable[str], expected: int) -> set[str]:
|
||||
"""Ответы дали не меньше двух разных `X-Instance-Id`; возвращает их.
|
||||
|
||||
`expected` — `EXPECT_REPLICAS`: сколько реплик ждали за `BASE_URL`.
|
||||
"""
|
||||
seen = set(values)
|
||||
assert len(seen) >= 2, (
|
||||
f"saw {len(seen)} X-Instance-Id {sorted(seen)} behind BASE_URL, "
|
||||
f"EXPECT_REPLICAS={expected}: no load balancing across replicas; "
|
||||
"against one API process run with EXPECT_REPLICAS=1"
|
||||
)
|
||||
return seen
|
||||
|
||||
|
||||
def json_body(resp: httpx.Response) -> Any:
|
||||
"""JSON-тело в UTF-8, непустые `X-Request-Id` и `X-Instance-Id`."""
|
||||
request_id = resp.headers.get("X-Request-Id", "")
|
||||
|
||||
@@ -2,12 +2,14 @@
|
||||
# тот же docker-compose.yml под проектом <рабочий>-failures (имя рабочего
|
||||
# проекта — из name в docker-compose.yml, сейчас mtusi-lab3), со своим
|
||||
# volume и сетью. Порты Postgres и Valkey не публикуются: к ним ходит только
|
||||
# fault_hook.py через docker compose exec. Сервис api не запускается,
|
||||
# контейнеры API создаёт оркестратор (docker compose run -p 127.0.0.1:...).
|
||||
# fault_hook.py через docker compose exec. Сервисы api и haproxy не
|
||||
# запускаются: контейнеры API создаёт оркестратор (docker compose run
|
||||
# -p 127.0.0.1:...), у реплик api своих портов нет. Порт LB сброшен, чтобы
|
||||
# случайный up не занял APP_OUT_PORT рабочего стенда.
|
||||
services:
|
||||
postgres:
|
||||
ports: !reset []
|
||||
valkey:
|
||||
ports: !reset []
|
||||
api:
|
||||
haproxy:
|
||||
ports: !reset []
|
||||
|
||||
@@ -3,9 +3,10 @@
|
||||
Создаёт базу в Postgres стенда, накатывает на неё миграции сервисом
|
||||
`migrate`, поднимает отдельный контейнер `api` из определения compose с
|
||||
подменой только `DATABASE__NAME`, прогоняет `make test` и
|
||||
`make student_test`, затем удаляет контейнер и базу — при любом исходе,
|
||||
в том числе по Ctrl+C. Рабочая база и рабочий контейнер API не
|
||||
трогаются. Valkey стенда общий: ключи кэша включают имя базы, и
|
||||
`make student_test` (`EXPECT_REPLICAS=1`: один процесс без
|
||||
балансировщика, тесты реплик пропускаются), затем удаляет контейнер и
|
||||
базу — при любом исходе, в том числе по Ctrl+C. Рабочая база и рабочие
|
||||
контейнеры стенда не трогаются. Valkey стенда общий: ключи кэша включают имя базы, и
|
||||
карточки тестового прогона не смешиваются с рабочими. Только stdlib:
|
||||
всё через docker compose и make. Решение 12 design change
|
||||
`postgres-storage`.
|
||||
@@ -193,6 +194,9 @@ def main() -> int:
|
||||
"make",
|
||||
target,
|
||||
f"BASE_URL={base_url}",
|
||||
# один контейнер API без балансировщика: тесты реплик
|
||||
# пропускаются с причиной
|
||||
"EXPECT_REPLICAS=1",
|
||||
check=False,
|
||||
).returncode
|
||||
failed = any(results.values())
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
форматы."""
|
||||
|
||||
import json
|
||||
from collections import Counter
|
||||
from typing import Any
|
||||
|
||||
import httpx
|
||||
@@ -141,13 +142,29 @@ def test_one_instance_id_per_process(
|
||||
alice: Actor,
|
||||
eve: Actor,
|
||||
chat: dict[str, Any],
|
||||
expect_replicas: int,
|
||||
) -> None:
|
||||
# набор этого change идёт против одного процесса API (make
|
||||
# test_isolated, консоль); стенд с балансировщиком — change replicas-lb
|
||||
responses = business_responses(api, alice, eve, chat)
|
||||
responses += service_responses(api)
|
||||
values = {assert_instance_id(resp) for resp, _ in responses}
|
||||
assert len(values) == 1, f"one process answered with {values}"
|
||||
"""Две одинаковые серии по 18 разных запросов. Против одного процесса
|
||||
— одно значение на всё. Через балансировщик (round-robin, до 8
|
||||
реплик) каждая реплика отвечает в серии хотя бы дважды: значение,
|
||||
новое на каждый запрос, не прошло бы ни одну проверку."""
|
||||
|
||||
def series() -> list[str]:
|
||||
responses = business_responses(api, alice, eve, chat)
|
||||
for _ in range(3):
|
||||
responses += service_responses(api)
|
||||
return [assert_instance_id(resp) for resp, _ in responses]
|
||||
|
||||
first, second = series(), series()
|
||||
counts = Counter(first + second)
|
||||
print(f"two series of {len(first)} requests: {dict(counts)}")
|
||||
if expect_replicas < 2:
|
||||
assert len(counts) == 1, f"one process answered with {set(counts)}"
|
||||
return
|
||||
assert all(served > 1 for served in counts.values()), counts
|
||||
assert set(second) <= set(first), (
|
||||
f"new X-Instance-Id in the second series: {set(second) - set(first)}"
|
||||
)
|
||||
|
||||
|
||||
@pytest.mark.spec("api-conventions", "Ошибка содержит request_id заголовка")
|
||||
|
||||
@@ -3,6 +3,8 @@
|
||||
Сценарии, которым нужен особый стенд (сбой записи, остановка БД, короткий
|
||||
срок ключа), — в `test_failures.py`; гонка одного ключа — в
|
||||
`test_race.py`; повтор после рестарта API — исключение с evidence.
|
||||
Повтору через другую реплику нужны ≥ 2 реплики за `BASE_URL` (фикстура
|
||||
`replicas`), против одного процесса он пропускается.
|
||||
"""
|
||||
|
||||
from typing import Any
|
||||
@@ -20,7 +22,9 @@ from api_client import (
|
||||
from contract import (
|
||||
BEARER_CHALLENGE,
|
||||
assert_error,
|
||||
assert_instance_id,
|
||||
assert_ok,
|
||||
assert_replicas,
|
||||
assert_unauthorized,
|
||||
)
|
||||
|
||||
@@ -273,3 +277,39 @@ def test_invalid_request_keeps_key_free(
|
||||
assert_error(resp, 400)
|
||||
message = api.send_message(alice, chat["id"], "теперь валидно", key=key)
|
||||
assert texts(api, alice, chat["id"]) == [message["text"]]
|
||||
|
||||
|
||||
@pytest.mark.spec("idempotency", "Повтор через другую реплику")
|
||||
def test_replay_on_other_replica(
|
||||
api: Api,
|
||||
alice: Actor,
|
||||
chat: dict[str, Any],
|
||||
replicas: int,
|
||||
) -> None:
|
||||
"""Повтор с тем же ключом, который обслужила другая реплика, — тот же
|
||||
`Message`; другое тело с этим ключом — 409 от разных реплик."""
|
||||
key = new_key()
|
||||
body = {"text": "повтор через реплики"}
|
||||
resp = api.post_message(alice, chat["id"], key=key, json=body)
|
||||
first = assert_ok(resp, 201, "Message")
|
||||
origin = assert_instance_id(resp)
|
||||
|
||||
replays: dict[str, Any] = {}
|
||||
for _ in range(2 * replicas):
|
||||
resp = api.post_message(alice, chat["id"], key=key, json=body)
|
||||
replays[assert_instance_id(resp)] = assert_ok(resp, 201, "Message")
|
||||
if replays.keys() - {origin}:
|
||||
break
|
||||
print(f"sent via {origin}, replayed via {sorted(replays)}")
|
||||
# повтор через другую реплику: среди отправки и повторов ≥ 2 значения
|
||||
assert_replicas({origin, *replays}, replicas)
|
||||
assert all(message == first for message in replays.values())
|
||||
|
||||
conflicts = set()
|
||||
for _ in range(2 * replicas):
|
||||
resp = api.post_message(alice, chat["id"], key=key, json={"text": "?"})
|
||||
assert_error(resp, 409)
|
||||
conflicts.add(assert_instance_id(resp))
|
||||
print(f"409 via {sorted(conflicts)}")
|
||||
assert_replicas(conflicts, replicas)
|
||||
assert texts(api, alice, chat["id"]) == [body["text"]]
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
"""Спек `load-balancing`: запросы одной сессии и запись через реплики.
|
||||
|
||||
Capability `load-balancing` вне сверки покрытия (`spec_coverage.py`):
|
||||
почти все её сценарии требуют действий над контейнерами и доказываются
|
||||
evidence. Сценарии, которые проверяются по HTTP, названы в докстрингах.
|
||||
Тесты нужны ≥ 2 реплики за `BASE_URL` (фикстура `replicas`).
|
||||
"""
|
||||
|
||||
from collections import Counter
|
||||
from typing import Any
|
||||
|
||||
from api_client import API, Actor, Api
|
||||
from contract import assert_instance_id, assert_ok, assert_replicas
|
||||
|
||||
SESSION_REQUESTS = 20
|
||||
|
||||
|
||||
def test_one_session_on_several_replicas(
|
||||
api: Api,
|
||||
alice: Actor,
|
||||
replicas: int,
|
||||
) -> None:
|
||||
"""Сценарий «Одна сессия на разных репликах»: один вход, 20 запросов
|
||||
с одним токеном — все 200 с этим пользователем, ≥ 2 реплики."""
|
||||
served: Counter[str] = Counter()
|
||||
for _ in range(SESSION_REQUESTS):
|
||||
resp = api.request("GET", f"{API}/users/me", actor=alice)
|
||||
assert assert_ok(resp, 200, "User") == alice.user
|
||||
served[assert_instance_id(resp)] += 1
|
||||
print(f"one session, {SESSION_REQUESTS} requests: {dict(served)}")
|
||||
assert_replicas(served, replicas)
|
||||
|
||||
|
||||
def test_write_visible_through_other_replica(
|
||||
api: Api,
|
||||
alice: Actor,
|
||||
bob: Actor,
|
||||
chat: dict[str, Any],
|
||||
replicas: int,
|
||||
) -> None:
|
||||
"""Сценарий «Запись видна через другую реплику»: сообщение,
|
||||
отправленное через одну реплику, есть в каждом следующем чтении
|
||||
истории, в том числе через другие реплики."""
|
||||
resp = api.post_message(alice, chat["id"], json={"text": "через LB"})
|
||||
message = assert_ok(resp, 201, "Message")
|
||||
writer = assert_instance_id(resp)
|
||||
|
||||
readers: Counter[str] = Counter()
|
||||
for _ in range(2 * replicas + 2):
|
||||
page = api.messages_page(bob, chat["id"])
|
||||
assert message in assert_ok(page, 200, "MessagePage")["items"]
|
||||
readers[assert_instance_id(page)] += 1
|
||||
print(f"written via {writer}, read via {dict(readers)}")
|
||||
assert_replicas(readers, replicas)
|
||||
assert readers.keys() - {writer}, (
|
||||
f"every read was served by the writer {writer}"
|
||||
)
|
||||
@@ -19,7 +19,12 @@ from api_client import (
|
||||
registration,
|
||||
unique_username,
|
||||
)
|
||||
from contract import assert_error, assert_ok
|
||||
from contract import (
|
||||
assert_error,
|
||||
assert_instance_id,
|
||||
assert_ok,
|
||||
assert_replicas,
|
||||
)
|
||||
|
||||
CLIENTS = 10
|
||||
MESSAGES_PER_CLIENT = 10
|
||||
@@ -152,9 +157,48 @@ def test_same_key_at_once(
|
||||
"""Спек `student-tests`, сценарий «Гонка одного ключа»: одно тело с
|
||||
одним ключом от `CLIENTS` клиентов сразу — ровно одно сообщение.
|
||||
|
||||
Против одного процесса API гонку решает PostgreSQL так же, как между
|
||||
репликами; ответы разных реплик требует change `replicas-lb`.
|
||||
На любом стенде: против одного процесса API гонку решает PostgreSQL
|
||||
так же, как между репликами. Ответы разных реплик требует
|
||||
`test_same_key_through_replicas`.
|
||||
"""
|
||||
results = race_one_key(api, alice, chat, base_url)
|
||||
peak = max_in_flight([(start, end) for _, start, end in results])
|
||||
assert peak >= 2, "requests did not overlap: race is not proven"
|
||||
|
||||
|
||||
@pytest.mark.spec("idempotency", "Гонка одного ключа через реплики")
|
||||
def test_same_key_through_replicas(
|
||||
api: Api,
|
||||
alice: Actor,
|
||||
chat: dict[str, Any],
|
||||
base_url: str,
|
||||
replicas: int,
|
||||
) -> None:
|
||||
"""Та же гонка через балансировщик: среди ответов есть пара
|
||||
пересекающихся по времени запросов, которые обслужили разные реплики.
|
||||
Это и есть «одновременно через разные реплики», а не просто «разные
|
||||
реплики за весь прогон». Против одного процесса — пропуск."""
|
||||
results = race_one_key(api, alice, chat, base_url)
|
||||
spans = [
|
||||
(assert_instance_id(resp), start, end) for resp, start, end in results
|
||||
]
|
||||
served = Counter(instance for instance, _, _ in spans)
|
||||
print(f"key race through replicas: {dict(served)}")
|
||||
assert_replicas(served, replicas)
|
||||
assert overlap_on_different_replicas(spans), (
|
||||
f"no overlapping requests on different replicas: {dict(served)}"
|
||||
)
|
||||
|
||||
|
||||
def race_one_key(
|
||||
api: Api,
|
||||
alice: Actor,
|
||||
chat: dict[str, Any],
|
||||
base_url: str,
|
||||
) -> list[tuple[httpx.Response, float, float]]:
|
||||
"""`CLIENTS` клиентов сразу шлют одно тело с одним ключом: все 201 с
|
||||
одним `Message`, в истории ровно одно сообщение. Возвращает ответы со
|
||||
временем начала и конца."""
|
||||
key = new_key()
|
||||
body = {"text": "один раз"}
|
||||
|
||||
@@ -172,8 +216,19 @@ def test_same_key_at_once(
|
||||
f"max in flight {peak}; history: {len(history)} messages",
|
||||
)
|
||||
|
||||
assert peak >= 2, "requests did not overlap: race is not proven"
|
||||
assert statuses == {201: CLIENTS}, statuses
|
||||
messages = [assert_ok(resp, 201, "Message") for resp, _, _ in results]
|
||||
assert all(message == messages[0] for message in messages)
|
||||
assert history == [messages[0]]
|
||||
return results
|
||||
|
||||
|
||||
def overlap_on_different_replicas(
|
||||
spans: list[tuple[str, float, float]],
|
||||
) -> bool:
|
||||
"""Есть два запроса разных реплик, которые были в полёте одновременно."""
|
||||
return any(
|
||||
first[0] != second[0] and first[1] < second[2] and second[1] < first[2]
|
||||
for number, first in enumerate(spans)
|
||||
for second in spans[number + 1 :]
|
||||
)
|
||||
|
||||
Reference in New Issue
Block a user