Files
mtusi2026lab4/REPORT.md
T
2026-11-06 17:03:03 +03:00

17 KiB
Raw Blame History

Отчёт — лабораторная 4

  • Автор, группа: Дыханова Алина БВТ2301
  • Целевая оценка: 5; выбранный трек 2 - согласованность PostgreSQL/S3
  • Источники, библиотеки и помощь ИИ: контракт и материалы репозитория; Flask, psycopg, Argon2, boto3, Pillow, RustFS, PostgreSQL, HAProxy, Redis.

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

Нужны Docker Desktop/Engine и Compose v2; первый запуск скачивает образы и Python-зависимости. Секреты создаются локально, не коммитятся и не печатаются:

python3 scripts/bootstrap.py
docker compose config --quiet
docker compose up -d --build --scale api=2 --wait --wait-timeout 180
make check
make test
python3 tests/attachments_negative.py

bootstrap.py создаёт secrets/ с правами 0700, файлы секретов — 0600, сохраняет уже существующие значения и создаёт .env. Bucket messenger-attachments идемпотентно создаётся bucket-bootstrap. Root RustFS credentials используются только для bootstrap; API получает отдельного IAM пользователя и policy с ограниченными правами к bucket. RustFS console выключена, портов object storage на host нет.

Безопасно остановить стенд с сохранением данных: docker compose down. Намеренно удалить учебные данные вместе с volumes: docker compose down -v (необратимо). Проверки сохранности/failover: make test-persistence ACTION_SCRIPT=scripts/restart.sh и make test-failover ACTION_SCRIPT=scripts/stop-one.sh. Запуск исследования трека 2: docker compose exec -T api python scripts/reconcile_experiment.py. Dry-run полного inventory: docker compose exec -T api python scripts/reconcile.py. После лабораторной остановить стенд без удаления данных: docker compose down.

Проверено 2026-11-06 на Docker Engine 29.8.0, Docker Desktop; в Compose закреплены rustfs/rustfs:1.0.3-glibc, rustfs/rc:v0.1.37, postgres:16.10-alpine, redis:7.4.6-alpine, haproxy:3.0.11-alpine; приложение — python:3.12.12-slim. Docker Compose config --quiet, сборка, запуск с двумя API replica и все указанные ниже сквозные проверки завершились успешно.

Архитектура и решения

клиент → HAProxy → API × 2
                       ├── PostgreSQL: users, sessions, chats, messages, attachment metadata
                       ├── Redis: необязательный кэш профиля
                       └── приватный RustFS (S3): оригиналы изображений

Перенесены регистрация и Argon2id-аутентификация, сессии, чаты, keyset-пагинация и транзакционная идемпотентность сообщений из предыдущих лабораторных. Вложение получает UUID и серверный object key {chat_id}/{attachment_id}; исходное имя используется только для отображения. Upload ограничен 10 MiB до чтения тела, проверяется сигнатура/формат PNG/JPEG через Pillow и ограничение 40 млн пикселей. Bytes синхронно сохраняются в S3, metadata — в PostgreSQL; 201 ready возвращается после сохранения обоих. Download проверяет членство в чате и возвращает исходные bytes через API без redirect.

S3 и PostgreSQL не образуют общую транзакцию. При обычной ошибке записи metadata код пытается удалить загруженный объект. При аварийном завершении или сбое компенсации reconciler обнаруживает orphan. В обычном режиме удаляются только объекты старше 24 часов, отсутствующие в БД; каждый ключ проверяется на ссылку ещё раз перед удалением. Missing-объекты только сообщаются, metadata не удаляется. Параметр --allow-short-grace разрешён только вместе с изолированным --prefix для теста; его нельзя применять к полному bucket.

Переменные .env.example сопоставлены реальному Compose: DATABASE_URL_FILE, CACHE_URL_FILE, S3_ACCESS_KEY_ID_FILE, S3_SECRET_ACCESS_KEY_FILE, S3_ENDPOINT=http://rustfs:9000, S3_REGION, S3_BUCKET, SESSION_TTL_SECONDS, MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS. Root и API credentials передаются через Docker secrets. Сервис RustFS слушает только внутреннюю сеть Compose.

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Офлайн-контракт make check PASS: проверены skeleton refs и синтаксис; приложение отдельно проверено ниже stdout проверки; scripts/check_contract.py
Compose/сборка/готовность docker compose config --quiet; docker compose up -d --build --scale api=2 --wait PASS: RustFS, PostgreSQL, Redis, API×2 и HAProxy healthy; bucket bootstrap и migration завершились с кодом 0 compose.yaml, evidence/runtime-checks.json
Публичный smoke lab4 make test PASS: сквозной API, checksum/байты оригинала, чтение участником, отказ постороннему tests/smoke.py, evidence/runtime-checks.json
PNG/JPEG и ошибки загрузки/доступа python3 tests/attachments_negative.py PASS: реальные PNG/JPEG загружаются; JPEG скачан участником побайтно; corrupt image=415, MIME spoof=415, 10 MiB+1=413, 40 972 801 пиксель=413, опасное имя=400, чужой attachment metadata/content=404, привязка к другому чату=404 tests/attachments_negative.py, tests/fixtures/sample.jpg, evidence/runtime-checks.json
Недоступный напрямую приватный bucket Unsigned S3 GET существующего object key из API network namespace PASS: RustFS вернул AccessDenied; порт S3 не опубликован на host infra/rustfs-policy.json, evidence/runtime-checks.json
Persistence make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS: hook сделал docker compose down и up без удаления volumes; старый bearer token, данные чата, сообщения и оригинал сохранились scripts/restart.sh, evidence/runtime-checks.json
API failover make test-failover ACTION_SCRIPT=scripts/stop-one.sh PASS: до отказа наблюдались 2 реплики; 127 успешных подтверждений, 2 переходных ошибки; первое восстановление записи через 1,273 с; остановленная реплика не обслуживала последние запросы; история и вложение проверены второй стороной scripts/stop-one.sh, evidence/runtime-checks.json
Недоступность S3 python3 tests/s3_unavailable.py PASS: upload получил 503, число metadata rows не выросло, RustFS был запущен обратно и стал healthy tests/s3_unavailable.py, evidence/runtime-checks.json
≥10 параллельных upload и память python3 tests/upload_load.py --base-url http://localhost:8080 PASS: 10 клиентов; 100 small и 30 large uploads, ошибок 0. На большом профиле Docker stats зафиксировал 135,9 MiB и 133,5 MiB для двух API при лимите 512 MiB на реплику tests/upload_load.py, evidence/upload-load.json
Трек 2: две стороны состояния, dry-run/apply/повтор docker compose exec -T api python scripts/reconcile_experiment.py PASS: свежий orphan пережил apply до grace; после aging был удалён только он; missing остался для диагностики, повторный dry-run стабилен; контрольное ready-вложение побайтно сохранилось scripts/reconcile_experiment.py, scripts/reconcile.py, evidence/reconcile-experiment.json

Сохранность проверялась реальным Compose hook: он остановил и удалил контейнеры всех сервисов, но оставил named volumes; затем заново создал PostgreSQL, RustFS, Redis, миграцию, API и LB. Failover hook остановил только ту API replica, чей alias вернул запрос; другая продолжила обслуживать запросы.

Эксперименты и отказы

Трек 2: гипотеза и результаты

Гипотеза. Reconciler сравнивает ссылки attachments.object_key с S3 inventory. Dry-run безопасен и только сообщает missing/orphan. В apply удаляются лишь неиспользуемые orphan старше grace period; missing и свежие/используемые объекты не удаляются. Повторный проход даёт стабильный результат.

Повторяемая методика. Команда scripts/reconcile_experiment.py создаёт уникальный S3 prefix, пишет один orphan object и одну metadata row с отсутствующим object key, выбирает существующее вложение как sentinel и сохраняет его SHA-256. Далее она запускает dry-run, сразу применяет с grace 3600 секунд и проверяет, что свежий orphan не удалён; ждёт 2,1 с, применяет --grace-seconds 1 --allow-short-grace --prefix <unique-prefix>, повторяет dry-run, сверяет sentinel и удаляет искусственную missing metadata row. Короткий grace ограничен уникальным prefix, существующие объекты лежат вне него.

Результат прогона 2026-11-06. Dry-run увидел db_rows=1, s3_objects=1, одну missing ссылку и один orphan, не удалил ничего. Немедленный apply с grace 3600 секунд тоже сохранил свежий orphan (eligible_orphans=[]). После ожидания 2,1 с apply с тестовым grace 1 секунда удалил только orphan. Повторный dry-run увидел s3_objects=0, orphan отсутствовал, missing запись осталась обнаруженной. Sentinel-вложение осталось ready и его SHA-256 совпал до/после. Время каждого обхода сохранено в JSON. После опыта тестовую missing row удалили; учебные файлы, загруженные smoke/load прогонами, оставлены в стенде.

Нагрузка и отказы

Для upload нагрузки использованы детерминированные PNG с шумом: 512×512 (787 247 байт, 262 144 пикселя) и 2048×1536 (9 441 653 байта, 3 145 728 пикселей). 10 worker начали параллельно; каждый сделал 10 запросов малого профиля и 3 большого. Это closed-loop синтетический опыт на локальном Docker Desktop без TLS. Метрики RPS и percentiles — только успешных запросов; генератор и измерение отражают эту конкретную машину, не production capacity. Docker stats обновляется примерно раз в секунду, поэтому пиковая память является sampled maximum и может не поймать короткий пик. В small-профиле длительность была около 1,3 с, отдельная выборка памяти не успела накопиться; для large доступно два telemetry sample.

Профиль Успешно / ошибки Время Успешных RPS p50 / p95 / p99 Пик памяти API-1 / API-2
512×512, 0,75 MiB, 100 загрузок 100 / 0 1,294 с 77,277 50,69 / 87,39 / 105,97 мс sampled отдельно не зафиксирован
2048×1536, 9,01 MiB, 30 загрузок 30 / 0 1,933 с 15,519 328,39 / 476,86 / 599,46 мс 135,9 / 133,5 MiB

Контейнеры API ограничены 512 MiB каждый и 0,75 CPU; память измерялась отдельно для двух реплик. Большой профиль держал API ниже 27% лимита по последнему sampled максимуму. Нагрузка закрытого типа и имеет coordinated omission; эти цифры характеризуют только описанный стенд.

Воздействие Что ожидали Что наблюдали Восстановление / потеря данных
Слишком большой upload 413 до декодирования Получен 413 на 10 MiB+1 Мгновенный отказ, записей нет
Испорченный файл / подменённый MIME / опасное имя 415 / 415 / 400 Коды совпали; API не вернул 500 Без побочных объектов
Посторонний user и вложение из другого чата 404 без раскрытия metadata/bytes Получен 404 на metadata, content и cross-chat attachment_ids Данные не изменились
Остановка одной API replica другая реплика продолжает подтверждать POST 127 подтверждений, 2 переходных ошибки; восстановление за 1,273 с Подтверждённые сообщения и оригинал не потеряны, дублей нет
Restart всех сервисов с volumes старые токены, сообщения и bytes доступны persistence hook завершился PASS Потери нет; все зависимости реально перезапущены
Missing+orphan и повторный reconciler удалить старый неиспользуемый orphan, сохранить missing и sentinel Обнаружены обе неисправности, удалён только orphan, повтор стабилен Sentinel bytes/checksum сохранены

Ограничения и следующие шаги

Работа подтверждена на локальном учебном стенде, но не является production deployment. Reconciler не восстанавливает утраченные bytes; он сохраняет metadata missing объекта для диагностики. Полный обход текущего bucket (424 metadata и 424 objects) занял 0,1364 с; стоимость на больших bucket надо измерять отдельно. Распределённой транзакции между S3 и PostgreSQL нет. Полный пик памяти может быть выше sampled Docker stats. Полную OpenAPI-валидацию (make validate) не удалось запустить: openapi-spec-validator отсутствовал локально, а установка из package index была недоступна из этой среды; make check и все runtime smoke/negative проверки выполнены. Не реализованы UI, thumbnail/background worker и presigned flow: они не входят в обязательный контракт lab4.