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:
2026-10-10 18:05:05 +03:00
co-authored by Claude Opus 5.5
parent 8e15e02898
commit ab71c3b51e
31 changed files with 1295 additions and 240 deletions
+72 -33
View File
@@ -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`
+9
View File
@@ -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
View File
@@ -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 с. Готовность ждёт сам тест. Секреты не печатает.
+12 -3
View File
@@ -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`). От
+6 -4
View File
@@ -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`, как
+30 -12
View File
@@ -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`, модуль
+71 -32
View File
@@ -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
+65 -9
View File
@@ -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
View File
@@ -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.
+35 -30
View File
@@ -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/`.
## Архитектура в двух словах
+52 -4
View File
@@ -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
View File
@@ -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
View File
@@ -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:
+95
View File
@@ -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
+15 -15
View File
@@ -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 в формате
+7 -2
View File
@@ -81,8 +81,13 @@ Unicode code points.
#### Scenario: Одно значение на процесс
- **WHEN** клиент выполняет серию разных запросов к одному процессу API
- **THEN** все ответы содержат одно и то же значение `X-Instance-Id`
- **WHEN** клиент дважды подряд выполняет одну и ту же серию разных
запросов — к одному процессу API или через балансировщик к
нескольким репликам
- **THEN** против одного процесса все ответы содержат одно значение
`X-Instance-Id`; через балансировщик каждое значение встречается
больше чем в одном ответе, а во второй серии нет значений, которых не
было в первой
### Requirement: Единый формат ошибки
+72 -28
View File
@@ -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
+17
View File
@@ -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
+229
View File
@@ -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** команда печатает по строке на каждый занятый слот реплики с
её адресом и состоянием проверки, а порт статистики не опубликован на
хосте
+57 -11
View File
@@ -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
View File
@@ -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
View File
@@ -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
+73
View File
@@ -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
+25
View File
@@ -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:
+15
View File
@@ -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", "")
+5 -3
View File
@@ -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 []
+7 -3
View File
@@ -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())
+23 -6
View File
@@ -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 заголовка")
+40
View File
@@ -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"]]
+57
View File
@@ -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}"
)
+59 -4
View File
@@ -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 :]
)