Files
mtusi2026lab3/REPORT.md

19 KiB
Raw Permalink Blame History

Отчёт — лабораторная 3

  • Автор: Щербаков Марк Игоревич, БПИ2303.
  • Целевая оценка: «3». Уровни 4/5 не заявляются.
  • Ветка решения: solution/BPI2303-Scherbakov. PR создаётся отдельно после push.
  • Помощь ИИ: OpenAI Codex — изучение предыдущих работ, реализация, проверки и отчёт.

Запуск из чистого clone

Нужны Docker с Linux-контейнерами, Compose v2 и Python 3.12 для проверок. Из корня этой лабораторной, без зависимости от соседних каталогов:

python scripts/bootstrap.py
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
python scripts/check_contract.py
python tests/smoke.py --base-url http://localhost:8080

Bootstrap создаёт .env из .env.example, случайный пароль учебной БД в secrets/postgres_password и DSN в secrets/database_url. Существующие файлы сохраняются. Секреты исключены из Git и Docker build context. Миграции автоматически выполняет сервис migrate после готовности PostgreSQL, до запуска API. Его завершение Exited (0) — норма.

APP_PORT в .env задаёт публичный порт LB. На проверенном Windows-хосте привязка 8080 была запрещена, поэтому использован APP_PORT=18083. Для повторения результатов установите эту строку перед запуском и используйте http://127.0.0.1:18083 в тестах. При HTTP proxy добавьте localhost и 127.0.0.1 в NO_PROXY.

Полная проверка с реальными перезапусками и остановкой реплик:

python scripts/verify.py --base-url http://127.0.0.1:18083 --output evidence/grade3-checks.txt

Windows использует hooks restart.cmd и stop-one.cmd. Linux/macOS требуют:

chmod +x scripts/restart.sh scripts/stop-one.sh
make check test PYTHON=python BASE_URL=http://localhost:18083
make test-persistence PYTHON=python BASE_URL=http://localhost:18083 ACTION_SCRIPT=scripts/restart.sh
make test-failover PYTHON=python BASE_URL=http://localhost:18083 ACTION_SCRIPT=scripts/stop-one.sh
# После отдельного failover восстановить реплику:
docker compose --env-file .env up -d --wait api1 api2

Без Make на Windows, эквивалентные команды публичных сценариев:

python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:18083
python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://127.0.0.1:18083
docker compose --env-file .env up -d --wait api1 api2
$env:BASE_URL = 'http://127.0.0.1:18083'
python -m unittest discover -s student-tests -v

Полная валидация спецификации, отдельно от HTTP-проверок:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
.\.venv\Scripts\python.exe scripts/validate_openapi.py

Linux: .venv/bin/python вместо .venv\Scripts\python.exe. Штатная остановка: docker compose down, именованный volume сохраняется. Только для намеренного удаления всех учебных данных: docker compose down -v. В hooks и проверках эта команда не используется.

Архитектура и решения

flowchart LR
    C[Клиенты] --> LB[HAProxy / localhost:APP_PORT]
    LB --> A1[api1 / Python]
    LB --> A2[api2 / Python]
    A1 --> PG[(Общий PostgreSQL)]
    A2 --> PG
    M[Одноразовый migrate] --> PG
    PG --> V[postgres_data volume]

Из lab2 перенесены HTTP API, scrypt, сессии, HMAC cursor, pool, первая миграция, Dockerfile и собственные тесты. Lab2 уже сохраняла сессии в PostgreSQL, поэтому Redis/Valkey для уровня 3 не требуется. Из lab1 унаследованы HTTP-транспорт, валидация, пагинация и обработка SIGTERM. Папки lab1/lab2 не изменялись; контракт и публичные tests lab3 сохранены.

Добавлены HAProxy, две API-реплики, отдельный migration job, X-Instance-Id, таблица ключей сообщений и action scripts. В памяти API нет пользователей, чатов, истории, сессий или результатов POST. Пул соединений, копия общего ключа cursor и флаг остановки локальны; источник истины — PostgreSQL.

Роль Service / версия Готовность Состояние и доступ
Балансировщик lb / haproxy:3.0.11-alpine Активные HTTP-проверки backend Единственный публичный порт, только localhost
API 1 и 2 api1, api2 / python:3.12.12-slim-bookworm /health/ready: Docker каждые 5 с, LB каждую 1 с Отдельные процессы; без volume/публикации порта; DSN через secret
Миграции migrate / тот же Dockerfile Завершение с кодом 0 Отдельная команда python -m src.database
БД и сессии postgres / postgres:16.10-bookworm pg_isready каждые 2 с; API проверяет схему/таблицы postgres_data; только внутренняя сеть; пароль через secret

Runtime-зависимости закреплены в requirements.txt: psycopg и psycopg-pool 3.2.6, typing_extensions 4.16.0. API: по 1 CPU / 256 MiB; PostgreSQL: 1 CPU / 256 MiB; LB: 0,5 CPU / 128 MiB; migrate: 0,5 CPU / 128 MiB. API работает как UID 10001 с read-only FS.

APP_ENV — метка стартового лога; SESSION_TTL_SECONDS — абсолютный срок сессии, по умолчанию 3600 с. Внутренние APP_HOST=0.0.0.0, APP_PORT=8080, DATABASE_URL_FILE и INSTANCE_ID задаёт Compose. Внутренний порт не зависит от опубликованного. Для прямого запуска поддерживается DATABASE_URL. Неиспользуемые настройки Redis/числа реплик удалены из .env.example: здесь два явных сервиса, добавление третьего требует изменить Compose и LB.

Балансировка и остановка

Round robin без sticky session. Процесс один раз генерирует alias api1- или api2-, неизменный до остановки. X-Instance-Id формирует API для успешных ответов, ошибок и health. После рестарта alias меняется.

HAProxy проверяет GET /health/ready: inter 1s, fall 2, rise 1, timeout check 1s. При неизменной доступности DNS расчётный бюджет исключения зависшего backend — примерно до 4 с; это не гарантия для любого перегруженного хоста. TCP connect timeout 500 мс, backend timeout 5 с. Docker DNS 127.0.0.11 перепроверяется с hold valid 1s, поэтому LB обновляет IP заменённого контейнера. Readiness проверяет миграцию lab3 и доступность общих таблиц; критическая зависимость — PostgreSQL. Liveness проверяет процесс.

LB повторяет только ошибку установления соединения (conn-failure), с redispatch. Переданные POST чата/сессии прозрачно не повторяются. Неопределённый результат отправки сообщения клиент повторяет с исходным ключом. При SIGTERM API закрывает listener, отвечает 503 при наблюдаемом флаге остановки и ждёт потоки до 5 с; Compose даёт 7 с, stop hook — 6 с.

stop_one.py принимает только alias вида api[12]-<12 hex>, сопоставляет его с сервисом, через внутренний health сверяет текущий alias процесса и выполняет docker compose stop. Реплика остаётся остановленной. БД/LB hook не трогает. TARGET_INSTANCE_ID передаёт публичный тест; вручную нужен alias из ответа API.

Идемпотентность и транзакции

002_idempotency.sql создаёт message_keys: PK (user_id, chat_id, key), FK на сообщение, expires_at = часы БД + 24 ч. Таблица используется только для POST /api/v1/chats/{chat_id}/messages, поэтому метод и канонический путь однозначно заданы назначением таблицы и chat_id. Пользователи/чаты независимы.

Сначала проверяются Bearer и членство. POST блокирует строку чата FOR UPDATE, валидирует ключ [A-Za-z0-9._:-]{1,128} и JSON. Под блокировкой проверяется общий ключ: прежний text возвращает 201 и прежний Message, другой text — 409. Сравнение декодированного text делает JSON whitespace/escape несущественными. OpenAPI lab3 содержит только text; вложения появляются в lab4.

Если действующего ключа нет, INSERT сообщения и ключа выполняются в одной транзакции. HTTP 201 отправляется после COMMIT. Сбой до COMMIT откатывает оба INSERT, потеря ответа после COMMIT позволяет найти прежний результат на другой реплике. READ COMMITTED после ожидания блокировки видит предыдущий COMMIT. Ошибки не сохраняются как окончательный результат.

При следующем использовании истёкшего ключа старая запись ключа удаляется, сообщение остаётся; ключ можно применить для новой отправки. Массовой очистки нет. Порядок истории и подписанный cursor lab2 сохранены. Миграции под advisory lock, с checksum и без seed; API схему не меняют. Подробнее: infra/schema.md.

Доказательства критериев

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Воспроизводимый стенд bootstrap, compose up --build --wait, config --quiet Два реальных API, LB, БД, отдельный migrate compose.yaml; BEFORE_RESTART в протоколе
Публичный smoke python tests/smoke.py --base-url http://127.0.0.1:18083 PASS lab3 evidence/grade3-checks.txt
Общая сессия verify: одна сессия, ≥2 alias через LB Один пользователь на обеих репликах OBSERVED_INSTANCES
Конкурентная идемпотентность test_same_key_concurrent_across_replicas 12 одинаковых ответов 201 через 2 реплики; одна запись Протокол собственных тестов
Конфликт body и область ключа test_conflicting_bodies_race, test_key_scope_and_access 201+409; независимость пользователей/чатов; доступ при replay 14 собственных тестов, OK
Отказ любой API Два публичных failover + параллельный reader api1, затем api2 exited; новые записи за <10 с FAILOVER_RUN, AFTER_FAILOVER, CONCURRENT_READS
Сохранность и retry Публичный failover, повтор restart-key Подтверждённые сообщения не потеряны, дублей нет PASS failover; проверка прежнего Message
Полный рестарт Публичный persistence + inspect StartedAt четырёх контейнеров изменился; volume, токен и cursor сохранены BEFORE_RESTART / AFTER_RESTART
Ключ после рестарта Повтор restart-key Прежний Message и 201 PASS four containers restarted
Согласованные миграции Два повторных запуска migrate Семь счётчиков не изменились PASS repeated migrations
Полная схема scripts/validate_openapi.py PASS evidence/contracts.txt

Полный протокол: evidence/grade3-checks.txt. На Windows Make отсутствует: выполнены те же Python-команды. Linux hooks и Make включены в CI, удалённый CI не запускался.

Эксперименты и отказы

Проверки проведены 13 ноября 2026. Протокол содержит UTC, Москва UTC+3. Клиент: Windows / Python 3.12.0. Docker Engine 29.5.3; Linux VM: 8 CPU, 2 967 707 648 байт RAM; лимиты сервисов приведены выше. Адрес: localhost:18083.

Гипотеза: остановка любого API не уничтожает сессию или подтверждённое сообщение, общий ключ делает безопасным повтор на оставшейся реплике. Проверены readiness, smoke, 14 собственных тестов, повтор миграций, полный рестарт и два отказа. Конкурентный сценарий: 12 синхронизированных клиентов с одним ключом; другой сценарий: 40 разных сообщений от 8 потоков. Это проверки корректности.

При каждом failover один последовательный writer с паузой 100 мс работает 15 секунд, повторяет неопределённый POST с прежним ключом. Отдельный reader с паузой 100 мс работает также во время подготовки/сбора inspect: его числа относятся к более длинному интервалу. Специального прогрева нет.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Полный restart API, БД и LB Данные/сессия сохраняются PASS persistence; прежний cursor и replay Без потерь; в бюджете публичного теста 90 с
Остановка api1 Работа через api2 97 успешных POST / 0 ошибок, чтения 139 / 1 ошибка Первое успешное POST после hook: 3,359 с от его запуска; без потерь
Восстановление api1, остановка api2 Работа через api1 95 успешных POST / 1 ошибка, чтения 130 / 0 ошибок Первое успешное POST после hook: 3,016 с от его запуска; без потерь

first_recovery — не длительность полного простоя: часть запросов обслуживается всё время. Метрика включает запуск hook, Docker CLI, проверку alias и остановку. Допустимые переходные ошибки учтены; retry не создал дубль. Inspect доказывает реальную остановку выбранных процессов, а не только смену заголовка. После проверки обе API восстановлены. PostgreSQL подтверждает локальный COMMIT/WAL, это не репликация/backup. Предельный RPS, p50/p95/p99, rolling update и CPU/RAM под нагрузкой не исследовались и для оценки 3 не заявляются.

Ограничения и следующие шаги

Один Docker-host, один LB и один PostgreSQL — точки единого отказа. Выдерживается остановка одной API при работающей второй и доступной БД. Полный рестарт проверен на сохранность, а не на непрерывную доступность. Нет защиты от потери volume/host, репликации БД, backup, многоузлового failover, автоматического масштабирования и rolling update. Поток на запрос и сериализация отправок внутри чата ограничивают производительность. Требуется очистка старых сессий/ключей. HTTP предназначен для локальных синтетических данных.

Источники: контракт, HAProxy 3.0 configuration, HAProxy retries, Compose services, PostgreSQL row locks, psycopg transactions.