diff --git a/REPORT.md b/REPORT.md index e98f75e9..db591b94 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,28 +1,221 @@ # Отчёт — лабораторная 5 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор, группа: Васюкова Наталья, БВТ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 -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Версии 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 # ТОЛЬКО если осознанно стираем данные +``` ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab4, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +Схема процессов и хранилищ: + +``` + ┌─ 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` — резервная переменная из скелета, не используется. ## Доказательства критериев -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | +| Критерий | Команда | Наблюдаемый результат | Уровень | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | +| Публичный 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 | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +### Выводы тестов + +``` +(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 +``` ## Эксперименты и отказы