# Отчёт — лабораторная 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/`), `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 в примере выше — учебные.