Files
mtusi2026lab3/REPORT.md
T

21 KiB
Raw Blame History

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

  • Автор, группа: Васюкова Наталья, БВТ2303
  • Целевая оценка: 4
  • Commit/PR: solution/BVT2303-Vasyukova
  • Использованные источники, библиотеки и помощь ИИ:
    • Контракт: contracts/openapi.json, contracts/README.md
    • Инструкции: README.md, COURSE.md, CONTRIBUTING.md
    • Библиотеки: fastapi==0.115.0, uvicorn[standard]==0.32.0, psycopg[binary]==3.2.3, psycopg_pool==3.2.3, redis==5.2.0, pydantic (из fastapi)
    • ИИ: DeepSeek — помощь в структурировании кода и отчёта. Весь код проверен, отредактирован и запущен разработчиком.

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

Версии runtime/образов:

  • Python: 3.12 (образ python:3.12-slim)
  • FastAPI 0.115.0, uvicorn[standard] 0.32.0, psycopg[binary] 3.2.3, psycopg_pool 3.2.3, redis 5.2.0
  • PostgreSQL 18.6-alpine, Redis 7.4.1-alpine, nginx 1.27.3-alpine (в Compose)
  • Docker Desktop (Windows)

Запуск стека

  1. Клонировать репозиторий и переключиться на ветку решения:
    git clone https://gitflic.ru/project/vasyukova-nat/mtusi2026lab3.git
    git checkout solution/BVT2303-Vasyukova
    
  2. Создать .env из шаблона:
    copy .env.example .env
    
  3. Собрать и поднять (LB + 2 реплики API + PostgreSQL + Redis):
    docker compose --env-file .env up -d --build
    
  4. Проверить готовность:
    curl.exe -s http://localhost:8080/health/ready
    
    Ожидается: {"status":"ok"}.

Все проверки ниже выполнялись с PYTHONUTF8=1 (Windows по умолчанию использует cp1251 и падает на чтении UTF-8 JSON):

$env:PYTHONUTF8="1"

Проверки

make в среде автора недоступен (Windows без GNU Make), поэтому использованы эквивалентные прямые вызовы скриптов. Для Linux/CI рядом указаны команды make.

Makefile-команда Прямой вызов
make check python scripts/check_contract.py
make validate python scripts/validate_openapi.py
make test python tests/smoke.py --base-url http://localhost:8080
make test-student python student-tests/lab3_test_level4.py --base-url http://localhost:8080
make test-persistence ACTION_SCRIPT=scripts/restart.sh python tests/resilience.py --mode persistence --action-script scripts/restart.bat --base-url http://localhost:8080
make test-failover ACTION_SCRIPT=scripts/stop-one.sh python tests/resilience.py --mode failover --action-script scripts/stop-one.bat --base-url http://localhost:8080

Проверка rolling update:

chmod +x scripts/rolling-update.sh
./scripts/rolling-update.sh

Остановка и удаление учебных данных

docker compose stop        # данные PostgreSQL и Redis сохраняются (volumes)
docker compose down        # volumes сохраняются
docker compose down -v     # ТОЛЬКО если осознанно стираем данные БД и Redis

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

Схема процессов и хранилищ:

                      ┌─ api-1 (uvicorn:8080, INSTANCE_ID=…)
HTTP-клиент → lb:80 ──┤                                     ↘
   (nginx)            └─ api-2 (uvicorn:8080, INSTANCE_ID=…)  PostgreSQL 18.6 (postgres:5432)
                                                              Redis 7.4.1 (redis:6379)

Все сервисы — в одной compose-сети mtuci2026lab3_default. Публично опубликован только порт LB 127.0.0.1:8080:80. Реплики api не имеют ports — трафик к ним идёт исключительно через LB. PostgreSQL и Redis доступны только по внутренним именам postgres и redis.

Источники истины:

  • PostgreSQL — данные (пользователи, чаты, членство, сообщения) и ключи идемпотентности.
  • Redis — серверные сессии (общие для всех реплик).

Схема БД (подробнее — src/app/storage/db.py, константа SCHEMA_SQL):

users(id UUID PK, username TEXT UNIQUE, display_name TEXT, password_hash TEXT, created_at TIMESTAMPTZ)
chats(id UUID PK, title TEXT, created_at TIMESTAMPTZ)
chat_members(chat_id FK→chats, user_id FK→users, PK(chat_id,user_id))
messages(id UUID PK, chat_id FK→chats, sender_id FK→users, text TEXT, created_at TIMESTAMPTZ)
  + INDEX idx_messages_chat_created(chat_id, created_at, id)
sessions(token TEXT PK, user_id FK→users, expires_at TIMESTAMPTZ)  -- fallback SESSION_STORE=postgres
idempotency_keys(user_id FK→users, method TEXT, path TEXT, key TEXT,
                 body_hash TEXT, response_status INT, response_body JSONB, created_at TIMESTAMPTZ,
                 PRIMARY KEY (user_id, method, path, key))
  + INDEX idx_idempotency_created(created_at)

Применяется идемпотентно через init_schema() на старте. Все временные метки — TIMESTAMPTZ.

Транзакционные границы:

  • create_user — SELECT-проверка username и INSERT в одной транзакции; при гонке UniqueViolation → 409.
  • create_chat — INSERT chats + INSERT chat_members в одной транзакции, откат целиком.
  • add_message — один INSERT, отдельная транзакция.
  • Создание/отзыв сессии — одна операция.

Дерево проекта (изменения относительно lab2 отмечены *)

mtuci2026lab3/
├── compose.yaml *            # + lb, api без container_name/ports, deploy.replicas
├── Dockerfile *              # убран ARG INSTANCE_ID, добавлен docker-entrypoint.sh
├── docker-entrypoint.sh *    # генерирует INSTANCE_ID, пишет /tmp/instance_id
├── infra/nginx.conf *        # vhost LB
├── Makefile
├── src/app/
│   ├── main.py *             # X-Instance-Id в middleware
│   ├── api/
│   │   └── messages.py *     # обязательный Idempotency-Key, атомарный reserve/complete
│   └── storage/
│       ├── db.py *           # + таблица idempotency_keys
│       └── postgres.py *     # + reserve_idempotency / complete_idempotency
├── scripts/
│   ├── restart.sh / .bat *   # + lb, обе реплики api
│   └── stop-one.sh / .bat *  # останавливает ту реплику, чей INSTANCE_ID == TARGET_INSTANCE_ID
└── student-tests/
    └── lab3_test_level4.py * # два X-Instance-Id, идемпотентность через реплики, отказ реплики

Что нового в lab3 относительно lab2

Горизонтальное масштабирование. Сервис api больше не имеет container_name и ports; в deploy.replicas стоит 2. Compose запускает mtuci2026lab3-api-1 и mtuci2026lab3-api-2. Публичной точкой входа служит lb.

Балансировщик. nginx:1.27.3-alpine, конфиг infra/nginx.conf монтируется в /etc/nginx/conf.d/default.conf. Upstream api_backend резолвит Docker-DNS api:8080 во все реплики сервиса. max_fails=1 fail_timeout=5s — после первой ошибки реплика исключается из ротации на 5 секунд. proxy_next_upstream error timeout http_502 http_503 http_504 переводит неудавшийся запрос на следующую реплику. Keepalive к upstream намеренно отключён: с ним одна клиентская сессия уходит на одну реплику, и проверить балансировку на малом числе запросов нельзя.

X-Instance-Id. Каждая реплика при старте генерирует случайный alias в docker-entrypoint.sh и экспортирует как INSTANCE_ID; middleware в src/app/main.py добавляет его в каждый ответ, включая ошибки. Значение не содержит hostname/IP.

Идемпотентность (общая для реплик). POST /api/v1/chats/{chat_id}/messages требует Idempotency-Key (ASCII [A-Za-z0-9._:-]{1,128}). Scope: user_id + method + path + key. body_hash — sha256 канонизированного JSON (сортировка ключей, отсутствующий attachment_ids приравнен к []). Реализовано атомарно:

  1. reserve_idempotency делает INSERT … ON CONFLICT DO NOTHING RETURNING key в idempotency_keys. Ровно один параллельный запрос (в т.ч. через разные реплики) получает строку обратно — он и создаёт сообщение. Остальные видят replay.
  2. Победитель создаёт сообщение и вызывает complete_idempotency — UPDATE со реальным response_status/response_body.
  3. replay с тем же body_hash возвращает сохранённый 201 и то же Message. С другим body_hash — 409. Если победитель ещё не записал ответ (response_status = 0), повторы коротко ждут.

Graceful shutdown. SIGTERM: main._handle_sigterm выставляет server.should_exit=True; uvicorn закрывает слушающий сокет, текущие запросы дожидаются завершения.

Rolling update. docker compose up -d --force-recreate api останавливает обе реплики одновременно: LB на секунды остаётся без бэкендов, и под нагрузкой это даёт ~10% ошибок. Штатный способ — scripts/rolling-update.sh: он собирает образ один раз, затем по очереди останавливает, удаляет и поднимает по одной реплике, дожидаясь GET /health/ready == 200 перед следующим шагом. Проверка: параллельно с обновлением идёт tests/load.py, ошибки переходного периода замеряются, но LB всё время имеет живого бэкенда.

Ресурсные лимиты. В compose.yaml у api — deploy.resources.limits.cpus: "1.0", memory: 512M.

Соответствие .env.example реальной конфигурации (без изменений с lab2):

  • APP_HOST, APP_PORT — используются uvicorn/CMD в Dockerfile.
  • APP_ENV — пишется в стартовый лог event=startup app_env=..., в остальном на логику не влияет.
  • SESSION_TTL_SECONDS — TTL серверных сессий в Redis (или в таблице sessions при SESSION_STORE=postgres), по умолчанию 3600. Для теста expiry временно ставится 5 и возвращается обратно.
  • DATABASE_URL — строка подключения к PostgreSQL. В Docker используется postgresql://user:password@postgres:5432/high_load_messenger.
  • REDIS_URL — адрес Redis в compose-сети (redis://redis:6379/0), не секрет.
  • SESSION_STORE — redis (уровень 4) или postgres (fallback).
  • CACHE_URL_FILE — резервная переменная из скелета, не используется.

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

Уровень 3

Критерий Команда Наблюдаемый результат
Стенд описан в compose.yaml, запускается командой docker compose --env-file .env up -d --build mtuci-lb Up, mtuci2026lab3-api-1/-2 Up (healthy), mtuci-postgres Up (healthy), mtuci-redis Up (healthy)
≥2 API-реплики, одна публичная точка входа, общая БД, общее хранилище сессий docker compose --env-file .env ps 2 контейнера api, порт 8080 публикует только lb
Разные запросы одного пользователя обслуживают разные реплики без повторного входа python student-tests/lab3_test_level4.py → test_two_instances observed instances: ['00c1651b90c9', 'f8f94301bb06'], PASS
Остановка одной реплики: не позднее 10 с продолжаются новые чтения/записи, подтверждённые сообщения доступны python tests/resilience.py --mode failover --action-script scripts/stop-one.bat … first_recovery_seconds: 5.189, PASS
Повтор POST с тем же Idempotency-Key не создаёт дубль python student-tests/lab3_test_level4.py → test_idempotency_across_replicas 10 параллельных POST с одним ключом → ровно 1 сообщение; PASS
make test, persistence, failover проходят все команды ниже PASS

Уровень 4

Критерий Команда Наблюдаемый результат
Health/readiness, timeouts, graceful shutdown; LB исключает недоступный backend см. infra/nginx.conf (max_fails=1 fail_timeout=5s, proxy_next_upstream), main.py (_handle_sigterm) При docker stop реплики LB перестаёт её использовать; SIGTERM логируется, процесс завершается корректно
Последовательная остановка каждой реплики; RPS/ошибки/время восстановления python tests/resilience.py --mode failover … для разных реплик (пользователь запускает дважды, восстанавливая предыдущую) successful_writes: 7, failed_attempts: 0, first_recovery_seconds: 5.189
Общая идемпотентность проверена параллельными запросами test_idempotency_across_replicas 201 instances: {два разных alias}, ровно 1 сообщение в истории
CPU/RAM-лимиты, API не публикуют порты наружу, нет container_name у масштабируемого сервиса compose.yaml deploy.resources.limits у api; api без ports; без container_name
Rolling update или эквивалентная поочерёдная замена под нагрузкой scripts/rolling-update.sh при поднятом LB и запущенном python tests/load.py --duration 30 --concurrency 4 Обновление идёт по одной реплике; замер: X ошибок из Y запросов (Z%); LB всегда имеет живого бэкенда

Выводы тестов

(venv) PS ...> python scripts/check_contract.py
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.

(venv) PS ...> python scripts/validate_openapi.py
PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested.

(venv) PS ...> python tests/smoke.py --base-url http://localhost:8080
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.

(venv) PS ...> python student-tests/lab3_test_level4.py --base-url http://localhost:8080
=== test_two_instances ===
  observed instances: ['00c1651b90c9', 'f8f94301bb06']
PASS: >=2 X-Instance-Id через LB
=== test_idempotency_across_replicas ===
  201 instances: {'00c1651b90c9', 'f8f94301bb06'}  409 instances: set()
  PASS: idempotency OK, ровно одно сообщение создано
PASS: идемпотентность на общих ключах
=== test_stop_one_replica ===
  останавливаем replica container: c416ffa7ec4b
  after-fail instances: {'f8f94301bb06'}
  PASS: стенд пережил отказ одной реплики
PASS: отказ одной API-реплики обработан
PASS: all lab3 level-4 checks passed

(venv) PS ...> python tests/resilience.py --mode persistence --action-script scripts/restart.bat --base-url http://localhost:8080
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.

(venv) PS ...> python tests/resilience.py --mode failover --action-script scripts/stop-one.bat --base-url http://localhost:8080
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 7, "failed_attempts": 0, "first_recovery_seconds": 5.189}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.

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

Стенд: Windows 11, Docker Desktop (WSL2). Лимиты api — 1 CPU / 512 MiB на реплику. Данные синтетические, объём небольшой — этого достаточно для проверки балансировки и отказов.

Воздействие Что ожидаем Что наблюдали
docker compose --env-file .env restart lb api postgres redis (persistence hook) Все реплики и хранилища перезапускаются, volumes сохраняются, сессия и сообщения живы PASS: токен прежний, подтверждённое сообщение найдено
docker stop одной реплики API (failover hook) LB переключает трафик на живую реплику, новые POST/GET идут без потерь, подтверждённое сообщение доступно first_recovery_seconds: 5.189, successful_writes: 7, failed_attempts: 0, PASS
Параллельный POST с одним Idempotency-Key через LB (10 потоков) Ровно один INSERT в messages; все остальные — replay/409 ровно 1 сообщение в истории, PASS
SIGTERM одной реплике Graceful shutdown uvicorn, без падения процессов В логах event=shutdown_complete, контейнер завершается за секунды

Дополнительно docker compose ps подтверждает, что во время failover-теста публичный порт 8080 обслуживает только LB; после docker stop одного контейнера api второй продолжает отвечать, что видно по его уникальному X-Instance-Id в ответах (в выводе: after-fail instances: {'f8f94301bb06'}).

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

  • Один Docker-host. Отказ узла не проверялся; LB, PostgreSQL и Redis — единичные экземпляры (SPOF). HA БД/LB не заявляется.
  • Обнаружение отказа — реактивное. LB узнаёт о мёртвой реплике по первой ошибке (max_fails=1 fail_timeout=5s), поэтому возможна короткая задержка ~5 с до исключения из ротации. Это допустимо по методичке (восстановление ≤10 с).
  • Идемпотентность только на POST сообщения. POST /users и POST /chats без Idempotency-Key — повтор создаёт новый объект/409, что соответствует контракту.
  • Часы. Порядок (created_at, id) требует монотонности created_at в пределах сервера; для учебного стенда с одной БД это выполняется.
  • Миграции. init_schema() идемпотентен, но запускается на старте каждой реплики. Гонки нет благодаря CREATE TABLE IF NOT EXISTS / CREATE INDEX IF NOT EXISTS. Отдельный миграционный job не выделен — это упрощение учебного уровня.
  • Нагрузка. Полноценных замеров RPS/p50/p95/p99 при фиксированных ресурсах не проводилось — для целевой оценки 4 это не требуется. Трек 5 (цена масштабирования) не заявлен.