Files
mtusi2026lab3/REPORT.md
T

124 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Лабораторная 3 — отчёт
- Автор: Саламатин, БПИ-2304.
- Целевая оценка: **4**, весь минимум уровня 3 и все пункты уровня 4. Треки на 5 не выполнялись.
- Проверка: 1 ноября 2026 года, Europe/Moscow. В JSON используется UTC.
- Ветка: `solution/bpi-2304-salamatin`. Основа задания — commit `0ab3a34` репозитория `mtusi2026/mtusi2026lab3`.
- Сборка и обязательные проверки повторены из отдельного локального clone; проверенный commit `8846b05` записан в `evidence/clean-source.json`.
- Публикация: [fork gwalut/mtusi2026lab3](https://gitea.privcloud.tech/gwalut/mtusi2026lab3), [PR №85](https://gitea.privcloud.tech/mtusi2026/mtusi2026lab3/pulls/85) в `main` преподавателя.
- Перенесена собственная lab2 из [gwalut/mtusi2026lab2](https://gitea.privcloud.tech/gwalut/mtusi2026lab2), ветка `solution/bpi-2304-salamatin`. README задания, COURSE, contracts и публичные tests lab3 сохранены.
## Запуск
Нужны Docker Desktop с Linux containers и Docker Compose. Для полного автоматического прогона на хосте нужен Python 3.9+; Python приложения и зависимости устанавливаются в контейнере. На Windows текстовые проверки запускаются с `-X utf8`.
Из корня clone, PowerShell:
```powershell
python -X utf8 scripts/init_local.py
python -X utf8 scripts/verify.py
```
`verify.py` собирает образы, поднимает стенд, выполняет публичные и собственные тесты, полный restart, failover, expiry, проверку SQL-плана и нагрузочные эксперименты. Итог — `evidence/verification.json`. Данные не удаляются; стенд остаётся работающим. Тесты создают только синтетических пользователей и сообщения.
На текущем компьютере переносимый Python находится на уровень выше репозитория:
```powershell
..\.tools\python\python.exe -X utf8 scripts/verify.py
```
Для обычного запуска на Windows без установленного Python: `./start.ps1`. Скрипт создаёт конфигурацию через Python-контейнер, собирает и запускает Compose. Эквивалентные команды вручную:
```powershell
docker run --rm --mount "type=bind,source=$($PWD.Path),target=/work" --workdir /work python:3.13.15-slim-bookworm python scripts/init_local.py
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait --wait-timeout 120
curl.exe --noproxy "*" http://127.0.0.1:8080/health/ready
```
`init_local.py` создаёт `.env` и локальные случайные пароли/DSN/ключ cursor в `secrets/`. Существующие значения сохраняются и не печатаются. Эти файлы исключены из Git. Не удалять секреты при сохранённых volumes: пароль существующей PostgreSQL не меняется от замены файла.
По умолчанию опубликован только `127.0.0.1:8080` балансировщика. Для другого свободного порта изменить `API_PORT` в `.env` до запуска. `API_REPLICAS=2` задаёт число API, `SESSION_TTL_SECONDS=3600` — срок новых сессий, `APP_VERSION` — метку конфигурации; остальные runtime-настройки и пути секретов заданы в Compose. Приложение всегда слушает `0.0.0.0:8080` внутри контейнера.
Отдельные проверки:
```powershell
docker compose run --rm --no-deps checks make check test
docker compose run --rm --no-deps checks make test-student
docker compose run --rm --no-deps checks sh -ec 'chmod +x scripts/restart.sh; make test-persistence ACTION_SCRIPT=scripts/restart.sh'
docker compose run --rm --no-deps checks sh -ec 'chmod +x scripts/stop-one.sh; make test-failover ACTION_SCRIPT=scripts/stop-one.sh'
docker compose start api
docker compose run --rm --no-deps checks make explain
python -X utf8 scripts/experiments.py --base-url http://127.0.0.1:8080
```
После публичного failover реплика намеренно остаётся остановленной: восстановление выполняется отдельной командой `docker compose start api`. Полный `verify.py` делает это сам. После восстановления нужно дождаться готовности обеих реплик. На Linux для прямого запуска hooks: `chmod +x scripts/restart.sh scripts/stop-one.sh`.
Остановка с сохранением данных: `docker compose stop`, либо `docker compose down` для удаления контейнеров и сети с сохранением volumes. Только для намеренного удаления всех учебных данных: `docker compose down --volumes`. Эта команда не применяется в проверках отказа и restart.
## Реализация
Клиент → HAProxy → API × 2 → общие PostgreSQL и Redis. Используется один масштабируемый сервис `api` без `container_name`. API, БД и Redis не публикуют порты. Балансировка round-robin, без sticky sessions. Лимиты установлены у всех runtime-контейнеров, сервиса миграций и клиента проверок.
Из lab2 сохранены FastAPI, PostgreSQL-миграции, параметризованные запросы, ограниченный pool, scrypt, Basic при входе, Bearer-сессии в Redis с TTL/AOF, проверка членства, подписанные cursor и индекс истории. Добавлены `X-Instance-Id`, обязательный ключ отправки, таблица `message_requests`, HAProxy и сценарии отказа/замены.
Результат отправки и само сообщение сохраняются одной SQL-транзакцией. Блокировка строки чата синхронизирует разные процессы. Повтор валидного тела и ключа в течение 24 часов возвращает тот же Message с 201; другое тело — 409. Область ключа включает пользователя и чат; повтор заново проходит аутентификацию и проверку доступа. Ошибка транзакции не сохраняется как окончательный результат. История не кэшируется.
Readiness API требует обе зависимости. HAProxy проверяет его с `inter 1s`, `fall 2`, `rise 1`, `fastinter 500ms`, `timeout check/connect 1s`; консервативный бюджет обнаружения зависшего backend — до 4 s при штатном планировании. Docker DNS обновляет адреса, HAProxy поддерживает до восьми реплик. API обрабатывает SIGTERM через Uvicorn: закрытие listener, до 5 s на текущие запросы; Compose даёт 8 s. Общий HTTP-бюджет API — 5 s, таймаут HAProxy до backend — 6 s. Прозрачных повторов POST в LB нет.
Миграции выполняет отдельный сервис `migrate`; advisory lock и checksum предотвращают гонку/изменение применённого SQL. Для последовательной замены миграции проверяются один раз перед обновлением. 002 добавляет новую таблицу, 001 сохранена. Подробности: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), сценарий защиты — [docs/DEFENSE.md](docs/DEFENSE.md).
## Проверки критериев
| Критерий | Команда / сценарий | Результат | Доказательство в evidence/ |
| --- | --- | --- | --- |
| Обязательный API и переход lab2 → lab3 | `make test` через LB и smoke с хоста | PASS | `smoke.txt`, `published-smoke.txt` |
| Две настоящие реплики и общая сессия | Повтор `/users/me` с одним токеном; Docker inspect | Не менее двух instance ID и разных контейнеров | `student-tests.txt`, `verification.json` |
| Идемпотентность между репликами | 100 запросов, 10 клиентов, один ключ | Одно сообщение и одна запись результата | `idempotency.json` |
| Конфликт, область ключа, expiry и повтор после logout | Собственные интеграционные тесты | 409 / независимые ключи / новый результат после expiry / 401 | `student-tests.txt` |
| Атомарность сообщения и результата | SQL-trigger вызывает ошибку при INSERT результата | 503; обе записи откатились; повтор после устранения ошибки успешен | `student-tests.txt` |
| Полный перезапуск и сохранность | `make test-persistence` с реализованным hook | Старый токен и данные сохранены; volumes те же, StartedAt изменился у всех пяти контейнеров | `persistence.txt`, `restart.json` |
| Публичный failover | `make test-failover` | Две реплики до отказа; восстановление 2.064 s, 2 ошибки, 117 успешных записей | `failover.txt`, `last-stop.json` |
| Readiness, timeouts и SIGTERM | Healthchecks HAProxy, stop каждой API | Оба процесса завершились с exit code 0, записи продолжились менее чем за 10 s | `failure-api-1.json`, `failure-api-2.json` |
| Отказ каждой реплики с восстановлением предыдущей | `scripts/experiments.py` | Измерены RPS, ошибки, latency и время первой записи после остановки | `experiments.json` |
| Ресурсные лимиты и одна точка входа | Inspect всех runtime-контейнеров | CPU/RAM ограничены; опубликован только LB; API non-root | `verification.json` |
| Поочерёдная замена под нагрузкой | Drain → stop/remove → recreate, отдельно для каждой API | Два новых контейнера; 0 HTTP-ошибок; все 4475 подтверждений сохранены | `rolling-update.json` |
| Прежние проверки уровня 4 lab2 | 12 интеграционных тестов, TTL=2, EXPLAIN | PASS; 401 через 2.3 s; индекс на 10 000 сообщениях | `student-tests.txt`, `expiry.json`, `explain.txt` |
| Воспроизводимость из чистого clone | Независимые secrets, Compose-проект и первоначально пустые volumes, повтор обязательных проверок | PASS; исходники не изменены; отдельный порт 18083 | `clean-source.json`, `clean-verification.json`, `clean-build.txt`, `clean-student-tests.txt` |
| Сохранность контракта задания | Сравнение с исходным commit, SHA-256 после нормализации EOL | 15 файлов задания/контракта/публичных проверок без изменений | `source-integrity.json` |
## Измерения
Стенд: Windows, Docker Desktop 4.50.0/Engine 28.5.1, Linux x86_64. Docker VM: 16 логических CPU, около 7.47 GiB RAM. Лимиты: каждая API — 1 CPU/256 MiB, PostgreSQL — 1 CPU/512 MiB, Redis — 0.5 CPU/192 MiB, HAProxy — 0.5 CPU/128 MiB, checks — 1 CPU/256 MiB. Нагрузочный клиент работает на хосте; CPU/RAM компонентов во время нагрузки сохранены в JSON.
Версии образов: Python `3.13.15-slim-bookworm`, PostgreSQL `17.6-bookworm`, Redis `7.4.5-bookworm`, HAProxy `3.0.12-alpine`, Docker CLI проверок `28.5.1-cli`. Зависимости закреплены в `requirements.txt`; image ID фактического стенда записаны в JSON.
Перед каждой нагрузкой создаётся отдельный чат и подтверждённое сообщение; наблюдаются две реплики с одной сессией. Нагрузка closed-loop, четыре клиента, преимущественно отправка сообщений и периодическое чтение текущего пользователя. Воздействие начинается через 4 секунды. При неопределённом результате POST сохраняются ключ и тело. После опыта читаются все страницы истории: сверяются ID и тела всех подтверждений, проверяются дубли. Общий snapshot истории не требуется.
| Опыт | Длительность | Успешные RPS | Ошибок попыток | Первая запись после воздействия | p50 / p95 / p99, ms | Подтверждений сверено |
| --- | ---: | ---: | ---: | ---: | --- | ---: |
| Остановка первой API | 24.041 s | 105.235 | 51 (1.976%) | 1.715 s | 32.652 / 75.027 / 96.705 | 2350 |
| Остановка второй API | 24.034 s | 108.762 | 57 (2.134%) | 1.697 s | 32.088 / 65.561 / 97.489 | 2429 |
| Поочерёдная замена обеих API | 45.015 s | 107.276 | 0 | Запросы продолжались; замена заняла около 23.5 s | 28.249 / 82.882 / 127.075 | 4475 |
Краткие ошибки при резкой остановке допустимы: HAProxy ещё обнаруживает отказ. Они включены в счётчики, потерянных подтверждений и дублей не обнаружено. При управляемой замене backend сначала переводится в drain; в выполненном опыте ошибок не было. Поле `first_write_after_action_seconds` отсчитывается от начала действия до первой записи после завершения действия; для rolling оно включает длительность всей замены и **не означает 23.5 секунды простоя**.
В отдельном clone повторены сборка, публичный API, 12 тестов, полный restart, публичный failover, expiry и SQL-план. Нагрузочные опыты там не повторялись. Вспомогательный запуск TTL-контейнера один раз завис в Compose Desktop: скрипт теперь после таймаута проверяет точное имя, метки проекта/сервиса, TTL и состояние запущенного контейнера, затем всё равно выполняет HTTP-проверку истечения сессии. Итоговый повтор завершился PASS. Проверочный стенд остановлен без удаления volumes.
Это одиночные функциональные опыты, не исследование максимальной производительности. Первые 4 s нагрузки служат коротким прогревом и входят в общий RPS. Percentile рассчитаны только для успешных HTTP-операций; closed-loop ограничен клиентом и не показывает реальную очередь при фиксированной входящей интенсивности. Профиль и лимиты одинаковы для двух отказов. Сырые агрегаты, двухсекундные интервалы нагрузки, ошибки, состояния контейнеров и выборки CPU/RAM находятся в соответствующих JSON.
## Ограничения
Один host, одна БД, один Redis и один LB остаются точками отказа. Проверен отказ одной API-реплики, а не потеря host или любого хранилища. Сессии требуют сохранённого volume Redis. Backup/restore и треки на 5 не выполнялись. Просроченные ключи очищаются при повторном использовании; периодическая фоновая уборка не добавлена.
Проверена эквивалентная поочерёдная замена контейнеров того же приложения с `APP_VERSION=lab3-v2`, без изменения бизнес-кода между версиями. Совместимость произвольных будущих миграций не обещается; изменения схемы должны быть обратно совместимыми либо требовать отдельного окна обслуживания. Смешанный запуск старого lab2 и нового lab3 API не поддерживается из-за изменения обязательного контракта ключа.
Учебный стенд использует локальный HTTP и синтетические данные. У API нет UI; отдельные опыты масштабирования 1/2/4 и отказ нескольких узлов не заявляются.
## Источники
- [Задание lab3](https://gitea.privcloud.tech/mtusi2026/mtusi2026lab3), нормативный OpenAPI и публичные проверки.
- [HAProxy: DNS resolution](https://www.haproxy.com/documentation/haproxy-configuration-tutorials/proxying-essentials/dns-resolution/), [health checks](https://www.haproxy.com/documentation/haproxy-configuration-tutorials/reliability/health-checks/), [Runtime API](https://www.haproxy.com/documentation/haproxy-runtime-api/).
- [Docker Compose services](https://docs.docker.com/reference/compose-file/services/), [PostgreSQL locking](https://www.postgresql.org/docs/17/explicit-locking.html).
- Использованы FastAPI, Pydantic, Uvicorn, Psycopg, redis-py и стандартная библиотека Python. Codex использовался при подготовке кода, проверок и документации.