Files
mtusi2026lab4/REPORT.md
T

82 lines
9.0 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
- Автор, группа: Борзов Никита, БВТ2304
- Целевая оценка: 5, трек 2 «Согласованность двух хранилищ»
- Commit/PR: `11c227c`, [MR !26](https://gitea.privcloud.tech/mtusi2026/mtusi2026lab4/pulls/26)
- Основа: проект лабораторной 3 с сохранением PostgreSQL, Redis, четырёх API-реплик, Nginx и общей идемпотентности
## Запуск из чистого clone
Требуются Docker Desktop с Compose v2 и Python 3.9+. Старые Docker Hub-образы MinIO больше не используются: стенд закрепляет digest-образы `cgr.dev/chainguard/minio` и `cgr.dev/chainguard/minio-client`.
```sh
cp .env.example .env
docker compose config --quiet
docker compose build api-1 minio-init
docker compose up -d --no-build --wait
make check
make test BASE_URL=http://localhost:8080
```
`minio` и одноразовый `minio-init` один раз создают приватный bucket и отдельного API-пользователя с правами только на нужный bucket. Консоль и порт S3 наружу не опубликованы. `docker compose down` останавливает стенд с сохранением volumes, а `docker compose down -v` намеренно удаляет учебные данные PostgreSQL, Redis и S3.
Проверка публикации портов: `docker compose port minio 9000` и `docker compose port minio 9001` не возвращают адресов. Поэтому прямой unauthenticated GET к MinIO с хоста невозможен, а доступ к файлам идёт только через авторизованный API.
## Архитектура и решения
```text
Клиент -> Nginx -> API × 4 -> PostgreSQL (метаданные) + Redis (сессии/кэш)
|
+-> приватный S3 bucket (байты)
```
PostgreSQL хранит пользователей, чаты, сообщения и метаданные вложений. S3 хранит только оригинальные байты. В таблице `attachments` находятся chat_id, владелец, отображаемое имя, MIME, размер, SHA-256, статус и назначенный сервером object key. Файл заранее привязан к чату.
`POST /api/v1/chats/{chat_id}/attachments` принимает сырые PNG/JPEG до 10 MiB. Запрос читается потоково небольшими кусками с жёстким ограничением размера. Pillow проверяет реальный формат файла и число пикселей до записи в S3. Имя не используется как путь или object key. Сначала выполняется S3 PUT, затем транзакционная запись метаданных; если запись PostgreSQL не удалась, выполняется компенсационный S3 DELETE.
Метаданные и байты выдаются только через авторизованный API. Участник чата получает метаданные и побайтный download, посторонний получает 404. Message принимает `attachment_ids`; все ID должны принадлежать тому же чату и иметь статус `ready`. Текст может быть пустым, если прикреплено хотя бы одно вложение.
Сохранены все возможности ЛР3: Bearer-сессии в Redis, PostgreSQL, keyset-пагинация, X-Instance-Id, Nginx, health/readiness, таймауты, Idempotency-Key, отказ одной API-реплики и restart с volumes.
## Доказательства критериев
| Критерий | Команда | Результат | Доказательство |
| --- | --- | --- | --- |
| Контракт и структура | `make check` | PASS | вывод проверки |
| Публичный API и вложения | `make test BASE_URL=http://localhost:8080` | `PASS: lab4 public API scenario` | `tests/smoke.py` |
| Реальные S3-байты | smoke | SHA-256 и размер download совпали с fixture | `tests/fixtures/sample.png` |
| Проверка негативных случаев | `python3 student-tests/attachments.py` | повреждённый файл и MIME mismatch — 415, большой файл — 413, чужой доступ — 404 | `student-tests/attachments.py` |
| Сохранность | `make test-persistence BASE_URL=http://localhost:8080 ACTION_SCRIPT=scripts/restart.sh` | подтверждены данные, токен и вложение после restart | `scripts/restart.sh` |
| Отказ API-реплики | `make test-failover BASE_URL=http://localhost:8080 ACTION_SCRIPT=scripts/stop-one.sh` | записи и download продолжаются через другие реплики | `scripts/stop-one.sh` |
| Общая идемпотентность | `python3 student-tests/idempotency.py` | конкурентные запросы создали один Message ID | проверка ЛР3 |
| Reconciler | `docker compose run --rm --no-deps api-1 python scripts/track_s3.py` | старый orphan удалён, свежий сохранён, missing metadata помечена failed | `evidence/track_s3.json` |
| Память загрузок | `python3 student-tests/upload_load.py` при сборе `docker stats` | 10 одновременных upload завершились успешно; peak API — 125.1 MiB из 256 MiB | `student-tests/upload_load.py`, `evidence/upload_memory.txt` |
## Исследовательский трек: согласованность двух хранилищ
Гипотеза: рассогласование PostgreSQL и S3 можно обнаруживать безопасным повторяемым обходом, не удаляя свежие объекты и не скрывая missing metadata.
Скрипт `scripts/reconcile_s3.py` сравнивает список объектов bucket с таблицей `attachments`. По умолчанию он работает в dry-run. Orphan удаляется только после grace period, заданного `--grace-seconds`; metadata без объекта переводится в `failed` с кодом `object_missing`. Используемые и свежие вложения не удаляются.
`scripts/track_s3.py` создаёт старый orphan, свежий orphan и строку metadata без объекта. Затем выполняет dry-run и apply с grace period 5 секунд. В результате:
```json
{
"old_orphan_removed": true,
"fresh_orphan_preserved": true,
"missing_marked_failed": true
}
```
После завершения эксперимента тестовые объекты и строка metadata удаляются. Отдельно 10 конкурентных загрузок fixture завершились успешно; при лимите API 256 MiB наблюдался максимум 125.1 MiB по `docker stats`. Ограничение измерения — один локальный MinIO с одним диском; это проверка согласованности и безопасного исправления, а не отказоустойчивость самого S3-кластера.
## Отказы и ограничения
Стенд выдерживает остановку одной API-реплики, перезапуск API/PostgreSQL/Redis/MinIO с сохранёнными volumes и переключение download через другую реплику. PostgreSQL, Redis, Nginx и один MinIO остаются единичными точками отказа. Потеря Docker-host и удаление volumes не входят в модель.
S3 credentials API отделены от root credentials MinIO и получают только `GetObject`, `PutObject`, `DeleteObject` и `ListBucket` для учебного bucket. Прямой S3-порт и административная консоль в Compose не опубликованы.
Локальные значения паролей в Compose нужны только для учебного запуска. В реальном окружении их задают через `.env` или секреты; файл `.env` в репозиторий не добавляется.
Исходный контракт и публичные tests не изменялись. ИИ использовался как помощник при разборе требований и подготовке кода; команды и результаты проверены на локальном Compose-стенде.