Files
mtusi2026lab5/REPORT.md
T

14 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, 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 *  # новый: негативные тесты, компенсация, параллельные загрузки

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

TODO

Соответствие .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
Остальные пункты уровня 3 TODO TODO TODO
Все пункты уровня 4, если заявлен TODO TODO TODO

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

(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

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

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

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

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

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