Files
2026-11-06 15:49:15 +03:00

188 lines
17 KiB
Markdown
Raw Permalink 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
- Автор, группа: Морозова Ольга Андреевна, БВТ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.