Files
mtusi2026lab4/REPORT.md
T

24 KiB
Raw Blame History

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

  • Автор, группа: Васюкова Наталья, БВТ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, 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
  • PostgreSQL 18.6-alpine, Redis 7.4.1-alpine, nginx 1.27.3-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/mtusi2026lab4.git
    git checkout solution/BVT2303-Vasyukova
    
  2. Создать .env из шаблона:
    copy .env.example .env
    
  3. Собрать и поднять (LB + 2 реплики API + PostgreSQL + Redis + MinIO + minio-init + 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/lab4_test_level4.py --base-url http://localhost:8080

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

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

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

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

                      ┌─ api-1 (uvicorn:8080, INSTANCE_ID=…)
HTTP-клиент → lb:80 ──┤                                     ↘
   (nginx)            └─ api-2 (uvicorn:8080, INSTANCE_ID=…)  PostgreSQL 18.6 (метаданные)
                                                              Redis 7.4.1 (сессии)
                                                              MinIO (S3-байты, приватный bucket)
                                                              s3_cleanup (сверка S3↔БД)

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

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

  • PostgreSQL — данные (пользователи, чаты, членство, сообщения) и ключи идемпотентности.
  • Redis — серверные сессии (общие для всех реплик).
  • MinIO (S3) — байты вложений (приватный bucket messenger-attachments).

Схема БД (подробнее — 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,
            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))
  + INDEX idx_msg_att_message(message_id, position)

Применяется идемпотентно через 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 ответа ключа в одной транзакции.
  • Создание/отзыв сессии — одна операция.

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

mtuci2026lab4/
├── compose.yaml *            # + minio, minio-init, s3_cleanup; lab4-network
├── Dockerfile
├── docker-entrypoint.sh       # генерирует INSTANCE_ID, пишет /tmp/instance_id
├── infra/nginx.conf
├── Makefile
├── requirements.txt *         # + boto3, Pillow
├── src/app/
│   ├── main.py *              # + attachments router, версия 1.4.0
│   ├── api/
│   │   ├── attachments.py *   # новый: upload/get/download вложений
│   │   ├── messages.py *      # CreateMessage c attachment_ids, проверка принадлежности чату
│   │   └── health.py *        # + проверка S3
│   ├── models/
│   │   └── schemas.py *       # + Attachment, Variant, Message.attachment_ids
│   └── storage/
│       ├── db.py *            # + attachments, message_attachments
│       ├── postgres.py *      # + методы для вложений, идемпотентность с attachments
│       └── s3.py *            # новый: boto3-клиент, keyspace
│       └── s3_cleanup.py *    # новый: фоновая сверка S3↔БД
├── scripts/
│   ├── restart.sh / .bat *    # + minio, s3_cleanup
│   └── stop-one.sh / .bat     # без изменений
└── student-tests/
    └── lab4_test_level4.py *  # новый: негативные тесты, компенсация, параллельные загрузки

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

  1. Разделение метаданных и байтов. Метаданные вложений (attachments) живут в PostgreSQL; сами байты — в приватном S3-bucket в MinIO. Object key назначает сервер: attachments/<chat_id>/<attachment_id>/original, filename используется только для отображения (не как ключ).
  2. Синхронный upload. POST /api/v1/chats/{chat_id}/attachments?filename=... принимает сырые байты одного PNG/JPEG (не multipart, не base64). После PUT в S3 и INSERT в БД возвращает 201 Attachment со status=ready. Порядок: сначала S3 PUT, потом INSERT. Если INSERT падает — объект удаляется из S3 (компенсация).
  3. Авторизованный download. GET /api/v1/attachments/{id} и GET /api/v1/attachments/{id}/content доступны только участникам чата. Байты отдаются через API без redirect. Приватный bucket сам по себе не заменяет ACL приложения.
  4. Лимиты. MAX_UPLOAD_BYTES=10485760 (10 MiB) и MAX_IMAGE_PIXELS=40000000 (40 млн пикселей). Лимит размера — до полного чтения (Content-Length + потоковое чтение с жёстким потолком); лимит пикселей — до полной распаковки (Pillow открывает заголовок и отдаёт size без load()). MIME определяется по байтам, не по заголовку.
  5. Вложение в сообщении. POST /messages принимает attachment_ids (0–10 уникальных UUID). Все ID должны принадлежать этому чату (иначе 404); failed прикреплять нельзя (в lab4 все ready). Можно отправить text="" с хотя бы одним вложением. Связь хранится в message_attachments, порядок сохраняется.
  6. MinIO bootstrap. minio-init создаёт bucket messenger-attachments (mc mb --ignore-existing), снимает анонимный доступ (mc anonymous set none), создаёт прикладного S3-пользователя messenger-app с ограниченной политикой (s3:GetBucketLocation, s3:ListBucket, s3:GetObject, s3:PutObject, s3:DeleteObject, s3:AbortMultipartUpload, s3:ListMultipartUploadParts). API использует эти ограниченные credentials; root (MINIO_ROOT_USER) остаётся только у minio/minio-init.
  7. Компенсация orphan. При сбое между S3 PUT и INSERT API удаляет S3-объект и отдаёт 503. Дополнительно s3_cleanup раз в CLEANUP_INTERVAL_SECONDS (по умолчанию 300 с) сверяет S3↔БД: объекты в S3 без метаданных старше ORPHAN_GRACE_SECONDS (по умолчанию 3600 с) удаляются; метаданные без объекта логируются как missing_object. Grace period защищает от удаления in-flight uploads.
  8. Readiness. /health/ready теперь проверяет PostgreSQL, Redis (в режиме redis) и S3. S3 — критичная зависимость для обязательного синхронного пути загрузки.

Соответствие .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 и s3_cleanup.
  • MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS — лимиты вложений.
  • CLEANUP_INTERVAL_SECONDS — период сверки S3↔БД.
  • ORPHAN_GRACE_SECONDS — grace period для удаления orphan-объектов.
  • CACHE_URL_FILE — резервная переменная из скелета, не используется.

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

Критерий Команда Наблюдаемый результат Уровень
Публичный smoke python tests/smoke.py PASS: lab4 public API scenario 3
S3-сервер в общем стенде, приватный bucket docker compose ps; minio-init minio/minio-init/s3_cleanup Up; bucket messenger-attachments создан 3
Метаданные в PostgreSQL, байты в S3 smoke: POST /attachments, GET /content 201 ready, SHA-256 оригинала совпадает с sha256 в ответе, байты скачаны побайтно 3
Вложение читается участниками чата; посторонний → 404 smoke, lab4_test_level4.py::test_foreign_attachment_and_cross_chat PASS: foreign → 404, cross-chat → 404 3
PNG/JPEG ≤10 MiB, ≤40M пикселей, MIME по содержимому lab4_test_level4.py::test_oversize, test_corrupted_image, test_mime_spoof 413, 415, 415 3
Опасный filename отклоняется lab4_test_level4.py::test_bad_filename 400 для ../, /, \, \x00, \n 3
Upload → stop replica → download через другую resilience.py --mode failover observed_instances_before=2, successful_writes=8, first_recovery=4.146 s, PASS 3
Restart сохраняет метаданные и оригинал resilience.py --mode persistence PASS (исходный файл сверен по SHA-256) 3
Пользовательская ошибка не превращается в 500 lab4_test_level4.py (все негативные кейсы) 4xx, не 5xx 4
Отказ между S3 PUT и INSERT не оставляет orphan lab4_test_level4.py::test_compensation_on_db_failure 503, bucket не вырос (before=10, after=10) 4
≥10 параллельных загрузок, пик RSS lab4_test_level4.py::test_parallel_uploads_memory 10 загрузок, пик RSS=88.94 MiB (<400 MiB) 4
Прикладные S3-credentials с ограниченной политикой minio-init (mc admin policy) API использует S3_APP_KEY_ID; root только у minio/minio-init 4
Приватный bucket вне API docker run ... mc anonymous get none; curl без credentials → 403 4
Bucket bootstrap идемпотентен повторный docker compose up -d minio-init не падает; bucket/user/policy не пересоздаются 4
Административная консоль не открыта наружу compose.yaml у minio нет ports:; localhost:9001 недоступен 4
Компенсация/сверка документирована src/app/storage/s3_cleanup.py + ORPHAN_GRACE_SECONDS лог event=orphan_deleted (см. Эксперименты) 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: lab4 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
PASS: persistence preserved confirmed data and existing session.

(venv) PS ...> python tests/resilience.py --mode failover --action-script scripts/stop-one.bat --base-url http://localhost:8080
{"observed_instances_before": 2, "successful_writes": 8, "failed_attempts": 0, "first_recovery_seconds": 4.146}
PASS: failover preserved confirmed data and existing session.

(venv) PS ...> python student-tests/lab4_test_level4.py --base-url http://localhost:8080
=== oversize ===
PASS: oversize -> 413
=== corrupted image ===
PASS: corrupted -> 415
=== spoofed MIME ===
PASS: spoofed MIME -> 415
=== bad filename ===
PASS: bad filename -> 400
=== foreign attachment / cross-chat ===
PASS: foreign -> 404, cross-chat -> 404
=== attachment belongs to chat ===
PASS: attachment from another chat -> 404
=== compensation on DB failure ===
  upload при мёртвой БД вернул 503
  компенсация: bucket не вырос (before=10 after=10)
PASS: компенсация orphan-объектов при отказе БД
=== parallel uploads memory ===
  10 параллельных загрузок, пик RSS=88.94 MiB
PASS: 10 параллельных загрузок в пределах лимита памяти
PASS: all lab4 level-4 checks passed

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

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

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker compose stop postgres во время upload S3 PUT прошёл, INSERT падает, компенсация удаляет объект, ответ 503 503, bucket не вырос (before=10, after=10) 0; после start postgres — ready за ≤90 с, по факту ~10 с
docker stop одной API-реплики (failover) Вторая реплика продолжает обслуживать; подтверждённое не теряется; идемпотентность без дублей 2 реплики до, 8 успешных записей, 0 ошибок, recovery=4.146 s ≤10 с; потери нет
scripts/restart.bat (LB, обе реплики, Postgres, Redis, MinIO, s3_cleanup) Данные PostgreSQL/Redis и оригинал в S3 сохраняются, сессия продолжает работать PASS: тот же токен и тот же SHA-256 файла после перезапуска Готовность ≤90 с; потери нет
10 одновременных загрузок sample.png Все 201; пик RSS API ограничен 10×201, пик RSS=88.94 MiB —
Ручное удаление строки attachments (orphan) + ожидание grace s3_cleanup удаляет объект, в логе event=orphan_deleted docker compose logs s3_cleanup: event=orphan_deleted key=attachments/.../original ≤CLEANUP_INTERVAL_SECONDS + ORPHAN_GRACE_SECONDS
Upload с MAX_UPLOAD_BYTES=10485761 413 до сохранения в S3 413, объект не появился в bucket 0

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

  • Один Docker-host. Отказ узла не проверялся; LB, PostgreSQL, Redis, MinIO — единичные экземпляры (SPOF). HA БД/LB/S3 не заявляется.
  • MinIO без репликации. Один bucket, один сервер. Отказ диска MinIO = потеря оригиналов, если не настроить репликацию/бэкап. Для уровня 4 это не требуется.
  • Обнаружение отказа API — реактивное. LB узнаёт о мёртвой реплике по первой ошибке (proxy_next_upstream), поэтому возможна короткая задержка ~4–5 с до исключения из ротации. Это укладывается в ≤10 с по методичке.
  • Компенсация «S3 → БД». Основной путь — удалить S3-объект при ошибке INSERT. Обратный случай (метаданные есть, S3-объект потерян) ловится s3_cleanup как missing_object, но не «самолечится» (файл восстановить неоткуда). Для учебного стенда этого достаточно.
  • s3_cleanup — best-effort. Если процесс упал во время цикла, при следующем запуске сверка продолжается. БД и S3 читаются без блокировок, гонки с in-flight upload защищены ORPHAN_GRACE_SECONDS.
  • Память загрузки. Тело загрузки читается в память (chunks: list[bytes]). При MAX_UPLOAD_BYTES=10 MiB и api limit 512M пик RSS 88.94 MiB при 10 параллельных загрузках — приемлемо. Для больших лимитов потребуется потоковая отправка в S3 (upload_fileobj) вместо буфера; для уровня 4 не требуется.
  • Pillow в threadpool. Валидация изображения выполняется в run_in_threadpool, чтобы не блокировать event loop. Порог пикселей берётся из заголовка до полной распаковки; «бомба» с маленьким заголовком и большим load() не пройдёт лимит по пикселям, а реальное декодирование отложено до клиента (побайтовая сверка sha256 всё равно сходится при скачивании).
  • Идемпотентность только на POST сообщения. POST /users, POST /chats, POST /attachments без Idempotency-Key — повтор создаёт новый объект, что соответствует контракту.
  • Часы. Порядок (created_at, id) требует монотонности created_at в пределах сервера; для учебного стенда с одной БД это выполняется.
  • Нагрузка. Полноценных замеров RPS/p50/p95/p99 при фиксированных ресурсах не проводилось — для целевой оценки 4 это не требуется. Трек 5 (presigned-upload или reconciler) не заявлен.