Files
mtusi2026lab4/REPORT.md
T

151 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 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/<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](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 тыс. объектов.