Files
mtusi2026lab6/REPORT.md
T

251 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 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: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.