forked from mtusi2026/mtusi2026lab3
158 lines
14 KiB
Markdown
158 lines
14 KiB
Markdown
# Отчёт — лабораторная 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 различны.
|