Files
mtusi2026lab5/REPORT.md
T

29 KiB
Raw Blame History

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

  • Автор, группа: Васюкова Наталья, БВТ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, boto3==1.35.74, Pillow==11.0.0, pika==1.3.2, 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, boto3 1.35.74, Pillow 11.0.0, pika 1.3.2
  • PostgreSQL 18.6-alpine, Redis 7.4.1-alpine, nginx 1.27.3-alpine
  • RabbitMQ 3.13.7-management-alpine
  • MinIO: netvark/minio:20260213 (зеркало официального образа; оригинальные minio/minio удалены с Docker Hub). CLI mc: netvark/mc:20260920.
  • Docker Desktop (Windows)

Запуск стека

  1. Клонировать репозиторий и переключиться на ветку решения:
    git clone https://gitflic.ru/project/vasyukova-nat/mtusi2026lab5.git
    git checkout solution/BVT2303-Vasyukova
    
  2. Создать .env из шаблона:
    copy .env.example .env
    
  3. Собрать и поднять (LB + 2 реплики API + PostgreSQL + Redis + MinIO + minio-init + rabbitmq + worker + outbox + s3_cleanup):
    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-persistence python tests/resilience.py --mode persistence --action-script scripts/restart.bat --base-url http://localhost:8080
make test-failover python tests/resilience.py --mode failover --action-script scripts/stop-one.bat --base-url http://localhost:8080
make test-student python student-tests/lab5_test_level4.py --base-url http://localhost:8080

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

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

Операторский replay failed-задач

Причина ошибки устранена — вернуть задачи в обработку (failed → queued + новая строка outbox, готовые не трогаются):

docker compose --env-file .env exec -T worker python -m app.storage.replay_failed --all-failed
# или конкретные ID:
docker compose --env-file .env exec -T worker python -m app.storage.replay_failed <attachment_id> [...]

Публикацию делает существующий outbox, обработку — worker; оба должны быть запущены. Проверка: status=queued, затем ready.

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

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

                      ┌─ api-1 (uvicorn:8080)     ┐
HTTP-клиент → lb:80 ──┤                            │
   (nginx)            └─ api-2 (uvicorn:8080)     ├→ PostgreSQL 18.6 (метаданные, outbox)
                                                   ├→ Redis 7.4.1 (сессии)
                                                   ├→ MinIO (S3: staging + final байты)
                                                   └→ RabbitMQ (durable job queue)

outbox (publisher)  → читает unpublished из PostgreSQL → публикует в RabbitMQ
worker (consumer)   → забирает job из RabbitMQ → читает staging → пишет final+variants → status=ready
s3_cleanup          → сверка S3↔БД, recover зависших processing

Все сервисы — в одной compose-сети mtuci2026lab5_default. Публично опубликован только порт LB 127.0.0.1:8080:80. Реплики api не имеют ports — трафик к ним идёт исключительно через LB. PostgreSQL, Redis, MinIO и RabbitMQ доступны только по внутренним именам. Административная консоль MinIO (:9001), S3 API (:9000) и RabbitMQ management (:15672) не публикуются наружу.

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

  • PostgreSQL — данные (пользователи, чаты, членство, сообщения, метаданные вложений, варианты, outbox, ключи идемпотентности).
  • Redis — серверные сессии (общие для всех реплик).
  • MinIO (S3) — байты вложений: staging (staging/…) и финальный attachments/… (приватный bucket).
  • RabbitMQ — durable очередь job'ов. Сама по себе не источник истины: намерение сохраняется в outbox до публикации.

Схема БД (подробнее — 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)
attachments(id UUID PK, chat_id FK→chats, owner_id FK→users,
            filename TEXT, content_type TEXT, size_bytes BIGINT, sha256 TEXT,
            object_key TEXT UNIQUE, status TEXT, error_code TEXT,
            processing_until TIMESTAMPTZ,             -- lab5: lease для worker
            created_at TIMESTAMPTZ, updated_at TIMESTAMPTZ)
  + INDEX idx_attachments_chat(chat_id)
message_attachments(message_id FK→messages, attachment_id FK→attachments, position INT,
                    PRIMARY KEY (message_id, attachment_id))
attachment_variants(attachment_id FK→attachments, pipeline_version INT, variant TEXT,
                    object_key TEXT, content_type TEXT, size_bytes BIGINT,
                    width INT, height INT, sha256 TEXT, created_at TIMESTAMPTZ,
                    PRIMARY KEY (attachment_id, pipeline_version, variant))  -- lab5
outbox(id BIGSERIAL PK, job_id UUID UNIQUE, payload JSONB, created_at TIMESTAMPTZ,
       published_at TIMESTAMPTZ)                    -- lab5 level 4
  + PARTIAL INDEX idx_outbox_unpublished(id) WHERE published_at IS NULL

Применяется идемпотентно через init_schema() в отдельном one-shot сервисе migrate (python -m app.storage.db). Все временные метки — TIMESTAMPTZ.

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

  • create_user — SELECT-проверка username и INSERT в одной транзакции; при гонке UniqueViolation → 409.
  • create_chat — INSERT chats + INSERT chat_members в одной транзакции, откат целиком.
  • add_message_idempotent — INSERT ключа идемпотентности, INSERT сообщения, INSERT связей с вложениями и UPDATE ответа ключа в одной транзакции.
  • create_attachment_queued (lab5) — INSERT attachments (status=queued) + INSERT outbox в одной транзакции. Это durable handoff: если API упадёт сразу после ответа 202, outbox гарантирует публикацию job'а.
  • finalize_ready — UPDATE attachments (status=ready, object_key=final) + INSERT attachment_variants с ON CONFLICT (attachment_id, pipeline_version, variant) DO NOTHING в одной транзакции. Идемпотентно к повторной доставке.

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

mtuci2026lab5/
├── compose.yaml *            # + rabbitmq, worker, outbox; tag lab5 для всех сервисов
├── Dockerfile
├── docker-entrypoint.sh       # генерирует INSTANCE_ID, пишет /tmp/instance_id
├── infra/nginx.conf
├── Makefile
├── requirements.txt *         # + pika
├── src/app/
│   ├── main.py *              # версия 1.5.0, title lab5
│   ├── api/
│   │   ├── attachments.py *   # upload → 202 queued; download variant
│   │   ├── messages.py        # без изменений с lab4
│   │   └── health.py          # без изменений с lab4
│   ├── models/
│   │   └── schemas.py         # без изменений с lab4
│   ├── storage/
│   │   ├── db.py *            # + attachment_variants, outbox, processing_until
│   │   ├── postgres.py *      # + lab5 методы (queued, variants, outbox, lease, recover)
│   │   ├── s3.py *            # + staging_key, variant_key
│   │   ├── rabbit.py *        # новый: topology, publish с confirm, retry, DLQ
│   │   └── s3_cleanup.py *    # + cleanup staging, recover processing
│   ├── worker.py *            # новый: consumer, обработка изображений
│   └── outbox_worker.py *     # новый: outbox publisher (level 4)
├── scripts/
│   ├── restart.sh / .bat *    # + rabbitmq, worker, outbox
│   └── stop-one.sh / .bat     # без изменений
└── student-tests/
    └── lab5_test_level4.py *  # новый: variants, outbox, DLQ, lease, retry

Что нового в lab5 относительно lab4

  1. Upload возвращает 202 queued. POST /api/v1/chats/{chat_id}/attachments теперь пишет байты в staging-prefix (staging/<chat_id>/<attachment_id>/original), затем одной транзакцией сохраняет attachments (status=queued) и outbox. Отвечает 202 Attachment со status=queued. Байты передаются в HTTP полностью, но тяжёлая обработка (resize) вынесена из API.
  2. RabbitMQ как broker. Durable quorum queue attachment.process.v1, retry-очереди с TTL (attachment.retry.5s/15s/60s) и DLQ (attachment.process.v1.dlq). Сообщения persistent (delivery_mode=2), публикуются с publisher confirm (confirm_delivery()), consumer делает manual ack после устойчивого эффекта. Доставка — at-least-once.
  3. Outbox закрывает разрыв COMMIT → publish (level 4). Отдельный процесс outbox каждые 2 секунды читает неопубликованные строки outbox, публикует в RabbitMQ с confirm, затем помечает published_at. Если API упал между COMMIT и publish — outbox опубликует job после рестарта. Если RabbitMQ недоступен — строка остаётся unpublished, повтор при следующем цикле.
  4. Worker отдельный от API. python -m app.worker забирает job из RabbitMQ с prefetch_count=1, атомарно переводит queued → processing с lease processing_until (60 с), скачивает staging, пишет оригинал (final) + thumbnail + crop + optimized, затем атомарно ready через finalize_ready. Staging удаляется после успешной фиксации.
  5. Идемпотентность эффекта. Ключ (attachment_id, pipeline_version, variant). claim_processing возвращает False для ready → повторная доставка — no-op. finalize_ready использует ON CONFLICT DO NOTHING. Повтор job не создаёт дублей вариантов.
  6. Retry с backoff и DLQ (level 4). Временные ошибки (S3 недоступен, staging missing) → публикация в retry-очередь с x-retry-count (5 → 15 → 60 с). После 4-й попытки — status=failed, error_code=retry_exhausted и сообщение в DLQ. Постоянные ошибки (invalid image) — сразу failed, error_code=invalid_image, без retry.
  7. Lease и recover зависших (level 4). processing_until — deadline для текущей попытки. s3_cleanup периодически (CLEANUP_INTERVAL_SECONDS) переводит просроченные processing обратно в queued (recover_stuck_processing). При старте worker также может поднять такие записи. Так зависший processing не «залипает» навсегда.
  8. Варианты обработки (level 4).
    • original — байты побайтно те же, что и исходный upload (SHA-256 оригинала в attachments.sha256).
    • thumbnail — JPEG, вписан в 256×256 с сохранением пропорций, без увеличения; EXIF orientation применяется; alpha компонуется на белый. Для 320×200 получается 256×160.
    • crop — JPEG, центрированный квадрат 128×128 (маленькие исходники могут увеличиваться).
    • optimized — WebP, вписан в 1280×1280 без увеличения, quality=82, EXIF удалён (Pillow не сохраняет его в WebP по умолчанию).
  9. Лимиты и защита. Те же MAX_UPLOAD_BYTES=10485760 и MAX_IMAGE_PIXELS=40000000. Pillow в threadpool; лимит пикселей проверяется до load(). Лимит 40 млн пикселей остаётся; worker дополнительно распаковывает под контролем того же лимита (файл уже проверен на входе, но worker defence-in-depth).
  10. Readiness. /health/ready проверяет PostgreSQL, Redis, S3. RabbitMQ не критичен для синхронного пути API (upload работает без брокера благодаря outbox); его недоступность не роняет readiness, но outbox не публикует, пока брокер не поднимется.

Соответствие .env.example реальной конфигурации:

  • APP_HOST, APP_PORT — используются uvicorn/CMD в Dockerfile.
  • APP_ENV — пишется в стартовый лог, на логику не влияет.
  • SESSION_TTL_SECONDS — TTL серверных сессий в Redis (или в таблице sessions при SESSION_STORE=postgres), по умолчанию 3600.
  • DATABASE_URL — строка подключения к PostgreSQL.
  • REDIS_URL — адрес Redis в compose-сети.
  • SESSION_STORE — redis (уровень 4) или postgres (fallback).
  • S3_ENDPOINT — внутренний адрес MinIO (http://minio:9000).
  • S3_REGION — регион (для MinIO фиктивный us-east-1).
  • S3_BUCKET — имя приватного bucket.
  • MINIO_ROOT_USER / MINIO_ROOT_PASSWORD — root-credentials MinIO, используются только сервисами minio и minio-init.
  • S3_APP_KEY_ID / S3_APP_SECRET_KEY — прикладные S3-credentials, используются API, worker, outbox, s3_cleanup.
  • MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS — лимиты вложений.
  • CLEANUP_INTERVAL_SECONDS — период сверки S3↔БД и recover зависших processing.
  • ORPHAN_GRACE_SECONDS — grace period для удаления orphan/staging объектов.
  • RABBITMQ_USER, RABBITMQ_PASSWORD — креды брокера (создаются при старте rabbitmq).
  • RABBITMQ_URL — AMQP URL (amqp://user:pass@rabbitmq:5672/%2F); worker, outbox используют его.
  • CACHE_URL_FILE — резервная переменная из скелета, не используется.

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

Критерий Команда Наблюдаемый результат Уровень
Публичный smoke python tests/smoke.py PASS: lab5 public API scenario 3
Broker + worker в общем стенде, at-least-once docker compose ps; rabbitmqctl list_queues rabbitmq/worker/outbox Up; consumer на attachment.process.v1 3
Upload возвращает 202 queued, работа переживает остановку worker lab5_test_level4.py::test_worker_stopped 202 queued → content 409 → старт worker → ready 3
Сохранение метаданных и сессии при рестарте resilience.py --mode persistence PASS: тот же токен и SHA-256 файла 3
Отказ одной API-реплики resilience.py --mode failover observed_instances_before=2, successful_writes=7, failed_attempts=0, first_recovery=4.245 s 3
Worker сохраняет original + один thumbnail по контракту lab5_test_level4.py::test_variants thumbnail JPEG 256×160, sha256/size совпадают 3
Ограниченный retry, финальный failed с error_code lab5_test_level4.py::test_broken_staging_dlq failed retry_exhausted + DLQ 3
Повтор job не создаёт второго набора вариантов lab5_test_level4.py::test_duplicate_delivery_no_duplicates variants не выросли, status=ready 3
Original неизменен, download побайтно smoke + test_variants SHA-256 совпадает; при скачивании — те же байты 3
Crop 128×128 (JPEG) lab5_test_level4.py::test_variants jpeg_size(crop) == (128,128) 4
Optimized WebP (≤1280×1280) lab5_test_level4.py::test_variants Content-Type image/webp, RIFF/WEBP 4
Outbox закрывает разрыв COMMIT → publish lab5_test_level4.py::test_outbox_crash stop outbox → upload 202 + outbox unpublished → start outbox → ready 4
Retry с backoff, DLQ, безопасный replay lab5_test_level4.py::test_broken_staging_dlq 4 попытки, retry_exhausted, DLQ +1 4
Ограниченная конкуренция, prefetch=1, очистка staging worker.py, s3_cleanup.py prefetch_count=1; staging удаляется после finalize 4
Lease: зависший processing возвращается в queued lab5_test_level4.py::test_stuck_processing_recovered processing (lease истёк) → queued → ready 4
Лимиты времени/памяти worker Pillow, MAX_IMAGE_PIXELS, threadpool Pillow в threadpool, лимит до load() 4
Гарантия, что в очереди ID, а не байты/креды rabbit.py, outbox_worker.py payload = {job_id, attachment_id, pipeline_version, created_at}; staging/финальные байты — в S3 4

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

(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: lab5 public API scenario; infrastructure and grading evidence remain separate.

(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": 4.245}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.

(venv) PS ...> python student-tests/lab5_test_level4.py --base-url http://localhost:8080
=== variants (thumbnail/crop/optimized) ===
PASS: original, thumbnail 256×160, crop 128×128, optimized WebP
=== outbox crash between COMMIT and publish ===
PASS: outbox recovers job after stop/start without manual intervention
=== duplicate delivery does not create duplicates ===
PASS: re-delivery of the same job is a no-op
=== worker stopped: 202 → content 409 → ready ===
PASS: accepted work survives worker restart
=== broken staging → retry_exhausted → failed + DLQ ===
PASS: bounded retry, failed with safe error_code, message in DLQ
=== stuck processing (lease) → queued → ready ===
PASS: expired lease is recovered, same attachment becomes ready
PASS: all lab5 level-4 checks passed

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

Hardware: Windows 11, Docker Desktop (WSL2). Лимиты контейнеров в compose.yaml (api: 1 CPU / 512M; worker: 1 CPU / 512M; outbox: 0.3 CPU / 128M; rabbitmq: 0.5 CPU / 512M; s3_cleanup: 0.3 CPU / 256M). Все данные синтетические (см. tests/smoke.py, student-tests/lab5_test_level4.py).

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker compose stop outbox между COMMIT и publish Строка outbox остаётся published_at IS NULL, attachment queued; после start outbox — публикация, ready upload → 202, outbox unpublished → start → ready ~2 с после старта outbox (polling интервал); потери нет
docker compose stop worker после upload 202 queued; content → 409; старт worker → ready PASS: 202 → 409 → ready, thumbnail доступен ~5–10 с после старта worker
docker compose stop postgres во время upload S3 staging PUT прошёл, INSERT падает, компенсация удаляет staging, ответ 503 503, staging-объект удалён (компенсация), bucket не вырос 0; после start postgres — ready за ≤90 с, по факту ~10 с
docker stop одной API-реплики (failover) Вторая реплика обслуживает; подтверждённое не теряется; идемпотентность без дублей 2 реплики до, 7 успешных записей, 0 ошибок, recovery=4.245 s ≤10 с; потери нет
scripts/restart.bat (все сервисы, включая RabbitMQ) Данные PostgreSQL/Redis/RabbitMQ и оригиналы в S3 сохраняются, сессия продолжает работать PASS: тот же токен и SHA-256 файла после перезапуска Готовность ≤90 с; потери нет
Broken staging (удалён объект staging/…) 4 попытки (5+15+60 с), failed retry_exhausted, сообщение в DLQ PASS: failed, error_code=retry_exhausted, DLQ +1 ≤180 с; потеря — только испорченный файл
Зависший processing (lease истёк) recover переводит в queued; worker доводит до ready PASS: processing → queued → ready ~несколько секунд после recover
Повторный publish того же job (эмуляция redelivery) claim_processing возвращает False для ready; variants не растут PASS: 3 → 3 варианта, status=ready —

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

  • Один Docker-host. Отказ узла не проверялся; LB, PostgreSQL, Redis, MinIO, RabbitMQ — единичные экземпляры (SPOF). HA БД/LB/S3/broker не заявляется.
  • RabbitMQ в одном узле. Quorum queue даёт durability при рестарте, но не переживёт потерю диска. Для уровня 4 этого достаточно; для продакшена — кластер RabbitMQ + репликация S3 + HA PostgreSQL.
  • Outbox polling. outbox работает с интервалом 2 с; задержка публикации ≤2 с. Для снижения latency можно LISTEN/NOTIFY вместо polling, но это не требуется для учебного стенда.
  • At-least-once, не exactly-once. Повторная доставка возможна (например, redelivery после ack-timeout); идемпотентность обеспечена ключом (attachment_id, pipeline_version, variant) и claim_processing, но не «exactly-once».
  • DLQ без автоматического replay. Failed-задачи остаются в DLQ; replay — ручной (операторский), как требует методичка для уровня 4. Автоматический replay не реализован.
  • Несколько pipeline_version. В коде PIPELINE_VERSION=1. Версионирование pipeline (трек 5) не реализовано; ON CONFLICT (attachment_id, pipeline_version, variant) уже готово к появлению v2, но второй pipeline не заявлен.
  • Память загрузки. Тело upload читается в память API (chunks: list[bytes]). При MAX_UPLOAD_BYTES=10 MiB и лимитах api это приемлемо; для больших лимитов нужен upload_fileobj в S3 (не требуется).
  • Пиксели в worker. Worker повторно открывает staging через Pillow. Основной лимит пикселей уже проверен на входе в API; worker не увеличивает допустимый размер, но и не делает дополнительных ограничений сверх MAX_IMAGE_PIXELS — это ответственность API на входе.
  • s3_cleanup — best-effort. Если процесс упал во время цикла, при следующем запуске сверка продолжается. Staging моложе ORPHAN_GRACE_SECONDS не удаляется (защита in-flight); зависшие processing восстанавливаются на каждом цикле.
  • Компенсация «S3 → БД». Основной путь — удалить staging при ошибке INSERT (компенсация). Обратный случай (метаданные есть, S3 staging потерян) ловится worker'ом как staging_unavailable → retry → при исчерпании retry_exhausted + DLQ. Содержимое файла восстановить неоткуда — это учебное ограничение.
  • Часы. Порядок (created_at, id) требует монотонности created_at в пределах сервера; для учебного стенда с одной БД это выполняется.
  • Нагрузка. Полноценных замеров RPS/p50/p95/p99 при фиксированных ресурсах не проводилось — для целевой оценки 4 это не требуется. Трек 5 (перегрузка очереди или versioned idempotency) не заявлен.