diff --git a/.claude/rules/balancer.md b/.claude/rules/balancer.md index 6e508341..e3125f66 100644 --- a/.claude/rules/balancer.md +++ b/.claude/rules/balancer.md @@ -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- api:<порт> check resolvers docker init-addr none`. Новая и пропавшая реплика - видны без перезагрузки LB. `` — запас слотов не меньше - максимального числа реплик в сериях трека 1. + видны без перезагрузки LB (`hold` 1 с). `` — запас слотов не + меньше максимального числа реплик в сериях трека 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 ` или - `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` diff --git a/.claude/rules/bench.md b/.claude/rules/bench.md index 5e308a52..6979af9f 100644 --- a/.claude/rules/bench.md +++ b/.claude/rules/bench.md @@ -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` рабочего стенда. Пароли diff --git a/.claude/rules/docker.md b/.claude/rules/docker.md index 56f0b7ce..29120d07 100644 --- a/.claude/rules/docker.md +++ b/.claude/rules/docker.md @@ -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 с. Готовность ждёт сам тест. Секреты не печатает. diff --git a/.claude/rules/run-modes.md b/.claude/rules/run-modes.md index 37937dbc..7e265d7f 100644 --- a/.claude/rules/run-modes.md +++ b/.claude/rules/run-modes.md @@ -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`). От diff --git a/.claude/rules/settings.md b/.claude/rules/settings.md index abce0dfc..1bba264d 100644 --- a/.claude/rules/settings.md +++ b/.claude/rules/settings.md @@ -149,10 +149,12 @@ Postgres и Valkey приходят мостами из `POSTGRES_PASSWORD` и Skeleton lab3 добавил ещё два имени: -- `API_REPLICAS` читает только compose (`deploy.replicas` сервиса - `api`), приложение — нет. Поэтому имя остаётся как есть, без секции: - строка в `.env.example` и `${API_REPLICAS:-2}` в compose. Разовая - подмена — `docker compose up --scale api=N`; +- `API_REPLICAS` читают compose (`deploy.replicas` сервиса `api`) и + Makefile (`make replicas`, `EXPECT_REPLICAS` тестов), приложение — + нет. Поэтому имя остаётся как есть, без секции: строка в + `.env.example`, `${API_REPLICAS:-2}` в compose и `API_REPLICAS ?= 2` + в Makefile — без строки в `.env` действует 2. Разовая подмена — + `make replicas API_REPLICAS=N`; - `IDEMPOTENCY_TTL_SECONDS` читает только приложение. Это `[idempotency] ttl_seconds` в `config.toml` (по умолчанию 86400 — 24 ч по контракту), соответствие — в `REPORT.md`, как diff --git a/.claude/rules/student-tests.md b/.claude/rules/student-tests.md index e86d878e..4e49c3ea 100644 --- a/.claude/rules/student-tests.md +++ b/.claude/rules/student-tests.md @@ -45,13 +45,30 @@ paths: и срок ключа — проверки отказов (`test_failures.py`); - гонка одного ключа (уровень 4, `test_race.py`): N потоков за `threading.Barrier` шлют одно тело с одним ключом. Все ответы 201 с - одним `id`, в истории ровно одно сообщение. С change `replicas-lb` - через LB тест ещё требует ≥2 разных `X-Instance-Id` среди ответов: - иначе «через разные реплики» не доказано. Против одного процесса - (`make test_isolated`, console) эта часть пропускается с явной - причиной, а не считается пройденной; -- распределение по репликам: запросы одной сессии через LB отвечают - ≥2 разными `X-Instance-Id` без повторного входа. + одним `id`, в истории ровно одно сообщение (`test_same_key_at_once`, + любой стенд). Через LB `test_same_key_through_replicas` ещё требует + пару пересекающихся по времени запросов с разными `X-Instance-Id`: + иначе «одновременно через разные реплики» не доказано; +- тесты реплик (нужны ≥ 2 реплики за `BASE_URL`, фикстура + `replicas`): + - `test_load_balancing.py` — одна сессия на разных репликах, запись + видна через другую реплику (спек `load-balancing` вне сверки + покрытия: сценарий — в докстринге); + - `test_idempotency.py::test_replay_on_other_replica` — повтор с + ключом через другую реплику, 409 от разных реплик; + - `test_race.py::test_same_key_through_replicas`. + + Сколько реплик за `BASE_URL`, набор узнаёт из `EXPECT_REPLICAS`, а не + угадывает по ответам: иначе сломанный LB давал бы пропуск вместо + падения. `make student_test` берёт его из `API_REPLICAS` (2), `make + test_isolated` и `driver.py student` против своего процесса передают + 1. При 1 тесты реплик пропускаются с причиной «one API process» (её + печатает `-rsP` в `addopts`), при ≥ 2 и одном увиденном значении — + падают с числом увиденных (`assert_replicas` в `contract.py`); +- «Одно значение на процесс» (`test_api_conventions.py`) — две + одинаковые серии по 18 запросов: против одного процесса одно + значение, через LB каждое значение повторяется, и вторая серия не + приносит новых. Опирается на round-robin LB. Проверки отказов реплик (остановка, kill, rolling update) — не pytest, а `make test-failover` и сценарии `balancer.md`: им нужен стенд с LB и @@ -79,11 +96,12 @@ paths: стенда (ключи кэша разделены именем базы), публичный smoke и весь набор против отдельного контейнера, затем уборка при любом исходе. Его вывод — evidence набора против контейнера. Это один контейнер - API без LB: тесты, которым нужны ≥2 реплики, здесь пропускаются. - `make student_test` — против любого запущенного стенда (`BASE_URL`), - он оставляет данные в рабочей базе. Против стенда compose лабы 3 - (`BASE_URL` = HAProxy) выполняются и тесты реплик; их вывод — второй - файл evidence. + API без LB (`EXPECT_REPLICAS=1`): тесты, которым нужны ≥2 реплики, + здесь пропускаются. `make student_test` — против любого запущенного + стенда (`BASE_URL`), он оставляет данные в рабочей базе. Против + стенда compose лабы 3 (`BASE_URL` = HAProxy) выполняются и тесты + реплик; их вывод — второй файл evidence + (`evidence/tests/student-test-lb.md`). - Проверкам, которым нужен особый стенд (TTL 2 с, остановленные или замороженные Postgres и Valkey, сбой БД посреди транзакции), обычный прогон не подходит. Это **проверки отказов**: маркер `fault`, модуль diff --git a/.claude/skills/run-mtusi-messenger/SKILL.md b/.claude/skills/run-mtusi-messenger/SKILL.md index 6463117d..c4e51aae 100644 --- a/.claude/skills/run-mtusi-messenger/SKILL.md +++ b/.claude/skills/run-mtusi-messenger/SKILL.md @@ -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 python3 $D req POST /api/v1/chats//messages --token --data '{"text":"hi"}' # печатает idempotency-key; повтор той же отправки — тот же запрос с --key <ключ> python3 $D smoke # публичный tests/smoke.py против этого порта -python3 $D student # make student_test BASE_URL=http://localhost: — ~15 с +python3 $D student # make student_test BASE_URL=http://localhost: — ~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:` | -| `student` | `make student_test BASE_URL=http://localhost:` (pytest по `student-tests/`); код 1, если каталога нет | +| `student` | `make student_test BASE_URL=http://localhost:` (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= 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}}' `. - **Экземпляр драйвера пишет в ту же рабочую базу**, что `make run_dev` и `make run_docker`: тестовые пользователи и чаты там остаются. Чистый прогон — `make test_isolated` (временная база `test_`), чистый @@ -215,11 +247,12 @@ make lint # ruff; затрагивает и dr `start` передаёт `APP__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 diff --git a/.claude/skills/run-mtusi-messenger/driver.py b/.claude/skills/run-mtusi-messenger/driver.py index 269cd72f..8abce1dc 100644 --- a/.claude/skills/run-mtusi-messenger/driver.py +++ b/.claude/skills/run-mtusi-messenger/driver.py @@ -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=`). +Порт по умолчанию 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, diff --git a/.env.example b/.env.example index 519a2cad..6a5fe524 100644 --- a/.env.example +++ b/.env.example @@ -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. diff --git a/AGENTS.md b/AGENTS.md index 9205a342..90a5b8a0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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_` с 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_` с 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_.py # сценарии основных спеков, маркер @pytest.mark.spec @@ -337,10 +340,10 @@ student-tests/ # black-box тесты по HTTP (уровень 4) run_isolated.py # make test_isolated: образ на временной базе test_ (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/`. ## Архитектура в двух словах diff --git a/Makefile b/Makefile index 93dc231f..9d681bd9 100644 --- a/Makefile +++ b/Makefile @@ -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_: сборка, миграции, отдельный # контейнер api на 127.0.0.1:TEST_APP_PORT, make test и make student_test, diff --git a/bench/bench.compose.yml b/bench/bench.compose.yml index 809a3438..43fc71b0 100644 --- a/bench/bench.compose.yml +++ b/bench/bench.compose.yml @@ -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) diff --git a/docker-compose.yml b/docker-compose.yml index d200844e..4072cd10 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -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: diff --git a/infra/haproxy/haproxy.cfg b/infra/haproxy/haproxy.cfg new file mode 100644 index 00000000..8e1b7aa9 --- /dev/null +++ b/infra/haproxy/haproxy.cfg @@ -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 diff --git a/openspec/changes/replicas-lb/tasks.md b/openspec/changes/replicas-lb/tasks.md index acc3cfdf..72d1f305 100644 --- a/openspec/changes/replicas-lb/tasks.md +++ b/openspec/changes/replicas-lb/tasks.md @@ -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 в формате diff --git a/openspec/specs/api-conventions/spec.md b/openspec/specs/api-conventions/spec.md index 62927151..995d0d81 100644 --- a/openspec/specs/api-conventions/spec.md +++ b/openspec/specs/api-conventions/spec.md @@ -81,8 +81,13 @@ Unicode code points. #### Scenario: Одно значение на процесс -- **WHEN** клиент выполняет серию разных запросов к одному процессу API -- **THEN** все ответы содержат одно и то же значение `X-Instance-Id` +- **WHEN** клиент дважды подряд выполняет одну и ту же серию разных + запросов — к одному процессу API или через балансировщик к + нескольким репликам +- **THEN** против одного процесса все ответы содержат одно значение + `X-Instance-Id`; через балансировщик каждое значение встречается + больше чем в одном ответе, а во второй серии нет значений, которых не + было в первой ### Requirement: Единый формат ошибки diff --git a/openspec/specs/container-run/spec.md b/openspec/specs/container-run/spec.md index d5eab6bc..624ff7c9 100644 --- a/openspec/specs/container-run/spec.md +++ b/openspec/specs/container-run/spec.md @@ -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 diff --git a/openspec/specs/idempotency/spec.md b/openspec/specs/idempotency/spec.md index 1072db91..1812df7e 100644 --- a/openspec/specs/idempotency/spec.md +++ b/openspec/specs/idempotency/spec.md @@ -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 diff --git a/openspec/specs/load-balancing/spec.md b/openspec/specs/load-balancing/spec.md new file mode 100644 index 00000000..0639794f --- /dev/null +++ b/openspec/specs/load-balancing/spec.md @@ -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** команда печатает по строке на каждый занятый слот реплики с + её адресом и состоянием проверки, а порт статистики не опубликован на + хосте diff --git a/openspec/specs/student-tests/spec.md b/openspec/specs/student-tests/spec.md index 7ff5b797..fee617ba 100644 --- a/openspec/specs/student-tests/spec.md +++ b/openspec/specs/student-tests/spec.md @@ -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_`, ни - тестового контейнера после команды нет, число строк в таблицах - рабочей базы не изменилось, а рабочий API продолжает отвечать +- **THEN** smoke и набор прошли, тесты реплик пропущены с причиной, + код выхода 0, ни базы `test_`, ни тестового контейнера после + команды нет, число строк в таблицах рабочей базы не изменилось, а + рабочий стенд продолжает отвечать через балансировщик #### Scenario: Упавшие тесты diff --git a/pyproject.toml b/pyproject.toml index e8002027..bb256217 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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", diff --git a/scripts/restart.sh b/scripts/restart.sh index 64a81780..28fe0187 100755 --- a/scripts/restart.sh +++ b/scripts/restart.sh @@ -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 diff --git a/scripts/stop-one.sh b/scripts/stop-one.sh new file mode 100755 index 00000000..5fbcfc3d --- /dev/null +++ b/scripts/stop-one.sh @@ -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 diff --git a/student-tests/conftest.py b/student-tests/conftest.py index 95c0374f..883ffe8a 100644 --- a/student-tests/conftest.py +++ b/student-tests/conftest.py @@ -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: diff --git a/student-tests/contract.py b/student-tests/contract.py index fc1fa278..cf512510 100644 --- a/student-tests/contract.py +++ b/student-tests/contract.py @@ -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", "") diff --git a/student-tests/failures.compose.yml b/student-tests/failures.compose.yml index 821fcad1..0b66a3d4 100644 --- a/student-tests/failures.compose.yml +++ b/student-tests/failures.compose.yml @@ -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 [] diff --git a/student-tests/run_isolated.py b/student-tests/run_isolated.py index 84362383..010709d8 100644 --- a/student-tests/run_isolated.py +++ b/student-tests/run_isolated.py @@ -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()) diff --git a/student-tests/test_api_conventions.py b/student-tests/test_api_conventions.py index 47418836..8dabcec6 100644 --- a/student-tests/test_api_conventions.py +++ b/student-tests/test_api_conventions.py @@ -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 заголовка") diff --git a/student-tests/test_idempotency.py b/student-tests/test_idempotency.py index 33b3dc24..401a01ba 100644 --- a/student-tests/test_idempotency.py +++ b/student-tests/test_idempotency.py @@ -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"]] diff --git a/student-tests/test_load_balancing.py b/student-tests/test_load_balancing.py new file mode 100644 index 00000000..60a9f576 --- /dev/null +++ b/student-tests/test_load_balancing.py @@ -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}" + ) diff --git a/student-tests/test_race.py b/student-tests/test_race.py index 0b2fcdeb..92835d87 100644 --- a/student-tests/test_race.py +++ b/student-tests/test_race.py @@ -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 :] + )