23 KiB
Отчёт — лабораторная 4
- Автор, группа: Алёна Курлова, БВТ2301
- Целевая оценка; выбранный трек 5: 5, трек 2 «Согласованность двух хранилищ»
- Commit/PR: PR #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.
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 нет»):
- тело читается потоком в
SpooledTemporaryFile(1 MiB в RAM, остальное во временный файл), считается SHA-256, лимит 10 MiB применяется на лету; MIME проверяется по magic bytes и Pillow, лимит пикселей проверяется по заголовку до декодирования; целостность проверяет app/imagecheck.py: для PNG собственный потоковый сканер (CRC всех chunk'ов, поля IHDR, zlib-поток разжимается порциями по 1 MiB, filter-байт каждой строки ∈ 0..4, размер данных точно равен вычисленному по IHDR, Adam7 учитывается), для JPEG полное декодирование через libjpeg в масштабе 1/8 (память ~1/64 изображения) плюс проверка маркера EOI; - в БД вставляется строка
status='uploading'(коммит); - PUT в S3;
UPDATE … SET status='ready' WHERE status='uploading'— только после этого клиент получает 201.
Любой сбой между шагами оставляет либо uploading-строку (с объектом или без), либо ничего. Клиентам такие строки не видны (404), прикрепить их к сообщению нельзя. Объект без строки получиться не может, потому что строка вставляется раньше. При ошибке API сам пытается компенсировать (удалить объект и строку); то, что не удалось, собирает reconciler.
Reconciler (app/reconcile.py, CLI 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: Get/Put/DeleteObject только на attachments/* и ListBucket. Bucket создаёт и делает приватным infra/minio/init.sh; скрипт идемпотентен (mb --ignore-existing, повтор политики и пользователя безвреден), запускается при каждом up.
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл |
|---|---|---|---|
| Публичный smoke | make test |
PASS (загрузка, привязка, скачивание вторым участником, 404 постороннему) | evidence/smoke.txt |
| Байты в S3, метаданные в БД, 201 после сохранения | код upload_attachment; student-tests/test_attachments.py |
sha256/размер совпадают, Content-Length скачивания равен оригиналу |
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 |
| Общие 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/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 |
| Устойчивость к некорректным входным данным | 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/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 |
| Прерывание загрузки | обрыв сокета на половине тела в test_attachments.py |
сервер здоров, следующий upload проходит | там же |
| Компенсация / сверка, безопасный grace | трек 2, ниже | 18/18 проверок | evidence/reconciler_experiment.txt |
| Пик памяти при ≥10 одновременных загрузках | student-tests/memory_experiment.py |
см. ниже | 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 |
| Отдельные 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, 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.txt. Ограничения: docker stats даёт моментальные срезы (раз в ~1–2 с), настоящий пик мог быть выше; одна конфигурация железа; один размер файла; медиана длительности загрузки выросла с 0.82 до 1.15 с (цена ограничения), в итоговой версии 0.76 с. Причину роста «до» (фрагментация аллокатора или реальная утечка) я не выяснял.
2. Трек 2 — reconciler с внедрением ошибок
Гипотеза: сверка по правилам выше находит и исправляет расхождения, не трогая свежие и используемые вложения.
Методика: 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). Стоимость обхода: 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 в примере выше — учебные.