forked from mtusi2026/mtusi2026lab4
100 lines
18 KiB
Markdown
100 lines
18 KiB
Markdown
# Отчёт — лабораторная 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.
|