# Отчёт — лабораторная 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= 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 различны.