diff --git a/.claude/rules/run-modes.md b/.claude/rules/run-modes.md index 54d08fb0..48338dd1 100644 --- a/.claude/rules/run-modes.md +++ b/.claude/rules/run-modes.md @@ -83,6 +83,13 @@ timeout_graceful_shutdown=..., log_config=None, access_log=False)`. базе (`student-tests.md`); Valkey общий с рабочим стендом, ключи кэша разделены именем базы. Скрипт запускается `$(PYTHON)`, а не `uv run`: uv повторно пересылает SIGINT, и Ctrl+C обрывал уборку. +- `failure_checks: env_setup` — проверки отказов на отдельном стенде, + проект compose `<рабочий>-failures` (`student-tests.md`). От + `start_db` не зависит: стенд свой и удаляется вместе с volume. + `FAULT_ARGS` — аргументы pytest (`make failure_checks FAULT_ARGS='-k + valkey'`). Скрипт тоже запускается `$(PYTHON)`. Все команды docker + проекта отказов — только с `-p <рабочий>-failures`: `down -v` без + него удалил бы рабочий volume. ## Troubleshooting diff --git a/.claude/rules/student-tests.md b/.claude/rules/student-tests.md index 79bf64b1..fd8949da 100644 --- a/.claude/rules/student-tests.md +++ b/.claude/rules/student-tests.md @@ -46,13 +46,39 @@ paths: Его вывод — evidence набора против контейнера. `make student_test` — против любого запущенного стенда (`BASE_URL`), он оставляет данные в рабочей базе. -- Проверкам, которым нужен особый стенд (TTL 2 с, остановленные - Postgres или Valkey), обычный прогон не подходит. Попадание в кэш по - HTTP не отличить от чтения из БД: такие сценарии `chat-cache` — - исключения с evidence. Сами тесты - контейнеры не трогают: стенд готовит явный hook или отдельная цель - Makefile, как `make test-persistence` в skeleton. Механизм выбирает - change `failure-checks`. +- Проверкам, которым нужен особый стенд (TTL 2 с, остановленные или + замороженные Postgres и Valkey, сбой БД посреди транзакции), обычный + прогон не подходит. Это **проверки отказов**: маркер `fault`, модуль + `test_failures.py`, команда `make failure_checks` (change + `failure-checks`). Попадание в кэш по HTTP не отличить от чтения из + БД: такие сценарии `chat-cache` — исключения с evidence. +- Как устроен `make failure_checks` (`student-tests/run_failures.py`): + - тот же `docker-compose.yml` под проектом `<рабочий>-failures` с + override `failures.compose.yml`: свои Postgres и Valkey со своим + volume, их порты не публикуются; + - два API на свободных портах `127.0.0.1`: обычный (`BASE_URL`) и + «тесный» (`FAULT_TIGHT_BASE_URL`: срок сессии 2 с, пул 1, короткие + таймауты); + - `pytest -m fault`, затем удаление стенда с volume при любом + исходе. Рабочий стенд не трогается. +- Тесты `fault` сами docker не трогают. На стенд они действуют только + через фикстуру `stand` — hook `student-tests/fault_hook.py`, как + `make test-persistence` вызывает `ACTION_SCRIPT`. Маркер `fault` + выбирает тесты, фикстура `stand` действует на стенд: имена разные + намеренно. Действия: `stop` / `start` / + `pause` / `unpause`, `flush-cache`, `cache-hits`, `cache-has-chat`, + `fail-members` (триггер, который роняет вставку участников), + `count-chats`. Hook работает только с проектом из `FAULT_PROJECT` и + отказывается работать с проектом рабочего стенда. +- Тест `fault`, который останавливает или замораживает хранилище, + делает это в `with outage(...)`: в `finally` хранилище возвращается, + и упавшая проверка не ломает следующие. Границы времени — с запасом + 0,3–0,5 с, но на порядок ниже «плохого» поведения (6 с повторов + redis-py, 8 с зависшего запроса). +- `addopts` содержит `-m 'not fault'`: `make student_test` и + `make test_isolated` тесты `fault` собирают (их сценарии видит сверка + покрытия), но не выполняют. Запуск `pytest -m fault` без + `make failure_checks` останавливается до первого теста с кодом 2. - Пароли и токены тестов синтетические, не печатаются и не попадают в `evidence/` (`evidence/README.md`). - `tests/` — публичные проверки skeleton: не править, не ослаблять, @@ -76,8 +102,9 @@ paths: - **Каждый тест сценария спека помечен** `@pytest.mark.spec("", "<Сценарий>")`, имя — дословно из `#### Scenario:`. Новый сценарий в основном спеке без теста роняет `test_coverage.py`. Если его нельзя - проверить по HTTP, добавить запись в `EXCLUDED` (`spec_coverage.py`) - с причиной и способом проверки. + проверить по HTTP даже на стенде отказов, добавить запись в + `EXCLUDED` (`spec_coverage.py`) с причиной и способом проверки. + Сценарии тестов `fault` сверка считает покрытыми и печатает их число. - Модуль сверки называется `spec_coverage.py`, а не `coverage.py`: каталог набора стоит в `pythonpath`, и `coverage.py` затенил бы пакет `coverage` (pytest-cov, coverage-runner IDE). diff --git a/.claude/skills/run-mtusi-messenger/SKILL.md b/.claude/skills/run-mtusi-messenger/SKILL.md index 176cc421..6a97e311 100644 --- a/.claude/skills/run-mtusi-messenger/SKILL.md +++ b/.claude/skills/run-mtusi-messenger/SKILL.md @@ -157,13 +157,23 @@ make run_dev # Postgres + миграции, Valkey, затем 127.0.0.1:8080, ```bash make check # офлайн-структура skeleton make test_isolated # образ на временной базе: smoke + student-tests, уборка +make failure_checks # проверки отказов (~45 с) на отдельном стенде <рабочий>-failures +make failure_checks FAULT_ARGS='-k valkey' # только часть проверок отказов python3 $D all # живой сервер + flow + smoke + student-tests make lint # ruff; затрагивает и driver.py ``` Ожидаемо: `PASS: offline skeleton structure...`, `FAILED: none` у `flow`, smoke — `PASS: lab2 public API scenario...`, student — все -прошли, `All checks passed!`; `all` и `test_isolated` — код 0. +прошли (12 тестов `fault` — `deselected`), `All checks passed!`; `all`, +`test_isolated` и `failure_checks` — код 0. + +Проверки отказов (`student-tests/test_failures.py`, маркер `fault`) +останавливают и замораживают Postgres и Valkey, поэтому идут только на +своём стенде: `make failure_checks` поднимает проект compose +`<рабочий>-failures` со своими хранилищами и volume и удаляет его после +прогона. Рабочий стенд на 8080 при этом не трогается. `pytest -m fault` +напрямую останавливается с кодом 2: нет hook стенда. ## Gotchas diff --git a/AGENTS.md b/AGENTS.md index e2e2585f..66d2cfd2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -81,22 +81,14 @@ pydantic-settings, structlog (JSON в stdout), redis-py (клиент Valkey). Код перенесён из лабы 1 (commit `7b775a2`), хранилище переведено на PostgreSQL (change `postgres-storage`), вход и Bearer-сессии — change -`session-auth`, кэш Valkey — change `membership-cache`. Этот файл и +`session-auth`, кэш Valkey — change `membership-cache`, автоматические +проверки отказов — change `failure-checks`. Этот файл и `.claude/rules/` описывают целевое состояние лабы 2, поэтому в остальном код с ними пока расходится: - `bench/` поднимает стенд без Postgres, его сценарии k6 ходят с `X-User-Id`, а `inproc.py` ссылается на удалённый `MemoryStore` — change `bench-postgres` (`bench.md`); -- сценарии основных спеков, которые выполнятся только после следующих - changes, — внести в их `tasks.md`: в `failure-checks` — - автоматическая проверка «Сбой при добавлении участников», «БД - остановлена», «БД вернулась», «Соединения исчерпаны» - (`data-storage`), «Хранилище не готово», «Кэш недоступен» - (`health`), «Истёкший токен», «Срок не продлевается», «БД - остановлена при запросе с токеном» (`sessions`), «Valkey - остановлен», «Valkey завис», «Valkey вернулся» (`chat-cache`); пока - это исключения в `spec_coverage.py` с ручным evidence; - в `track2-backup-restore` — `FLUSHALL` Valkey после восстановления базы: иначе в кэше останутся карточки чатов, созданных после снятия backup (design change `membership-cache`, Risks); @@ -258,7 +250,8 @@ PostgreSQL (change `postgres-storage`), вход и Bearer-сессии — chan | `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) против запущенного сервера; сервер недоступен — код 2 и одна строка с адресом | +| `make student_test [BASE_URL=...]` | собственные тесты `student-tests/` (pytest) против запущенного сервера, кроме проверок отказов (`-m 'not fault'`); сервер недоступен — код 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=...]` | полная матрица (~18 мин на лабе 1) на своём стенде `mtusi-bench-*` без портов хоста; результаты в `evidence/bench/<метка>/`, занятая метка — отказ. Перед запуском — подготовка хоста. Цели `bench*` под Postgres ещё не доработаны (`.claude/rules/bench.md`) | | `make bench_quick` | самопроверка стенда на малых размерах (~1,5 мин), метка `quick-<время>`, в git не идёт | | `make bench_inproc [BENCH_LABEL=...]` | куда уходит время одного запроса (~2 мин): приложение вызывается внутри процесса в образе стенда, без сервера и сети; заодно сверяет формат времени с эталоном. Результат в `evidence/profile/<метка>.txt`, занятая метка — отказ. Объясняет, но не меряет пропускную способность | @@ -310,13 +303,17 @@ 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, сбор маркеров spec + conftest.py # BASE_URL, проверка доступности, фикстуры alice/bob/eve/chat и stand/tight_api, сбор маркеров spec, стоп без hook api_client.py # Api поверх httpx; Actor.headers() — единственное место идентификации contract.py # тела по схемам contracts/openapi.json, форматы id и created_at, assert_error spec_coverage.py # исключения (сценарии, которые не проверить по HTTP) и сверка покрытия test_rubric.py, test_race.py # обязательные сценарии и гонки уровня 4 test_.py # сценарии основных спеков, маркер @pytest.mark.spec + test_failures.py # проверки отказов (маркер fault): только make failure_checks 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 стенда отказов: без публикации портов bench/ # нагрузочный стенд из лабы 1 (под Postgres не доработан): make bench / make bench_quick run.py # оркестратор: стенд, матрица, метрики, runs.csv / summary.md / meta.json k6/ # сценарии k6: prepare, prefill, cursors, read, tail, write; lib.js — общие хелперы @@ -335,7 +332,7 @@ evidence/storage/ # отказы БД, пул, statement_timeout, р evidence/migrations/ # миграции с нуля и повторно, ошибка миграции evidence/auth/ # пароли и токены в БД, срок сессии, TTL из конфига evidence/cache/ # попадания в кэш, отказ Valkey, FLUSHALL и рестарт -evidence/tests/ # выводы make test_isolated и make student_test для REPORT.md +evidence/tests/ # выводы make test_isolated, make student_test и make failure_checks для REPORT.md evidence/bench/<метка>/ # результаты make bench: паспорт, прогоны, наполнение, сводка, сырые итоги k6 evidence/profile/<метка>.txt # результаты make bench_inproc evidence/compare/ # таблицы make bench_compare: <до>__<после>.md diff --git a/Makefile b/Makefile index 98838429..354956bc 100644 --- a/Makefile +++ b/Makefile @@ -191,6 +191,15 @@ student_test: test_isolated: env_setup start_db start_cache $(PYTHON) student-tests/run_isolated.py $(if $(KEEP_TEST_DB),--keep-db,) +# проверки отказов (pytest -m fault) на отдельном стенде: свой проект +# compose <рабочий>-failures со своими Postgres и Valkey, обычный и +# «тесный» API, hook student-tests/fault_hook.py; стенд и его volume +# удаляются при любом исходе, рабочий стенд не затрагивается. +# FAULT_ARGS — дополнительные аргументы pytest, например -k "Valkey" +.PHONY: failure_checks +failure_checks: env_setup + $(PYTHON) student-tests/run_failures.py $(FAULT_ARGS) + .PHONY: lint lint: @ruff format . diff --git a/openspec/changes/failure-checks/.openspec.yaml b/openspec/changes/failure-checks/.openspec.yaml new file mode 100644 index 00000000..480ad4de --- /dev/null +++ b/openspec/changes/failure-checks/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-01 diff --git a/openspec/changes/failure-checks/design.md b/openspec/changes/failure-checks/design.md new file mode 100644 index 00000000..34f4b39a --- /dev/null +++ b/openspec/changes/failure-checks/design.md @@ -0,0 +1,236 @@ +# Design + +## Context + +Мотивация — `proposal.md`, раздел Why. Требования — дельта спека +`student-tests`. + +Что уже есть и на что опираемся: + +- `make test_isolated` (`student-tests/run_isolated.py`) поднимает + отдельный контейнер API на временной базе в Postgres рабочего стенда, + гоняет smoke и набор и убирает за собой при любом исходе. Для отказов + он не годится: остановить общий Postgres значит остановить рабочий + стенд. +- Публичная `make test-persistence` (`tests/resilience.py`) сама + запускает исполняемый hook из `ACTION_SCRIPT` — это прецедент «тест + действует на стенд только через явный hook оператора». Правило + `student-tests.md` требует того же и оставляет выбор механизма этому + change. +- Ручные прогоны отказов уже сняты: `evidence/storage/db-unavailable.md`, + `pool-timeout.md`, `evidence/auth/expiry.md`, `evidence/cache/outage.md`, + `flush-restart.md`. Значения (503 за 0,01 с при остановленной БД, + пул 1 и `pool_timeout` 1 с → 503 за 1 с, Valkey на паузе — +0,2 с) + дают границы для проверок. +- Проверено на Compose v5.5.1: `docker compose -p mtusi-lab2-failures -f + docker-compose.yml -f ` даёт отдельный volume + `mtusi-lab2-failures_postgres_data` и сеть, а `ports: !reset []` в + override снимает публикацию портов. +- Ошибка из триггера PostgreSQL (`RAISE EXCEPTION`, SQLSTATE `P0001`) не + входит в классы недоступности `src/infra/db/errors.py`, поэтому API + ответит 500 `internal_error`, а не 503. +- pytest: свой `pytest_collection_modifyitems` в `conftest.py` помечен + `tryfirst` и собирает маркеры `spec` до отбора по `-m` (у плагина меток + pytest хук без `tryfirst`). Значит, тесты, исключённые из прогона + через `-m "not fault"`, сверка покрытия всё равно видит. + +## Goals / Non-Goals + +**Goals:** + +- Одна команда без ручных шагов, которая проверяет все сценарии отказов + и оставляет хост в исходном состоянии. +- Рабочий стенд не меняется ни на секунду: ни рестарта, ни паузы, ни + чужих данных в его базе и кэше. +- Проверки устойчивы к скорости хоста: границы времени с запасом, но + ловят порядок величины (0,2 с против 6 с). + +**Non-Goals:** + +- Изменения кода приложения: проверяется готовое поведение. +- Отказ API-реплики и балансировщика — лаба 3 (`make test-failover`). +- Сценарии, которым нужен рестарт стенда («Прежний токен после + рестарта» — это `make test-persistence`), доступ к таблицам + («Токена нет в хранилище», «Хэш в БД») или браузер: они остаются + исключениями с evidence. +- Запуск проверок отказов в CI skeleton: CI приложение не запускает. + +## Decisions + +### 1. Отдельный проект compose `mtusi-lab2-failures` + +Стенд отказов — тот же `docker-compose.yml` (те же пины, healthcheck, +конфиг Valkey, якорь окружения), запущенный под другим именем проекта и +с override `student-tests/failures.compose.yml`: + +```yaml +services: + postgres: { ports: !reset [] } + valkey: { ports: !reset [] } + api: { ports: !reset [] } +``` + +Свой volume, своя сеть, порты Postgres и Valkey не публикуются: с хоста к +ним ходит только hook через `docker compose exec`. Сервис `api` проекта +не запускается — контейнеры API создаёт оркестратор (решение 2). + +*Альтернативы:* +- Проверки на рабочем стенде: останавливают рабочую БД и кэш, смешивают + тестовые данные с рабочими. Отвергнута. +- Временная база в рабочем Postgres, как у `test_isolated`: остановить + или заморозить можно только весь сервер. Отвергнута. + +### 2. Два контейнера API: обычный и «тесный» + +Оркестратор поднимает их как `run_isolated.py`: `docker compose run -d +--no-deps --name … -p 127.0.0.1:<порт>:${APP__PORT} -e … api`. Порты +хоста — свободные, их выбирает оркестратор (bind на `127.0.0.1:0`): +новых переменных в `.env` не нужно. + +| API | Окружение | Для сценариев | +|---|---|---| +| обычный | настройки по умолчанию (срок сессии 3600 с, пул 10 + 5) | отказы БД и Valkey, readiness, откат, очистка кэша | +| тесный | `AUTH__SESSION_TTL_SECONDS=2`, `DATABASE__POOL_SIZE=1`, `DATABASE__MAX_OVERFLOW=0`, `DATABASE__POOL_TIMEOUT_SECONDS=1`, `DATABASE__REQUEST_TIMEOUT_SECONDS=2` | истечение сессии, исчерпание пула | + +Обычный нужен отдельно: «БД остановлена при запросе с токеном» требует, +чтобы после возврата БД *тот же* токен получил 200, а со сроком 2 с он +истёк бы раньше. Срок и пул в одном тесном контейнере не мешают друг +другу: эти тесты короткие и идут по очереди. Короткий срок запроса +(2 с) сокращает тест пула: первый запрос освобождает соединение через +2 + 2 с, а не через 6 + 2 с. + +*Альтернатива:* три контейнера (срок, пул, обычный). Отвергнута: лишний +контейнер без выигрыша в ясности проверок. + +### 3. Hook `student-tests/fault_hook.py` + +Исполняемый stdlib-скрипт. Тест вызывает его как `[FAULT_HOOK, действие, +аргументы…]` без shell, как `resilience.py` вызывает `ACTION_SCRIPT`. +Hook работает только с проектом из переменной `FAULT_PROJECT`. Если её +нет или она совпадает с проектом рабочего стенда, hook отказывается +работать (код 2). Каждый вызов — команда `docker compose -p +$FAULT_PROJECT -f docker-compose.yml -f student-tests/failures.compose.yml`. + +| Действие | Что делает | Вывод | +|---|---|---| +| `stop` / `start` `postgres`\|`valkey` | `stop`; `start` + `up -d --wait` (ждёт healthcheck) | — | +| `pause` / `unpause` `postgres`\|`valkey` | заморозка; разморозка + ожидание ответа сервиса той же проверкой, что в healthcheck (`pg_isready`, `PING`). Статус Docker после `unpause` до следующего запуска healthcheck (до 5 с) остаётся `unhealthy`, и `up --wait` сразу выходит с ошибкой — найдено на первом прогоне | — | +| `flush-cache` | `FLUSHALL` | — | +| `cache-hits` | `keyspace_hits` из `INFO stats` | число | +| `cache-has-chat ` | `EXISTS` ключа карточки (`messenger:v1::chat:`) | `0` / `1` | +| `fail-members ` | триггер `BEFORE INSERT ON chat_members`: `RAISE EXCEPTION`, если у чата это название | — | +| `clear-fail-members` | удаляет триггер и функцию | — | +| `count-chats <title>` | `count(*)` из `chats` по названию | число | + +Пароль Valkey hook не видит и не печатает: `valkey-cli` в контейнере +берёт его из `VALKEYCLI_AUTH`. psql — от `POSTGRES_USER` контейнера. + +*Альтернатива:* тесты сами вызывают `docker compose`. Отвергнута: тест +тогда знает про docker и может задеть рабочий стенд; правило +`student-tests.md` и спек это запрещают. + +*Альтернатива для отката:* заморозить БД между двумя вставками. +Отвергнута: окна нет, вставки идут подряд за миллисекунды. Триггер в +базе стенда отказов даёт сбой ровно на второй вставке; база после +прогона удаляется вместе со стендом, миграций он не касается. + +### 4. Тесты: `student-tests/test_failures.py`, маркер `fault` + +- Маркер `fault` объявлен в `pyproject.toml`. В `addopts` добавлено + `-m "not fault"`: `make student_test` и `make test_isolated` эти тесты + собирают, но не выполняют. Оркестратор запускает `pytest -m fault`: + последний `-m` перекрывает `addopts`. +- Фикстуры в `conftest.py`: `stand` (вызов hook, возвращает stdout: + `stand("stop", "postgres")`), `tight_api` (`Api` на + `FAULT_TIGHT_BASE_URL`). Фикстура названа не `fault`, чтобы не + путаться с маркером: маркер выбирает тесты, фикстура действует на + стенд. Если `FAULT_HOOK` не задан, а выбран хотя бы один тест `fault`, + — `pytest.exit` в `pytest_collection_finish` с текстом «run make + failure_checks» и кодом 2, до первого теста: ни одно хранилище не + трогается (спек, «Проверка отказа без hook»). +- Каждый тест, который останавливает или замораживает хранилище, делает + это в контекстном менеджере, который в `finally` запускает и + размораживает его обратно. Упавшая проверка не оставляет стенд + сломанным для следующих. +- Границы времени (запас на планировщик Docker Desktop): + + | Сценарий | Проверка | + |---|---| + | «БД остановлена» | 503 `unavailable`, `message` — общий текст, ответ < 2 с | + | «Хранилище не готово» | `/health/ready` 503 < 2,5 с, `/health/live` 200 | + | «Соединения исчерпаны» | второй запрос — 503 < 1 + 0,5 с, пока первый держит соединение | + | «Valkey завис» | первый запрос не дольше медианы до паузы + 0,2 + 0,3 с | + | «Valkey остановлен» | 200 / 201 / 200, тела как с кэшем, < 0,2 + 0,3 с | + | «Valkey вернулся» | после `start` и 5,5 с — `cache-hits` растёт при чтении карточки | + | «Истёкший токен», «Срок не продлевается» | тесный API, 401 с вызовом Bearer к 3 с после входа | + +- Сценарий «Сбой при добавлении участников»: `fail-members <уникальное + название>`, `POST /chats` → 500 `internal_error`, чата с этим названием + нет в списках обоих участников и `count-chats` = 0; в `finally` — + `clear-fail-members`. + +### 5. Оркестратор `student-tests/run_failures.py` и цель Makefile + +По образцу `run_isolated.py`, только stdlib, запускается `$(PYTHON)`: + +1. Имя проекта — `<проект рабочего стенда>-failures`. Перед стартом + проверка: имя не совпадает с рабочим, иначе выход с кодом 2. +2. Уборка хвоста: `down -v --remove-orphans` проекта отказов и `docker + rm -f` контейнеров API по именам. +3. `docker compose build api` — образ из рабочего дерева (тот же тег, что + у `test_isolated`; работающий рабочий контейнер это не затрагивает). +4. `up -d --wait postgres valkey`, `run --rm migrate`, два `run -d` API, + ожидание `/health/ready` каждого. +5. `uv run pytest -m fault` с окружением `BASE_URL`, + `FAULT_TIGHT_BASE_URL`, `FAULT_HOOK`, `FAULT_PROJECT`. +6. При провале — хвосты журналов обоих API. В `finally` — уборка как в + шаге 2, повторный Ctrl+C игнорируется. + +`Makefile`: `failure_checks: env_setup` → `$(PYTHON) +student-tests/run_failures.py`. От `start_db` цель не зависит: стенд +свой. + +### 6. Сверка покрытия + +13 записей `EXCLUDED` удаляются: их сценарии получают тесты с маркерами +`spec` и `fault`. `Collected` дополнительно запоминает сценарии, чьи +тесты помечены `fault`. Итог сверки становится таким: «coverage: N +scenarios in M specs, T tested (F by make failure_checks), E excluded». + +### 7. Evidence + +`evidence/tests/failure-checks.md`: команда, дата, commit, стенд, +вывод прогона с длительностями, список проверенных сценариев. +Доказательство, что рабочий стенд не тронут: `StartedAt` его контейнеров +до и после и число строк в его таблицах. + +## Risks / Trade-offs + +- [`down -v` в уборке удаляет volume — ошибка в имени проекта стёрла бы + рабочие данные] → Имя проекта — константа с суффиксом `-failures`. + Оркестратор и hook сверяют его с проектом рабочего стенда и + отказываются работать при совпадении. Команды без `-p` не вызываются. +- [Проверки времени нестабильны на медленном хосте] → Запас 0,3–0,5 с + к границам, которые отличаются от «плохого» поведения на порядок (6 с + повторов redis-py, 8 с зависшего запроса). В выводе — фактические + длительности. +- [Прогон дольше `test_isolated`: свой Postgres с initdb, окна пропуска + кэша по 5 с, срок сессии 2–3 с] → Около 2 минут. Это отдельная цель, + в обычный прогон она не входит. +- [`make student_test` больше не выполняет часть тестов набора] → Вывод + pytest показывает их как `deselected`. Сверка покрытия печатает, + сколько сценариев покрыто через `make failure_checks`. `REPORT.md` и + правило называют обе команды. +- [Сбой отката вызван триггером, а не реальной ошибкой БД] → Проверяется + свойство транзакции, а не причина сбоя: любая ошибка второй вставки + должна откатить первую. Ответ 500 — честный исход внутреннего сбоя. +- [Образ `mtusi-messenger:lab2` пересобирается, как и в `test_isolated`] + → Уже работающий рабочий контейнер держит прежний образ. + `make run_docker` его и так пересобирает. + +## Migration Plan + +Порядок: override и hook → оркестратор и цель Makefile → тесты и +фикстуры → маркер и сверка покрытия → прогон `make failure_checks` и +`make test_isolated` → документы → commit → evidence → `REPORT.md` → +commit. Откат — `git revert`: приложение и рабочий стенд не меняются. diff --git a/openspec/changes/failure-checks/proposal.md b/openspec/changes/failure-checks/proposal.md new file mode 100644 index 00000000..c73926b7 --- /dev/null +++ b/openspec/changes/failure-checks/proposal.md @@ -0,0 +1,94 @@ +# Proposal + +## Why + +Уровень «4» требует автоматическую проверку истечения сессии при коротком +`SESSION_TTL_SECONDS` и недоступности Redis/Valkey и БД: при потере +сервиса приложение отвечает ограниченной ошибкой или обходит кэш и не +принимает анонимный запрос (`README.md`). Сейчас эти сценарии проверены +только вручную. В `spec_coverage.py` это 13 исключений со ссылками на +evidence: истечение сессии, остановленная и зависшая БД, исчерпанный +пул, откат создания чата, отказы Valkey, readiness. Обычный прогон их +выполнить не может: ему нужны особый стенд и действия над хранилищами, +а набор `student-tests` по правилу сам стенд не трогает. + +## What Changes + +- Новая цель `make failure_checks` поднимает **отдельный стенд отказов**: + - свой проект compose `mtusi-lab2-failures` со своими PostgreSQL и + Valkey, без публикации их портов; + - образ из рабочего дерева и миграции; + - два контейнера API: с настройками по умолчанию и «тесный» — срок + сессии 2 с, пул из одного соединения, короткие таймауты. + + Затем цель прогоняет проверки отказов и удаляет стенд вместе с его + volume при любом исходе. Рабочий стенд, его база и кэш не + затрагиваются. +- Проверки отказов — тесты `student-tests` с маркером `fault`. На стенд + они действуют только через явный hook, который им передаёт + `make failure_checks`, как `make test-persistence` передаёт + `ACTION_SCRIPT`. Hook умеет: + - останавливать, запускать, замораживать и размораживать Postgres и + Valkey; + - очищать кэш; + - включать сбой записи участников (триггер в базе стенда отказов); + - отвечать на вопросы о состоянии: есть ли чат с названием, есть ли + ключ карточки, сколько попаданий в кэш. + + Код приложения и docker тесты сами не трогают. +- `make student_test` и `make test_isolated` проверки отказов не + запускают: маркер `fault` исключён из обычного прогона. Его сценарии + при этом считаются покрытыми, и сверка покрытия по-прежнему видит + все сценарии. +- Автоматическими становятся 13 сценариев: + - `sessions`: «Истёкший токен», «Срок не продлевается», «БД + остановлена при запросе с токеном»; + - `data-storage`: «Сбой при добавлении участников», «БД остановлена», + «БД вернулась», «Соединения исчерпаны»; + - `health`: «Хранилище не готово», «Кэш недоступен»; + - `chat-cache`: «Valkey остановлен», «Valkey завис», «Valkey + вернулся», «Очистка кэша». + + Их записи в `EXCLUDED` удаляются. Исключениями остаются сценарии, + которым нужен не отказ, а рестарт стенда, доступ к таблицам или + браузер. +- Поведение приложения не меняется: проверяется то, что уже + реализовано. + +Вне этого change: нагрузочный стенд и EXPLAIN (`bench-postgres`), трек 2, +отказ API-реплики (лаба 3, `make test-failover`). + +## Capabilities + +### New Capabilities + +Нет. + +### Modified Capabilities + +- `student-tests`: + - новое требование — проверки отказов на отдельном стенде + (`make failure_checks`); + - «Только по HTTP» — действие на стенд только через переданный hook; + - «Запуск одной командой» — набор без проверок отказов; + - «Покрытие сценариев основных спеков» — сценарий, покрытый + проверкой отказа, считается покрытым; + - «Результат прогона сохраняется» — и вывод `make failure_checks`. + +## Impact + +- Тесты: `student-tests/test_failures.py` (маркер `fault`), фикстуры + hook и тесного API в `conftest.py`, `api_client.py` при необходимости; + `spec_coverage.py` — удаление 13 исключений; итог сверки покрытия + называет число сценариев, покрытых проверками отказов. +- Инструменты: `student-tests/run_failures.py` (оркестратор, stdlib), + `student-tests/fault_hook.py` (hook, stdlib, исполняемый), + `student-tests/failures.compose.yml` (override: без публикации + портов); `Makefile` — цель `failure_checks`; `pyproject.toml` — + маркер `fault` и его исключение из обычного прогона. +- Код приложения, контракт и compose рабочего стенда не меняются. +- Документы: правила `student-tests.md`, `run-modes.md`; `AGENTS.md` + (команды, карта кода, «Переходное состояние» — пункт про + `failure-checks` закрывается); скилл; `REPORT.md` — строки уровня «4» + про автоматические проверки и `make failure_checks` в «Проверках»; + `evidence/tests/failure-checks.md`. diff --git a/openspec/changes/failure-checks/specs/student-tests/spec.md b/openspec/changes/failure-checks/specs/student-tests/spec.md new file mode 100644 index 00000000..d13f7c20 --- /dev/null +++ b/openspec/changes/failure-checks/specs/student-tests/spec.md @@ -0,0 +1,145 @@ +# Spec Delta + +## ADDED Requirements + +### Requirement: Проверки отказов на отдельном стенде + +Сценарии отказов SHALL проверяться автоматически одной командой +`make failure_checks`: +- сессии: «Истёкший токен», «Срок не продлевается», «БД остановлена при + запросе с токеном»; +- `data-storage`: «Сбой при добавлении участников», «БД остановлена», + «БД вернулась», «Соединения исчерпаны»; +- `health`: «Хранилище не готово», «Кэш недоступен»; +- `chat-cache`: «Valkey остановлен», «Valkey завис», «Valkey вернулся», + «Очистка кэша». + +Команда SHALL: +- собрать образ из рабочего дерева; +- поднять отдельный стенд со своими PostgreSQL и Valkey, применить + миграции; +- запустить API с настройками по умолчанию и API с коротким сроком + сессии и пулом из одного соединения; +- выполнить проверки отказов; +- удалить стенд вместе с его данными при любом исходе. + +Порты PostgreSQL и Valkey этого стенда MUST NOT публиковаться на хосте, +API — только на `127.0.0.1`. Рабочий стенд, его база, кэш и контейнеры +MUST NOT затрагиваться. Код выхода SHALL быть ненулевым, если не прошла +хотя бы одна проверка или уборка. + +#### Scenario: Успешный прогон + +- **WHEN** рабочий стенд запущен, и выполнен `make failure_checks` +- **THEN** все проверки отказов прошли, код выхода 0, контейнеров и + volume стенда отказов после команды нет, а у контейнеров рабочего + стенда прежнее время старта, и рабочий API отвечает + +#### Scenario: Упавшая проверка + +- **WHEN** во время `make failure_checks` падает хотя бы одна проверка +- **THEN** код выхода ненулевой, журналы API стенда отказов выведены, + стенд отказов удалён + +#### Scenario: Прерывание + +- **WHEN** `make failure_checks` прерван Ctrl+C +- **THEN** стенд отказов остановлен и удалён вместе с volume + +#### Scenario: Хвост прошлого прогона + +- **WHEN** контейнеры или volume стенда отказов остались от прогона, + убитого без уборки +- **THEN** следующий `make failure_checks` удаляет их и начинает заново + +## MODIFIED Requirements + +### Requirement: Запуск одной командой + +Набор, кроме проверок отказов (требование «Проверки отказов на +отдельном стенде»), SHALL запускаться одной командой `make student_test` +против сервера по адресу `BASE_URL`, по умолчанию +`http://localhost:8080`. Команда SHALL завершаться с кодом 0, только +если прошли все тесты. Если сервер по `BASE_URL` не отвечает, набор +MUST завершаться с ненулевым кодом и сообщением о недоступности адреса, +а не множеством ошибок отдельных тестов. + +#### Scenario: Все тесты прошли + +- **WHEN** сервер запущен и `make student_test` выполняется без + аргументов +- **THEN** все тесты, кроме проверок отказов, проходят, команда + завершается с кодом 0, а проверки отказов в прогоне не выполняются + +#### Scenario: Другой адрес + +- **WHEN** выполняется `make student_test BASE_URL=http://localhost:8090` +- **THEN** тесты обращаются к `http://localhost:8090` + +#### Scenario: Сервер не запущен + +- **WHEN** по `BASE_URL` никто не слушает +- **THEN** команда завершается с ненулевым кодом, а вывод называет + недоступный адрес + +### Requirement: Только по HTTP + +Тесты SHALL обращаться к сервису только по HTTP и MUST NOT импортировать +код приложения, запускать или останавливать сервер. Проверки отказов +SHALL действовать на хранилища стенда и узнавать их состояние только +через hook, который им передаёт `make failure_checks`. Без hook они +MUST завершаться ошибкой с указанием этой команды, а не обращаться к +хранилищам сами. Один и тот же набор SHALL проходить против сервера, +запущенного на хосте, и против контейнера. + +#### Scenario: Консоль и контейнер + +- **WHEN** набор запускается сначала против `make run_dev`, затем против + `make run_docker` +- **THEN** оба прогона проходят одинаково + +#### Scenario: Проверка отказа без hook + +- **WHEN** проверки отказов запущены pytest напрямую, без + `make failure_checks` +- **THEN** они завершаются ошибкой, которая называет `make + failure_checks`, и ни одно хранилище не останавливается + +### Requirement: Покрытие сценариев основных спеков + +Для каждого сценария основных спеков `api-conventions`, +`identification`, `sessions`, `users`, `chats`, `messages`, +`pagination`, `data-storage`, `chat-cache` и `health`, который +воспроизводится по HTTP против работающего сервера, в том числе на +стенде отказов, SHALL быть тест. Из имени или описания теста SHALL быть +понятно, какой capability и сценарий он проверяет. Сценарий, который +проверяет тест отказа, SHALL считаться покрытым, хотя `make +student_test` этот тест не выполняет; итог сверки SHALL называть, сколько +сценариев покрыто проверками отказов. Сценарии, которые по HTTP не +воспроизвести, SHALL быть перечислены с причиной и способом проверки. + +#### Scenario: Сверка покрытия + +- **WHEN** проверяющий берёт любой сценарий перечисленных спеков +- **THEN** находится проверяющий его тест либо запись в списке + исключений с причиной + +#### Scenario: Сценарий отказа в сверке + +- **WHEN** выполняется `make student_test` +- **THEN** сверка считает сценарии проверок отказов покрытыми, не + требует для них исключений и печатает их число + +### Requirement: Результат прогона сохраняется + +Вывод прогона против контейнера (`make test_isolated`) и вывод `make +failure_checks` SHALL сохраняться в `evidence/` с командой, датой, +commit, адресом стенда и итогом. `REPORT.md` SHALL ссылаться на них в +строках уровня «4»: собственные тесты, 100 сообщений от 10 клиентов и +автоматические проверки истечения сессии и недоступности БД и Valkey. + +#### Scenario: Доказательство в отчёте + +- **WHEN** проверяющий открывает строку уровня «4» в `REPORT.md` +- **THEN** в ней есть команда, наблюдаемый результат и путь к файлу + вывода в `evidence/` diff --git a/openspec/changes/failure-checks/tasks.md b/openspec/changes/failure-checks/tasks.md new file mode 100644 index 00000000..5ab65f49 --- /dev/null +++ b/openspec/changes/failure-checks/tasks.md @@ -0,0 +1,90 @@ +# Tasks + +Как строить — `design.md` (дальше «решение N»), что должно получиться — +дельта `specs/student-tests/spec.md`. Перед первым файлом слоя прочитать +его правило: `student-tests.md`, `run-modes.md`, `docker.md`. Evidence +снимается с закоммиченного кода, коммит — только после подтверждения +пользователя (`bench.md`, «Измеренное состояние — commit»). + +## 1. Стенд отказов и hook + +- [x] 1.1 `student-tests/failures.compose.yml` — override без публикации + портов `postgres`, `valkey`, `api` (решение 1). Проверка: `docker + compose -p mtusi-lab2-failures -f docker-compose.yml -f + student-tests/failures.compose.yml config` — у сервисов нет `ports`, + volume `mtusi-lab2-failures_postgres_data`. +- [x] 1.2 `student-tests/fault_hook.py` — действия из таблицы решения 3, + отказ без `FAULT_PROJECT` и при совпадении с рабочим проектом, + исполняемый бит. Проверка: без `FAULT_PROJECT` и с + `FAULT_PROJECT=mtusi-lab2` — код 2 и ни одной команды docker; на + поднятом вручную проекте отказов каждое действие отрабатывает + (`stop`/`start`, `pause`/`unpause`, `cache-hits`, `fail-members` → + вставка участников падает, `clear-fail-members` → проходит). +- [x] 1.3 `student-tests/run_failures.py` и цель `failure_checks` в + `Makefile` (решения 2, 5): уборка хвоста, сборка, стенд, миграции, + два API на свободных портах, `pytest -m fault`, журналы при провале, + уборка в `finally`, защита от имени рабочего проекта. Проверка: `make + -n failure_checks`; прогон с пустым набором (`-k nothing`) — стенд + поднимается и удаляется, `docker volume ls` без + `mtusi-lab2-failures_*`; Ctrl+C во время прогона — уборка доходит до + конца. + +## 2. Проверки отказов + +- [x] 2.1 Маркер `fault` в `pyproject.toml`, `-m "not fault"` в + `addopts`; фикстуры `stand` и `tight_api`, остановка прогона без + `FAULT_HOOK` (решение 4). Проверка: `uv run pytest -m fault` без + оркестратора — код 2 и текст про `make failure_checks`; `make + student_test` — тесты `fault` в `deselected`. +- [x] 2.2 `student-tests/test_failures.py`: сценарии `sessions` + («Истёкший токен», «Срок не продлевается», «БД остановлена при запросе + с токеном») и `data-storage` («Сбой при добавлении участников», «БД + остановлена», «БД вернулась», «Соединения исчерпаны»), маркеры `spec` + и `fault`, восстановление хранилища в `finally`. Проверка: `make + failure_checks` — проверки проходят. Временная порча приложения + (например, 500 вместо 503 в `get_db_session`) роняет «БД остановлена» + и не попадает в коммит. +- [x] 2.3 Сценарии `health` («Хранилище не готово», «Кэш недоступен») и + `chat-cache` («Valkey остановлен», «Valkey завис», «Valkey вернулся», + «Очистка кэша») с границами времени из решения 4. Проверка: `make + failure_checks` — проходят. Временный клиент с повторами redis-py по + умолчанию роняет «Valkey завис» и в коммит не попадает. +- [x] 2.4 Сверка покрытия (решение 6): 13 записей `EXCLUDED` удалены, + `Collected` различает тесты `fault`, итог печатает их число. + Проверка: `make student_test` — `test_coverage.py` проходит, строка + `coverage:` называет число сценариев через `make failure_checks`; + `openspec validate --specs`. + +## 3. Документы и проверка кода + +- [x] 3.1 `/opsx:sync` дельты `student-tests`. Правила: + `student-tests.md` (выбранный механизм, hook, маркер `fault`), + `run-modes.md` (цель `failure_checks`); `AGENTS.md` — команды, карта + кода, «Переходное состояние» без пункта про `failure-checks`; скилл — + `make failure_checks` в разделе Test. Проверка: `grep -rn + "failure-checks" AGENTS.md .claude` — нет обещаний на будущее, только + описание сделанного. +- [x] 3.2 Финальная проверка: `make lint`, `make check`, `openspec + validate failure-checks --strict`, `make test_isolated` — код 0 (тесты + `fault` в нём не выполняются), `make failure_checks` — код 0, рабочий + стенд не перезапускался (`StartedAt`). Затем показать изменения, + предложить сообщение и после подтверждения закоммитить. + +## 4. Evidence и отчёт + +- [ ] 4.1 `evidence/tests/failure-checks.md` с закоммиченного кода + (решение 7). Проверка: в файле дата, commit, стенд, длительности + проверок, `StartedAt` рабочих контейнеров до и после; паролей и + токенов нет. +- [ ] 4.2 `REPORT.md`: + - `make failure_checks` в «Проверках» и «Сценарии защиты»; + - строки уровня «4» про автоматические проверки истечения сессии и + недоступности БД и Valkey, про атомарность создания чата (вместо + TODO) — со ссылкой на evidence; + - «Остальные пункты уровня 4» — только EXPLAIN. + + Проверка: у каждой строки таблицы доказательств есть команда, + наблюдение и файл. +- [ ] 4.3 `make lint`, `make check`, `openspec validate failure-checks + --strict`, `graphify update .`; показать изменения и после + подтверждения закоммитить evidence и отчёт. diff --git a/openspec/specs/student-tests/spec.md b/openspec/specs/student-tests/spec.md index 9ac8d4f6..b19342bf 100644 --- a/openspec/specs/student-tests/spec.md +++ b/openspec/specs/student-tests/spec.md @@ -11,18 +11,20 @@ ### Requirement: Запуск одной командой -Весь набор SHALL запускаться одной командой `make student_test` против -сервера по адресу `BASE_URL`, по умолчанию `http://localhost:8080`. -Команда SHALL завершаться с кодом 0, только если прошли все тесты. Если -сервер по `BASE_URL` не отвечает, набор MUST завершаться с ненулевым -кодом и сообщением о недоступности адреса, а не множеством ошибок -отдельных тестов. +Набор, кроме проверок отказов (требование «Проверки отказов на +отдельном стенде»), SHALL запускаться одной командой `make student_test` +против сервера по адресу `BASE_URL`, по умолчанию +`http://localhost:8080`. Команда SHALL завершаться с кодом 0, только +если прошли все тесты. Если сервер по `BASE_URL` не отвечает, набор +MUST завершаться с ненулевым кодом и сообщением о недоступности адреса, +а не множеством ошибок отдельных тестов. #### Scenario: Все тесты прошли - **WHEN** сервер запущен и `make student_test` выполняется без аргументов -- **THEN** все тесты проходят, команда завершается с кодом 0 +- **THEN** все тесты, кроме проверок отказов, проходят, команда + завершается с кодом 0, а проверки отказов в прогоне не выполняются #### Scenario: Другой адрес @@ -38,9 +40,12 @@ ### Requirement: Только по HTTP Тесты SHALL обращаться к сервису только по HTTP и MUST NOT импортировать -код приложения, запускать или останавливать сервер. Один и тот же набор -SHALL проходить против сервера, запущенного на хосте, и против -контейнера. +код приложения, запускать или останавливать сервер. Проверки отказов +SHALL действовать на хранилища стенда и узнавать их состояние только +через hook, который им передаёт `make failure_checks`. Без hook они +MUST завершаться ошибкой с указанием этой команды, а не обращаться к +хранилищам сами. Один и тот же набор SHALL проходить против сервера, +запущенного на хосте, и против контейнера. #### Scenario: Консоль и контейнер @@ -48,6 +53,13 @@ SHALL проходить против сервера, запущенного н `make run_docker` - **THEN** оба прогона проходят одинаково +#### Scenario: Проверка отказа без hook + +- **WHEN** проверки отказов запущены pytest напрямую, без + `make failure_checks` +- **THEN** они завершаются ошибкой, которая называет `make + failure_checks`, и ни одно хранилище не останавливается + ### Requirement: Независимость прогонов Каждый тест SHALL создавать собственных пользователей с уникальным @@ -136,10 +148,13 @@ SHALL проходить против сервера, запущенного н Для каждого сценария основных спеков `api-conventions`, `identification`, `sessions`, `users`, `chats`, `messages`, `pagination`, `data-storage`, `chat-cache` и `health`, который -воспроизводится по HTTP против работающего сервера, SHALL быть тест. Из -имени или описания теста SHALL быть понятно, какой capability и -сценарий он проверяет. Сценарии, которые по HTTP не воспроизвести, -SHALL быть перечислены с причиной и способом проверки. +воспроизводится по HTTP против работающего сервера, в том числе на +стенде отказов, SHALL быть тест. Из имени или описания теста SHALL быть +понятно, какой capability и сценарий он проверяет. Сценарий, который +проверяет тест отказа, SHALL считаться покрытым, хотя `make +student_test` этот тест не выполняет; итог сверки SHALL называть, сколько +сценариев покрыто проверками отказов. Сценарии, которые по HTTP не +воспроизвести, SHALL быть перечислены с причиной и способом проверки. #### Scenario: Сверка покрытия @@ -147,6 +162,12 @@ SHALL быть перечислены с причиной и способом п - **THEN** находится проверяющий его тест либо запись в списке исключений с причиной +#### Scenario: Сценарий отказа в сверке + +- **WHEN** выполняется `make student_test` +- **THEN** сверка считает сценарии проверок отказов покрытыми, не + требует для них исключений и печатает их число + ### Requirement: Проверка формы ответов Тесты SHALL проверять не только статус. @@ -163,10 +184,11 @@ SHALL быть перечислены с причиной и способом п ### Requirement: Результат прогона сохраняется -Вывод прогона против контейнера SHALL сохраняться в `evidence/` с -командой, датой, commit, адресом стенда и итогом. `REPORT.md` SHALL -ссылаться на него в строках уровня «4»: собственные тесты и 100 -сообщений от 10 клиентов. +Вывод прогона против контейнера (`make test_isolated`) и вывод `make +failure_checks` SHALL сохраняться в `evidence/` с командой, датой, +commit, адресом стенда и итогом. `REPORT.md` SHALL ссылаться на них в +строках уровня «4»: собственные тесты, 100 сообщений от 10 клиентов и +автоматические проверки истечения сессии и недоступности БД и Valkey. #### Scenario: Доказательство в отчёте @@ -222,3 +244,53 @@ MUST NOT затрагиваться, а карточки чатов тестов - **WHEN** выполнен `make test_isolated KEEP_TEST_DB=1` - **THEN** после прогона тестовый контейнер удалён, база `test_<db>` остаётся, а команда печатает её имя + +### Requirement: Проверки отказов на отдельном стенде + +Сценарии отказов SHALL проверяться автоматически одной командой +`make failure_checks`: +- сессии: «Истёкший токен», «Срок не продлевается», «БД остановлена при + запросе с токеном»; +- `data-storage`: «Сбой при добавлении участников», «БД остановлена», + «БД вернулась», «Соединения исчерпаны»; +- `health`: «Хранилище не готово», «Кэш недоступен»; +- `chat-cache`: «Valkey остановлен», «Valkey завис», «Valkey вернулся», + «Очистка кэша». + +Команда SHALL: +- собрать образ из рабочего дерева; +- поднять отдельный стенд со своими PostgreSQL и Valkey, применить + миграции; +- запустить API с настройками по умолчанию и API с коротким сроком + сессии и пулом из одного соединения; +- выполнить проверки отказов; +- удалить стенд вместе с его данными при любом исходе. + +Порты PostgreSQL и Valkey этого стенда MUST NOT публиковаться на хосте, +API — только на `127.0.0.1`. Рабочий стенд, его база, кэш и контейнеры +MUST NOT затрагиваться. Код выхода SHALL быть ненулевым, если не прошла +хотя бы одна проверка или уборка. + +#### Scenario: Успешный прогон + +- **WHEN** рабочий стенд запущен, и выполнен `make failure_checks` +- **THEN** все проверки отказов прошли, код выхода 0, контейнеров и + volume стенда отказов после команды нет, а у контейнеров рабочего + стенда прежнее время старта, и рабочий API отвечает + +#### Scenario: Упавшая проверка + +- **WHEN** во время `make failure_checks` падает хотя бы одна проверка +- **THEN** код выхода ненулевой, журналы API стенда отказов выведены, + стенд отказов удалён + +#### Scenario: Прерывание + +- **WHEN** `make failure_checks` прерван Ctrl+C +- **THEN** стенд отказов остановлен и удалён вместе с volume + +#### Scenario: Хвост прошлого прогона + +- **WHEN** контейнеры или volume стенда отказов остались от прогона, + убитого без уборки +- **THEN** следующий `make failure_checks` удаляет их и начинает заново diff --git a/pyproject.toml b/pyproject.toml index 640eae7d..e8002027 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -69,9 +69,12 @@ dev = [ testpaths = ["student-tests"] # каталог с дефисом не пакет: хелперы импортируются как модули pythonpath = ["student-tests"] -addopts = "-v -rP --strict-markers" +# проверки отказов (маркер fault) — только make failure_checks: там +# pytest -m fault перекрывает этот -m +addopts = "-v -rP --strict-markers -m 'not fault'" markers = [ "spec(capability, scenario): сценарий основного спека, который проверяет тест", + "fault: проверка отказа хранилища; нужен стенд make failure_checks и его hook", ] [tool.hatch.build.targets.wheel] diff --git a/student-tests/conftest.py b/student-tests/conftest.py index 53d73fdb..b3225571 100644 --- a/student-tests/conftest.py +++ b/student-tests/conftest.py @@ -1,7 +1,8 @@ """Настройка набора: адрес стенда, проверка доступности, фикстуры.""" import os -from collections.abc import Iterator +import subprocess +from collections.abc import Callable, Iterator from typing import Any import httpx @@ -11,6 +12,10 @@ from api_client import Actor, Api from spec_coverage import COLLECTED, Collected BASE_URL = os.environ.get("BASE_URL", "http://localhost:8080").rstrip("/") +# hook стенда отказов и «тесный» API задаёт make failure_checks +FAULT_HOOK = os.environ.get("FAULT_HOOK", "") +FAULT_TIGHT_BASE_URL = os.environ.get("FAULT_TIGHT_BASE_URL", "").rstrip("/") +FAULT_HOOK_TIMEOUT_S = 120 @pytest.hookimpl(tryfirst=True) @@ -22,15 +27,35 @@ def pytest_collection_modifyitems( collected = Collected() for item in items: collected.modules.add(item.path.name) + is_fault = item.get_closest_marker("fault") is not None for mark in item.iter_markers("spec"): if len(mark.args) != 2 or mark.kwargs: raise pytest.UsageError( f"{item.nodeid}: spec marker takes (capability, scenario)", ) collected.marks.setdefault(mark.args, []).append(item.nodeid) + if is_fault: + collected.fault.add(mark.args) config.stash[COLLECTED] = collected +@pytest.hookimpl(trylast=True) +def pytest_collection_finish(session: pytest.Session) -> None: + """Проверки отказов без стенда make failure_checks не запускаются. + + Выход до первого теста: без hook ни одно хранилище не трогается. + """ + selected = [ + item for item in session.items if item.get_closest_marker("fault") + ] + if selected and not (FAULT_HOOK and FAULT_TIGHT_BASE_URL): + pytest.exit( + "fault checks need the failure stand and its hook: " + "run make failure_checks", + returncode=2, + ) + + @pytest.fixture(scope="session", autouse=True) def _server_reachable() -> None: """Без сервера прогон останавливается одной строкой, а не 100 ошибками.""" @@ -80,3 +105,37 @@ def eve(api: Api) -> Actor: def chat(api: Api, alice: Actor, bob: Actor) -> dict[str, Any]: """Чат Алисы и Боба.""" return api.create_chat(alice, bob, title="Алиса и Боб") + + +@pytest.fixture(scope="session") +def stand() -> Callable[..., str]: + """Действие над стендом отказов через hook; возвращает его stdout. + + `stand("stop", "postgres")` — «стенд, останови postgres». Hook — + исполняемый файл, вызов без shell, как `ACTION_SCRIPT` в + `tests/resilience.py`. Сам тест docker не трогает. Не путать с + маркером `fault`: он только выбирает тесты (`-m fault`). + """ + + def call(*args: str) -> str: + result = subprocess.run( + [FAULT_HOOK, *args], + capture_output=True, + text=True, + timeout=FAULT_HOOK_TIMEOUT_S, + check=False, + ) + assert result.returncode == 0, ( + f"fault hook {' '.join(args)}: {result.stderr.strip()}" + ) + return result.stdout.strip() + + return call + + +@pytest.fixture(scope="session") +def tight_api() -> Iterator[Api]: + """API стенда отказов со сроком сессии 2 с и пулом из одного + соединения.""" + with Api(FAULT_TIGHT_BASE_URL) as client: + yield client diff --git a/student-tests/failures.compose.yml b/student-tests/failures.compose.yml new file mode 100644 index 00000000..91fec194 --- /dev/null +++ b/student-tests/failures.compose.yml @@ -0,0 +1,12 @@ +# Override стенда отказов make failure_checks (student-tests/run_failures.py): +# тот же docker-compose.yml под проектом mtusi-lab2-failures, со своим +# volume и сетью. Порты Postgres и Valkey не публикуются: к ним ходит только +# fault_hook.py через docker compose exec. Сервис api не запускается, +# контейнеры API создаёт оркестратор (docker compose run -p 127.0.0.1:...). +services: + postgres: + ports: !reset [] + valkey: + ports: !reset [] + api: + ports: !reset [] diff --git a/student-tests/fault_hook.py b/student-tests/fault_hook.py new file mode 100755 index 00000000..5370560c --- /dev/null +++ b/student-tests/fault_hook.py @@ -0,0 +1,249 @@ +#!/usr/bin/env python3 +"""Hook стенда отказов для проверок `fault` (`make failure_checks`). + +Тесты вызывают его как `[FAULT_HOOK, действие, аргументы…]` без shell — +так же `tests/resilience.py` вызывает `ACTION_SCRIPT`. Сами тесты docker +не трогают. Hook работает только с проектом compose из `FAULT_PROJECT`, +его задаёт `student-tests/run_failures.py`. Проект рабочего стенда hook +не трогает. Решение 3 design change `failure-checks`. + +Действия: + stop|start|pause|unpause postgres|valkey + flush-cache FLUSHALL + cache-hits keyspace_hits из INFO stats + cache-has-chat <chat_id> EXISTS ключа карточки: 0 или 1 + fail-members <title> вставка участников чата с этим названием + падает (триггер в базе стенда отказов) + clear-fail-members убрать триггер + count-chats <title> число чатов с этим названием + +Пароли не печатает: valkey-cli берёт пароль из VALKEYCLI_AUTH +контейнера, psql работает от POSTGRES_USER контейнера. Только stdlib. +""" + +from __future__ import annotations + +import json +import os +import subprocess +import sys +import time +import uuid +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +COMPOSE_FILES = ( + ROOT / "docker-compose.yml", + ROOT / "student-tests" / "failures.compose.yml", +) +PROJECT_SUFFIX = "-failures" +SERVICES = ("postgres", "valkey") +# та же проверка, что в healthcheck сервиса в docker-compose.yml +PROBES = { + "postgres": 'pg_isready -q -h 127.0.0.1 -U "$POSTGRES_USER" ' + '-d "$POSTGRES_DB"', + "valkey": 'test "$(valkey-cli -p "$VALKEY_PORT" ping)" = PONG', +} +PROBE_TIMEOUT_S = 30 +# начало ключа карточки — как CACHE_KEY_PREFIX приложения +CACHE_KEY_PREFIX = "messenger:v1" + +FAIL_MEMBERS_SQL = """\ +CREATE OR REPLACE FUNCTION fault_fail_members() RETURNS trigger +LANGUAGE plpgsql AS $$ +BEGIN + IF (SELECT title FROM chats WHERE id = NEW.chat_id) = TG_ARGV[0] THEN + RAISE EXCEPTION 'fault injected: chat members insert'; + END IF; + RETURN NEW; +END +$$; +DROP TRIGGER IF EXISTS fault_fail_members ON chat_members; +CREATE TRIGGER fault_fail_members BEFORE INSERT ON chat_members + FOR EACH ROW EXECUTE FUNCTION fault_fail_members(:'title'); +""" +CLEAR_FAIL_MEMBERS_SQL = """\ +DROP TRIGGER IF EXISTS fault_fail_members ON chat_members; +DROP FUNCTION IF EXISTS fault_fail_members(); +""" +COUNT_CHATS_SQL = "SELECT count(*) FROM chats WHERE title = :'title';\n" + + +class HookError(Exception): + """Неверный вызов или проект: код 2 и сообщение в stderr.""" + + +def working_project() -> str: + """Имя проекта рабочего стенда — из docker-compose.yml без `-p`.""" + result = subprocess.run( + ["docker", "compose", "config", "--format", "json"], + cwd=ROOT, + text=True, + capture_output=True, + check=True, + ) + return json.loads(result.stdout)["name"] + + +def fault_project() -> str: + project = os.environ.get("FAULT_PROJECT", "") + if not project.endswith(PROJECT_SUFFIX): + raise HookError( + f"FAULT_PROJECT must end with {PROJECT_SUFFIX!r}: " + "run make failure_checks", + ) + if project == working_project(): + raise HookError("FAULT_PROJECT is the working stand, refusing") + return project + + +def compose_run( + project: str, + *args: str, + stdin: str | None = None, +) -> subprocess.CompletedProcess[str]: + files = [arg for path in COMPOSE_FILES for arg in ("-f", str(path))] + return subprocess.run( + ["docker", "compose", "-p", project, *files, *args], + cwd=ROOT, + input=stdin, + text=True, + capture_output=True, + check=False, + ) + + +def compose(project: str, *args: str, stdin: str | None = None) -> str: + result = compose_run(project, *args, stdin=stdin) + if result.returncode != 0: + sys.stderr.write(result.stderr) + raise SystemExit(result.returncode) + return result.stdout.strip() + + +def wait_answers(project: str, name: str) -> str: + """Ждать, пока сервис ответит своей проверкой из healthcheck. + + После `unpause` Docker до следующего запуска healthcheck (до 5 с) + показывает `unhealthy`, и `up --wait` сразу выходит с ошибкой, хотя + сервис уже отвечает. Поэтому проверка — напрямую. + """ + deadline = time.monotonic() + PROBE_TIMEOUT_S + while time.monotonic() < deadline: + probe = compose_run( + project, + "exec", + "-T", + name, + "sh", + "-c", + PROBES[name], + ) + if probe.returncode == 0: + return "" + time.sleep(0.2) + raise HookError(f"{name} does not answer in {PROBE_TIMEOUT_S}s") + + +def valkey(project: str, *args: str) -> str: + # аргументы — позиционные параметры sh, без подстановки в строку + return compose( + project, + "exec", + "-T", + "valkey", + "sh", + "-c", + 'exec valkey-cli -p "$VALKEY_PORT" "$@"', + "sh", + *args, + ) + + +def psql(project: str, sql: str, *, title: str = "") -> str: + return compose( + project, + "exec", + "-T", + "postgres", + "sh", + "-c", + 'exec psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -XAtq ' + '-v ON_ERROR_STOP=1 -v title="$1"', + "sh", + title, + stdin=sql, + ) + + +def service(name: str) -> str: + if name not in SERVICES: + raise HookError(f"service must be one of {SERVICES}") + return name + + +def wait_healthy(project: str, name: str) -> str: + # тот же контейнер, без пересоздания; --wait ждёт его healthcheck + return compose(project, "up", "-d", "--wait", "--no-recreate", name) + + +def cache_hits(project: str) -> str: + for line in valkey(project, "INFO", "stats").splitlines(): + if line.startswith("keyspace_hits:"): + return line.split(":", 1)[1].strip() + raise HookError("keyspace_hits not found in INFO stats") + + +def cache_has_chat(project: str, chat_id: str) -> str: + database = compose( + project, + "exec", + "-T", + "postgres", + "printenv", + "POSTGRES_DB", + ) + key = f"{CACHE_KEY_PREFIX}:{database}:chat:{uuid.UUID(chat_id)}" + return valkey(project, "EXISTS", key) + + +def run(project: str, action: str, args: list[str]) -> str: + """Выполнить действие; синтаксис без match: hook запускают и 3.9.""" + if action in ("stop", "pause") and len(args) == 1: + return compose(project, action, service(args[0])) + if action == "start" and len(args) == 1: + return wait_healthy(project, service(args[0])) + if action == "unpause" and len(args) == 1: + compose(project, "unpause", service(args[0])) + return wait_answers(project, args[0]) + if action == "flush-cache" and not args: + return valkey(project, "FLUSHALL") + if action == "cache-hits" and not args: + return cache_hits(project) + if action == "cache-has-chat" and len(args) == 1: + return cache_has_chat(project, args[0]) + if action == "fail-members" and len(args) == 1: + return psql(project, FAIL_MEMBERS_SQL, title=args[0]) + if action == "clear-fail-members" and not args: + return psql(project, CLEAR_FAIL_MEMBERS_SQL) + if action == "count-chats" and len(args) == 1: + return psql(project, COUNT_CHATS_SQL, title=args[0]) + raise HookError(f"unknown action or arguments: {action} {args}") + + +def main() -> int: + if len(sys.argv) < 2: + print(__doc__, file=sys.stderr) + return 2 + try: + output = run(fault_project(), sys.argv[1], sys.argv[2:]) + except (HookError, ValueError) as e: + print(f"fault_hook: {e}", file=sys.stderr) + return 2 + if output: + print(output) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/student-tests/run_failures.py b/student-tests/run_failures.py new file mode 100644 index 00000000..6a0afda6 --- /dev/null +++ b/student-tests/run_failures.py @@ -0,0 +1,258 @@ +"""`make failure_checks`: проверки отказов на отдельном стенде. + +Поднимает тот же `docker-compose.yml` под проектом `<рабочий>-failures` +с override `student-tests/failures.compose.yml`: свои PostgreSQL и Valkey +со своим volume, порты хранилищ не публикуются. Затем: +- собирает образ из рабочего дерева и применяет миграции; +- запускает два контейнера API: обычный и «тесный» (срок сессии 2 с, пул + из одного соединения); +- прогоняет тесты с маркером `fault` (`pytest -m fault`), передав им hook + `student-tests/fault_hook.py`; +- удаляет стенд вместе с volume при любом исходе, в том числе по Ctrl+C. + +Рабочий стенд, его база и кэш не затрагиваются. Только stdlib. Решения +1, 2, 5 design change `failure-checks`. Запускается `$(PYTHON)`, а не +`uv run`, по той же причине, что `run_isolated.py`. +""" + +from __future__ import annotations + +import json +import os +import signal +import socket +import subprocess +import sys +import time +import urllib.error +import urllib.request +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +ENV_FILE = ROOT / ".env" +COMPOSE_FILES = ( + ROOT / "docker-compose.yml", + ROOT / "student-tests" / "failures.compose.yml", +) +FAULT_HOOK = ROOT / "student-tests" / "fault_hook.py" +PROJECT_SUFFIX = "-failures" +READY_TIMEOUT_S = 60 +LOG_TAIL_LINES = 50 +# «тесный» API: короткий срок сессии и пул из одного соединения +TIGHT_ENV = { + "AUTH__SESSION_TTL_SECONDS": "2", + "DATABASE__POOL_SIZE": "1", + "DATABASE__MAX_OVERFLOW": "0", + "DATABASE__POOL_TIMEOUT_SECONDS": "1", + "DATABASE__REQUEST_TIMEOUT_SECONDS": "2", +} + + +def say(message: str) -> None: + print(f"[failure_checks] {message}", flush=True) + + +def run( + *args: str, + check: bool = True, + quiet: bool = False, + env: dict[str, str] | None = None, +) -> subprocess.CompletedProcess[str]: + """Команда из корня репозитория; вывод — в терминал, если не quiet.""" + return subprocess.run( + args, + cwd=ROOT, + check=check, + text=True, + capture_output=quiet, + env=env, + ) + + +def dc( + project: str, + *args: str, + check: bool = True, + quiet: bool = False, +) -> subprocess.CompletedProcess[str]: + """docker compose проекта отказов; без `-p` не вызывается никогда.""" + files = [arg for path in COMPOSE_FILES for arg in ("-f", str(path))] + return run( + "docker", + "compose", + "-p", + project, + *files, + *args, + check=check, + quiet=quiet, + ) + + +def working_project() -> str: + config = run("docker", "compose", "config", "--format", "json", quiet=True) + return json.loads(config.stdout)["name"] + + +def app_port() -> str: + """`APP__PORT` из `.env`: на нём слушает API внутри контейнера.""" + if ENV_FILE.exists(): + for line in ENV_FILE.read_text(encoding="utf-8").splitlines(): + if line.strip().startswith("APP__PORT="): + return line.split("=", 1)[1].strip() + return "8080" + + +def free_port() -> int: + with socket.socket() as sock: + sock.bind(("127.0.0.1", 0)) + return sock.getsockname()[1] + + +def wait_ready(url: str, container: str) -> None: + deadline = time.monotonic() + READY_TIMEOUT_S + while time.monotonic() < deadline: + try: + with urllib.request.urlopen(url, timeout=2) as response: + if response.status == 200: + return + except (urllib.error.URLError, OSError): + pass + state = run( + "docker", + "inspect", + "-f", + "{{.State.Running}}", + container, + check=False, + quiet=True, + ) + if state.stdout.strip() != "true": + raise RuntimeError(f"container {container} is not running") + time.sleep(1) + raise RuntimeError(f"{url} not ready in {READY_TIMEOUT_S}s") + + +def cleanup(project: str, containers: list[str]) -> bool: + """Контейнеры API, сервисы и volume проекта отказов; True — чисто.""" + for name in containers: + run("docker", "rm", "-f", name, check=False, quiet=True) + down = dc(project, "down", "-v", "--remove-orphans", check=False) + left = run( + "docker", + "volume", + "ls", + "-q", + "--filter", + f"label=com.docker.compose.project={project}", + quiet=True, + check=False, + ) + return down.returncode == 0 and not left.stdout.strip() + + +def start_api( + project: str, + name: str, + port: int, + env: dict[str, str], +) -> str: + env_args = [ + arg for key, value in env.items() for arg in ("-e", f"{key}={value}") + ] + dc( + project, + "run", + "-d", + "--no-deps", + "--name", + name, + *env_args, + "-p", + f"127.0.0.1:{port}:{app_port()}", + "api", + quiet=True, + ) + base_url = f"http://127.0.0.1:{port}" + wait_ready(f"{base_url}/health/ready", name) + return base_url + + +def main() -> int: + pytest_args = sys.argv[1:] + working = working_project() + project = f"{working}{PROJECT_SUFFIX}" + if project == working or not project.endswith(PROJECT_SUFFIX): + say(f"refusing to use project {project!r}") + return 2 + default_name = f"{project}-api" + tight_name = f"{project}-api-tight" + containers = [default_name, tight_name] + + say(f"project={project} (working stand: {working})") + if not cleanup(project, containers): + say("leftovers of a previous run could not be removed") + return 1 + + results: dict[str, int] = {} + failed = True + try: + say("build image") + dc(project, "build", "api") + say("start postgres and valkey") + dc(project, "up", "-d", "--wait", "postgres", "valkey") + say("migrations") + dc(project, "run", "--rm", "migrate") + say("start api containers") + base_url = start_api(project, default_name, free_port(), {}) + tight_url = start_api(project, tight_name, free_port(), TIGHT_ENV) + say(f"ready: api={base_url} tight={tight_url}") + env = os.environ | { + "BASE_URL": base_url, + "FAULT_TIGHT_BASE_URL": tight_url, + "FAULT_HOOK": str(FAULT_HOOK), + "FAULT_PROJECT": project, + } + say("pytest -m fault") + results["fault"] = run( + "uv", + "run", + "pytest", + "-m", + "fault", + *pytest_args, + check=False, + env=env, + ).returncode + failed = bool(results["fault"]) + except KeyboardInterrupt: + say("interrupted") + results["interrupted"] = 130 + except (subprocess.CalledProcessError, RuntimeError) as e: + say(f"setup failed: {e}") + results["setup"] = 1 + finally: + # повторный Ctrl+C не должен оборвать уборку на полпути + signal.signal(signal.SIGINT, signal.SIG_IGN) + if failed: + for name in containers: + say(f"last {LOG_TAIL_LINES} lines of {name}") + run( + "docker", + "logs", + "--tail", + str(LOG_TAIL_LINES), + name, + check=False, + ) + say("cleanup") + if not cleanup(project, containers): + say("cleanup failed") + results["cleanup"] = 1 + + say(f"results: {results}") + return next((code for code in results.values() if code), 0) + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/student-tests/spec_coverage.py b/student-tests/spec_coverage.py index 3853a1e4..811a6fc3 100644 --- a/student-tests/spec_coverage.py +++ b/student-tests/spec_coverage.py @@ -57,26 +57,6 @@ EXCLUDED: dict[Scenario, Exclusion] = { reason="срок ключа виден только в Valkey", check="TTL ключа карточки через valkey-cli — evidence/cache/hits.md", ), - ("chat-cache", "Valkey остановлен"): Exclusion( - reason="нужно остановить Valkey, тесты стенд не трогают", - check="evidence/cache/outage.md; автоматическая проверка — " - "change failure-checks", - ), - ("chat-cache", "Valkey завис"): Exclusion( - reason="нужен docker compose pause для Valkey", - check="evidence/cache/outage.md: время ответа; автоматическая " - "проверка — change failure-checks", - ), - ("chat-cache", "Valkey вернулся"): Exclusion( - reason="нужно остановить и снова запустить Valkey", - check="evidence/cache/outage.md: warning и info в журнале, " - "ключи снова пишутся; автоматическая проверка — change " - "failure-checks", - ), - ("chat-cache", "Очистка кэша"): Exclusion( - reason="нужен FLUSHALL в Valkey, тесты стенд не трогают", - check="evidence/cache/flush-restart.md", - ), ("chat-cache", "Временная база"): Exclusion( reason="ключи видны только в Valkey, а набор не знает, на какой " "базе работает", @@ -89,38 +69,6 @@ EXCLUDED: dict[Scenario, Exclusion] = { "прежний токен читает те же данные — " "evidence/storage/test-persistence.md", ), - ("data-storage", "Сбой при добавлении участников"): Exclusion( - reason="нужен сбой БД посреди транзакции: штатным запросом его " - "не вызвать, участники проверяются до вставки", - check="одна транзакция и один commit в ChatService.create_chat; " - "автоматическая проверка отката — change failure-checks", - ), - ("data-storage", "БД остановлена"): Exclusion( - reason="нужно остановить Postgres, тесты стенд не трогают", - check="evidence/storage/db-unavailable.md; автоматическая " - "проверка — change failure-checks", - ), - ("data-storage", "БД вернулась"): Exclusion( - reason="нужно остановить и снова запустить Postgres", - check="evidence/storage/db-unavailable.md; автоматическая " - "проверка — change failure-checks", - ), - ("data-storage", "Соединения исчерпаны"): Exclusion( - reason="нужны пул из одного соединения и замороженный Postgres", - check="evidence/storage/pool-timeout.md; автоматическая " - "проверка — change failure-checks", - ), - ("health", "Хранилище не готово"): Exclusion( - reason="нужно остановить Postgres, тесты стенд не трогают", - check="evidence/storage/db-unavailable.md: /health/ready — 503, " - "/health/live — 200; автоматическая проверка — change " - "failure-checks", - ), - ("health", "Кэш недоступен"): Exclusion( - reason="нужно остановить Valkey, тесты стенд не трогают", - check="evidence/cache/outage.md: /health/ready — 200; " - "автоматическая проверка — change failure-checks", - ), ("identification", "Кнопка Authorize в Swagger"): Exclusion( reason="это интерфейс /docs в браузере", check="схемы bearerAuth и basicAuth, из которых строится кнопка, " @@ -132,27 +80,11 @@ EXCLUDED: dict[Scenario, Exclusion] = { check="поиск выданного токена по всем таблицам через psql — " "evidence/auth/passwords-and-tokens.md", ), - ("sessions", "Истёкший токен"): Exclusion( - reason="нужен сервис со сроком сессии 2 с, а обычный стенд — с 3600 с", - check="AUTH__SESSION_TTL_SECONDS=2 — evidence/auth/expiry.md; " - "автоматическая проверка — change failure-checks", - ), - ("sessions", "Срок не продлевается"): Exclusion( - reason="нужен сервис со сроком сессии 2 с", - check="запросы каждые 0,5 с при сроке 2 с — " - "evidence/auth/expiry.md; автоматическая проверка — change " - "failure-checks", - ), ("sessions", "Прежний токен после рестарта"): Exclusion( reason="нужен рестарт стенда, тесты сервер не трогают", check="make test-persistence ACTION_SCRIPT=scripts/restart.sh — " "evidence/storage/test-persistence.md", ), - ("sessions", "БД остановлена при запросе с токеном"): Exclusion( - reason="нужно остановить Postgres, тесты стенд не трогают", - check="evidence/auth/expiry.md; автоматическая проверка — " - "change failure-checks", - ), ("users", "Хэш в БД"): Exclusion( reason="нужен доступ к таблице users, а тесты ходят по HTTP", check="строки users через psql: префикс $argon2id$ и разные " @@ -163,10 +95,13 @@ EXCLUDED: dict[Scenario, Exclusion] = { @dataclass class Collected: - """Что собрал pytest: маркеры `spec` и модули тестов.""" + """Что собрал pytest: маркеры `spec`, модули тестов и сценарии, + которые проверяют тесты `fault` (их выполняет только + `make failure_checks`).""" marks: dict[Scenario, list[str]] = field(default_factory=dict) modules: set[str] = field(default_factory=set) + fault: set[Scenario] = field(default_factory=set) COLLECTED = pytest.StashKey[Collected]() diff --git a/student-tests/test_coverage.py b/student-tests/test_coverage.py index 0c782641..8bb40eab 100644 --- a/student-tests/test_coverage.py +++ b/student-tests/test_coverage.py @@ -34,10 +34,12 @@ def test_every_scenario_is_covered(request: pytest.FixtureRequest) -> None: scenarios = all_scenarios() problems = coverage_problems(scenarios, collected.marks, EXCLUDED) tested = len(scenarios & collected.marks.keys()) + # тесты fault выполняет только make failure_checks + by_fault = len(scenarios & collected.fault) print( f"coverage: {len(scenarios)} scenarios in " - f"{len(CAPABILITIES)} specs, {tested} tested, " - f"{len(EXCLUDED)} excluded", + f"{len(CAPABILITIES)} specs, {tested} tested " + f"({by_fault} by make failure_checks), {len(EXCLUDED)} excluded", ) assert not problems, "\n".join(problems) diff --git a/student-tests/test_failures.py b/student-tests/test_failures.py new file mode 100644 index 00000000..d98324d8 --- /dev/null +++ b/student-tests/test_failures.py @@ -0,0 +1,327 @@ +"""Проверки отказов: выполняет только `make failure_checks` (маркер `fault`). + +Стенд и hook готовит `student-tests/run_failures.py`: свои Postgres и +Valkey, обычный API (`BASE_URL`) и «тесный» (срок сессии 2 с, пул из +одного соединения). На хранилища тесты действуют только через фикстуру +`stand` (hook `student-tests/fault_hook.py`) и всегда возвращают их в +рабочее состояние. Решение 4 design change `failure-checks`. +""" + +import statistics +import threading +import time +import uuid +from collections.abc import Callable, Iterator +from contextlib import contextmanager +from typing import Any + +import httpx +import pytest + +from api_client import API, Actor, Api +from contract import ( + BEARER_CHALLENGE, + assert_error, + assert_ok, + assert_unauthorized, +) + +pytestmark = pytest.mark.fault + +type Stand = Callable[..., str] + +RESTORE = {"stop": "start", "pause": "unpause"} +# запас к границам времени: планировщик Docker Desktop +SLACK_S = 0.3 +# [cache] timeout_seconds и retry_after_seconds по умолчанию +CACHE_TIMEOUT_S = 0.2 +CACHE_RETRY_AFTER_S = 5 +# окружение «тесного» API (TIGHT_ENV в run_failures.py) +SESSION_TTL_S = 2 +POOL_TIMEOUT_S = 1 +# срок проверки Postgres в /health/ready +READINESS_TIMEOUT_S = 2 +ME = f"{API}/users/me" + + +@contextmanager +def outage(stand: Stand, action: str, service: str) -> Iterator[None]: + """`stop` или `pause` хранилища; в `finally` — обратно.""" + stand(action, service) + try: + yield + finally: + stand(RESTORE[action], service) + + +def timed( + call: Callable[[], httpx.Response], +) -> tuple[httpx.Response, float]: + started = time.monotonic() + resp = call() + return resp, time.monotonic() - started + + +def read_chat(api: Api, actor: Actor, chat: dict[str, Any]) -> httpx.Response: + return api.request("GET", f"{API}/chats/{chat['id']}", actor=actor) + + +def wait_cache_ready( + api: Api, + stand: Stand, + actor: Actor, + chat: dict[str, Any], +) -> None: + """Дождаться, пока чтение снова пишет карточку в кэш. + + После отказа в прошлом тесте API пропускает кэш ещё до 5 с. + """ + deadline = time.monotonic() + CACHE_RETRY_AFTER_S + 2 + stand("flush-cache") + while time.monotonic() < deadline: + assert_ok(read_chat(api, actor, chat), 200, "Chat") + if stand("cache-has-chat", chat["id"]) == "1": + return + time.sleep(0.5) + raise AssertionError("cache did not come back") + + +def chat_titles(api: Api, actor: Actor) -> set[str]: + return { + chat["title"] + for page in api.chat_pages(actor) + for chat in page["items"] + } + + +# --------------------------------------------------------------------------- +# Сессии: срок 2 с на «тесном» API, БД остановлена — на обычном +# --------------------------------------------------------------------------- + + +@pytest.mark.spec("sessions", "Истёкший токен") +def test_expired_token(tight_api: Api) -> None: + actor = tight_api.register() + assert_ok(tight_api.request("GET", ME, actor=actor), 200, "User") + time.sleep(SESSION_TTL_S + 1) + assert_unauthorized( + tight_api.request("GET", ME, actor=actor), + BEARER_CHALLENGE, + ) + + +@pytest.mark.spec("sessions", "Срок не продлевается") +def test_use_does_not_extend_session(tight_api: Api) -> None: + actor = tight_api.register() + logged_in = time.monotonic() + successes = 0 + while time.monotonic() - logged_in < SESSION_TTL_S - SLACK_S: + assert_ok(tight_api.request("GET", ME, actor=actor), 200, "User") + successes += 1 + time.sleep(0.5) + assert successes >= 3, "too few requests before expiry" + time.sleep(max(0.0, logged_in + SESSION_TTL_S + 1 - time.monotonic())) + assert_unauthorized( + tight_api.request("GET", ME, actor=actor), + BEARER_CHALLENGE, + ) + + +@pytest.mark.spec("sessions", "БД остановлена при запросе с токеном") +def test_token_while_database_stopped(api: Api, stand: Stand) -> None: + actor = api.register() + with outage(stand, "stop", "postgres"): + resp = api.request("GET", ME, actor=actor) + assert_error(resp, 503) + # недоступность хранилища — не отказ в аутентификации + assert "WWW-Authenticate" not in resp.headers + assert_ok(api.request("GET", ME, actor=actor), 200, "User") + + +# --------------------------------------------------------------------------- +# Хранение: откат, остановленная БД, исчерпанный пул +# --------------------------------------------------------------------------- + + +@pytest.mark.spec("data-storage", "Сбой при добавлении участников") +def test_members_failure_rolls_back_chat( + api: Api, + stand: Stand, + alice: Actor, + bob: Actor, +) -> None: + title = f"fault-{uuid.uuid4().hex}" + stand("fail-members", title) + try: + resp = api.request( + "POST", + f"{API}/chats", + actor=alice, + json={"title": title, "member_ids": [alice.id, bob.id]}, + ) + assert_error(resp, 500) + finally: + stand("clear-fail-members") + for actor in (alice, bob): + assert title not in chat_titles(api, actor) + assert stand("count-chats", title) == "0" + + +@pytest.mark.spec("data-storage", "БД остановлена") +@pytest.mark.spec("data-storage", "БД вернулась") +def test_database_stopped_and_back( + api: Api, + stand: Stand, + alice: Actor, + chat: dict[str, Any], +) -> None: + path = f"{API}/chats/{chat['id']}/messages" + with outage(stand, "stop", "postgres"): + resp, took = timed( + lambda: api.request( + "POST", + path, + actor=alice, + json={"text": "во время отказа"}, + ), + ) + error = assert_error(resp, 503) + assert took < 2, f"503 took {took:.2f}s" + for word in ("postgres", "sql", "connect"): + assert word not in error["message"].lower() + message = api.send_message(alice, chat["id"], "после возврата") + # запись во время отказа не зафиксирована, новая — видна + assert api.all_messages(alice, chat["id"]) == [message] + + +@pytest.mark.spec("data-storage", "Соединения исчерпаны") +def test_pool_exhausted(tight_api: Api, stand: Stand) -> None: + actor = tight_api.register() + holder = Api(str(tight_api.client.base_url), timeout=15) + first: list[int] = [] + + def hold_connection() -> None: + first.append(holder.request("GET", ME, actor=actor).status_code) + + with outage(stand, "pause", "postgres"): + thread = threading.Thread(target=hold_connection) + thread.start() + time.sleep(SLACK_S) + resp, took = timed(lambda: tight_api.request("GET", ME, actor=actor)) + assert_error(resp, 503) + assert took < POOL_TIMEOUT_S + 0.5, f"503 took {took:.2f}s" + thread.join() + holder.close() + assert first == [503] + # срок сессии 2 с мог истечь за время паузы: проверяем пул новым входом + fresh = tight_api.register() + assert_ok(tight_api.request("GET", ME, actor=fresh), 200, "User") + + +# --------------------------------------------------------------------------- +# Readiness +# --------------------------------------------------------------------------- + + +@pytest.mark.spec("health", "Хранилище не готово") +def test_readiness_without_database(api: Api, stand: Stand) -> None: + with outage(stand, "stop", "postgres"): + resp, took = timed(lambda: api.request("GET", "/health/ready")) + assert_error(resp, 503) + assert took < READINESS_TIMEOUT_S + 0.5, f"ready took {took:.2f}s" + live = api.request("GET", "/health/live") + assert live.status_code == 200 + assert api.request("GET", "/health/ready").status_code == 200 + + +@pytest.mark.spec("health", "Кэш недоступен") +def test_readiness_without_cache(api: Api, stand: Stand) -> None: + with outage(stand, "stop", "valkey"): + assert api.request("GET", "/health/ready").status_code == 200 + + +# --------------------------------------------------------------------------- +# Кэш карточки чата +# --------------------------------------------------------------------------- + + +@pytest.mark.spec("chat-cache", "Очистка кэша") +def test_flush_cache( + api: Api, + stand: Stand, + bob: Actor, + chat: dict[str, Any], +) -> None: + wait_cache_ready(api, stand, bob, chat) + stand("flush-cache") + assert stand("cache-has-chat", chat["id"]) == "0" + assert assert_ok(read_chat(api, bob, chat), 200, "Chat") == chat + assert stand("cache-has-chat", chat["id"]) == "1" + + +@pytest.mark.spec("chat-cache", "Valkey остановлен") +def test_valkey_stopped( + api: Api, + stand: Stand, + alice: Actor, + bob: Actor, + chat: dict[str, Any], +) -> None: + path = f"{API}/chats/{chat['id']}/messages" + sent = [api.send_message(alice, chat["id"], "до отказа")] + with outage(stand, "stop", "valkey"): + resp, took = timed(lambda: read_chat(api, bob, chat)) + assert assert_ok(resp, 200, "Chat") == chat + assert took < CACHE_TIMEOUT_S + SLACK_S, f"read took {took:.2f}s" + resp, took = timed( + lambda: api.request( + "POST", + path, + actor=alice, + json={"text": "во время отказа"}, + ), + ) + sent.append(assert_ok(resp, 201, "Message")) + assert took < CACHE_TIMEOUT_S + SLACK_S, f"send took {took:.2f}s" + assert api.all_messages(bob, chat["id"]) == sent + + +@pytest.mark.spec("chat-cache", "Valkey завис") +def test_valkey_paused( + api: Api, + stand: Stand, + bob: Actor, + chat: dict[str, Any], +) -> None: + wait_cache_ready(api, stand, bob, chat) + baseline = statistics.median( + timed(lambda: read_chat(api, bob, chat))[1] for _ in range(5) + ) + with outage(stand, "pause", "valkey"): + resp, took = timed(lambda: read_chat(api, bob, chat)) + assert assert_ok(resp, 200, "Chat") == chat + assert took < baseline + CACHE_TIMEOUT_S + SLACK_S, ( + f"read took {took:.2f}s, baseline {baseline:.3f}s" + ) + # окно пропуска: следующий запрос таймаута не ждёт + resp, took = timed(lambda: read_chat(api, bob, chat)) + assert assert_ok(resp, 200, "Chat") == chat + assert took < CACHE_TIMEOUT_S, f"second read took {took:.2f}s" + + +@pytest.mark.spec("chat-cache", "Valkey вернулся") +def test_valkey_back( + api: Api, + stand: Stand, + bob: Actor, + chat: dict[str, Any], +) -> None: + with outage(stand, "stop", "valkey"): + assert_ok(read_chat(api, bob, chat), 200, "Chat") + # API не перезапускался; кэш снова в работе после окна пропуска + time.sleep(CACHE_RETRY_AFTER_S + 0.5) + assert_ok(read_chat(api, bob, chat), 200, "Chat") + assert stand("cache-has-chat", chat["id"]) == "1" + hits = int(stand("cache-hits")) + assert assert_ok(read_chat(api, bob, chat), 200, "Chat") == chat + assert int(stand("cache-hits")) > hits