forked from mtusi2026/mtusi2026lab4
141 lines
23 KiB
Markdown
141 lines
23 KiB
Markdown
# Отчёт — лабораторная 4
|
||
|
||
- Автор, группа: Алёна Курлова, БВТ2301
|
||
- Целевая оценка; выбранный трек 5: **5, трек 2 «Согласованность двух хранилищ»**
|
||
- Commit/PR: PR [#49](https://gitea.privcloud.tech/mtusi2026/mtusi2026lab4/pulls/49), основной коммит `ba6e32a`, ветка `solution/bvt2301-kurlova`
|
||
- Источники, библиотеки, помощь ИИ: FastAPI, psycopg, boto3, Pillow, MinIO; код лабы 3 перенесён и расширен. Реализацию, тесты и черновик отчёта выполнял Claude Code (ИИ) под руководством автора; результаты прогонов ниже получены на локальном стенде.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Prerequisites: Docker Desktop (Compose v2), Python 3.9+, вход `docker login` (Docker Hub). Проверено на macOS, arm64.
|
||
|
||
```sh
|
||
cp .env.example .env # значения в примере совпадают с теми, на которых получены evidence/
|
||
mkdir -p secrets
|
||
printf 'messenger' > secrets/postgres_password
|
||
printf 'postgresql://messenger:messenger@postgres:5432/messenger' > secrets/database_url
|
||
printf 'valkey://valkey:6379/0' > secrets/cache_url
|
||
printf 'messenger_root' > secrets/minio_root_user
|
||
python3 -c "import secrets;print(secrets.token_urlsafe(24),end='')" > secrets/minio_root_password
|
||
printf 'messenger_app' > secrets/s3_access_key_id
|
||
python3 -c "import secrets;print(secrets.token_urlsafe(24),end='')" > secrets/s3_secret_access_key
|
||
docker compose --env-file .env up -d --build # postgres, valkey, minio, minio-init, migrate, api-1, api-2, nginx
|
||
make test # ждёт готовности по /health/ready
|
||
```
|
||
|
||
Остановка с сохранением данных: `docker compose stop`. Намеренное удаление учебных данных: `docker compose down -v`. Каталог `secrets/` и `.env` в git не попадают.
|
||
|
||
## Архитектура и решения
|
||
|
||
| Роль | Сервис | Версия | Health | Volume | Сеть / порт | Credentials |
|
||
| --- | --- | --- | --- | --- | --- | --- |
|
||
| LB | nginx | 1.27.3-alpine | `/health/live`; health-скрипт опрашивает `/health/ready` реплик | — | `127.0.0.1:8080` | — |
|
||
| API ×2 | api-1, api-2 | собираются из исходников, python 3.12.8 | `/health/ready` | нет (stateless) | только внутренняя сеть | Docker secrets |
|
||
| БД | postgres | 17.7-alpine@sha256 | `pg_isready` | `pgdata` | внутренняя | secret |
|
||
| Кэш сессий | valkey | 8.1-alpine@sha256 | `valkey-cli ping` | нет | внутренняя | — |
|
||
| S3 | minio | `madlabcg/minio@sha256:ad134b2d…` | `mc ready local` | `miniodata` | внутренняя, **порты и консоль не опубликованы** (`MINIO_BROWSER=off`) | root-secret только у minio и minio-init |
|
||
| Bootstrap S3 | minio-init | тот же образ | — | — | — | root + app secrets |
|
||
|
||
**Источник истины.** Метаданные — PostgreSQL (`attachments`, `message_attachments`), байты — приватный bucket. Object key назначает сервер (`attachments/<uuid4>`), `filename` хранится только как отображаемое имя.
|
||
|
||
**Порядок записи и границы согласованности** (ответ на «что если PUT прошёл, а COMMIT нет»):
|
||
1. тело читается потоком в `SpooledTemporaryFile` (1 MiB в RAM, остальное во временный файл), считается SHA-256, лимит 10 MiB применяется на лету; MIME проверяется по magic bytes и Pillow, лимит пикселей проверяется по заголовку до декодирования; целостность проверяет [app/imagecheck.py](app/imagecheck.py): для PNG собственный потоковый сканер (CRC всех chunk'ов, поля IHDR, zlib-поток разжимается порциями по 1 MiB, filter-байт каждой строки ∈ 0..4, размер данных точно равен вычисленному по IHDR, Adam7 учитывается), для JPEG полное декодирование через libjpeg в масштабе 1/8 (память ~1/64 изображения) плюс проверка маркера EOI;
|
||
2. в БД вставляется строка `status='uploading'` (коммит);
|
||
3. PUT в S3;
|
||
4. `UPDATE … SET status='ready' WHERE status='uploading'` — только после этого клиент получает **201**.
|
||
|
||
Любой сбой между шагами оставляет либо `uploading`-строку (с объектом или без), либо ничего. Клиентам такие строки не видны (404), прикрепить их к сообщению нельзя. Объект без строки получиться не может, потому что строка вставляется раньше. При ошибке API сам пытается компенсировать (удалить объект и строку); то, что не удалось, собирает reconciler.
|
||
|
||
**Reconciler** ([app/reconcile.py](app/reconcile.py), CLI [scripts/reconcile.py](scripts/reconcile.py), фоновый цикл в каждом API раз в `RECONCILE_INTERVAL_SECONDS`=300 с, grace `RECONCILE_GRACE_SECONDS`=900 с). Работает под `pg_try_advisory_lock`, поэтому две реплики не дублируют работу. Правила:
|
||
- `uploading` старше grace **и** объект (если есть) старше grace по `LastModified` → удалить объект и строку; старая строка со свежим объектом не трогается (повторная проверка HEAD перед удалением);
|
||
- объект без строки и старше grace → удалить (перед удалением строка перепроверяется);
|
||
- `ready`-строка, подтверждённая (`updated_at`) раньше grace, без объекта (перепроверка HEAD) → `status='failed'`, `error_code='object_missing'`; строка **не удаляется**, даже если на неё ссылается сообщение;
|
||
- по умолчанию dry-run (`--apply` меняет данные), повторный запуск идемпотентен.
|
||
|
||
**Что изменено в lab3-коде.** Сообщение принимает `attachment_ids` (0–10) и допускает пустой `text` при наличии вложений (миграция 0004 ослабляет CHECK). Хеш идемпотентности включает `attachment_ids`; повтор без ключа `attachment_ids` равен `[]`. **Критичные зависимости `/health/ready`: PostgreSQL и S3.** Недоступность любой из них даёт 503 в общем формате ошибки с `X-Instance-Id`; состояние S3 обновляется фоновой пробой раз в секунду (отдельный клиент с таймаутами 1 с / 1.5 с, чтобы зависший S3 не вешал проверку). При этом недоступный S3 **не** блокирует остальной API: текстовые сообщения и метаданные продолжают работать (запросы блокируются только при недоступной БД), а вложения отвечают 503. Чтобы 503 не выбивал реплики из upstream и клиенты не видели 502, nginx не использует `http_503` как признак сбоя для `/health/`, `/attachments/` и upload; если обе реплики не готовы, health-скрипт оставляет обе в ротации. nginx также отдаёт JSON-ошибку 413 (с `X-Request-Id`) для тел больше `client_max_body_size` 11m. S3-клиент: без повторов, connect 3 с, read 6 с; компенсация при сбое PUT выполняется в фоне.
|
||
|
||
**Дополнительная валидация входных данных.** filename: 1..255 code points, не только пробелы, не `.`/`..`, без `/`, `\` и любых символов категорий Cc/Cs/Zl/Zp (в том числе DEL и C1). `Idempotency-Key` не обрезается (HTTP-парсер уже убирает крайние пробелы); порядок `attachment_ids` сохраняется в ответе, повторе и истории, переставленный список с тем же ключом — 409.
|
||
|
||
**Права S3.** API использует отдельного пользователя `messenger_app` с политикой [infra/minio/app-policy.json](infra/minio/app-policy.json): Get/Put/DeleteObject только на `attachments/*` и ListBucket. Bucket создаёт и делает приватным [infra/minio/init.sh](infra/minio/init.sh); скрипт идемпотентен (`mb --ignore-existing`, повтор политики и пользователя безвреден), запускается при каждом `up`.
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл |
|
||
| --- | --- | --- | --- |
|
||
| Публичный smoke | `make test` | PASS (загрузка, привязка, скачивание вторым участником, 404 постороннему) | [evidence/smoke.txt](evidence/smoke.txt) |
|
||
| Байты в S3, метаданные в БД, 201 после сохранения | код `upload_attachment`; `student-tests/test_attachments.py` | sha256/размер совпадают, `Content-Length` скачивания равен оригиналу | [evidence/attachments_tests.txt](evidence/attachments_tests.txt) |
|
||
| Upload → остановка реплики → download через другую; restart с volumes | `student-tests/test_attachment_resilience.py` | загрузил api-1, скачал api-2, sha256 совпал; после рестарта postgres/valkey/minio/api/nginx метаданные и оригинал целы | [evidence/attachment_resilience.txt](evidence/attachment_resilience.txt) |
|
||
| Общие persistence / failover | `make test-persistence`, `make test-failover` (хуки `scripts/restart.sh`, `scripts/stop-one.sh`) | PASS; failover: 131 успешная запись, 0 ошибок, восстановление 0.45 с | [evidence/persistence.txt](evidence/persistence.txt), [evidence/failover.txt](evidence/failover.txt) |
|
||
| Лимиты 10 MiB / 40 Mpx, MIME по содержимому, опасные filename | `test_attachments.py` | 10 MiB+ → 413; PNG 8000×6000 → 413 до декодирования; подмена MIME и мусор → 415; `../`, `/`, `\`, NUL, `\n`, пустое, 256 символов → 400 | [evidence/attachments_tests.txt](evidence/attachments_tests.txt) |
|
||
| Устойчивость к некорректным входным данным | `student-tests/test_input_hardening.py`, `scripts/jpeg_check_experiment.py` (запуск: `docker compose cp scripts/jpeg_check_experiment.py api-1:/tmp/ && docker compose exec -T api-1 python /tmp/jpeg_check_experiment.py`) | усечённый PNG, filter-байт 5/0xFF, битый IDAT, 27-байтный JPEG → 415 (в том числе для изображений 6 и 36 Mpx); filename из пробелов, DEL, C1, `.` → 400; порядок вложений; `[]` ≡ отсутствует; 12 MiB → JSON 413 | [evidence/input_hardening.txt](evidence/input_hardening.txt), [evidence/jpeg_check.txt](evidence/jpeg_check.txt) |
|
||
| Чужое / неизвестное / чужого чата attachment_id, ошибки не 500 | `test_attachments.py` | 404 / 404 / 404; дубликаты, не-UUID, >10 → 400 | там же |
|
||
| Недоступность и зависание S3 | `student-tests/test_s3_outage.py` | остановка: upload/download/ready → 503 JSON с `X-Instance-Id`, метаданные и текст работают, без 502; `docker pause`: upload отвечает 503 за 7 с; восстановление за секунды | [evidence/s3_outage.txt](evidence/s3_outage.txt) |
|
||
| Прерывание загрузки | обрыв сокета на половине тела в `test_attachments.py` | сервер здоров, следующий upload проходит | там же |
|
||
| Компенсация / сверка, безопасный grace | трек 2, ниже | 18/18 проверок | [evidence/reconciler_experiment.txt](evidence/reconciler_experiment.txt) |
|
||
| Пик памяти при ≥10 одновременных загрузках | `student-tests/memory_experiment.py` | см. ниже | [evidence/memory_experiment.txt](evidence/memory_experiment.txt) |
|
||
| Private bucket вне API, консоль не открыта | `student-tests/check_private_bucket.sh` | анонимные GET/LIST из сети compose → 403, порты 9000/9001 на хосте не опубликованы, `mc anonymous get` → private | [evidence/private_bucket.txt](evidence/private_bucket.txt) |
|
||
| Отдельные S3 credentials с ограниченными правами | `infra/minio/app-policy.json`, `init.sh` | API работает под `messenger_app`; root-secret API не получает | `compose.yaml` |
|
||
|
||
Проверка hook'ов подтверждает перезапуск реальных процессов: `restart.sh` перезапускает postgres, valkey, minio, api-1, api-2, nginx без `down -v`; `stop-one.sh` останавливает только указанную реплику.
|
||
|
||
## Эксперименты и отказы
|
||
|
||
### 1. Память при 10 одновременных загрузках
|
||
|
||
Гипотеза: основная память уходит на параллельное декодирование Pillow и S3 PUT, а не на хранение тел запросов; ограничение числа одновременных тяжёлых стадий снизит пик.
|
||
|
||
Методика: [student-tests/memory_experiment.py](student-tests/memory_experiment.py), PNG 8.27 MiB (1700×1700, несжимаемый шум), 10 параллельных загрузок через LB, 3 раунда, замер `docker stats` каждого API (лимит контейнера 256 MiB, 0.5 CPU). Mac arm64, Docker Desktop.
|
||
|
||
| Вариант | Простой, MiB | Пик api-1 / api-2, MiB | Динамика по раундам | 201 / всего |
|
||
| --- | --- | --- | --- | --- |
|
||
| До: без ограничения тяжёлых стадий | 88 | 182 / 155 | рост 144 → 166 → 182 | 30 / 30 |
|
||
| После: `UPLOAD_CONCURRENCY=2` на реплику | 87 | 110 / 116 | 110 → 109 → 110, роста нет | 30 / 30 |
|
||
| После + потоковый PNG-сканер и JPEG-проверка (итоговая версия) | 98–100 | 115 / 114 | 115 → 115 → 115, роста нет | 30 / 30 |
|
||
|
||
Сырые данные: [evidence/memory_experiment_before_semaphore.txt](evidence/memory_experiment_before_semaphore.txt), [evidence/memory_experiment.txt](evidence/memory_experiment.txt). Ограничения: `docker stats` даёт моментальные срезы (раз в ~1–2 с), настоящий пик мог быть выше; одна конфигурация железа; один размер файла; медиана длительности загрузки выросла с 0.82 до 1.15 с (цена ограничения), в итоговой версии 0.76 с. Причину роста «до» (фрагментация аллокатора или реальная утечка) я не выяснял.
|
||
|
||
### 2. Трек 2 — reconciler с внедрением ошибок
|
||
|
||
Гипотеза: сверка по правилам выше находит и исправляет расхождения, не трогая свежие и используемые вложения.
|
||
|
||
Методика: [scripts/reconcile_experiment.py](scripts/reconcile_experiment.py) внутри api-контейнера снимает базовую линию (в БД могут быть остатки прошлых тестов), создаёт строки/объекты, имитирующие сбои на обеих сторонах, и запускает dry-run, apply, apply после истечения grace, повторный apply. Счётчики сравниваются с базовой линией. `LastModified` объекта в MinIO задним числом не изменить, поэтому «старый объект» моделируется ожиданием grace.
|
||
|
||
| Внедрённая ошибка | Ожидание | Наблюдение |
|
||
| --- | --- | --- |
|
||
| `uploading` старше grace, объект есть, но моложе grace (падение после PUT) | не трогать до истечения grace | сохранены; собраны после grace |
|
||
| `uploading` старше grace, но под его ключом свежий объект | не трогать | не тронуты; собраны после grace |
|
||
| `ready`, подтверждённая только что, объект ещё не виден | не помечать missing | не помечена |
|
||
| `uploading` старше grace, объекта нет (падение до PUT) | строка удалена | удалена |
|
||
| `uploading` свежее grace (загрузка идёт) | не трогать | не тронута; после истечения grace собрана |
|
||
| объект без строки внутри grace | не трогать | не тронут; удалён после grace |
|
||
| `ready`, объект потерян | пометить `failed/object_missing` | помечено |
|
||
| `ready`, привязано к сообщению, объект на месте | не трогать | не тронуто |
|
||
| `ready`, привязано к сообщению, объект потерян | строку не удалять, пометить | сохранена, `failed` |
|
||
| dry-run | ничего не менять, но показать счётчики | счётчики верны, состояние не изменилось |
|
||
| повторный apply | нулевые изменения | 0 / 0 / 0 |
|
||
|
||
Итог: 18/18 проверок ([evidence/reconciler_experiment.txt](evidence/reconciler_experiment.txt)). **Стоимость обхода:** 1000 `ready`-вложений (около 1100 объектов вместе с остатками прошлых тестов) — 1.25 с в dry-run (в основном 1000 HEAD-запросов к S3; листинг идёт страницами по 500 с одним запросом к БД на страницу). Оценка масштабирования линейна, на больших объёмах не измерялась.
|
||
|
||
### 3. Отказы
|
||
|
||
| Воздействие | Ожидаем | Наблюдали | Восстановление / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| Остановка обслужившей API-реплики | download через другую реплику, тот же файл | api-1 → api-2, sha256 совпал | без потерь |
|
||
| Остановка MinIO | 503 на вложениях и ready, текст работает | upload/download/ready → 503 JSON, сообщения читаются, 502 нет | возврат за секунды после старта, без потерь |
|
||
| Зависание MinIO (`docker pause`) | быстрый 503 без вечного ожидания | upload → 503 за 7 с, download → 503 | восстановление после `unpause` |
|
||
| Остановка PostgreSQL | 503 JSON с `X-Instance-Id` на ready и бизнес-эндпоинтах | так и есть | возврат после старта |
|
||
| Рестарт postgres, valkey, minio, API, nginx с volumes | метаданные и байты на месте | сохранены | без потерь |
|
||
| Обрыв клиента на середине upload | нет 500 и мусора | сервер здоров; строка в БД ещё не создана | — |
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
- **Образ MinIO.** Официальные образы `minio/minio` на Docker Hub и `quay.io/minio/minio` в моей среде недоступны (pull denied / 401), поэтому использован сторонний `madlabcg/minio`, закреплённый по digest. Его происхождение и содержимое я не проверял; для защиты нужно заменить образ на проверенный (собрать из исходников MinIO или взять образ, указанный преподавателем).
|
||
- **Валидация изображений.** PNG проверяется собственным потоковым сканером (структура, CRC, filter-байты, точный размер данных), JPEG — полным декодированием libjpeg в масштабе 1/8 и проверкой EOI. Не обнаруживается JPEG, у которого поток обрезан посередине, а после обрезки дописан маркер EOI: libjpeg трактует это как нормальный конец данных (и Pillow тоже принимает такой файл). Также сканер не проверяет содержимое palette/ancillary chunk'ов, кроме CRC и PLTE-правил.
|
||
- Проверка размера по `Content-Length` невозможна для chunked-запросов: тогда лимит применяется по факту чтения потока.
|
||
- Проверка PNG ограничена по времени (`SCAN_SECONDS`=10 с); на очень медленной машине валидный файл с огромной степенью сжатия может получить 415.
|
||
- Вложения, загруженные, но так и не прикреплённые к сообщению, не считаются мусором и не удаляются; политики TTL для них нет.
|
||
- Reconciler при проверке `ready`-строк делает HEAD на каждую; для очень больших объёмов нужен инкрементальный режим по курсору или S3 Inventory.
|
||
- Нагрузочное тестирование с заданным arrival rate, p95/p99 не выполнялось; измерялась только память.
|
||
- Не реализованы: трек 1 (presigned upload), варианты изображений (lab5), TLS (локальный стенд с синтетическими данными).
|
||
- Секреты в `secrets/` сгенерированы локально и не коммитятся; учётные данные Postgres в примере выше — учебные.
|