Files
mtusi2026lab4/REPORT.md
T
Artu-RitoandClaude Sonnet 5 38268f63f8 Лаба 4: SeaweedFS S3-хранилище и вложения (оценка 4)
Переиспользован стек 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>
2026-10-30 00:59:13 +03:00

92 lines
12 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
- Целевая оценка: 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-масштаба нужна инкрементальная сверка (например, по журналу событий), не полный обход при каждом запуске.