Files
mtusi2026lab4/REPORT.md
T

176 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.
# Отчёт — лабораторная 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-репликой.