29 KiB
Отчёт — лабораторная 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). CLImc:netvark/mc:20260920. - Docker Desktop (Windows)
Запуск стека
- Клонировать репозиторий и переключиться на ветку решения:
git clone https://gitflic.ru/project/vasyukova-nat/mtusi2026lab5.git git checkout solution/BVT2303-Vasyukova - Создать
.envиз шаблона:copy .env.example .env - Собрать и поднять (LB + 2 реплики API + PostgreSQL + Redis + MinIO + minio-init + rabbitmq + worker + outbox + s3_cleanup):
docker compose --env-file .env up -d --build - Проверить готовность:
Ожидается:
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— INSERTchats+ INSERTchat_membersв одной транзакции, откат целиком.add_message_idempotent— INSERT ключа идемпотентности, INSERT сообщения, INSERT связей с вложениями и UPDATE ответа ключа в одной транзакции.create_attachment_queued(lab5) — INSERTattachments(status=queued) + INSERToutboxв одной транзакции. Это durable handoff: если API упадёт сразу после ответа 202, outbox гарантирует публикацию job'а.finalize_ready— UPDATEattachments(status=ready,object_key=final) + INSERTattachment_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
- 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. - 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. - Outbox закрывает разрыв COMMIT → publish (level 4). Отдельный процесс
outboxкаждые 2 секунды читает неопубликованные строкиoutbox, публикует в RabbitMQ с confirm, затем помечаетpublished_at. Если API упал между COMMIT и publish — outbox опубликует job после рестарта. Если RabbitMQ недоступен — строка остаётся unpublished, повтор при следующем цикле. - Worker отдельный от API.
python -m app.workerзабирает job из RabbitMQ сprefetch_count=1, атомарно переводитqueued→processingс leaseprocessing_until(60 с), скачивает staging, пишет оригинал (final) + thumbnail + crop + optimized, затем атомарноreadyчерезfinalize_ready. Staging удаляется после успешной фиксации. - Идемпотентность эффекта. Ключ
(attachment_id, pipeline_version, variant).claim_processingвозвращает False дляready→ повторная доставка — no-op.finalize_readyиспользуетON CONFLICT DO NOTHING. Повтор job не создаёт дублей вариантов. - 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. - Lease и recover зависших (level 4).
processing_until— deadline для текущей попытки.s3_cleanupпериодически (CLEANUP_INTERVAL_SECONDS) переводит просроченныеprocessingобратно вqueued(recover_stuck_processing). При старте worker также может поднять такие записи. Так зависший processing не «залипает» навсегда. - Варианты обработки (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 по умолчанию).
- Лимиты и защита. Те же
MAX_UPLOAD_BYTES=10485760иMAX_IMAGE_PIXELS=40000000. Pillow в threadpool; лимит пикселей проверяется доload(). Лимит 40 млн пикселей остаётся; worker дополнительно распаковывает под контролем того же лимита (файл уже проверен на входе, но worker defence-in-depth). - 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) не заявлен.