Files
mtusi2026lab5/REPORT.md
T

18 KiB
Raw Blame History

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

  • Автор, группа: Герейханов Ильяс, БВТ2301
  • Целевая оценка: 4
  • Commit/PR: ветка solution/bvt2301-Gereykhanov. PR: ЛР 5 — БВТ2301 — Герейханов — на 4
  • Использованные источники, библиотеки и помощь ИИ: Python 3.12, FastAPI, Uvicorn, PostgreSQL 16, Redis 7, Nginx 1.27, MinIO, RabbitMQ 3.13, Pillow, boto3, asyncpg, argon2-cffi, Pydantic, Pytest, Docker Compose, AWS S3 API, OpenAPI 3.1.0. ИИ использовался для подготовки шаблонов очередей и расширения тестов pytest.

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

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

    • Локальный runtime: Linux, Docker 29.9.1, Docker Compose v5.6.0
    • Load Balancer: nginx:1.27-alpine
    • API контейнеры (api-1, api-2): python:3.12-slim
    • Worker фоновый процесс: python:3.12-slim
    • Брокер сообщений: rabbitmq:3.13-alpine
    • PostgreSQL: postgres:16-alpine
    • Redis: redis:7-alpine
    • S3-совместимое хранилище: cleanstart/minio:0.20260330.001845
  2. Подготовка окружения и запуск стека:

    git checkout solution/bvt2301-Gereykhanov
    cp .env.example .env
    
    # Сборка и запуск всех сервисов
    make up
    
  3. Ожидание готовности и запуск проверок:

    # Проверка структуры и синтаксиса
    make check
    
    # Валидация схемы OpenAPI
    make validate PYTHON=.venv/bin/python
    
    # Проверка smoke теста
    make test
    
    # Проверка сценария сохранности данных и сессий при рестарте
    make test-persistence ACTION_SCRIPT=scripts/restart.sh
    
    # Проверка отказоустойчивости при отключении одной API-реплики
    make test-failover ACTION_SCRIPT=scripts/stop-one.sh
    
    # Восстановление остановленной реплики после теста
    docker compose up -d
    
    # Запуск собственных тестов
    make test-student
    
    # Запуск нагрузочного теста
    python3 tests/load.py --duration 15 --concurrency 4 --output evidence/load.json
    
    # Команда перезапуска задачи из DLQ:
    docker compose exec api-1 python -m app.cli replay <attachment_id>
    
  4. Остановка и очистка:

    # Остановка с сохранением данных volumes
    docker compose down
    
    # Остановка с удалением volumes
    docker compose down -v
    

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

  • Топология процессов и распределение ролей:

    • Клиент отправляет HTTP-запросы в единую точку входа Nginx Load Balancer на порт 8080.
    • Nginx балансирует запросы между двумя репликами API (api-1 и api-2) по схеме Round-Robin.
    • Реплики API работают в stateless-режиме, обращаются к общим PostgreSQL, Redis, MinIO S3 и RabbitMQ.
    • Фоновый процесс OutboxRelay считывает задания из outbox_jobs и публикует их в RabbitMQ с Publisher Confirms.
    • Сервис worker забирает задачи из RabbitMQ (prefetch_count=4), генерирует варианты через Pillow и сохраняет в MinIO.
    • Отдельный контейнер migration применяет init.sql перед запуском API-реплик и воркера.
  • Хранилища данных и источник истины:

    • PostgreSQL: источник истины для пользователей, чатов, сообщений, метаданных вложений в attachments и задач в outbox_jobs.
    • MinIO S3: хранилище бинарного контента в бакете messenger-attachments. Стейджинг: staging/{attachment_id}/{filename}, оригинал: chats/{chat_id}/{attachment_id}/original, варианты: chats/{chat_id}/{attachment_id}/{variant_name}.
    • Redis: сессионный кэш Bearer-токенов с TTL 3600 с и кэш ключей идемпотентности.
    • RabbitMQ: брокер сообщений (direct exchange messenger.attachments, очередь messenger.attachments.jobs, DLX/DLQ).
  • Что перенесено из лабы 4:

    • Nginx с Round-robin 50/50, заголовками X-Request-Id, X-Instance-Id и быстрым переключением при сбоях.
    • Единое хранилище сессий в Redis.
    • Идемпотентность отправки сообщений по заголовку Idempotency-Key.
    • Keyset-пагинация сообщений по индексу (created_at, id).
    • Изоляция MinIO без проброса портов на хост.
    • Проверка MIME по содержимому, декодирование растра img.load() до принятия файла и защита от пиксельных бомб.
  • Асинхронная загрузка и Transactional Outbox:

    • Загрузка вложения (POST /api/v1/chats/{chat_id}/attachments) сохраняет поток в staging S3 и в одной транзакции PostgreSQL создает запись в attachments (status='queued') и задачу в outbox_jobs. Ответ клиенту возвращается с кодом 202 Accepted.
    • Ликвидирован разрыв COMMIT/publish: задача сохранена в БД до публикации. OutboxRelay считывает её через FOR UPDATE SKIP LOCKED и отправляет в RabbitMQ с подтверждением брокера (publisher_confirms=True).
  • Обработка вложений воркером и Pillow:

    • Воркер атомарно переводит статус в processing (идемпотентность по attachment_id) и скачивает staging-файл.
    • Синхронная обработка ограничена дедлайном 30 секунд для предотвращения зависания живого воркера.
    • Генерируются 3 варианта: thumbnail (JPEG, 256×256 без апскейла, альфа на белый фон), crop (JPEG, 128×128), optimized (WebP, до 1280×1280).
    • Готовые файлы пишутся в S3, статус обновляется в ready, после чего staging удаляется.
  • Отказоустойчивость, DLQ и Watchdog:

    • Временные ошибки повторяются до 5 раз с экспоненциальным backoff и jitter.
    • Неустранимые сбои или исчерпание попыток переводят вложение в failed, а сообщение уходит в messenger.attachments.dlq.
    • Фоновый watchdog сбрасывает зависшие в processing задачи старше 60 секунд обратно в queued.
    • Для ручного перезапуска failed-задач из DLQ реализован CLI: python -m app.cli replay <attachment_id>.
  • Связывание с сообщениями и скачивание контента:

    • В сообщения разрешено прикреплять вложения со статусом queued и processing. Вложения со статусом failed отклоняются с кодом 409.
    • Скачивание через GET /api/v1/attachments/{id}/content?variant=... возвращает запрошенный вариант (original, thumbnail, crop, optimized). До перехода в статус ready возвращается 409. Посторонний получает 404.

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Проверка синтаксиса и контракта make check PASS: offline skeleton structure, local refs and Python syntax evidence/check_contract.log
Полная OpenAPI 3.1 валидация make validate PYTHON=.venv/bin/python PASS: full OpenAPI 3.1 and JSON Schema validation evidence/validate_openapi.log
Публичный smoke тест make test PASS: lab5 public API scenario evidence/smoke_test.log
Чередование реплик for i in {1..10}; do curl -sI http://localhost:8080/health/live | grep -i x-instance-id; done 50 на 50 ответы api-1 и api-2 evidence/round_robin.log
Сохранение данных и сессий при рестарте make test-persistence ACTION_SCRIPT=scripts/restart.sh Стек перезапущен, токен, сообщения, вложения и outbox сохранены evidence/persistence_test.log
Отказ API-реплики под нагрузкой make test-failover ACTION_SCRIPT=scripts/stop-one.sh Восстановление записи за 0.87 с, 116 успешных запросов, 0 сбоев evidence/failover_test.log
Асинхронная загрузка make test-student POST возвращает 202 queued, воркер генерирует варианты и переводит в ready evidence/student_tests.log
Блокировка скачивания до ready make test-student Запрос контента для queued или processing возвращает 409 Conflict evidence/student_tests.log
Привязка вложений к сообщениям make test-student Queued/processing прикрепляются успешно, failed отклоняются с 409 Conflict evidence/student_tests.log
Отсечение битых файлов на входе make test-student Усеченный и поврежденный PNG отклоняется с 415 до принятия в очередь evidence/student_tests.log
Все собственные тесты make test-student 35 тестов проходят: асинхронный цикл, RabbitMQ, outbox, варианты, идемпотентность evidence/student_tests.log
Статусы и изоляция контейнеров docker compose ps Все 8 сервисов healthy, API и MinIO не открывают порты на хост evidence/docker_services.log
Нагрузочный тест python3 tests/load.py 318.1 RPS, p50 = 6.6 ms, p95 = 59.5 ms, p99 = 80.6 ms, 0 ошибок evidence/load.json

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

  • Профиль нагрузки: скрипт tests/load.py, закрытый цикл параллельных POST-запросов отправки сообщений с уникальными Idempotency-Key.
  • Параметры: длительность 15 секунд, 4 параллельных потока.
  • Результаты нагрузки (evidence/load.json):
    {
      "lab": 5,
      "workload": "closed-loop POST messages; no automatic retries",
      "requested_duration_seconds": 15.0,
      "elapsed_seconds": 15.007,
      "concurrency": 4,
      "successful_requests": 4773,
      "failed_requests": 0,
      "error_ratio": 0.0,
      "successful_rps": 318.051,
      "successful_latency_ms": {
        "p50": 6.603,
        "p95": 59.542,
        "p99": 80.594
      }
    }
    
Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Остановка воркера во время загрузки API возвращает 202 Accepted, файл прикрепляется к сообщению, скачивание вариантов возвращает 409 Conflict Все запросы API успешны; после повторного запуска воркера статус автоматически стал ready, сгенерированы все 3 варианта потерь данных нет, обработка возобновилась сразу после старта воркера
Остановка одной реплики API Nginx переключает трафик на живую реплику, продолжение записи без дубликатов 116 успешных записей во время остановки, 0 ошибок, переключение за 0.87 с 0.87 сек, потерь данных нет
Рестарт всего стека при активной сессии Сохранение подтверждённых данных в Postgres, токенов сессий в Redis, очереди в RabbitMQ и файлов в MinIO Контейнеры перезапущены, токен валиден, история сообщений, очереди и файлы сохранены Восстановление около 5 сек, потерь данных нет
Загрузка декомпрессионной бомбы Отклонение запроса с кодом 413 payload_too_large без исчерпания RAM воркера Запрос отклонен мгновенно по метаданным IHDR без распаковки растра Мгновенно (< 2 мс)
Загрузка поврежденного PNG файла Отклонение с кодом 415 unsupported_media_type до постановки в очередь img.load() на входе API обнаруживает повреждение растра и возвращает 415 Мгновенно
Загрузка изображения с нечетными пропорциями Формирование thumbnail с размерами 256×160 с округлением вниз Метаданные и растр thumbnail имеют точные габариты 256×160 Мгновенно
Попытка скачивания незавершенного вложения Возврат 409 Conflict Клиент получает 409 Conflict до момента перехода в статус ready Мгновенно
Попытка доступа к метаданным или контенту посторонним пользователем Защита приватности: возврат 404 Not Found без утечки факта существования Посторонний получает 404 на GET /attachments/{id} и /content Мгновенно
Попытка передачи опасного имени файла Отклонение запроса с кодом 400 invalid_request Валидатор отклоняет некорректное имя до обращения к хранилищу Мгновенно
Аварийная остановка воркера посреди обработки задачи Watchdog перехватывает задачу по истечению lease 60 секунд и сбрасывает статус в queued Задача безопасно подхватывается после рестарта воркера и доходит до ready Восстановление в пределах lease timeout

Ограничения

  • Какие отказы выдерживаются и какие нет:
    1. Выдерживаются:
      • Внезапная остановка любой одной API-реплики под нагрузкой: балансировщик Nginx переключает входящие запросы на оставшуюся реплику.
      • Полный рестарт стека: все подтверждённые данные, активные токены, задачи в Outbox и файлы в S3 сохраняются благодаря volumes.
      • Аварийная остановка воркера: необработанные задачи сохраняются в очередях RabbitMQ, зависшие в processing задачи перехватываются по lease timeout.
      • Зависание синхронных операций воркера: прерываются общим дедлайном asyncio.timeout.
      • Временные сетевые сбои: механизм retry с экспоненциальным backoff и jitter.
      • Атаки декомпрессионными бомбами, поврежденными файлами и опасными именами.
    2. Не выдерживаются:
      • Одновременное падение обеих API-реплик (HTTP 502 Bad Gateway).
      • Падение единственного экземпляра PostgreSQL, Redis, MinIO или RabbitMQ.
      • Удаление через docker compose down -v.
  • Учебные упрощения:
    1. Nginx, PostgreSQL, Redis, MinIO и RabbitMQ запущены в единственном экземпляре.
    2. Скачивание контента реализовано через чтение из S3 и проксирование байтов API-репликой.