Files
mtusi2026lab4/REPORT.md
T
2026-10-16 22:47:54 +03:00

35 KiB
Raw Blame History

Лабораторная 4 — S3 и вложения

  • Автор: Максим Шептунов, БВТ2301.
  • Целевая оценка: 5; трек 2, «Согласованность двух хранилищ».
  • Skeleton: ec540a1a725862a8619fcb758daec4ad197f0dd5.
  • Проверки и эксперимент: 16.10.2026, локальный Docker-стенд в WSL2.
  • Помощь ИИ: помощь с реализацией, проверками и разбором результатов.

Ниже описано решение и результаты моего запуска. Числа рассчитаны по evidence/local_* и исходным JSON; результаты эксперимента сохранены в evidence. README, публичные tests и контракт skeleton сохранены.

Запуск из чистого clone

Нужны Docker Engine с Compose v2/BuildKit, Python 3.10+ на хосте и Linux/amd64 для закреплённых S3-бинарников. В Windows — WSL Ubuntu с Docker Desktop. Порт 8080 должен быть свободен. Сборка требует доступа к PyPI, Docker Hub для базовых образов и GitHub Releases для MinIO/mc.

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt -r requirements-experiment.txt
chmod +x scripts/*.sh
make setup
make start
make ready
make check
make validate
make test
make student-checks
make test-files
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
bash scripts/restore-api.sh
make test-file-failover
make test-availability
make test-dependencies
make test-expiry
make experiment
make test

API-зависимости устанавливаются внутри Docker из requirements.txt. setup.sh генерирует .env и секреты в .secrets, не выводя значения. Папка секретов 700; файлы, читаемые пользователем API через mount, 644 внутри закрытой папки; root-credentials MinIO и пароль PG — 600. Secrets/.env исключены из Git и build context. Настройки повторно не генерируют новые credentials.

Сервис migrate применяет SQL и завершается, s3-bootstrap создаёт приватный bucket и ограниченного пользователя API и тоже завершается. Exited(0) для них нормален. Затем работают две API, LB, PG, Redis, MinIO и reconciler.

Общий запуск выполняется без Compose --wait: у фонового reconciler нет healthcheck. После up скрипт отдельно ждёт две готовые API через LB (stack.py wait --count 2).

make stop сохраняет volumes. Намеренное удаление всех учебных данных: docker compose down -v; оно не используется в тестах сохранности.

Python-образ 3.12.10 slim-bookworm, PG 16.9 bookworm, Redis 7.4.3 bookworm, HAProxy 3.0.11 bookworm. MinIO RELEASE.2025-04-22T22-12-26Z и mc RELEASE.2025-04-16T18-13-26Z собираются в локальные образы через infra/s3.Dockerfile: официальные GitHub Release binaries, проверка закреплённого SHA-256 до запуска. Это не требует доступа к переставшим быть общедоступными образам minio/minio. Все библиотеки закреплены по версиям.

Окружение измерений

Параметр Значение
Дата 16.10.2026
Система WSL2, Linux 5.15.146.1-microsoft-standard-WSL2, x86_64
Ресурсы Docker 16 логических CPU; 8187711488 bytes RAM, около 7.63 GiB
Docker Engine сервера 26.1.1, Docker Desktop
Docker CLI 28.0.1
Docker Compose 2.27.0-desktop.2
Python на хосте 3.10.12
API 2 реплики, каждая 1 CPU / 512 MiB, DB_POOL_MAX=8
Reconciler 0.5 CPU / 256 MiB

Источник: evidence/local_environment.txt, experiment_environment.json, containers_before.json, containers_final.json. CPU/RAM-лимиты API также сохранены отдельно для каждого повтора upload в upload_memory.json. После всех сценариев снова видны две готовые API; финальный smoke прошёл.

Перенос и архитектура

Основа — фактическое решение lab3 после проверок: PostgreSQL, общие сессии, Argon2id, Redis-кеш, keyset-пагинация, две API за HAProxy, X-Instance-Id, идемпотентность сообщений, рестарт и rolling. Сохранены исправления выбора реально работающего контейнера вместо жёсткого индекса API и Redis fallback. Исследование масштабирования lab3 повторно не запускается: в lab4 выбран другой трек.

Также перенесено исправление проверки cursor из lab3: JSON должен быть объектом, created_at и id — строками; неверные типы возвращают 400 invalid_request. Регрессионные проверки охватывают историю и список чатов на обеих API.

Добавлены MinIO, bootstrap bucket/IAM, вложения, третья миграция, reconciler и сценарии файлов/RAM/двух хранилищ. Описание переноса включено в этот отчёт, отдельного Markdown-файла миграции нет.

Клиент → HAProxy → API ×2 → PostgreSQL + приватный S3. PostgreSQL хранит метаданные, ACL, связи с сообщениями и результаты повторов; S3 — оригинальные bytes. Redis — кеш публичных полей профиля, не источник сессий. Для download авторизация и участие проверяются снова; случайный ключ не заменяет ACL. Наружу опубликован только 127.0.0.1:8080 у LB. У API/S3 нет опубликованных портов. Административная консоль MinIO выключена и привязана к loopback контейнера.

API и reconciler используют общего ограниченного S3-пользователя, отдельного от root. Его права: GET/PUT/DELETE в messenger-attachments/originals/* и LIST этого namespace. Нет прав создания bucket или администрирования IAM. Root credentials доступны S3 и bootstrap, но не API/reconciler. Bootstrap повторно безопасен: bucket/private policy/user создаются или приводятся к заданной конфигурации.

Контракт файла и сообщения

POST attachment принимает raw bytes PNG/JPEG, не multipart. Лимит 10485760 bytes проверяется по Content-Length до чтения и по счётчику потока, включая chunked body. Проверяются отображаемое имя 1–255 символов, отсутствие разделителей пути и управляющих символов, формат по содержимому и соответствие MIME. Через Pillow проверяются структура и полноценное декодирование; площадь ограничена 40000000 пикселей до load. PNG text metadata также ограничены. Повреждение/MIME — 415, byte/pixel limit — 413, опасное имя — 400.

Object key назначает сервер: originals/<chat UUID>/<attachment UUID>. Filename не используется как путь. SHA-256 и размер описывают исходные bytes. Валидация не перекодирует оригинал. Upload возвращает 201 ready только после успешного S3 PUT и COMMIT метаданных. Публичный Attachment не содержит object key или S3 URL. Download — авторизованный StreamingResponse с chunks 64 KiB, без redirect.

Message содержит attachment_ids. Можно передать пустой текст при хотя бы одном вложении; все ID уникальны и принадлежат этому чату. Любой участник может ссылаться на доступное вложение, независимо от uploader. Чужое/неизвестное — 404, неготовое — 409. Message и связи вложений сохраняются одной транзакцией. Отложенный SQL trigger проверяет текст/связи при COMMIT.

Идемпотентность lab3 сохранена. В хеш включается упорядоченный список непустых attachment_ids; отсутствующее поле и [] равны. Для старых текстовых запросов хеш не меняется. Миграция дополняет сохранённые старые ответы полем [] и не удаляет сообщения/сессии. Разные JSON key order/whitespace не меняют смысл.

Память, таймауты, готовность

Тело пишется потоково во временный bounded spool; это не постоянное хранилище оригинала в API. TemporaryFile закрывается после запроса, download читает S3. На процесс допускаются четыре активных upload, декодируется только одно изображение одновременно. Остальные клиенты ждут, а не декодируют параллельно. Нет await request.body() на весь файл. Дисковая запись/валидация выполняются в thread pool, чтобы не блокировать event loop.

API — по 1 CPU/512 MiB: RAM увеличена относительно lab3 для разрешённых больших изображений. PG 1 CPU/512 MiB, MinIO 1 CPU/512 MiB, Redis/LB по 0.5 CPU/128 MiB, reconciler 0.5 CPU/256 MiB. Фактические значения фиксируются через Docker inspect. S3 connect/read timeout 2/5 s, SDK не повторяет PUT автоматически; upload timeout 45 s, LB server timeout 50 s. SQL/lock/pool timeouts 3/2/2 s для API. Uvicorn graceful shutdown 8 s, Docker grace 10 s. Fault hook намеренно останавливает выбранную API; после неопределённого message POST повторяется прежний ключ.

Liveness проверяет процесс. Readiness проверяет PG и доступ к приватному S3 namespace; Redis не критичен. HAProxy опрашивает ready с interval 1 s, check timeout 1 s, fall 2/rise 1; Docker DNS обнаруживает актуальные реплики. Ориентир обнаружения отказа — несколько секунд; фактическую границу ≤10 s измеряет failover. Проверка LIST не обещает отсутствие любого будущего отказа диска или PUT.

.env управляет APP_PORT, SESSION_TTL_SECONDS, API_CPU, API_MEMORY, DB_POOL_MAX. S3 endpoint/bucket/region и пути credentials заданы в compose; MAX_* не превышают контрактные значения. API_REPLICAS из исходного .env.example заменено Compose scale; SESSION_STORE фиксирован как PG, CACHE_URL задан напрямую, TTL ключа — 24 h.

Согласованность PostgreSQL и S3

Общей транзакции между ними нет. Протокол upload:

  1. Полностью принять и проверить bounded файл.
  2. Взять PostgreSQL session advisory lock на UUID вложения.
  3. Сохранить устойчивую запись uploading с lease 120 s и COMMIT.
  4. Выполнить S3 PUT с transport Content-MD5 и метаданными SHA-256.
  5. Обновить ready и COMMIT, затем разрешить 201.
  6. Освободить lock. После ошибки остаётся uploading для безопасной компенсации.

Если PUT прошёл, а запись ready не прошла, объект учтён durable intent. Если PUT отказал, остаётся uploading без объекта. Обрыв HTTP до полной валидации не создаёт объектов/метаданных. Upload не имеет гарантии идемпотентности: повтор его POST может создать другое вложение, как допускает контракт.

Reconciler периодически запускается отдельным контейнером: каждые 60 s, grace 600 s. Разовый запуск по умолчанию dry-run:

make reconcile
docker compose run --rm --no-deps reconciler python -m src.reconcile --apply

Можно ограничить обход одним чатом через --chat-id UUID. Используются LIST, повторный HEAD и свежий запрос PG под общей блокировкой, а не только старый snapshot. Недоступность зависимости не считается отсутствием объекта. Dry-run не меняет данные.

Состояние Безопасное действие
Объект без метаданных Удалить только после grace, повторной проверки и отсутствия активного lock
Незавершённый uploading Ждать lease/grace; при отсутствии ссылок очистить старый объект и запись
Используемый ready Сохранить объект и метаданные
Слишком свежий объект/запись Пропустить
Ready, но bytes отсутствуют Сохранить метаданные/ссылки, пометить missing; API сообщает 503
Исходные bytes возвращены Проверить размер/SHA-256, затем восстановить ready

Reconciler не восстанавливает потерянные bytes из ничего. В сценарии оператор возвращает оригинал из fixture; только после проверки он снова становится ready. При исправлении missing ссылки из сообщений не удаляются. Повтор применённой сверки не должен повторно менять уже исправленное состояние.

Проверки и доказательства

Критерий Команда Результат моего стенда Evidence
Структура/контракт make check; make validate PASS; структура и схемы, отдельно от HTTP local_check.txt, local_validate.txt
Обязательный API make test PASS до/после отказов и в финале local_smoke.txt, local_smoke_after_failures.txt, local_final_smoke.txt
Минимум lab3, SQL и ключи make student-checks PASS; 100 сообщений от 10 клиентов, 32 повтора → 1 сообщение local_student_checks.txt, idempotency.json
Типы cursor make student-checks PASS; 400 invalid_request на обеих API, история и список чатов local_student_checks.txt
PNG/JPEG, лимиты, ACL make test-files PASS; bytes/pixels, MIME, filename, чужие ID/чаты, replay local_files.txt
Приватность bucket и права make test-files; make experiment PASS; anonymous GET 403, CreateBucket AccessDenied, console недоступна private_bucket.json
Прерывание body make test-files; make experiment PASS; отправлено 16 из заявленных 4096 bytes, 0 объектов и записей upload_interrupted.json
Полный restart make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS; старый токен, сообщения и оригинал сохранились local_persistence.txt, containers_before.json, containers_after_restart.json
Отказ выбранной API make test-failover ACTION_SCRIPT=scripts/stop-one.sh PASS; первая успешная запись после hook за 1.524 s local_failover.txt
Стоп uploader → другая API make test-file-failover PASS; 111817 bytes, SHA-256 совпал, 1.370 s attachment_failover.json
Каждая API и rolling make test-availability PASS; подтверждённые сообщения и оригиналы сохранены local_availability.txt, failures.json, rolling.json, rolling_containers.json
Redis/PG/S3 outage make test-dependencies PASS; Redis fallback, PG/S3 → 503, затем восстановление dependencies.json, local_dependencies.txt
Истечение сессии make test-expiry PASS; TTL=2 s, затем обычная конфигурация возвращена local_expiry.txt
Ошибки двух хранилищ make experiment, этап faults PASS; dry-run/apply/restore/repeat и защита вложений reconcile_faults.json, s3_write_failure.json
10 concurrent upload, память make experiment, этап memory PASS; 6 серий, 60/60 оригиналов, 0 ошибок upload_memory.json, upload_memory.png
Цена обхода make experiment, этап cost PASS; 100/500/1000, по 3 измерения после прогрева reconcile_cost.json, reconcile_cost.png, experiment_summary.json

Сохранность и переключение реплик

Snapshots до и после restart показывают новый started_at у PG, Redis, S3, LB и обеих API. Для PG/Redis/S3 сохранены container ID; API/LB пересозданы. Публичный persistence повторно прочитал данные и оригинал с прежней сессией. attachment_failover.json фиксирует остановленный контейнер uploader и другой X-Instance-Id скачавшей API. Контейнер uploader действительно остановлен в after.

Публичный failover: 122 успешные записи, 3 неуспешные попытки, первая успешная запись после старта hook через 1.524 s. Отдельный файловый failover: 1.370 s, 0 неуспешных попыток скачивания, оригинал 111817 bytes совпал побайтно и по SHA-256. Это разные сценарии и разные точки отсчёта, а не одно измерение.

Нагрузка Успешных запросов Неуспешных попыток Доля ошибок RPS успешных p95, ms Подтверждено / найдено сообщений
Стоп API №1 2034 38 1.834% 126.663 86.066 1228 / 1228
Стоп API №2 1995 56 2.730% 124.562 82.536 1212 / 1212
Rolling двух API 7020 176 2.446% 200.515 71.279 4254 / 4254

Для остановки каждой API верхняя оценка восстановления по секундным bucket — 2.998 s, меньше требуемых 10 s. Во всех трёх сценариях оригинал также проверен. Ошибки во время переключения не скрываются: клиенты повторяют неопределённые message POST с прежним Idempotency-Key. Все подтверждения сверены с историей. Нулевая потеря подтверждений не означает нулевую долю неуспешных попыток. В rolling сохранены шаги замены контейнеров; это не бесшовное обновление без ошибок.

При остановке Redis профиль и запись сообщения продолжили работать; серия контрольных запросов заняла 7.079 s. Это длительность серии с fallback, не latency одного запроса. При остановке PG readiness и запрос профиля вернули 503; при остановке S3 readiness и download вернули 503. После возврата зависимостей сохранились прежний токен, сообщение и оригинал.

Эксперимент на 5

Гипотеза: durable intent вместе с lease/lock/grace и повторной сверкой позволяет исправлять разрыв между S3 и PG, сохраняя свежие, активные и используемые вложения.

Ошибки реальные: временное удаление PUT из IAM-прав API; PostgreSQL trigger, отказывающий UPDATE ready после S3 PUT; объект без метаданных; удаление bytes используемого вложения. Все данные синтетические. Trigger удаляется в finally, обычная IAM policy возвращается, фоновый reconciler на время сценария остановлен. В тесте grace 20 s и контролируемые старые timestamps PG; возраст S3 orphan измеряется настоящим ожиданием. Это не настройка production grace.

Проверяются dry-run, apply, сохранность свежих/используемых объектов и активного lease/lock, возвращение оригинала, повторный apply и сохранность истории. Автоматическое восстановление S3/PG-кластеров не заявляется.

RAM-серия: два размера noise PNG, 256×256 и 1024×1024; по десять одновременно отправляющих клиентов, три повтора. API пересоздаются между случаями для нового high-water mark. Измеряется peak RSS процесса API и cgroup peak при наличии счётчика ядра, а не только редкие snapshots. Фиксируются реальные лимиты, aliases, RPS конечного burst, ошибки, p50/p95/p99 и проверка оригиналов второго участника. Burst RPS не является предельной sustained throughput сервера.

Цена обхода: отдельный синтетический чат, 100/500/1000 объектов и метаданных, прогрев полного прохода и по три dry-run. Он выполняется в роли reconciler с теми же CPU/RAM-лимитами. Сохраняются длительность, LIST/HEAD/GET/bytes counters, process RSS high-water и полный список решений. Raw сохраняется в JSON, сводка — в experiment_summary.json, графики — в PNG.

Результаты согласованности

Источник: evidence/reconcile_faults.json, s3_write_failure.json.

Сценарий Наблюдение и результат
S3 PUT запрещён IAM policy API вернула 503; в PG осталась uploading, объекта нет
Компенсация отказа PUT Dry-run сохранил запись, apply удалил просроченную запись без объекта; 0.035159 / 0.027420 s
PG отказала при UPDATE ready после PUT API вернула 503; uploading и объект существуют. Немедленная сверка за 0.027833 s ничего не удалила
Старый orphan + незавершённый upload + missing используемого файла Dry-run нашёл delete_orphan, delete_stale_upload, mark_missing; applied=false для всех, данные не изменены
Apply того же плана Те же три действия применены; ссылки и метаданные missing сохранены
Свежие, используемые, активная lease и удерживаемый lock Защитные проверки пройдены, вложения не удалены
Возврат оригинала оператором После возврата fixture выполнен GET 111817 bytes и проверен SHA-256; restore_ready
Повторный apply actions пуст; новых исправлений нет, история и исходные bytes доступны
Проход Время, ms Действий
dry_run 47.514 3
apply 53.742 3
restore 72.341 1
repeat 37.725 0

Ошибки внедрены на обеих сторонах реальными отказами IAM/SQL, а не подменой ответов клиента. Исправление безопасно в проверенных состояниях: свежие и используемые файлы не удаляются, пропавшие bytes не подменяются выдуманным файлом. В тесте отдельно подтверждён возврат оригинала оператором и проверка его checksum.

Результаты десяти одновременных загрузок

Два размера PNG, по три серии из 10 одновременно стартующих клиентов. Каждая серия достигла обеих API, успешно загрузила 10 файлов и скачала их вторым участником с проверкой исходных bytes и SHA-256. Итого 60/60, ошибок 0. API пересоздавались перед каждой серией; лимиты каждой реплики — 1 CPU/512 MiB.

PNG Размер, bytes Повтор Burst RPS p95 upload, ms Max RSS одной API, MiB Max cgroup peak одной API, MiB
256×256 197173 1 50.001 199.251 129.832 124.703
256×256 197173 2 69.096 143.348 111.172 116.461
256×256 197173 3 66.421 149.041 111.160 106.207
1024×1024 3151221 1 24.810 402.166 127.586 122.039
1024×1024 3151221 2 23.200 429.619 125.387 131.141
1024×1024 3151221 3 22.433 444.786 125.195 129.051

Медианы по трём сериям: для 256×256 — 66.421 burst RPS и p95 149.041 ms; для 1024×1024 — 23.200 burst RPS и p95 429.619 ms. Здесь медиана p95 — медиана трёх отдельных p95, а не общий p95 всех 30 запросов.

Максимальный process RSS среди всех серий — 129.832 MiB, максимальный cgroup peak — 131.141 MiB, заметно ниже лимита 512 MiB на API. Это максимум одной реплики, а не одновременная сумма памяти двух контейнеров. Cgroup peak измерен через cgroup v1 memory.max_usage_in_bytes; RSS получен через ru_maxrss.

Пик включает запуск процесса, регистрацию и вход перед upload, поэтому более крупный файл не обязан дать больший абсолютный RSS. Максимальный прирост RSS high-water между снимками before/after составил 4.797 MiB для 256×256 и 18.668 MiB для 1024×1024. Это прирост счётчика максимума, не точное выделение памяти только под содержимое файла. Burst RPS описывает короткую серию из 10 запросов и не заменяет продолжительный throughput-тест.

Пик памяти API при десяти одновременных загрузках

Стоимость обхода

Отдельный контейнер роли reconciler, лимиты 0.5 CPU/256 MiB. На каждом размере выполнен прогрев и три измеренных dry-run. Источник: evidence/reconcile_cost.json.

Объектов и записей PG Три прохода, s Медиана, s LIST / HEAD за проход GET содержимого / bytes Max RSS процесса, MiB
100 0.692223, 0.696161, 0.808335 0.696161 1 / 100 0 / 0 68.250
500 3.238328, 3.476147, 3.516724 3.476147 1 / 500 0 / 0 69.797
1000 6.510459, 6.586175, 6.482201 6.510459 1 / 1000 0 / 0 71.859

На каждом проходе просмотрены ровно N объектов и N метаданных, исправлений 0. Содержимое здоровых файлов не скачивалось: 0 GET и 0 bytes означают именно содержимое объектов, а не отсутствие сетевого трафика LIST/HEAD и SQL.

При росте количества объектов в 10 раз медианное время увеличилось примерно в 9.35 раза: 0.696161 → 6.510459 s. На измеренном диапазоне стоимость близка к линейной: один LIST и N HEAD, плюс запросы/блокировки PostgreSQL. Лишнее чтение оригиналов не требуется для обычного прохода; полный SHA-256 проверяется при восстановлении missing или несогласованности HEAD.

RSS здесь — накопительный максимум одного процесса, который последовательно готовил и обходил все три набора. Поэтому значения памяти по размерам не являются независимыми измерениями чистой памяти одного прохода. Максимум 71.859 MiB не достиг лимита reconciler 256 MiB. На большие объёмы эти числа не экстраполирую.

Стоимость обхода двух хранилищ

Вывод: на этом стенде гипотеза подтверждена для воспроизведённых состояний. Reconciler обнаружил оба вида рассогласования, безопасно выполнил компенсацию, сохранил свежие/используемые вложения; повторная сверка не внесла новых изменений. Стоимость проверенного обхода растёт вместе с числом объектов; выполнены отдельные измерения RAM для 10 конкурентных upload.

Ограничения и источники

Один host, PG, LB и S3 остаются SPOF. Две API не защищают от потери S3-диска. Повреждённые/отсутствующие оригиналы требуют восстановления из внешней копии. Полный проход хранит inventory/IDs в памяти, его стоимость растёт с числом объектов; для больших объёмов нужны paging/checkpoints и отдельный бюджет обслуживания. Обычный ready проверяется по HEAD/метаданным; полный checksum bytes выполняется при восстановлении missing или несогласованности HEAD. Это не постоянный full scrub. Истёкшие сессии/ключи и неиспользуемые ready-вложения автоматически не удаляются. Grace может задержать очистку; lease не является универсальным distributed transaction.

Измерения выполняются на одном компьютере; мониторинг/контрольные запросы также потребляют его ресурсы. RAM-серия охватывает файлы 197173 и 3151221 bytes; она не измеряет пик для каждого допустимого файла до 10 MiB/40 млн пикселей. Защита предельного размера и пикселей отдельно проверена отрицательными тестами. Для длинной нагрузки результаты нужно проверять отдельно. HTTP допускается только в локальном изолированном стенде. Прямой presigned upload и pipeline thumbnail не реализованы, поскольку выбран трек 2 lab4.

Источники: README/COURSE/OpenAPI lab4 и собственное решение lab3; MinIO release, mc release, S3 PutObject, Pillow Image, PostgreSQL locks.