Files
mtusi2026lab4/REPORT.md
T

24 KiB
Raw Blame History

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

  • Автор, группа: Кушнаренко Николай Вячеславович, БПИ2302
  • Целевая оценка; выбранный трек 5, если нужен: 5, трек 2 «Согласованность двух хранилищ»
  • Commit/PR: ветка solution/bpi2302-kushnarenko в форке kolya; ссылка на PR добавляется после открытия
  • Использованные источники, библиотеки и помощь ИИ: Python 3.12, uvicorn, asyncpg, aiobotocore (S3), Pillow (проверка изображений), argon2-cffi; SeaweedFS 4.48 (S3); HAProxy; PostgreSQL; Valkey. Код lab3 перенесён. ИИ-ассистенты использовались для помощи с кодом, тестами и отчётом; Codex проверил подготовку к сдаче, усилил проверки исследования и выполнил реальные запуски 11.11.2026

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

Prerequisites: Docker Compose v2, bash (Git Bash на Windows), Python ≥ 3.9; на Windows PYTHONUTF8=1 для tests/*.py. Версии: python:3.12.12-slim-bookworm@sha256:593bd06e…, postgres:17.11-alpine@sha256:b0f9560a…, valkey/valkey:8.1.10-alpine@sha256:081c2f5c…, haproxy:3.0-alpine@sha256:56b887da…, chrislusf/seaweedfs:4.48@sha256:4e61d15f…, зависимости — requirements.txt (закреплены, включая aiobotocore==3.9.2, pillow==12.3.0).

sh scripts/init-secrets.sh                      # secrets/*: пароль БД, ключи S3 (admin и отдельные ключи API), seaweed_s3.json
cp .env.example .env
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build    # postgres, valkey, seaweedfs -> migrate + s3-init (один раз) -> api x2 -> lb
curl http://127.0.0.1:8080/health/ready
python3 tests/smoke.py --base-url http://127.0.0.1:8080
python3 tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080
python3 tests/resilience.py --mode failover    --action-script scripts/stop-one.sh --base-url http://127.0.0.1:8080
sh scripts/restore-replicas.sh
# собственные тесты (стенд должен быть запущен)
python3 -m unittest discover -s student-tests -p "test_api.py" -v
python3 -m unittest discover -s student-tests -p "test_attachments.py" -v
python3 student-tests/test_idempotency.py
python3 student-tests/test_topology.py
python3 student-tests/test_s3_failures.py
python3 student-tests/test_expiry.py
python3 student-tests/test_dependencies.py

Windows: scripts/restart.cmd и scripts/stop-one.cmd вместо .sh. Остановка с сохранением данных — docker compose --env-file .env stop; намеренное удаление учебных данных — docker compose --env-file .env down -v (volumes pgdata, valkeydata, seaweeddata).

Выбор S3-сервера. Используется SeaweedFS, разрешённый заданием. Образ закреплён тегом и digest. SeaweedFS запускается одним процессом (weed server -filer -s3), права задаются файлом identities (secrets/seaweed_s3.json).

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

Клиент ─▶ HAProxy ─▶ API ×2 ─▶ PostgreSQL (метаданные вложений, сообщения, сессии, ключи идемпотентности)
                         ├─▶ SeaweedFS S3 (приватный bucket, байты вложений)   [volume seaweeddata]
                         └─▶ Valkey (кэш сессий)
Роль Сервис Health Volume Сеть Credentials
S3 seaweedfs (master+volume+filer+S3) wget …:9333/cluster/status и nc -z :8333 seaweeddata только backend, порты не опубликованы, консоли/админки наружу нет seaweed_s3.json (secret)
bootstrap s3-init (one-shot) код выхода 0 — backend admin-ключи (только он), ключи API для проверки
остальные роли как в lab3
  • Данные. Метаданные — таблицы attachments (id, chat_id, owner_id, display filename, content_type, size, sha256, status, error_code, s3_key, …) и message_attachments (message_id, attachment_id, position); байты — в S3 под ключом att/<uuid>/original, который назначает сервер; filename используется только как отображаемое имя и нигде не входит в путь/ключ. Байты не хранятся ни в БД, ни в локальном каталоге API (временный буфер загрузки — SpooledTemporaryFile, удаляется после запроса).
  • Загрузка (POST /chats/{id}/attachments?filename=…, сырые bytes): авторизация → членство (чужой чат 404) → filename (1–255 code points; /, \, NUL, управляющие символы → 400) → Content-Type PNG/JPEG (иначе 415) → размер ≤ 10 MiB проверяется по Content-Length до чтения и по счётчику при потоковом приёме (413, соединение закрывается) → тело принимается порциями (до 1 MiB в RAM, далее временный файл) с подсчётом SHA-256 → проверка изображения до полной распаковки: сигнатура PNG/JPEG должна совпасть с заявленным типом (подмена MIME → 415), формат и размеры по заголовку Pillow, >40 млн пикселей → 413 (decompression bomb отклоняется по заголовку), целостность: PNG — CRC всех чанков (verify) + потоковая распаковка IDAT с проверкой конца потока и ожидаемого размера данных, JPEG — декодирование в режиме draft (≈1/64 памяти) → запись в S3 → строка в PostgreSQL (status=ready, 201). Ограничение одновременных загрузок на реплику (UPLOAD_CONCURRENCY=4, очередь 16, далее 429).
  • Скачивание (GET /attachments/{id}/content, ?variant=original|thumbnail|crop|optimized): авторизация → доступ по членству в чате вложения (постороннему/несуществующему — 404 без различий) → потоковая отдача из S3 порциями по 64 КиБ с истинным Content-Type, Content-Length, X-Content-Type-Options: nosniff, без redirect; недоступный S3 → 503; несуществующий вариант → 404; невалидный variant → 400.
  • Сообщения: attachment_ids (0–10 уникальных UUID, по умолчанию []; пустой текст допустим только с вложением). Вложение другого чата/неизвестное/чужое → 404; дубликаты, >10 → 400; идемпотентный повтор учитывает attachment_ids (нормализованное тело: порядок ключей JSON и отсутствие поля == []). Проверка вложений и вставка — внутри той же серверной функции send_message (миграция 0004), то есть атомарно.
  • Readiness API = PostgreSQL. S3 в readiness не включён осознанно: при падении S3 текстовые сообщения продолжают работать (проверено тестом), вложения отвечают 503 + Retry-After.

Согласованность S3 и PostgreSQL (механизм компенсации и сверки — уровень 4)

Порядок записи: сначала объект в S3, затем строка в PostgreSQL. Окна отказа:

Сбой Результат Исправление
Клиент оборвал загрузку ни объекта, ни строки (проверено тестом) —
S3 недоступен 503, строка не создаётся —
Сбой БД после записи в S3 клиент получает ошибку; объект удаляется компенсацией сразу (проверено внедрением сбоя FAULT_INJECTION=db_after_put) компенсация
Сбой БД и неудача удаления (или крах процесса между S3 и COMMIT) «осиротевший» объект без строки reconciler python -m app.reconcile

Reconciler (src/app/reconcile.py): по умолчанию dry-run; сравнивает attachments.s3_key и листинг bucket. Находит: orphan_object (объект без строки; удаляется только если старше grace — по умолчанию 900 с, поэтому свежая, ещё не зафиксированная загрузка не затрагивается), missing_object (строка ready без объекта → failed/object_missing, строка не удаляется, сообщения сохраняются, скачивание даёт 409), size_mismatch (размер объекта ≠ size_bytes → failed/size_mismatch). Объект, у которого есть строка в БД, не удаляется никогда; перед удалением выполняется повторная проверка строки. Повторный запуск идемпотентен.

Исправление отказа общей БД при подготовке к сдаче

В первом повторе 11.11.2026 тест остановки PostgreSQL обнаружил ответ вне JSON-контракта: после отрицательного readiness всех реплик HAProxy отдавал собственную ошибку вместо ответа приложения. Добавлен резервный backend по liveness, используемый только при отсутствии ready-реплик. Теперь живое приложение возвращает 503 с Retry-After и X-Request-Id, сохраняет 401 для запроса без токена и 200 для /health/live. Основная маршрутизация по readiness сохранена. Тест ждёт 5 с после остановки БД, чтобы гарантированно покрыть состояние после healthcheck балансировщика.

Также автоматические повторы HAProxy ограничены ошибкой установления соединения: ответ/таймаут уже отправленного upload POST не повторяется, поскольку контракт не делает загрузку идемпотентной. Описание директив: HAProxy 3.0 Configuration Manual. Первичный сбой сохранён в evidence/checks_before_fix_2026-11-11.txt; полный итоговый прогон — в evidence/checks_2026-11-11.txt.

Доказательства критериев — повторная проверка 11.11.2026

Проверены текущая ветка решения и исходный skeleton ec540a1. README задания, COURSE, CONTRIBUTING, публичные tests/ и contracts/ сохранены без изменений. Команды и фактический вывод: evidence/checks_2026-11-11.txt. В Windows выполнены Python-команды, соответствующие make check, make validate и make test; GNU Make для проверки не требуется.

Критерий Проверка Результат
Контракт и публичный сценарий check_contract, validate_openapi, smoke PASS
API, авторизация и идемпотентность между репликами test_api + test_idempotency 12 + 9 тестов OK
Изображения, лимиты, MIME, filename, ACL, чужой чат, прерывание upload, private bucket test_attachments 11 тестов OK; пользовательские ошибки не дают 500; анонимный S3 GET → 403
Реплики, порты, лимиты, непривилегированный пользователь test_topology 6 тестов OK
Компенсация, dry-run/apply, свежие orphan, используемые вложения, отказ S3 test_s3_failures 4 теста OK; защищённый файл связан с сообщением, ссылка сохранена
Истечение сессии, недоступность PostgreSQL и Valkey test_expiry + test_dependencies 2 + 2 теста OK
Сохранность при restart и остановке обслужившей реплики tests/resilience.py persistence/failover PASS; восстановление записи 2.329 с, 105 успешных записей, 0 неуспешных попыток
Идемпотентный bootstrap, отдельные ограниченные ключи API два повторных запуска s3-init существующий bucket сохранён; anonymous → 403; create_bucket ключом API → AccessDenied
≥10 параллельных загрузок и пик памяти research/upload_memory.py 12 клиентов; все файлы приняты и SHA-256 совпали; OOM нет
Трек 2: обнаружение и исправление расхождений, стоимость обхода research/reconcile_bench.py 20 orphan / 20 missing / 5 size mismatch; безопасное исправление и повтор без изменений

Всего 46 собственных тестов. После экспериментов дополнительно повторены persistence и smoke. В lifecycle.json зафиксировано изменение StartedAt всех сервисов (включая обе API-реплики и S3), сохранение имён volumes и healthy после restart.

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

Гипотеза. Reconciler находит внедрённые расхождения в обе стороны; dry-run ничего не меняет; apply удаляет только старые объекты без строки в БД, помечает потерянные/повреждённые вложения failed и сохраняет свежие объекты и файлы сообщений. Повтор apply не вносит изменений. Стоимость полного обхода увеличивается с числом объектов.

Методика и окружение. Windows, Docker Desktop с Linux-контейнерами, Python клиента 3.11.9, aiohttp 3.14.3, Pillow 12.3.0; приложение — Python 3.12.12. Образы и лимиты закреплены в compose.yaml. Во время исследования на машине оставался другой Docker-проект; абсолютные времена зависят от фоновой нагрузки. Один измерительный прогон на точку, статистическая значимость различий не оценивалась. Команды воспроизведения — student-tests/README.md.

В клиенте исследования сверки отключено повторное использование HTTP-соединений: блокирующий вызов Docker мог длиться дольше keep-alive сервера, и первая попытка остановилась с ServerDisconnectedError до внедрения расхождений. После исправления выполнен полный повтор сверки; исходный вывод сохранён в evidence/recheck_2026-11-11/commands_before_client_fix.txt. Замеры памяти не повторялись: они завершились успешно и не зависели от этого клиента. SHA-256 проверенных исходников записаны в source_metadata.json рядом с результатами.

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

12 клиентов загружают по 8.73 MiB PNG (шум 1700×1700). Для каждой точки создаётся одна новая API-реплика, 1 CPU / 256 MiB; меняется только UPLOAD_CONCURRENCY. Пик — VmHWM процесса API, это не суммарная память всех контейнеров. После измерения каждый принятый файл скачивается и проверяется SHA-256. В конце восстановлены две реплики с UPLOAD_CONCURRENCY=4.

UPLOAD_CONCURRENCY Пик RSS, MiB Загрузка всех файлов, с Принято и цело OOMKilled
1 99.2 1.31 12/12 false
4 119.0 1.18 12/12 false
12 121.2 1.14 12/12 false

Сверка двух хранилищ

К существующим синтетическим данным добавлены 3000 вложений тремя порциями по 1000. После каждой порции измерен dry-run. Затем созданы 20 orphan в S3, удалены объекты 20 существующих вложений и изменён размер ещё 5. 200 других вложений прикреплены к 20 сообщениям (по 10); перед исправлением сохранены идентификаторы сообщений и их attachment_ids.

После паузы больше 5 с выполняются два dry-run, затем apply с grace=5 параллельно с задачей загрузки 200 новых файлов, затем повторный apply. Рабочее значение grace — 900 с; короткий grace используется только в эксперименте. Отдельный тест детерминированно оставляет свежий orphan и подтверждает, что --apply --grace 900 его не удаляет.

Проверка Фактический результат
dry-run ×2 ровно 20 orphan, 20 missing, 5 size mismatch; fixed=0/0; повторяемо
apply удалено 20 старых orphan, 25 строк помечены failed (20 object_missing, 5 size_mismatch)
Новые загрузки 200/200 приняты и скачаны с совпадающей SHA-256
Вложения сообщений 200/200 целы; все 20 сообщений и attachment_ids неизменны
Повтор apply 0 удалений, 0 изменений статусов, новых расхождений нет
Строк БД Объектов S3 Запрос БД, мс Листинг S3, мс Весь обход, мс
19554 19530 20.2 3540.6 3649.4
20554 20530 19.0 3697.2 3806.4
21554 21530 21.2 3939.1 4055.0

На проверенном наборе основную стоимость даёт листинг S3; результаты трёх точек не доказывают линейное время на произвольном объёме. Алгоритм хранит снимки метаданных и листинга в памяти: время и дополнительная память — O(N). Сырой результат: upload_memory.json, track2_reconcile.json; вывод команд — commands.txt.

Границы. Сверяются наличие и размер, но не содержимое S3-объектов: подмена байтов без изменения размера этим reconciler не обнаруживается. Целостность контрольных файлов подтверждает скачивание с SHA-256. Потерянные байты не восстанавливаются, строка остаётся failed. Grace должен превышать время загрузки и таймаутов; для рабочих запусков принят 900 с. S3 и PostgreSQL — по одному узлу. Старые октябрьские результаты сохранены в evidence/checks.txt, evidence/upload_memory.json и evidence/track2_reconcile.json; текущие выводы опираются на повтор 11.11.2026.

Отказы

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Остановка S3 загрузка/скачивание 503 + Retry-After, текст работает, ready=200 OK (test_s3_down…) после старта S3 — сразу; метаданные не накапливают «битых» строк
Остановка одной реплики после upload файл скачивается другой репликой failover PASS (восстановление записи 2.329 с) потерь нет
Рестарт всего стенда метаданные и оригинал на месте persistence PASS < 90 с
Сбой БД после записи в S3 объект не остаётся удаляется компенсацией; при сбое компенсации — reconciler потерь подтверждённых данных нет

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

  • Один узел S3 и один PostgreSQL (SPOF); репликации нет. Загрузка проксируется через API (прямые подписанные URL не реализованы — трек 1 не выбран).
  • Проверка содержимого JPEG — декодирование в режиме draft (1/8), PNG — потоковая проверка; полная валидация пикселей не выполняется (это не нужно для отдачи оригинала).
  • Подтверждено экспериментом: обнаружение/исправление расхождений, защита свежих и используемых вложений, стоимость обхода на трёх размерах набора, ограничение памяти при 12 одновременных загрузках. Гипотеза без доказательства: поведение reconciler на бакетах > 100 тыс. объектов.