forked from mtusi2026/mtusi2026lab3
124 lines
20 KiB
Markdown
124 lines
20 KiB
Markdown
# Лабораторная 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 использовался при подготовке кода, проверок и документации.
|