Files
mtusi2026lab3/REPORT.md
T

158 lines
14 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
- Автор: Шурман А.Р., БПИ2302 (как в лабораторной 2).
- Целевая оценка: **4**, без треков на 5 и без UI.
- Ветка: `solution/bpi2302-shurman`. [PR #142](https://gitea.privcloud.tech/mtusi2026/mtusi2026lab3/pulls/142) из `aliska/mtusi2026lab3-fork` в исходный репозиторий. Реализация и проверки: `7da0348`.
- Основа: собственная лабораторная 2 (`mtusi2026lab2-fork`), исходный контракт и публичные тесты лабораторной 3. Помощь OpenAI Codex: реализация, проверки, отчёт.
- Библиотеки: FastAPI, Uvicorn, psycopg/pool, Argon2, redis-py; версии в `app/requirements.txt`.
## Запуск
Нужны Docker Desktop/Engine с Compose и Python 3.9+ для проверок.
Из корня этого репозитория:
```sh
python3 scripts/bootstrap.py
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
make check
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
docker compose start api
python3 student-tests/verify.py
```
После `up` дождаться ответа 200 от `http://localhost:8080/health/ready`.
После публичного failover запустить остановленную реплику командой `start api`;
собственный сценарий дожидается готовности обеих реплик перед экспериментами.
Публичный failover сам передаёт `TARGET_INSTANCE_ID` action-скрипту.
Ручная остановка: `TARGET_INSTANCE_ID=<hostname API из docker inspect> scripts/stop-one.sh`.
OpenAPI: `python3 -m venv .venv`, затем
`.venv/bin/python -m pip install -r requirements-dev.txt` и
`make validate PYTHON=.venv/bin/python`.
Безопасная остановка: `docker compose down` (volumes остаются).
Преднамеренное удаление учебных данных: `docker compose down -v` — только если
нужен полный сброс. При проверках эта команда не используется.
API и Swagger доступны через LB: http://localhost:8080/docs.
Порты API/БД/Valkey на хост не публикуются. Порт LB привязан к loopback.
Версии образов: Python 3.12.7, PostgreSQL 16.6, Valkey 8.0.2, HAProxy 3.0.5.
Bootstrap создаёт новые локальные secrets, не копирует пароли лабораторной 2,
не перезаписывает существующие файлы. Secrets и `.env` исключены из Git/build.
В `.env` используются `HOST_PORT` и `SESSION_TTL_SECONDS`.
Адреса БД/кэша передаются через `DATABASE_URL_FILE`/`CACHE_URL_FILE`.
Сессии всегда PostgreSQL, срок идемпотентности фиксирован 24 часа.
Число реплик задаётся `deploy.replicas: 2`; для изменения — `--scale api=N`.
Остальные переменные исходного `.env.example` — описание интерфейсов skeleton,
а не переключатели реализации.
## Архитектура
Клиент → HAProxy → две реплики одного Compose-service `api` → PostgreSQL.
Valkey — общий необязательный кэш неизменяемых профилей, как в лабораторной 2.
PostgreSQL хранит пользователей, чаты, участников, сообщения, сессии и ключи
идемпотентности. Локального состояния, влияющего на корректность, в API нет.
Пароли — Argon2id; токены 256 бит, в БД только hash и абсолютный expiry.
Сессия проверяется в БД при каждом запросе; недоступность Valkey даёт fallback.
История не кэшируется: подтверждённый COMMIT виден следующему чтению любой реплики.
Каждый ответ API (включая ошибки/health) имеет X-Request-Id и X-Instance-Id.
Instance ID — hostname реального контейнера. Один Uvicorn-процесс на контейнер.
HAProxy round-robin без sticky sessions; заголовки сопоставляются с docker inspect.
POST сообщения требует ключ ASCII длиной 1–128. Область ключа — пользователь,
чат и единственный endpoint POST сообщения. PostgreSQL advisory transaction lock
сериализует одинаковый ключ между процессами. Сообщение и результат ключа
сохраняются в одной транзакции; сбой откатывает оба изменения. Повтор возвращает
тот же Message/201, другой текст — 409. Проверка сессии/доступа выполняется снова.
5xx не сохраняются. Коллизия 64-битного lock только сериализует посторонние ключи,
но не смешивает данные: поиск/UNIQUE используют полную тройку значений.
Контракт lab3 принимает только `text`; вложения относятся к lab4.
## Готовность, таймауты и обновление
- Liveness проверяет процесс; readiness — доступность PostgreSQL и таблицы миграций.
- HAProxy: проверка раз в 1 s, timeout 1 s, `fall 2`, `rise 1`.
Консервативный бюджет обнаружения недоступного backend — до 4 s при нормальном
планировании. Это не гарантия при зависании хоста. DNS Docker обновляется с
`hold valid/obsolete 1s`, адреса не зафиксированы в конфигурации.
- HAProxy connect timeout 1 s, server timeout 10 s, client 15 s. Автоматических
повторов нет (`retries 0`), чтобы не дублировать POST создания чата/регистрации.
- Pool 1–8, ожидание до 3 s, SQL timeout 3 s, lock timeout 2 s. Кэш timeout 0.2 s.
- Uvicorn получает SIGTERM напрямую, закрывает listener, завершает активные
запросы (до 8 s), затем закрывает pool/cache. Docker даёт 10 s на остановку.
При попадании в закрывающийся backend допустима краткая ошибка; клиент повторяет
сообщение с прежним ключом. Исключение backend контролирует HAProxy, а не Compose.
- Docker healthcheck: каждые 5 s, timeout 4 s; он нужен для запуска/наблюдения.
Проверки маршрутизации независимо выполняет HAProxy каждую секунду.
Лимиты: каждая API/migrate 0.5 CPU/256 MiB, PostgreSQL 1 CPU/512 MiB,
Valkey 0.25 CPU/128 MiB, LB 0.5 CPU/128 MiB. `container_name` нет.
API non-root. Пароль PostgreSQL получает только БД; URL БД/кэша — API и мигратор.
LB не получает secrets. Сетевые зависимости доступны только в сети проекта.
Мигратор — отдельный завершённый сервис, до запуска API, с advisory lock и
checksum применённых SQL. Повторный запуск безопасен. Миграция 002 добавляет
таблицу, не меняя старые структуры. Для обновления: собрать новый образ,
`docker compose run --rm migrate`, затем `python3 scripts/rolling.py`.
Скрипт поочерёдно останавливает/заменяет каждую старую API-реплику и ждёт здоровья
новой, пока другая работает. Проверен эквивалент rolling update: замена обоих
контейнеров текущим образом под нагрузкой. Совместимость произвольных будущих
версий не заявляется: нужны обратно совместимые миграции; удаление колонок
потребует отдельного плана. В этой работе destructive migration нет.
## Проверки и результаты
Измерения 12.11.2026 на локальном Docker Desktop arm64, только синтетические данные.
Публичные `tests/`, `contracts/`, README и COURSE не изменены.
| Критерий | Проверка | Доказательство |
|---|---|---|
| Структура, OpenAPI, обязательный API | make check/validate/test | evidence/check.txt, validate.txt, smoke.txt |
| Данные и прежний токен после рестарта всех сервисов | test-persistence | evidence/persistence.txt, restart-containers.json |
| Две реальные реплики и отказ через LB | публичный test-failover | evidence/failover.txt |
| Один ключ одновременно на двух репликах | 16 параллельных POST, 1 Message | evidence/grade4.json |
| Последовательный отказ каждой реплики | 4 потока чтения/записи, восстановление предыдущей | evidence/grade4.json |
| Поочерёдная замена под нагрузкой | новые container IDs, чтение/запись продолжаются | evidence/grade4.json |
| Лимиты и отсутствие обходных портов | compose + inspect | evidence/containers.json |
`student-tests/verify.py` создаёт отдельный чат, проверяет гонку одного ключа,
затем поочерёдный отказ каждой реплики и замену обеих. Каждый эксперимент:
4 закрытых клиентских потока, прогрев 2 s, воздействие, ещё 5 s нагрузки;
одна итерация — POST сообщения + GET пользователя, пауза 20 ms.
RPS в `grade4.json` — успешные пары записи/чтения в секунду, не максимум системы.
При неопределённом результате повторяется тот же ключ. После каждого сценария
проверяется сохранность всех подтверждённых сообщений и отсутствие дубликатов.
`max_success_gap_seconds` — максимальный промежуток без успешных пар;
`first_success_after_action_seconds` отсчитывается от завершения action.
Публичный failover отдельно измеряет восстановление от начала action (бюджет 10 s).
Ошибки учитываются, процентили/throughput не объявляются production SLA.
Фактический прогон:
| Воздействие | Успешных пар/с | Ошибок | Максимальный разрыв между успехами |
|---|---:|---:|---:|
| Остановка первой API | 87.66 | 24 | 1.051 s |
| Остановка второй API | 81.78 | 25 | 1.055 s |
| Замена обеих API | 99.08 | 50 | 1.025 s |
Ошибки кратковременны во время обнаружения остановки, нулевая потеря HTTP-запросов
не заявляется. Все подтверждённые сообщения сохранены; повтор с прежним ключом
не создал дубликатов. Продолжительность экспериментов: 7.974 / 7.459 / 28.603 s.
Это один функциональный прогон, а не исследование масштабирования уровня 5.
Публичный failover: 2 наблюдаемых реплики, 116 успешных записей, 2 неудачные
попытки, восстановление за 1.682 s от начала action. Persistence прошёл с прежним
токеном; StartedAt всех пяти работающих контейнеров изменился.
Повторный запуск мигратора: Migrations OK (`evidence/migrations.txt`).
## Ограничения
Один LB, PostgreSQL и хост остаются точками отказа; отказ узла/диска не проверен.
HTTP разрешён только локально для учебных данных, для удалённого стенда нужен TLS.
Нет UI, файлов, брокера, треков на 5, фоновой очистки истёкших ключей/сессий.
Keyset pagination сортирует по `(created_at,id)`; на неизменной истории повторов
нет, но поздний COMMIT с более ранним временем может остаться за уже пройденным
cursor. Между страницами snapshot не сохраняется. Часы и порядок commit различны.