Files

146 lines
27 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
- Целевая оценка; выбранный трек 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 потребуют отдельной стратегии.