Files
mtusi2026lab6/REPORT.md
T

17 KiB
Raw Blame History

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

  • Автор, группа: Васюкова Наталья, БВТ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

TODO

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

Критерий Команда Наблюдаемый результат Уровень
Публичный 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

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

TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
TODO TODO TODO TODO

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

TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.