# Отчёт — лабораторная 4 - Автор, группа: Морозова Ольга Андреевна, БВТ2303 - Целевая оценка: **4** (треки на 5 не заявлены) - Commit/PR: TODO после публикации - Использованные источники: [README.md](README.md), [COURSE.md](COURSE.md), [contracts/openapi.json](contracts/openapi.json), документация Go, MinIO, PostgreSQL, Nginx, Redis, Docker. - Библиотеки: Go 1.22 (stdlib), github.com/google/uuid v1.6.0, github.com/jackc/pgx/v5 v5.5.5, github.com/redis/go-redis/v9 v9.5.1, golang.org/x/crypto v0.23.0, github.com/minio/minio-go/v7 v7.0.72. Тесты — Python 3 (stdlib). - Помощь ИИ: Deepseek — написание и проверка кода. ## Запуск из чистого clone Команды выполнялись в WSL2 (Ubuntu) на Windows 11. Требования: Docker 24+ (Compose v2), Python 3.9+ (для тестов), `make`. Версии (фиксированные теги образов): - `golang:1.22-alpine` — build stage - `alpine:3.20` — runtime stage - `postgres:16.3-alpine` — база данных - `redis:7.2.5-alpine` — кэш - `nginx:1.27.0-alpine` — балансировщик - `pgsty/silo:RELEASE.2026-10-26T00-00-00Z` — S3-совместимое хранилище ### Подготовка ```sh git clone https://gitea.privcloud.tech/MiniLynx/mtusi2026lab4-fork cd mtusi2026lab4-fork # 1. Секреты (не входят в Git) mkdir -p secrets printf 'local-dev-postgres-password\n' > secrets/postgres_password.txt printf 'postgres://messenger:local-dev-postgres-password@postgres:5432/messenger?sslmode=disable\n' > secrets/database_url.txt printf 'redis://redis:6379/0\n' > secrets/cache_url.txt printf 'minioadmin\n' > secrets/minio_root_user.txt printf 'minioadmin-dev-password\n' > secrets/minio_root_password.txt printf 'messenger-api\n' > secrets/s3_access_key_id.txt printf 'messenger-api-dev-secret\n' > secrets/s3_secret_access_key.txt chmod 600 secrets/*.txt # 2. Локальный .env cp .env.example .env # ВАЖНО: В .env нужно исправить S3_ENDPOINT на s3:9000 (без http://), так как minio-go ожидает host:port sed -i 's|S3_ENDPOINT=.*|S3_ENDPOINT=s3:9000|' .env ``` # 3. Python для проверок python3 -m venv .venv source .venv/bin/activate python -m pip install -r requirements-dev.txt # 4. Скрипты chmod +x scripts/restart.sh scripts/stop-one.sh scripts/restore-api.sh ```` ### Сборка и запуск ```sh docker compose --env-file .env config --quiet docker compose --env-file .env up -d --build # Дождаться /health/ready docker compose ps ```` Для запуска с другим количеством реплик добавить `API_REPLICAS=$n` перед `docker compose --env-file .env up -d --build`, где `$n` - желаемое количество реплик. ### Тесты ```sh make check make validate PYTHON=.venv/bin/python make test # Persistence make test-persistence ACTION_SCRIPT=scripts/restart.sh # Failover make test-failover ACTION_SCRIPT=scripts/stop-one.sh # Восстановление реплики после теста: ./scripts/restore-api.sh # Собственные тесты (негативные сценарии, нагрузка, отказ S3, GC) make my_tests ``` ### Остановка (с сохранением volumes) ```sh docker compose --env-file .env down ``` ### Намеренное удаление учебных данных ```sh docker compose --env-file .env down -v rm -f secrets/*.txt ``` ## Архитектура и решения ```text HTTP-клиент → Nginx (порт 8080) → API (Go, x N реплик, non-root) ├── PostgreSQL 16.3 ─ users, chats, messages, sessions, idempotency_keys, attachments, attachment_gc ├── Redis 7.2.5 ─ кэш сессий └── S3 (pgsty/silo) ─ приватный bucket messenger-attachments ``` - **S3-хранилище:** Развернуто S3-совместимое хранилище `pgsty/silo`. Создание бакета и ограниченного пользователя API вынесено в отдельный идемпотентный сервис `s3-init` (`infra/minio/bootstrap.sh`), который запускается один раз перед стартом API. Бакет приватный (`mc anonymous set none`). Консоль управления (9001) не проброшена наружу. - **Права S3:** API использует отдельные креды (`messenger-api`), которым через политику `api-attachments` разрешены только `PutObject`, `GetObject`, `DeleteObject` и `ListBucket` в рамках бакета. Root-креды (`minioadmin`) используются только на этапе bootstrap. - **Потоковая обработка (без OOM):** В `src/domain/s3.go` метод `PutValidatedImage` читает тело запроса с жестким лимитом (`MAX_UPLOAD_BYTES + 1`) напрямую во временный файл на диске (`os.CreateTemp`). Это исключает выделение оперативной памяти под весь файл. MIME определяется по первым 512 байтам (`http.DetectContentType`), размеры проверяются через image.DecodeConfig до полного декодирования. Пиксели ограничены `MAX_IMAGE_PIXELS`. Затем файл стримится в S3 с одновременным вычислением SHA-256. - **Устойчивость к отказам S3:** В `S3Store` настроен кастомный `http.Transport` с короткими таймаутами (Dial — 3с, Response Header — 5с). Для скачивания реализована логика ретраев (до 2 попыток с интервалом 500 мс) с общим дедлайном 6 секунд. Это предотвращает «зависание» API-реплики при недоступности S3. - **Компенсация (GC):** При загрузке сначала создается запись `pending` в `attachments`. После успешного `PutObject` и проверки файла запись переводится в `ready` транзакцией. Если S3 PUT прошел, а COMMIT в БД упал — ключ объекта помещается в таблицу `attachment_gc`. Фоновый процесс (запускается каждые 2 минуты в `main.go`) вызывает `ReconcileOrphans`, который безопасно удаляет объекты из `attachment_gc` и «зависшие» `pending`-записи старше grace period (600 секунд). - **Авторизация:** Скачивание и получение метаданных вложения доступно только участникам чата (JOIN с `chat_members`). Посторонние получают 404. - **Graceful shutdown:** API перехватывает SIGTERM и корректно завершает текущие запросы (15 секунд). ### Что перенесено из lab3 - PostgreSQL, миграции, структура Go-пакета. - Argon2id для паролей, схема sessions. - Redis как кэш, горизонтальное масштабирование, Nginx как балансировщик. - Механизм идемпотентности на базе `idempotency_keys`. ### Что изменено - Добавлена миграция `0005_attachments.sql` (таблицы `attachments`, `attachment_gc`, поле `attachment_ids` в `messages`). - Добавлены обработчики загрузки (`POST /api/v1/chats/{id}/attachments`), метаданных и скачивания (`GET /api/v1/attachments/{id}/content`). - В `compose.yaml` добавлены сервисы `s3` и `s3-init`, проброшены секреты MinIO. - В `messages` добавлена поддержка массива `attachment_ids`, который валидируется при отправке сообщения (вложение должно принадлежать этому чату). - В `domain/s3.go` добавлены кастомные таймауты, запись во временный файл и ретраи. ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | -------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | Offline-структура и локальные refs | `make check` | PASS | [png](evidence/1_Tests_Passing.png) | | Полная OpenAPI 3.1 и JSON Schema | `make validate PYTHON=.venv/bin/python` | PASS | [png](evidence/1_Tests_Passing.png) | | Публичный smoke (lab4) | `make test` | PASS | [png](evidence/1_Tests_Passing.png) | | Persistence: перезапуск API+БД+Redis+S3, вложение живо | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS | [png](evidence/1_Tests_Passing.png) | | **Уровень 3:** остановка любой 1 реплики (с вложением) | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | `observed_instances_before: 2`, `successful_writes: 78`, `failed_attempts: 1`, `first_recovery: 2.8s` | [png](evidence/1_Tests_Passing.png) | | **Уровень 4:** негативные сценарии (413, 415, MIME, ACL) | `python3 student-tests/negative.py` | PASS: lab4 negative suite | [png](evidence/2_My_Tests_Passing.png) | | **Уровень 4:** эксперимент ≥10 параллельных загрузок | `python3 student-tests/load_mem.py` | Пик памяти API: 62.89 MB (лимит 128M) | [png](evidence/2_My_Tests_Passing.png), [txt](evidence/mem_report.txt) | | **Уровень 4:** private bucket вне API | `docker compose exec api wget ...` | `403 Forbidden` | [png](evidence/3_Private_Bucket_Check.png) | | **Уровень 4:** отказ S3 и восстановление | `python3 student-tests/test_s3_failure.py` | Остановка S3 → 503, Запуск S3 → 200 | [png](evidence/2_My_Tests_Passing.png) | | **Уровень 4:** очистка orphan-объектов (GC) | `python3 student-tests/test_gc.py` | Записи удалены фоновым reconciler за 22 с. | [png](evidence/2_My_Tests_Passing.png) | | Топология: 2 реплики, S3, LB | `docker compose ps` | Все контейнеры healthy | [png](evidence/4_Healthcheck.png) | ## Эксперименты и отказы ### Эксперимент с памятью (≥10 параллельных загрузок) **Гипотеза:** Запись тела запроса во временный файл на диске (`os.CreateTemp`) и ограничение чтения (`io.LimitReader`) предотвратят неограниченный рост RAM при множественных одновременных загрузках больших файлов. **Методика:** - Запуск 10 параллельных POST-запросов на загрузку изображения размером 5 МБ. - В процессе выполнения каждые 100 мс снимались показатели `docker stats` целевого контейнера API. - Лимит памяти контейнера API: `128M`. **Результат:** - Все 10 запросов завершились успешно (201 Created) за 1.97 с. - Пиковое потребление памяти (RSS) на API-реплике: **62.89 MB**. - Превышения лимита и OOM-kill не произошло, память зависит от размера буферов HTTP, а не от общего объема загружаемых файлов. **Вывод:** Обработка безопасна по памяти, буферизация в RAM отсутствует. ### Отказы | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | -------------------------------- | ---------------------------------- | -------------------------------------------- | ---------------------------------------------------- | | `SIGTERM` (graceful shutdown) | Корректное завершение, 0 потерь | `shutting down... → stopped` | ≤1 с | | SIGKILL одной реплики (failover) | Nginx убирает её, трафик на живые | `make test-failover` PASS | 2.8 с; данные и вложения сохранены | | Отказ S3 (контейнер остановлен) | Ошибка 503 для загрузки/скачивания | 503 Service Unavailable | До восстановления контейнера S3 (проверено скриптом) | | Redis недоступен | API работает через PostgreSQL | 200 на `/health/ready` | без потерь | | PostgreSQL недоступен | `/health/ready` → 503 | 503 | до восстановления контейнера | | Прерывание между S3 и БД | Объект не остается вечным мусором | `attachment_gc` + фоновый `ReconcileOrphans` | Grace period 600 с | | Скачивание файла посторонним | 404 Not Found | 404 | — | ## Ограничения и следующие шаги - **Один Docker-host:** падение хоста или PostgreSQL/Redis/S3-контейнеров не покрывается. Nginx, БД и S3 остаются SPOF (Single Point of Failure) для физических серверов. - **Reconciler:** запускается внутри каждого процесса API раз в 2 минуты. При масштабировании реплик возможна параллельная работа нескольких реконсилеров (частично решается `FOR UPDATE SKIP LOCKED` или выделенным фоновым процессом). - **Безопасность:** Соединение между API и S3 идет по HTTP внутри изолированной Docker-сети (backend), без TLS/mTLS.