forked from mtusi2026/mtusi2026lab4
Переиспользован стек lab3 (LB/2 реплики/Postgres/Redis/идемпотентность). Добавлены: S3-хранилище байтов вложений (SeaweedFS вместо MinIO — публичные MinIO-образы недоступны без авторизации), метаданные attachments в Postgres, проверка изображений по содержимому с защитой от decompression bomb, ограниченные S3-credentials, скрипт сверки orphan-объектов. make test/ test-persistence/test-failover/validate зелёные для обеих реплик; собраны доказательства по превышению размера, MIME-спуфингу, чужим attachment_id, приватности bucket, конкурентным загрузкам и orphan-очистке — см. REPORT.md. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
92 lines
12 KiB
Markdown
92 lines
12 KiB
Markdown
# Отчёт — лабораторная 4
|
||
|
||
- Автор, группа: Сарибекян, БПИ2303
|
||
- Целевая оценка: 4
|
||
- Commit/PR: см. ветку `solution/БПИ2303-Сарибекян`
|
||
- Использованные источники, библиотеки и помощь ИИ: база lab3 (FastAPI/asyncpg/redis-py/argon2-cffi/Nginx) плюс `boto3` (S3-клиент) и `Pillow` (проверка изображений). Хранилище — **SeaweedFS** (не MinIO — см. ограничения), S3-совместимый API. Реализация подготовлена с помощью AI-ассистента (Claude Code); проверено локальным запуском `make check/test/test-persistence/test-failover/validate` и серией ручных edge-case тестов.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Версии: Python 3.12.7, PostgreSQL 16.4, Redis 7.4.1, Nginx 1.27.2, SeaweedFS 3.73.
|
||
|
||
```sh
|
||
git clone <ваш форк>
|
||
cd mtusi2026lab4
|
||
mkdir -p secrets
|
||
openssl rand -hex 20 > secrets/postgres_password.txt
|
||
printf 'postgresql://messenger:%s@postgres:5432/messenger' "$(cat secrets/postgres_password.txt)" > secrets/database_url.txt
|
||
printf 'redis://redis:6379/0' > secrets/cache_url.txt
|
||
printf 'messenger-api' > secrets/s3_access_key_id.txt
|
||
openssl rand -hex 20 > secrets/s3_secret_access_key.txt
|
||
AK=$(cat secrets/s3_access_key_id.txt); SK=$(cat secrets/s3_secret_access_key.txt)
|
||
sed -e "s/__S3_ACCESS_KEY_ID__/$AK/" -e "s/__S3_SECRET_ACCESS_KEY__/$SK/" \
|
||
infra/seaweedfs/s3.json.template > secrets/s3.json
|
||
chmod 600 secrets/*.txt secrets/s3.json
|
||
printf 'SESSION_TTL_SECONDS=3600\nMAX_UPLOAD_BYTES=10485760\nMAX_IMAGE_PIXELS=40000000\n' > .env
|
||
|
||
docker compose --env-file .env config --quiet
|
||
docker compose --env-file .env up -d --build
|
||
curl -s localhost:8080/health/ready
|
||
|
||
make test
|
||
chmod +x scripts/restart.sh scripts/stop-one.sh
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
|
||
# после отказа одной реплики: docker compose start api1 (или api2), повторить для второй.
|
||
```
|
||
|
||
Остановка: `docker compose stop`. Намеренное удаление данных: `docker compose down -v`.
|
||
|
||
## Архитектура и решения
|
||
|
||
```
|
||
Клиент → lb (Nginx) → api1 / api2 → PostgreSQL (метаданные) + Redis (сессии) + SeaweedFS S3 (байты, приватный bucket)
|
||
```
|
||
|
||
- **Почему SeaweedFS, а не MinIO**: официальные образы `minio/minio` больше не тянутся публично ни с Docker Hub, ни с Quay.io (`401/403` на pull) — MinIO изменил политику распространения community-образов. SeaweedFS (`chrislusf/seaweedfs:3.73`, закреплённый тег) доступен свободно и был указан как разрешённая альтернатива в README.
|
||
- **S3 bucket**: `messenger-attachments`. API использует **не root**, а отдельную identity `messenger-api`, заданную в `infra/seaweedfs/s3.json.template` (реальные ключи — в гитигнорированном `secrets/s3.json`), с правами ровно `Read/Write/List` на этот один bucket. Админ-консоли/порта управления SeaweedFS наружу не публикуется.
|
||
- **Bucket bootstrap идемпотентен без прав администратора**: т.к. у `messenger-api` нет права `CreateBucket`, bootstrap (`storage.ensure_bucket()`) просто пишет маркерный объект `.bootstrap` — SeaweedFS (как и S3) автосоздаёт bucket при первом успешном `PutObject`. Повторные запуски — не ошибка (перезапись того же объекта).
|
||
- **Схема**: `attachments(id, chat_id, owner_id, filename, content_type, size_bytes, sha256, status, error_code, s3_key, created_at, updated_at)` + `message_attachments(message_id, attachment_id)` (migrations `0003_attachments.sql`). `s3_key` генерируется сервером (`attachments/<uuid>`), `filename` — только отображаемое имя, никогда не используется как путь.
|
||
- **Валидация изображения по содержимому** (`app/images.py`): реальный формат (`Pillow` `Image.open().format`) сравнивается с заявленным `Content-Type`; пиксельный бюджет (40 млн) проверяется **до** `img.load()` (защита от decompression bomb); файл читается потоково с проверкой байтового лимита (10 MiB) **во время** чтения тела запроса, не после.
|
||
- **Синхронный upload**: `201 Attachment{status:"ready"}` возвращается только после того, как байты реально в S3 **и** транзакция метаданных закоммичена в Postgres (в этом порядке — см. раздел про orphan-объекты).
|
||
- **Идемпотентность с вложениями**: хэш для `Idempotency-Key` теперь включает `sorted(attachment_ids)`, не только `text`.
|
||
- **Совместимость с lab3**: текстовые `POST` без вложений остаются валидны; `message_attachments` — отдельная таблица, не меняющая существующие колонки `messages`.
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||
| --- | --- | --- | --- |
|
||
| Публичный smoke | `make test` | `PASS: lab4 public API scenario...` | вывод команды |
|
||
| Персистентность | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | `PASS` | вывод команды |
|
||
| Upload→стоп реплики→download через другую | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`, дважды (по разу на реплику) | `successful_writes:97/97, failed_attempts:0`, встроенная в тест проверка SHA-256 после отказа — без ошибок | вывод команды |
|
||
| ≤10 MiB / ≤40 млн пикселей | upload 11 МБ файла | `413 payload_too_large` (после фикса Nginx — см. ограничения) | `evidence/attachment_edge_cases.txt` |
|
||
| MIME по содержимому | настоящий JPEG, заявлен как `image/png` | `415 unsupported_media_type: declared content type does not match actual image format` | `evidence/attachment_edge_cases.txt` |
|
||
| Битое изображение | произвольные байты с `Content-Type: image/png` | `415 unsupported_media_type` | `evidence/attachment_edge_cases.txt` |
|
||
| Чужой `attachment_id` | вложение из chat A в сообщение chat B | `404 not_found` | `evidence/attachment_edge_cases.txt` |
|
||
| Приватный bucket вне API | прямой `curl` с хоста на `seaweedfs:8333` | порт не опубликован → `connection refused` (curl exit 7) | `evidence/attachment_edge_cases.txt` |
|
||
| ≥10 конкурентных загрузок, память | 15 параллельных upload | все `201`; `api1` 73.4→75.2 MiB, `api2` 69.6→68.9 MiB (лимит 256 MiB) | `evidence/attachment_edge_cases.txt` |
|
||
| Orphan-компенсация | `scripts/reconcile_attachments.py` на искусственно созданном orphan-объекте | найден, затем удалён `--delete`; реальные вложения не тронуты | `evidence/reconcile_demo.txt` |
|
||
| Отдельные S3-credentials с ограниченными правами | `infra/seaweedfs/s3.json.template`: identity только `Read/Write/List` на один bucket | код/конфиг-ревью | `infra/seaweedfs/s3.json.template` |
|
||
| `make validate` | `make validate PYTHON=.venv/bin/python` | `PASS: full OpenAPI 3.1...` | вывод команды |
|
||
|
||
## Эксперименты и отказы
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| Остановка `api1` во время upload/download цикла | Чтение/запись продолжаются, SHA-256 совпадает после переключения на `api2` | `successful_writes=97, failed_attempts=0, first_recovery_seconds=1.155` | восстановление 1.16с, потерь нет |
|
||
| Остановка `api2` (вторая реплика) | То же | `successful_writes=97, failed_attempts=0, first_recovery_seconds=0.884` | восстановление 0.88с, потерь нет |
|
||
| `docker compose restart postgres redis seaweedfs api1 api2 lb` (последовательно, с ожиданием healthy) | Вложения и сообщения сохраняются | `PASS` в `make test-persistence` | восстановление <90с, без потерь |
|
||
| 15 параллельных upload одного файла (~112 KB) | Нет деградации/ошибок | все `201`, рост RSS на несколько МБ, в пределах лимита 256 MiB | — |
|
||
| Искусственный orphan-объект в S3 (без строки в БД) | Обнаруживается сверкой, не трогает реальные вложения | найден `scripts/reconcile_attachments.py --grace-minutes 0`, удалён с `--delete` | — |
|
||
|
||
**Ограничение:** нагрузочный тест на реальных конкурентных upload >15 и трек исследования уровня 5 (presigned URL / полноценный reconciler с внедрением ошибок на обеих сторонах) не выполнялись — цель лабы — оценка 4.
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
- **MinIO недоступен публично** (см. архитектуру) — заменён на SeaweedFS; если преподаватель ожидает конкретно MinIO, нужно либо получить доступ к их registry, либо принять эту замену как равноценную (README явно разрешает выбор одного из трёх).
|
||
- Найден и исправлен баг: **Nginx перехватывал превышение размера раньше приложения** и отдавал свою HTML-страницу `413` вместо контрактного JSON-конверта. Исправлено: `client_max_body_size` в Nginx поднят чуть выше (11 MiB) собственного лимита приложения (10 MiB), так что именно приложение формирует финальный ответ.
|
||
- Найден и исправлен баг **гонки при restart**: `scripts/restart.sh` не ждал реальной готовности (healthcheck) зависимостей между стадиями перезапуска — API падал на старте, не успев подключиться к ещё не готовому SeaweedFS/Postgres/Redis. Добавлено явное ожидание `healthy`-статуса между этапами.
|
||
- Healthcheck SeaweedFS не может быть обычным HTTP-GET на S3-порт (анонимный запрос получает `403`, что ломает любой healthcheck на основе кода ответа) — используется проверка открытости TCP-порта (`nc -z`).
|
||
- Трек исследования уровня 5 не реализован.
|
||
- `scripts/reconcile_attachments.py` — рабочий, но простой инструмент (полный скан bucket через `list_objects_v2`); для production-масштаба нужна инкрементальная сверка (например, по журналу событий), не полный обход при каждом запуске.
|