# Отчёт — лабораторная 4 - Автор, группа: Герейханов Ильяс, БВТ2301 - Целевая оценка: 4 - Commit/PR: ветка `solution/bvt2301-Gereykhanov`. PR: `ЛР 4 — БВТ2301 — Герейханов — на 4` - Использованные источники, библиотеки и помощь ИИ: Python 3.12, FastAPI, Uvicorn, PostgreSQL 16, Redis 7, Nginx 1.27, MinIO, boto3, Pillow, asyncpg, argon2-cffi, Pydantic, Pytest, Docker Compose; документация AWS S3 API, RFC 7231, OpenAPI 3.1.0. ИИ использовался для подготовки скриптов, отладки конфигурации nginx и расширения тестов pytest. ## Запуск из чистого clone 1. **Версии runtime и образов:** - Локальный runtime: Linux, Docker 29.9.1, Docker Compose v5.6.0 - Load Balancer: `nginx:1.27-alpine` - API контейнеры: `python:3.12-slim` - PostgreSQL: `postgres:16-alpine` - Redis: `redis:7-alpine` - S3-совместимое хранилище: `cleanstart/minio:0.20260330.001845` 2. **Подготовка окружения и запуск стека:** ```sh git checkout solution/bvt2301-Gereykhanov cp .env.example .env # Сборка и запуск всех сервисов make up ``` 3. **Ожидание готовности и запуск проверок:** ```sh # Проверка структуры и синтаксиса make check # Валидация схемы OpenAPI make validate PYTHON=.venv/bin/python # Проверка smoke теста make test # Проверка сценария сохранности данных и сессий при рестарте make test-persistence ACTION_SCRIPT=scripts/restart.sh # Проверка отказоустойчивости при отключении одной API-реплики make test-failover ACTION_SCRIPT=scripts/stop-one.sh # Восстановление остановленной реплики после теста docker compose up -d # Запуск собственных тестов make test-student # Запуск нагрузочного теста python3 tests/load.py --duration 30 --concurrency 4 --output evidence/load.json ``` 4. **Остановка и очистка:** ```sh # Остановка с сохранением данных volumes docker compose down # Остановка с удалением volumes docker compose down -v ``` ## Архитектура и решения - **Топология процессов и распределение ролей:** - **Клиент** отправляет все HTTP-запросы в единую точку входа **Nginx Load Balancer** на порт `8080`. - **Nginx** осуществляет Round-Robin балансировку между двумя независимыми репликами API (`api-1` и `api-2`). - Реплики API работают в stateless-режиме, не имеют открытых портов на хост и доступны только через балансировщик. - Каждая реплика API обращается к общему **PostgreSQL**, **Redis** и **MinIO S3**. - Отдельный одноразовый контейнер **migration** применяет `init.sql` перед стартом API-реплик. - **Хранилища данных и источник истины:** - **PostgreSQL:** источник истины для реляционных данных пользователей, чатов, сообщений и метаданных вложений в таблице `attachments` (`id`, `chat_id`, `owner_id`, `filename`, `content_type`, `size_bytes`, `sha256`, `s3_key`, `status`, `error_code`, `created_at`, `updated_at`). - **MinIO S3:** хранилище бинарного контента в приватном бакете `messenger-attachments`. Ключи объектов формируются по схеме `chats/{chat_id}/{attachment_id}/{filename}`. - **Redis:** сессионный кэш Bearer-токенов с TTL 3600 с и сохранением на volume `redis_data` через `--appendonly yes`. - **Что перенесено из лабы 3:** - Балансировщик Nginx с Round-robin 50/50 и `proxy_next_upstream` для быстрого переключения при сбое. - Сквозные заголовки `X-Request-Id` и `X-Instance-Id` в ответах API. - Единое хранилище сессий в Redis. - Идемпотентность отправки сообщений по заголовку `Idempotency-Key` с сохранением `request_hash` в БД. - Keyset-пагинация сообщений по индексу. - **Интеграция S3 и изоляция сети:** - MinIO включен во внутреннюю Docker-сеть с постоянным volume `minio_data`. - Порты MinIO не проброшены на хост наружу, консоль закрыта от общей сети. - При старте API выполняется автоматический идемпотентный bootstrap: проверка и создание бакета `messenger-attachments` через `boto3`. - **Загрузка, валидация и защита от атак:** - Эндпоинт `POST /api/v1/chats/{chat_id}/attachments?filename=...` принимает сырое бинарное тело (PNG/JPEG) до 10 MiB. - **Проверка MIME по содержимому:** проверяются магические сигнатуры байтов. Невалидные форматы отклоняются с кодом `415`. - **Защита от decompression bomb:** через библиотеку `Pillow` считываются размеры изображения из заголовков IHDR/SOF без декомпрессии растра в память. Превышение лимита 40 млн пикселей возвращает `413 payload_too_large`. - **Валидация имени файла (`filename`):** длина 1–255 символов; отклоняются path-traversal последовательности, NUL-байт (`\0`) и управляющие символы с кодом `400 invalid_request`. - **Компенсация сиротских объектов и прямой download:** - Файл сначала сохраняется в S3 через `boto3.put_object`, после чего выполняется запись метаданных в базу. При ошибке в БД блок `except` вызывает `s3_client.delete_object`, удаляя объект из S3. - Скачивание через `GET /api/v1/attachments/{id}/content` возвращает байты напрямую из S3 без 302/307 редиректов. Запрос от постороннего возвращает строго `404 not_found`. - **Связывание с сообщениями и настройки Nginx:** - В таблицу `messages` добавлено поле `attachment_ids UUID[]`. - Разрешена отправка сообщения с пустым текстом `text=""`, если прикреплены файлы. - В `infra/nginx.conf` задана директива `client_max_body_size 15M;` для пропуска 10 MiB загрузок. - Все параметры согласованы с `.env.example`: `S3_ENDPOINT`, `S3_BUCKET`, `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS`. ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | | Проверка синтаксиса и контракта | `make check` | `PASS: offline skeleton structure, local refs and Python syntax` | [`evidence/check_contract.log`](evidence/check_contract.log) | | Полная OpenAPI 3.1 валидация | `make validate PYTHON=.venv/bin/python` | `PASS: full OpenAPI 3.1 and JSON Schema validation` | [`evidence/validate_openapi.log`](evidence/validate_openapi.log) | | Публичный smoke тест | `make test` | `PASS: lab4 public API scenario` | [`evidence/smoke_test.log`](evidence/smoke_test.log) | | Чередование реплик | `for i in {1..10}; do curl -sI http://localhost:8080/health/live \| grep -i x-instance-id; done` | 50 на 50 ответы `api-1` и `api-2` | [`evidence/round_robin.log`](evidence/round_robin.log) | | Сохранение данных и сессий при рестарте | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | Стек перезапущен, токен, сообщения и вложения в S3 сохранены | [`evidence/persistence_test.log`](evidence/persistence_test.log) | | Отказ API-реплики под нагрузкой | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | Восстановление записи за **0.778 с**, 105 успешных запросов, 0 сбоев | [`evidence/failover_test.log`](evidence/failover_test.log) | | Защита от decompression bomb (>40M px) | `make test-student` | Запрос с 50M px изображением отклонен с `413 payload_too_large` | [`evidence/student_tests.log`](evidence/student_tests.log) | | Проверка MIME по магическим байтам | `make test-student` | Поддельные и поврежденные изображения отклоняются с `415` | [`evidence/student_tests.log`](evidence/student_tests.log) | | Компенсация сирот S3 при отказе БД | `make test-student` | При сбое PostgreSQL объект удаляется из S3, в хранилище нет сирот | [`evidence/student_tests.log`](evidence/student_tests.log) | | Закрытый бакет и лимит RAM (10 загрузок) | `make test-student` | Порт 9000 закрыт снаружи, 10 параллельных загрузок успешны, RAM стабильна | [`evidence/student_tests.log`](evidence/student_tests.log) | | Собственные тесты | `make test-student` | **34 теста проходят**: валидация вложений, компенсация S3, курсор, идемпотентность | [`evidence/student_tests.log`](evidence/student_tests.log) | | Статусы и изоляция контейнеров | `docker compose ps` | Все 6 сервисов healthy, API и MinIO не открывают порты на хост | [`evidence/docker_services.log`](evidence/docker_services.log) | | Нагрузочный тест | `make load` | **309.4 RPS**, p50 = 7.9 ms, p95 = 40.8 ms, p99 = 63.0 ms, 0 ошибок | [`evidence/load.json`](evidence/load.json) | ## Эксперименты и отказы - **Профиль нагрузки:** скрипт `tests/load.py`, закрытый цикл параллельных POST-запросов отправки сообщений с уникальными `Idempotency-Key`. - **Параметры:** длительность 30 секунд, 4 параллельных потока. - **Результаты нагрузки (`evidence/load.json`):** ```json { "lab": 4, "workload": "closed-loop POST messages; no automatic retries", "requested_duration_seconds": 30.0, "elapsed_seconds": 30.015, "concurrency": 4, "successful_requests": 9286, "failed_requests": 0, "error_ratio": 0.0, "successful_rps": 309.375, "successful_latency_ms": { "p50": 7.928, "p95": 40.768, "p99": 62.963 } } ``` | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | | Остановка одной реплики API (`scripts/stop-one.sh`) | Nginx переключает трафик на живую реплику, продолжение записи $\le 10$ с, нет дубликатов | 105 успешных записей во время остановки, 0 ошибок, переключение за 0.778 с | 0.778 сек, потерь данных нет | | Рестарт всего стека (`scripts/restart.sh`) при активной сессии| Сохранение подтверждённых данных в Postgres, токенов сессий в Redis и файлов в MinIO | Контейнеры перезапущены, токен валиден, история сообщений и файлы сохранены | Восстановление около 5 сек, потеря подтверждённых данных: 0 | | Загрузка декомпрессионной бомбы (изображение 10000x5000) | Отклонение запроса с кодом 413 `payload_too_large` без исчерпания RAM | Запрос отклонен мгновенно по метаданным IHDR без распаковки растра | Мгновенно (< 2 мс) | | Загрузка файла размером более 10 MiB | Отклонение запроса с кодом 413 `payload_too_large` | Запрос отклонен до сохранения в S3 | Мгновенно | | Попытка загрузки файла с поддельным расширением | Отклонение с кодом 415 `unsupported_media_type` | Проверка сигнатуры байтов выявляет подмену и возвращает 415 | Мгновенно | | Попытка доступа к метаданным или контенту посторонним пользователем | Защита приватности: возврат строго 404 Not Found без утечки факта существования файла | Посторонний получает 404 на `GET /attachments/{id}` и `/content` | Мгновенно | | Попытка передачи опасного имени файла | Отклонение запроса с кодом 400 `invalid_request` | Валидатор отклоняет некорректное имя до обращения к хранилищу | Мгновенно | | Сбой сохранения метаданных в БД после успешного `PUT` в S3 | Автоматическое удаление объекта из S3 | В S3 не остается мусорных файлов | Мгновенно | | Конкурентная загрузка ≥10 файлов с контролем RAM | Все файлы сохраняются в S3, память API стабильна | 10 параллельных загрузок вернули 201 ready, утечек памяти нет | Мгновенно (< 1 с) | | Попытка прямого обращения к MinIO на порт 9000 с хоста | Соединение отклоняется (Connection Refused), консоль закрыта | Порты MinIO не проброшены наружу, прямой доступ невозможен | Мгновенно | ## Ограничения - **Какие отказы выдерживаются и какие нет:** 1. *Выдерживаются:* - Внезапная остановка любой одной API-реплики под нагрузкой: балансировщик Nginx переключает входящие запросы на оставшуюся реплику. - Полный рестарт стека: все подтверждённые данные, активные токены и файлы в S3 сохраняются благодаря volumes. - Конкурентная отправка сообщений с одинаковым `Idempotency-Key` в разные реплики. - Попытки атак декомпрессионными бомбами и внедрения вредоносных имен файлов. - Сбои транзакций после записи в S3: механизм компенсации удаляет сиротские объекты. 2. *Не выдерживаются:* - Одновременное падение обеих API-реплик (HTTP 502 Bad Gateway). - Падение единственного экземпляра PostgreSQL, Redis или MinIO. - Удаление через `docker compose down -v`. - **Учебные упрощения:** 1. Nginx, PostgreSQL, Redis и MinIO запущены в единственном экземпляре без распределенной репликации. 2. Скачивание контента реализовано через проксирование байтов API-репликой.