# Отчёт — лабораторная 4 - Автор, группа: Кушнаренко Николай Вячеславович, БПИ2302 - Целевая оценка; выбранный трек 5, если нужен: **5**, трек 2 «Согласованность двух хранилищ» - Commit/PR: ветка `solution/bpi2302-kushnarenko` в [форке kolya](https://gitea.privcloud.tech/kolya/mtusi2026lab4); ссылка на 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 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//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](https://docs.haproxy.org/3.0/configuration.html). Первичный сбой сохранён в `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](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](evidence/recheck_2026-11-11/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](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](evidence/recheck_2026-11-11/upload_memory.json), [track2_reconcile.json](evidence/recheck_2026-11-11/track2_reconcile.json); вывод команд — [commands.txt](evidence/recheck_2026-11-11/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 тыс. объектов.