forked from mtusi2026/mtusi2026lab4
146 lines
27 KiB
Markdown
146 lines
27 KiB
Markdown
# Отчёт — лабораторная 4
|
||
|
||
- Автор, группа: Унру Д.В. БПИ2303
|
||
- Целевая оценка; выбранный трек 5, если нужен: **3** (трек 5 не заявлен)
|
||
- Commit/PR: TODO после публикации
|
||
- Использованные источники, библиотеки и помощь ИИ: FastAPI, Pydantic v2, Uvicorn, Psycopg 3, redis-py, argon2-cffi, boto3/botocore, Pillow, pytest; документация [S3 uploads](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html), [Pillow Image](https://pillow.readthedocs.io/en/stable/reference/Image.html), [Boto3 configuration](https://docs.aws.amazon.com/boto3/latest/guide/configuration.html), [MinIO IAM](https://github.com/minio/minio/blob/master/docs/multi-user/README.md), [Nginx upstream](https://nginx.org/en/docs/http/ngx_http_upstream_module.html).
|
||
|
||
## Запуск из чистого clone
|
||
|
||
```sh
|
||
git clone <fork-url> && cd <каталог-fork-лабораторной-4>
|
||
make up # secrets → сборка API/MinIO/mc → migrate/init → api×2/cleanup/Nginx
|
||
curl -fsS http://localhost:8080/health/ready
|
||
docker compose ps --all # API×2/PG/Redis/MinIO/cleanup/LB работают; migrate и minio-init — Exited(0)
|
||
|
||
make check
|
||
make validate-container
|
||
make test # публичный smoke lab4 через Nginx
|
||
make test-student # 21 собственный интеграционный тест
|
||
make test-fresh # миграции 001–003, новый bucket и тесты на отдельных пустых volumes
|
||
make test-attachments # private bucket, upload→отказ API→download, обрыв, crash+cleanup, отказ S3
|
||
make uploads # 10 одновременных загрузок с измерением пика RAM
|
||
make test-cluster # сохранённые проверки общей сессии/idempotency/restart/failover/SIGTERM/rolling
|
||
```
|
||
|
||
`make up` выполняет bootstrap, `docker compose build api minio minio-init`, затем `up --wait` и ожидание двух API-alias через LB. При повторной сборке Go/Python-слои используются из кэша. Сценарии отказов и замер памяти запускать по одному: они останавливают/пересоздают контейнеры. `make uploads` пересоздаёт только API, чтобы сбросить kernel memory high-water marks; volumes и данные сохраняются.
|
||
|
||
**Почему MinIO собирается из исходников:** проверенные release-образы в Docker Hub/Quay недоступны, официальный архив бинарников ответил 410. В `infra/minio/Dockerfile` собираются официальные теги и проверяется точный commit: MinIO `RELEASE.2025-04-22T22-12-26Z` / `0d7408fc9969caf07de6a8c3a84f9fbb10a6739e`, mc `RELEASE.2025-04-16T18-13-26Z` / `b00526b153a31b36767991a4f5ce2cced435ee8e`. Builder — `golang:1.24.2-bookworm`, зависимости сверяются по upstream go.sum. Runtime-образы локальные `mtusi-lab4-minio:2025-04-22` и `mtusi-lab4-mc:2025-04-16`; скачивать готовый сервер преподавателя не требуется.
|
||
|
||
`bootstrap.sh` однократно создаёт пароль БД, root-credentials MinIO и отдельные API S3 credentials в `secrets/`; повтор их не меняет. Каталог 0700 на хосте, файлы доступны нужному uid через Compose secrets. Root S3 secrets получает только MinIO и minio-init; API/cleanup получают ограниченного пользователя. `.env`, secrets и volumes не входят в Git/build context. Учебные данные и credentials lab3 не копировались.
|
||
|
||
Безопасная остановка: `make down`, именованные volumes `postgres_data`, `redis_data`, `minio_data` сохраняются. Намеренное удаление всех учебных данных: `docker compose down --volumes`. Restart hook volumes не удаляет. `make test-fresh` удаляет только созданные им временные volumes отдельного проекта. После обычных тестов синтетические пользователи/сообщения/вложения остаются — delete не входит в обязательный API.
|
||
|
||
Отдельные команды:
|
||
|
||
```sh
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
|
||
# После отдельного публичного failover восстановить остановленную реплику:
|
||
docker compose up -d --no-recreate --wait --wait-timeout 90
|
||
python3 scripts/cluster.py wait
|
||
|
||
make cleanup-dry-run
|
||
# Явная безопасная очистка с обычным grace 300s:
|
||
docker compose run --rm --no-deps cleanup python -m messenger.cleanup --apply
|
||
```
|
||
|
||
## Архитектура и решения
|
||
|
||
```text
|
||
клиент → Nginx → API ×2 ──→ PostgreSQL: пользователи/чаты/сообщения/сессии/metadata/связи
|
||
├─→ Redis: кэш публичного профиля
|
||
└─→ MinIO: оригинальные байты, приватный bucket
|
||
|
||
migrate → PostgreSQL minio-init → bucket/user/policy
|
||
cleanup → S3 listing + PostgreSQL recheck → удаление только старых неучтённых объектов
|
||
```
|
||
|
||
- **Перенос из lab3.** Сохранены Nginx, два экземпляра одного service api, общая PostgreSQL, Argon2id/Basic→Bearer, Redis cache-aside профиля, keyset-пагинация, X-Instance-Id и транзакционная идемпотентность сообщений. Сохранены публичные tests/contracts/README текущего skeleton. Служебные документы находятся отдельно в `lab4/docs/`.
|
||
- **Схема** (`003_attachments.sql`). `attachments`: UUID PK, chat_id/owner_id FK, составной FK на членство, filename, MIME, размер 1–10 MiB, SHA-256, уникальный object_key, created_at/updated_at. `message_attachments`: FK на сообщение/вложение, position 0–9, уникальны пара и позиция. Байты не хранятся в PostgreSQL. Проверка same-chat перед INSERT связи даёт 404 для чужого/неизвестного attachment_id. Любой участник может использовать доступное вложение своего чата.
|
||
- **Совместимость сообщения.** В ответах добавлен attachment_ids; в запросе по умолчанию []. Пустой/пробельный text допустим только с вложением. Список не содержит дублей, до 10 UUID, порядок сохраняется. Отсутствие списка и [] дают одинаковый fingerprint; пустой список не включается в fingerprint, поэтому сохраняется hash прежних text-only запросов lab3. Replay возвращает прежний Message 201, другой валидный body 409, доступ и сессия перепроверяются.
|
||
- **Пути и ACL.** Object key — `originals/<случайный UUID>`, не filename и не публичный URL. Имя — только отображаемое поле: 1–255 Unicode code points, не пустое, без slash/backslash/NUL/control. Сначала Bearer и членство, затем загрузка; metadata/content доступны только участникам, посторонний/неизвестный объект 404. Публичный JSON не раскрывает object key, bucket, endpoint или credentials.
|
||
- **Получение файла.** POST принимает сырой PNG/JPEG, не multipart. Content-Length проверяется заранее, но фактически полученные bytes тоже считаются. Тело читается через Request.stream в TemporaryFile на диске, SHA-256 считается по ходу. Лимит 10 MiB и абсолютное ожидание тела 30 с; слот загрузки ожидается до 1 с. Файл удаляется/закрывается в finally, постоянной локальной копии оригинала у API нет.
|
||
- **Проверка изображения.** Pillow определяет формат и размеры до load; MIME должен совпадать. >40 млн пикселей даёт 413 до полной распаковки. verify проверяет структуру, повторный open/load — декодирование. Повреждённый/неподдерживаемый файл 415, слишком большой 413, опасное имя 400. Текстовые PNG chunks ограничены 1 MiB. На API один decoder и не более 6 одновременно обрабатываемых upload: несколько больших распаковок не размножают расход RAM. Оригинальные байты не перекодируются; crop/thumbnail/очереди относятся к следующим работам.
|
||
- **Буферы Nginx.** На upload-route client_max_body_size 11 MiB, чтобы 10 MiB+1 дошёл до API и получил 413; client_body_buffer_size 64 KiB, остальное буферизуется на диск. `proxy_request_buffering on`, максимум 16 параллельных загрузок на LB, inactivity timeout тела 10 с, upload read/send timeout 30 с. Это сознательное дисковое буферизование, не обещание мгновенного приёма произвольно медленного клиента.
|
||
- **201 и согласованность.** После валидации API начинает PG-транзакцию и берёт advisory lock от object_key. Затем выполняются S3 PUT и INSERT metadata; 201 возвращается только после успешного COMMIT. У S3 и PostgreSQL нет общей атомарной транзакции. Подтверждённые metadata доступны всем API, оригинал находится в общем MinIO.
|
||
- **Компенсация неизвестного результата.** Ошибка PUT/SQL/COMMIT вызывает новую проверку под тем же lock. Объект удаляется только если БД точно подтверждает отсутствие metadata. При неизвестном COMMIT или недоступной БД слепого DeleteObject нет: уже учтённый файл должен остаться, неучтённый подберёт janitor. Обрыв неполного клиентского тела не начинает S3 PUT; аварийное завершение после PUT может оставить orphan.
|
||
- **Автоматическая очистка.** Отдельный cleanup-service каждые 60 с листает только originals/* страницами до 1000 объектов. Grace по умолчанию 300 с, минимум 60 с. Для старого кандидата pg_try_advisory_xact_lock и свежий SELECT повторно проверяют metadata; учтённый/свежий/активно заблокированный объект пропускается. При ошибке БД удаления не происходит. Dry-run не удаляет, повтор apply идемпотентен. Здесь реализована компенсация/orphan cleanup уровня 4, не полный исследовательский reconciler из трека 5 и не восстановление missing bytes.
|
||
- **Скачивание.** GET content возвращает StreamingBody S3 кусками 64 KiB через авторизованный API, без redirect. До 8 открытых S3-stream на API; close/release выполняется в finally ответа, включая ошибку отправки headers и disconnect. Content-Length сверяется с metadata. Variant в lab4 разрешён только original; прочие значения 400. Истинный MIME и RFC5987 filename передаются в headers.
|
||
- **MinIO и права.** minio-init идемпотентно создаёт bucket, запрещает anonymous, создаёт отдельного API user и policy. Get/Put/Delete разрешены только originals/* этого bucket; ListBucket — только для этого prefix; GetBucketLocation — для bucket. CreateBucket, чужие bucket/prefix и admin-права не выдаются. Console слушает 127.0.0.1:9001 внутри MinIO, не опубликована и недоступна из API-сети. Приватный bucket не заменяет ACL приложения.
|
||
- **Здоровье и таймауты.** Readiness требует PostgreSQL, совместимую схему и доступный S3 bucket с API credentials; Redis — необязательный кэш. Boto3 connect 1 с/read 3 с, одна попытка, пул/stream gate 8. PG-пул 8 на API, ожидание 2 с, statement 3 с/lock 2 с. S3 outage даёт 503 API либо 502/503/504 LB после исключения backend. Nginx OSS использует Docker DNS resolve и пассивные max_fails 1/fail_timeout 2 с; активный health_check Plus не используется. SIGTERM/rolling сохраняют схему lab3.
|
||
|
||
Роли, ресурсы и запуск:
|
||
|
||
| Service | Версия / ресурсы | Данные, сеть и готовность |
|
||
| --- | --- | --- |
|
||
| api×2 | `mtusi-lab4-api:lab4`; каждая 1 CPU/512 MiB, uid10001 | front+data, без host ports; HTTP ready, только ограниченные S3 secrets |
|
||
| lb | `nginx:1.28.0-alpine`; 0.5 CPU/128 MiB | только front; единственный public endpoint 127.0.0.1:8080 |
|
||
| postgres | `postgres:17.5-bookworm`; 1 CPU/512 MiB | internal data; postgres_data, pg_isready |
|
||
| redis | `redis:7.4.4-bookworm`; 0.25 CPU/128 MiB | internal data; redis_data, AOF, ping |
|
||
| minio | официальный release 2025-04-22, сборка из pinned source; 1 CPU/512 MiB, uid10002 | internal data; minio_data; HTTP /minio/health/ready; root secrets |
|
||
| minio-init | официальный mc release 2025-04-16, сборка; 0.25 CPU/128 MiB | root+API secrets, policy read-only, Exited(0) |
|
||
| migrate | образ API; 0.5 CPU/256 MiB | только DB secret, версии/lock/checksum, Exited(0) до API |
|
||
| cleanup | образ API; 0.25 CPU/192 MiB | DB+ограниченные S3 secrets, только data, цикл 60 с |
|
||
|
||
Python 3.13.5, библиотеки и транзитивные зависимости закреплены в requirements.lock. В .env реально используется SESSION_TTL_SECONDS; S3_ENDPOINT/REGION/BUCKET и *_FILE задаются Compose. Контрактные пределы 10 MiB/40 Mp не увеличиваются через переменные. Отдельные migrate и minio-init завершаются до API. Dockerfile приложения не запускает миграции каждой репликой.
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||
| --- | --- | --- | --- |
|
||
| Контракт и публичный API (3) | make check/validate-container/test | PASS: lab4 public API scenario, checksum, ACL и сообщения с ids | evidence/check.txt, openapi.txt, smoke.txt |
|
||
| Метаданные в PG, bytes в приватном S3 (3) | схема 003, security test, download | готовые originals в bucket, API не раскрывает key; anonymous 403 | migrations/003_attachments.sql, evidence/s3-security.json |
|
||
| PNG/JPEG и исходные bytes (3) | собственные тесты + smoke | 201 ready, SHA-256/размер/bytes совпадают, image-only сообщение валидно | evidence/student-tests.txt, smoke.txt |
|
||
| Byte/pixel/MIME/filename ограничения (3) | тесты повреждений, >10 MiB, chunked, >40 Mp header | 400/413/415; pixel limit до load, пользовательская ошибка не 500 | evidence/student-tests.txt |
|
||
| Upload на одной, download на другой (3) | verify_attachments.py failover | остановлен точно upload-instance; другой вернул тот же hash/bytes | evidence/attachment-failover.json |
|
||
| Полный restart с S3 volume (3) | verify_cluster.py persistence | прежняя сессия, metadata и оригинал доступны; реальные процессы перезапущены | evidence/persistence.txt, persistence.json |
|
||
| Прежняя балансировка/идемпотентность (3) | test-cluster, собственные регрессии | concurrent replay, failover/SIGTERM/rolling проходят | evidence/concurrent-idempotency.json, public-failover.txt, sequential-failover.json, graceful-shutdown.json, rolling-update.json |
|
||
| Все отрицательные случаи файлов/чужих ids (4) | make test-student | 21 тест PASS, включая MIME, corrupt/oversize, чужой attachment и другой чат | evidence/student-tests.txt |
|
||
| Компенсация после PUT/DB failure (4) | SQL trigger перед metadata INSERT, затем реальный SIGKILL | SQL-сбой 503 компенсирован; orphan после kill обнаружен и удалён после grace | evidence/student-tests.txt, orphan-cleanup.json |
|
||
| Безопасная очистка (4) | dry-run/apply/repeat; fresh/tracked/locked | dry-run: 0 удалений; apply удалил orphan; повтор 0; свежий/используемый/locked сохранены | evidence/orphan-cleanup.json |
|
||
| Потоковая обработка и RAM при ≥10 загрузках (4) | make uploads | 10/10 одновременно, 2 API, 0 ошибок/OOM; пик 205.824/214.730 MiB при 512 MiB | evidence/concurrent-uploads.json |
|
||
| Bucket bootstrap идемпотентен, IAM ограничен (4) | повтор minio-init; прямые S3-запросы | objects/metadata не изменились; anonymous 403, CreateBucket 403, другой prefix: 403 | evidence/s3-security.json |
|
||
| Консоль не открыта (4) | socket из API к minio:9001; infrastructure snapshot | соединение не установлено, root secret в API не смонтирован, host ports только у LB | evidence/s3-security.json, infrastructure.json |
|
||
| Миграции/инициализация с нуля | make test-fresh | schema 001–003 и private bucket на новых volumes, тесты PASS | evidence/fresh-migrations.txt |
|
||
|
||
Pytest также выводит предупреждение старой закреплённой botocore об utcnow в Python 3.13 и диагностическое предупреждение Pillow в тесте pixel-bomb; проверки результата 413 и все assertions проходят. Публичные проверки и контракт не ослаблялись.
|
||
|
||
## Эксперименты и отказы
|
||
|
||
Исследовательский трек 5 не выполнялся. Файлы синтетические. Обрыв тела и сбой между PUT/COMMIT проверяются раздельно: одного успешного API-запроса недостаточно для доказательства компенсации.
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Восстановление / потери |
|
||
| --- | --- | --- | --- |
|
||
| Upload → stop обслужившей API → download | файл читается через другую API | тот же SHA-256 и bytes, другой alias | 1.988 с от старта действия / потерь нет |
|
||
| Обрыв HTTP upload | неполное тело не создаёт объект/metadata | из 500000 объявленных передано 108 bytes, TCP закрыт; counts не изменились | orphan нет |
|
||
| Ошибка INSERT metadata после S3 PUT | rollback PG и компенсация S3 | HTTP 503, нет строки и нового объекта | подтверждения не было |
|
||
| SIGKILL после PUT, до COMMIT | неподтверждённый объект может остаться и будет очищен | наблюдался exit 137; объект есть, metadata нет; после 61 с реального ожидания dry-run показал кандидата, apply удалил его | orphan устранён, 201 не выдан |
|
||
| Repeat cleanup, fresh/linked/locked | безопасные повторы | повтор не удаляет объекты; свежий и используемый сохранены, объект под lock сохранён до unlock | потерь используемых данных нет |
|
||
| MinIO недоступен | ограниченная ошибка без ложного 201 | upload 503 за 0.2487 с; после старта прежний оригинал читается | тот же токен, bytes сохранены |
|
||
| Полный restart API/PG/Redis/MinIO/cleanup/Nginx | сессия и оригинал переживают restart | public persistence PASS | именованные volumes сохранены |
|
||
|
||
**Методика crash/cleanup:** временный BEFORE INSERT trigger задерживает ровно одно имя файла через pg_sleep(2). После наблюдения INSERT в pg_stat_activity и появления объекта в S3 API получает SIGKILL. Metadata не зафиксирована, 201 не отправлен. Контейнер восстановлен, trigger удалён. После настоящего 61-секундного ожидания применяется grace 60 с. Дополнительно проверены старый объект под advisory lock, свежий объект и старое вложение, связанное с сообщением. После снятия lock его тестовый orphan также удалён. В обычном запуске grace 300 с, цикл 60 с; при недоступной БД уборка откладывается.
|
||
|
||
**Память при десяти загрузках:** воспроизводимый RGB PNG 3000×1000, 9002318 bytes, zlib level 0, строки из SHAKE-256. Один неизменяемый payload используется десятью клиентскими потоками с barrier. Все десять HTTP-интервалов перекрывались 0.345 с, завершились 201, обе API наблюдались, ошибок 0. Время группы 1.563 с. Один оригинал скачан другим участником и побайтно сверен.
|
||
|
||
Перед опытом API пересозданы, чтобы memory.peak и VmHWM относились к этому запуску. Peak включает startup/bootstrap/загрузки/контрольное скачивание. Kernel high-water mark не пропускает короткие пики между samples:
|
||
|
||
| API-процесс | Cgroup memory peak | PID 1 VmHWM | Лимит | OOM |
|
||
| --- | --- | --- | --- | --- |
|
||
| Первый | 205.824 MiB | 182.871 MiB | 512 MiB | 0 |
|
||
| Второй | 214.730 MiB | 183.293 MiB | 512 MiB | 0 |
|
||
|
||
Cgroup включает cache и вспомогательные процессы, VmHWM — resident peak API. Профиль, версии, limits, baseline/final, интервалы запросов и checksum — в evidence/concurrent-uploads.json. Опыт показывает расход памяти этого профиля, а не максимальный throughput или универсальный RSS для всех допустимых JPEG/PNG. Сценарии lab3 под текстовой нагрузкой сохранены отдельно; их числа не заменяют эксперимент с файлами.
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
- Один Docker-host, одна PostgreSQL и один MinIO: отказ узла/диска и HA хранилищ не покрываются. Named volume не заменяет backup. Потерянные bytes из missing object janitor восстановить не может.
|
||
- S3 и PostgreSQL неатомарны. Между PUT и COMMIT есть окно orphan; компенсация и grace-cleanup закрывают его после восстановления зависимостей. При недоступной БД удаление запрещено; время уборки не является SLA.
|
||
- Janitor удаляет только неучтённые старые объекты. Учтённое, но никуда не прикреплённое вложение сохраняется: в обязательном API нет delete/retention для таких файлов.
|
||
- Readiness считает S3 критичной зависимостью. При S3 outage Nginx может исключить обе API, и text-only запросы тоже станут недоступны, хотя PG жив. Внутренний live процесса остаётся 200.
|
||
- Таймауты SDK/Nginx относятся к отдельным операциям I/O. После начала HTTP download нельзя заменить частичное 200 структурированным 503; клиент проверяет размер/checksum.
|
||
- Нагрузочный замер: десять одновременных загрузок по 9 MB, две API, один прогон. Исследования максимального RPS, presigned upload, thumbnail/crop и фоновой обработки lab5 не проводились.
|
||
- MinIO собран из закреплённого исторического релиза; стенд локальный и учебный. HTTP/Basic только на localhost с синтетическими данными; TLS, rotation, secret manager и полное разделение DB privileges оставлены следующим работам.
|
||
- Между страницами нет общего snapshot. Сохраняются оговорённые в lab3 ограничения часов и конкурентных вставок. Breaking DB migrations потребуют отдельной стратегии.
|