Files
mtusi2026lab4/REPORT.md
T

100 lines
18 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
- Автор: **Владислав Гавриленко, БПИ2303**.
- Целевая оценка: **3**, исследовательские треки 4/5 не заявлены.
- Ветка: `solution/bpi2303-gavrilenko`, форк: https://gitea.privcloud.tech/sxdees/mtusi2026lab4.
- MR: ссылка добавляется после публикации.
- Основа: собственная [лабораторная 3](https://gitea.privcloud.tech/sxdees/mtusi2026lab3/src/commit/51dae8c44a93c4cd5488be89ac84146d7e9cb61c), commit `51dae8c44a93c4cd5488be89ac84146d7e9cb61c`.
- Источники: контракт и публичные проверки этой лабораторной; [SeaweedFS S3](https://github.com/seaweedfs/seaweedfs/wiki/Amazon-S3-API), [Pillow Image](https://pillow.readthedocs.io/en/stable/reference/Image.html), [boto3 S3](https://docs.aws.amazon.com/boto3/latest/reference/services/s3.html). Код и отчёт подготовлены с помощью Codex.
## Запуск из чистого clone
Нужны Docker Engine с Compose v2, Python 3.9+ для публичных проверок, свободный порт 8084 и несколько GiB свободного места **в Linux-диске Docker**. Проверено на macOS arm64 / OrbStack, Docker Engine 29.8.2. Образы: Python 3.13.7 slim-bookworm, PostgreSQL 17.6-bookworm, HAProxy 3.2.6-alpine, SeaweedFS 4.48; runtime: psycopg 3.2.10, boto3 1.44.2, Pillow 13.0.0.
```sh
git clone -b solution/bpi2303-gavrilenko https://gitea.privcloud.tech/sxdees/mtusi2026lab4.git
cd mtusi2026lab4
scripts/setup.sh
docker compose config --quiet
docker compose up -d --build --wait
curl --fail http://localhost:8084/health/ready
make check test BASE_URL=http://localhost:8084
python3 student-tests/check.py --base-url http://localhost:8084
python3 student-tests/idempotency.py --base-url http://localhost:8084
python3 -m venv .venv
.venv/bin/pip install Pillow==13.0.0 -r requirements-dev.txt
make validate PYTHON=.venv/bin/python
.venv/bin/python student-tests/attachments.py --base-url http://localhost:8084
docker compose exec -T api python - < student-tests/storage.py
docker compose exec -T api python - < student-tests/db_check.py
make test-persistence BASE_URL=http://localhost:8084 ACTION_SCRIPT=scripts/restart.sh
make test-failover BASE_URL=http://localhost:8084 ACTION_SCRIPT=scripts/stop-one.sh
docker compose up -d --wait
python3 student-tests/attachment_failover.py --base-url http://localhost:8084
python3 student-tests/s3_outage.py --base-url http://localhost:8084
```
`setup.sh` создаёт случайные DB/S3 credentials в игнорируемом каталоге `secrets/` с правами 0700, локальный `.env`; существующие файлы сохраняются. Файлы, читаемые непривилегированным API UID 10001 через Docker secrets, имеют права 0644 внутри защищённого каталога. Не копировать `.env`/`secrets/` в Git. Для другого порта изменить `HOST_PORT` и `BASE_URL`.
Миграции выполняет одноразовый сервис `migrate`: PostgreSQL advisory lock, журнал `schema_migrations`, все изменения атомарны. Одноразовый `bucket` ждёт готовности S3, создаёт bucket при отсутствии и убирает bucket policy с публичными разрешениями; повторный запуск безопасен. `NoSuchBucketPolicy` означает уже приватное состояние. Compose запускает две API-реплики после завершения обоих заданий.
Безопасная остановка с сохранением данных: `docker compose down`. Повторный запуск: `docker compose up -d --wait`. **Намеренное удаление всех учебных данных этого проекта:** `docker compose down -v`, затем `rm -rf data/s3` (для persistence не использовать). Другие Compose-проекты эти команды не затрагивают.
## Архитектура и решения
`клиент → 127.0.0.1:8084 HAProxy → API × 2 → PostgreSQL + SeaweedFS S3`.
Из lab3 перенесены исходники сервера/БД, первые две миграции, Dockerfile, HAProxy DNS service discovery, настройки двух реплик, скрипты и собственные проверки. README, COURSE, contracts, lab.json и публичные tests сохранены из lab4. PostgreSQL хранит пользователей, scrypt-хеши паролей, SHA-256 bearer-токенов с expiry, чаты/членство, сообщения, результаты идемпотентных POST и метаданные вложений. Бинарные оригиналы находятся только в приватном S3 bucket `messenger-attachments`.
Новая миграция `003_attachments.sql` создаёт Attachment и разрешает сообщение с пустым текстом при непустом `attachment_ids`. Вложение принадлежит чату и загрузившему участнику; серверный ключ `original/<случайный UUID>` не зависит от filename и не попадает в публичный JSON. Сообщение содержит до 10 уникальных UUID; API проверяет существование и принадлежность каждого тому же чату. Идемпотентность сохраняется: ключ блокируется транзакционно в PostgreSQL, отсутствующий список и `[]` эквивалентны, изменение текста или списка возвращает 409.
До чтения тела проверяются аутентификация, членство, filename, Content-Length ≤10 MiB и заявленный MIME. Тело читается с известным ограничением; chunked upload не поддерживается и возвращает 400. Pillow определяет реальный PNG/JPEG, сверяет MIME, проверяет число пикселей **до декодирования**, затем verify/load выявляют повреждение. Лимит 40 млн пикселей; превышение — 413, чужой/повреждённый формат — 415, опасное имя — 400. Filename с `/`, `\`, NUL, C0/C1/DEL, пустой или длиннее 255 символов отклоняется. Изображение не перекодируется: S3 получает исходные bytes, API возвращает тот же оригинал с правильным MIME, без redirect.
Сначала синхронный S3 PUT, затем INSERT метаданных и COMMIT PostgreSQL, только после этого 201 `ready`, `variants=[]`, `error_code=null`. При известном отказе до COMMIT выполняется попытка удалить записанный объект. При неясном исходе COMMIT объект не удаляется: это защищает потенциально подтверждённые метаданные. S3 и PostgreSQL не составляют распределённую транзакцию; аварийное завершение/отказ компенсации может оставить orphan. Автоматической сверки нет (это уровень 4/5).
`postgres_data` хранит БД, `./data/s3` (persistent bind mount) — master/volume/filer. Filer использует LevelDB2 явно в `/data/filerldb2`, а не ephemeral `/tmp`. На API нет тома или локального каталога оригиналов. SeaweedFS master, volume, filer и S3 запущены одним сервисом `s3`. Все его порты и порты БД/API доступны только в Compose-сети; наружу опубликован лишь localhost LB. S3 требует подпись из сгенерированного JSON с identities; анонимного пользователя нет. На уровне 3 API и bootstrap используют одну административную S3 identity.
`/health/live` не зависит от хранилищ. `/health/ready` требует PostgreSQL SELECT и S3 HeadBucket, поскольку S3 входит в обязательный синхронный путь; HAProxy проверяет readiness, исключая неготовые реплики. Проверка соединения не гарантирует свободное место для будущей записи. S3 имеет таймаут подключения 2s, чтения 3s и одну попытку, без скрытого retry upload.
`.env.example` соответствует реально читаемым переменным: `HOST_PORT`, `SESSION_TTL_SECONDS`, `API_REPLICAS`, `IDEMPOTENCY_TTL_SECONDS`. `DATABASE_URL_FILE`, S3 endpoint/region/bucket и пути credentials задаёт Compose. `APP_HOST`/`APP_PORT` заданы там же. Ограничения 10485760 bytes / 40000000 pixels фиксированы контрактом в коде; Redis/Valkey для оценки 3 не используется, сессии устойчиво хранятся в PostgreSQL.
## Доказательства критериев
Проверено 13.11.2026 (Europe/Moscow). Тесты используют синтетические данные, bearer tokens не сохраняются.
| Критерий | Команда / сценарий | Наблюдаемый результат | Доказательство |
| --- | --- | --- | --- |
| Контракт и публичный smoke lab4 | `make check validate`, `make test BASE_URL=http://localhost:8084` | PASS; исходные public tests/contracts не изменены | `evidence/checks.txt`, `evidence/final.txt` |
| Возможности lab3: идентификация, ACL, Unicode, пагинация, идемпотентность | `student-tests/check.py`, `student-tests/idempotency.py` | PASS; 32 конкурентных повтора через ≥2 процесса создали ровно одно сообщение | `evidence/checks.txt` |
| Истечение сессии из lab2 | Одноразовая API с `SESSION_TTL_SECONDS=2`, `student-tests/expiry.py` | Сразу GET 200; через 3s GET и logout 401 | `evidence/expiry.txt` |
| Реальные PNG/JPEG, limits, filename, MIME, сообщения с вложениями | `.venv/bin/python student-tests/attachments.py --base-url http://localhost:8084` | Побайтное совпадение PNG/JPEG, 10 MiB / 40M pixels приняты, превышения 413, повреждение/MIME 415, чужой чат 404, retry/conflict корректны | `evidence/checks.txt` |
| Разделение БД/S3, приватный bucket | `docker compose exec -T api python - < student-tests/storage.py` | Все строки Attachment имеют S3-оригинал с правильным размером/SHA256; anonymous GET реальных ключей →403 | `evidence/checks.txt`, `evidence/final.txt` |
| Устойчивые volumes, прежние сессии и оригинал | `make test-persistence BASE_URL=http://localhost:8084 ACTION_SCRIPT=scripts/restart.sh` | PASS; рестарт LB, API×2, PostgreSQL и S3 без удаления данных | `evidence/persistence.txt`, `evidence/containers-before.json`, `evidence/containers-after.json` |
| Отказ API во время записи | `make test-failover BASE_URL=http://localhost:8084 ACTION_SCRIPT=scripts/stop-one.sh` | Две реплики до отказа; 95 успешных записей, 3 переходные ошибки, восстановление 2,44s; потерь/дублей нет | `evidence/failover.txt` |
| Upload → остановка именно загрузившей реплики → download другой | `python3 student-tests/attachment_failover.py --base-url http://localhost:8084` | PASS отдельно для обеих реальных реплик; остановленный контейнер оставался выключен во время побайтного сравнения | `evidence/attachment-failover.txt` |
| Недоступность настоящего S3 | `python3 student-tests/s3_outage.py --base-url http://localhost:8084` | Live 200; ready/upload/content 503; число Attachment не выросло; после восстановления исходные bytes доступны | `evidence/s3-outage.txt` |
| Миграции и отсутствие потери данных при rollback | `docker compose exec -T api python - < student-tests/db_check.py` | Повторные миграции сохраняют counts, включая attachments; KDF/token digests и FK/rollback проверены | `evidence/final.txt` |
Для проверки S3 outage запросы идут изнутри API-контейнера на `localhost:8080`: LB специально исключает обе неготовые реплики. Порты реплик на host не публикуются. Снимки до/после содержат container ID, StartedAt и типы mounts, без env/credentials. После всех отказов обе API-реплики восстановлены, финальный smoke и проверка всех оригиналов повторены.
Проверку короткого TTL можно повторить отдельным контейнером, не меняя основной стенд:
```sh
docker compose run -d --rm --no-deps --name gavrilenko-lab4-expiry -v "$PWD:/work:ro" -e SESSION_TTL_SECONDS=2 api
until [ "$(docker inspect --format '{{.State.Health.Status}}' gavrilenko-lab4-expiry)" = healthy ]; do sleep 1; done
docker exec gavrilenko-lab4-expiry python /work/student-tests/expiry.py --base-url http://localhost:8080
docker stop gavrilenko-lab4-expiry
```
В `.github/workflows/application.yml` добавлен отдельный job: сборка Compose, готовность, smoke, собственные проверки, persistence/failover и остановка. На Gitea Actions отключены; hosted job не запускался, соответствующие команды выполнены локально.
## Эксперименты и отказы
Цель — подтвердить корректность уровня 3, а не максимальную пропускную способность. Нагрузочные исследования, RPS/p95 и ≥10 параллельных upload не заявлены. В `student-tests/idempotency.py` проверяются 32 конкурентных повтора сообщения через две реальные реплики.
Во время подготовки образ MinIO оказался недоступен в Docker Hub и quay.io; выбран разрешённый SeaweedFS. Первые запуски выявили заполненный диск Docker: сборка завершалась `no space left on device`, затем S3 отказывался писать при свободном месте менее 1%. Освобождён пересоздаваемый build-cache и неиспользуемый скачиваемый образ sitespeedio; чужие volumes/контейнеры не удалялись. OrbStack затем снова показывал ~245 MiB свободного места внутри динамического Linux-диска при 29 GiB на macOS. Для S3 выбран persistent bind mount `./data/s3`, который видит свободное место macOS; уже созданные данные скопированы при остановленном S3. Минимальную защиту SeaweedFS по свободному месту не отключали. Итоговые результаты ниже относятся к повторным запускам после устранения причины.
## Ограничения и следующие шаги
Только оценка 3. Нет reconciler для orphan, отдельной ограниченной S3 identity API, presigned flow, thumbnail/worker, исследования памяти и полного fuzz/security audit. HTTP допустим для localhost с синтетическими данными; удалённая демонстрация требует TLS. `http.server`, соединение БД на запрос и отсутствие ограничения общего числа HTTP threads — учебные упрощения. Одна загрузка ограничена по bytes/pixels, но много параллельных декодирований может превысить лимит памяти API 512 MiB. Истёкшие сессии/старые ключи не чистятся фоновым заданием. PostgreSQL, S3, LB и host — одиночные точки отказа; переживается остановка одной API-реплики и рестарт с сохранением volumes, а не потеря диска или host.