Использованные источники, библиотеки и помощь ИИ: FastAPI, SQLAlchemy 2, Alembic, boto3, Pillow, SeaweedFS (S3-совместимое хранилище), argon2-cffi. ИИ-ассистент использовался для генерации кода и текста отчёта; все команды и результаты воспроизводились локально.
Запуск из чистого clone
Prerequisites: Docker Engine 24+, Docker Compose v2, Python 3.12 (для тестов), Git Bash/WSL на Windows (для .sh-хуков).
Источник истины: PostgreSQL для метаданных, SeaweedFS для байтов. API-реплики stateless — любая реплика читает файл из S3.
Транзакционная граница: POST /attachments сначала кладёт объект в S3, затем пишет метаданные в БД. При ошибке COMMIT — компенсация delete_object (best-effort). Обратный порядок (сначала БД, потом S3) дал бы «висячие» метаданные без байтов, что хуже для чтения.
Идемпотентность: Idempotency-Key для сообщений (lab3) сохранён; attachment_ids входит в хэш тела, поэтому повтор с другим набором вложений даёт 409.
Лимиты: 10 MiB на файл, 40 млн пикселей, MIME по magic bytes, filename не используется как путь/ключ S3.
Приватность bucket: SeaweedFS S3-шлюз по умолчанию не выдаёт публичный доступ; API использует отдельные credentials (в учебном стенде — учётные данные S3-шлюза, в production — отдельный IAM-пользователь с s3:GetObject/PutObject/DeleteObject на bucket).
Что перенесено из lab3: аутентификация (Basic → Bearer), сессии, чаты, сообщения, keyset-пагинация, идемпотентность, health, X-Request-Id/X-Instance-Id.
Что изменено: добавлены attachments, message_attachments, поле attachment_ids в Message, роутер attachments, S3-клиент, bootstrap bucket, сервис s3 в compose.
Соответствие .env.example: S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_ACCESS_KEY_ID_FILE, S3_SECRET_ACCESS_KEY_FILE, MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS, UPLOAD_CHUNK_SIZE — читаются в app/config.py. S3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEY — только для локального стенда SeaweedFS.
Доказательства критериев
Критерий README
Команда/сценарий
Наблюдаемый результат
Файл доказательства
Публичный smoke
make test
PASS: lab4 public API scenario
evidence/smoke.txt
S3 в общем стенде, метаданные в PG, байты в приватном bucket
Upload → остановка реплики → download через другую
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
PASS: failover preserved confirmed data
evidence/failover.txt
Restart с сохранением volumes
make test-persistence ACTION_SCRIPT=scripts/restart.sh
PASS: persistence preserved
evidence/persistence.txt
Уровень 4: негативные тесты
python3 tests/test_attachments.py
все PASS
evidence/attachments-all.txt
Уровень 4: компенсация при сбое S3/БД
код app/routers/attachments.py (try/except + delete_object)
orphan не остаётся
evidence/compensation.md
Уровень 4: ≥10 одновременных загрузок, пик RAM
test_concurrent_uploads_memory + docker stats
10/10 успешны, RSS API < 200 MiB
evidence/memory.txt
Уровень 4: идемпотентный bootstrap bucket
docker compose up s3-init дважды
второй запуск: "bucket already exists"
evidence/bootstrap.txt
Уровень 4: приватный bucket вне API
curl http://localhost:8333/messenger-attachments/<key> без подписи
403 AccessDenied
evidence/private-bucket.txt
Эксперименты и отказы
Эксперимент 1: одновременные загрузки и память.
Гипотеза: потоковая валидация с жёстким лимитом 10 MiB не даёт неограниченного роста RAM.
Профиль: 10 параллельных POST /attachments с fixture 111817 байт, 1 API-реплика, docker stats каждые 0.5 с.
Результат: 10/10 успешны, пик RSS API ≈ 120 MiB (базовый ≈ 80 MiB), пик не растёт линейно с числом загрузок.
Ограничение: файл мал; для больших файлов лимит 10 MiB гарантирует верхнюю границу памяти на запрос.
Эксперимент 2: отказ S3.
Воздействие: docker compose stop s3.
Ожидание: POST /attachments → 503 unavailable; GET /attachments/{id}/content → 503; /health/ready остаётся 200 (S3 не критичен для синхронного пути чтения метаданных).
Наблюдение: 503 в обоих случаях, метаданные не создаются, orphan в S3 не появляется.
Эксперимент 3: failover API.
make test-failover ACTION_SCRIPT=scripts/stop-one.sh — PASS, подтверждённые сообщения и вложения сохранены, дублей нет.
Учебные упрощения: учётные данные S3-шлюза SeaweedFS используются API (в production — отдельный IAM-пользователь); нет фонового worker (lab4 синхронный); нет rate limiting.
Что подтверждено: базовый upload/download, лимиты, приватность bucket, компенсация при сбое COMMIT, failover и persistence.
Что остаётся гипотезой: поведение при массовых параллельных загрузках больших файлов (нужен отдельный нагрузочный сценарий с k6/Locust).
# Отчёт — лабораторная 4
- Автор, группа: Бушков Евгений, БВТ2301
- Целевая оценка: **4** (трек 5 не заявляется)
- Commit/PR: ЛР4 — БВТ2301— Бушков — на 4
- Использованные источники, библиотеки и помощь ИИ: FastAPI, SQLAlchemy 2, Alembic, boto3, Pillow, SeaweedFS (S3-совместимое хранилище), argon2-cffi. ИИ-ассистент использовался для генерации кода и текста отчёта; все команды и результаты воспроизводились локально.
## Запуск из чистого clone
Prerequisites: Docker Engine 24+, Docker Compose v2, Python 3.12 (для тестов), Git Bash/WSL на Windows (для `.sh`-хуков).
```sh
git clone <repo> && cd <repo>
cp .env.example .env
# Секреты для локального стенда (не коммитить):
mkdir -p secrets
printf 'postgresql+psycopg://messenger:messenger@postgres:5432/messenger' > secrets/database_url
printf 'redis://redis:6379/0' > secrets/cache_url
printf 'seaweedfs' > secrets/s3_access_key_id
printf 'seaweedfs-local-only' > secrets/s3_secret_access_key
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# Дождаться /health/ready:
until curl -fsS http://localhost:8080/health/ready; do sleep 1; done
make test
python3 tests/test_attachments.py --base-url http://localhost:8080
```
Остановка: `docker compose --env-file .env down` (volumes сохраняются).
Намеренное удаление учебных данных: `docker compose --env-file .env down -v` (удаляет `pgdata` и `s3data`).
## Архитектура и решения
```
Клиент → nginx (LB, :8080) → api-1 / api-2 (FastAPI)
├── PostgreSQL (метаданные: users, chats, messages, attachments, message_attachments, idempotency_keys)
├── Redis (кэш сессий, опционально)
└── SeaweedFS (приватный bucket messenger-attachments, байты)
```
- **Источник истины**: PostgreSQL для метаданных, SeaweedFS для байтов. API-реплики stateless — любая реплика читает файл из S3.
- **Транзакционная граница**: `POST /attachments` сначала кладёт объект в S3, затем пишет метаданные в БД. При ошибке COMMIT — компенсация `delete_object` (best-effort). Обратный порядок (сначала БД, потом S3) дал бы «висячие» метаданные без байтов, что хуже для чтения.
- **Идемпотентность**: `Idempotency-Key` для сообщений (lab3) сохранён; `attachment_ids` входит в хэш тела, поэтому повтор с другим набором вложений даёт 409.
- **Лимиты**: 10 MiB на файл, 40 млн пикселей, MIME по magic bytes, `filename` не используется как путь/ключ S3.
- **Приватность bucket**: SeaweedFS S3-шлюз по умолчанию не выдаёт публичный доступ; API использует отдельные credentials (в учебном стенде — учётные данные S3-шлюза, в production — отдельный IAM-пользователь с `s3:GetObject/PutObject/DeleteObject` на bucket).
- **Что перенесено из lab3**: аутентификация (Basic → Bearer), сессии, чаты, сообщения, keyset-пагинация, идемпотентность, health, X-Request-Id/X-Instance-Id.
- **Что изменено**: добавлены `attachments`, `message_attachments`, поле `attachment_ids` в `Message`, роутер `attachments`, S3-клиент, bootstrap bucket, сервис `s3` в compose.
Соответствие `.env.example`: `S3_ENDPOINT`, `S3_REGION`, `S3_BUCKET`, `S3_ACCESS_KEY_ID_FILE`, `S3_SECRET_ACCESS_KEY_FILE`, `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS`, `UPLOAD_CHUNK_SIZE` — читаются в `app/config.py`. `S3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEY` — только для локального стенда SeaweedFS.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | `make test` | PASS: lab4 public API scenario | `evidence/smoke.txt` |
| S3 в общем стенде, метаданные в PG, байты в приватном bucket | `docker compose ps`; `docker compose exec s3 wget -qO- http://127.0.0.1:8333/` | сервис `s3` healthy; объекты в bucket | `evidence/compose-ps.txt` |
| POST вложения → 201 ready, оригинал скачивается побайтно | `python3 tests/test_attachments.py::AttachmentTests::test_upload_and_download_roundtrip` | 201, sha256 совпадает | `evidence/attachments-roundtrip.txt` |
| Message с attachment_ids читается участниками | `test_message_with_attachment` | 201, `attachment_ids` в ответе | `evidence/attachments-message.txt` |
| Посторонний получает 404 | `test_outsider_cannot_read` | 404 для metadata и content | `evidence/attachments-outsider.txt` |
| PNG/JPEG ≤10 MiB, ≤40 млн пикселей, MIME по содержимому | `test_oversized_rejected`, `test_mime_spoof_rejected`, `test_corrupted_image_rejected` | 413 / 415 | `evidence/attachments-limits.txt` |
| Опасные filename отклоняются | `test_dangerous_filename_rejected` | 400 | `evidence/attachments-filename.txt` |
| Upload → остановка реплики → download через другую | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | PASS: failover preserved confirmed data | `evidence/failover.txt` |
| Restart с сохранением volumes | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS: persistence preserved | `evidence/persistence.txt` |
| Уровень 4: негативные тесты | `python3 tests/test_attachments.py` | все PASS | `evidence/attachments-all.txt` |
| Уровень 4: компенсация при сбое S3/БД | код `app/routers/attachments.py` (try/except + `delete_object`) | orphan не остаётся | `evidence/compensation.md` |
| Уровень 4: ≥10 одновременных загрузок, пик RAM | `test_concurrent_uploads_memory` + `docker stats` | 10/10 успешны, RSS API < 200 MiB | `evidence/memory.txt` |
| Уровень 4: идемпотентный bootstrap bucket | `docker compose up s3-init` дважды | второй запуск: "bucket already exists" | `evidence/bootstrap.txt` |
| Уровень 4: приватный bucket вне API | `curl http://localhost:8333/messenger-attachments/<key>` без подписи | 403 AccessDenied | `evidence/private-bucket.txt` |
## Эксперименты и отказы
**Эксперимент 1: одновременные загрузки и память.**
- Гипотеза: потоковая валидация с жёстким лимитом 10 MiB не даёт неограниченного роста RAM.
- Профиль: 10 параллельных POST `/attachments` с fixture 111817 байт, 1 API-реплика, `docker stats` каждые 0.5 с.
- Результат: 10/10 успешны, пик RSS API ≈ 120 MiB (базовый ≈ 80 MiB), пик не растёт линейно с числом загрузок.
- Ограничение: файл мал; для больших файлов лимит 10 MiB гарантирует верхнюю границу памяти на запрос.
**Эксперимент 2: отказ S3.**
- Воздействие: `docker compose stop s3`.
- Ожидание: `POST /attachments` → 503 `unavailable`; `GET /attachments/{id}/content` → 503; `/health/ready` остаётся 200 (S3 не критичен для синхронного пути чтения метаданных).
- Наблюдение: 503 в обоих случаях, метаданные не создаются, orphan в S3 не появляется.
**Эксперимент 3: failover API.**
- `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` — PASS, подтверждённые сообщения и вложения сохранены, дублей нет.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| `stop s3` | 503 на upload/download | 503, метаданные не создаются | n/a, потерь нет |
| `stop api-1` | запись через api-2 | PASS failover | < 10 с, потерь нет |
| `restart.sh` (postgres + s3 + api) | данные и сессии сохранены | PASS persistence | ~15 с, потерь нет |
| `stop postgres` | 503 на `/health/ready` | 503 `unavailable` | n/a |
## Ограничения и следующие шаги
- **Не реализовано**: presigned upload (трек 1), reconciler orphan/missing (трек 2), thumbnail/crop/optimized (lab5), HTTPS/mTLS (lab7).
- **Учебные упрощения**: учётные данные S3-шлюза SeaweedFS используются API (в production — отдельный IAM-пользователь); нет фонового worker (lab4 синхронный); нет rate limiting.
- **Что подтверждено**: базовый upload/download, лимиты, приватность bucket, компенсация при сбое COMMIT, failover и persistence.
- **Что остаётся гипотезой**: поведение при массовых параллельных загрузках больших файлов (нужен отдельный нагрузочный сценарий с k6/Locust).
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Отчёт — лабораторная 4
Запуск из чистого clone
Prerequisites: Docker Engine 24+, Docker Compose v2, Python 3.12 (для тестов), Git Bash/WSL на Windows (для
.sh-хуков).Остановка:
docker compose --env-file .env down(volumes сохраняются).Намеренное удаление учебных данных:
docker compose --env-file .env down -v(удаляетpgdataиs3data).Архитектура и решения
POST /attachmentsсначала кладёт объект в S3, затем пишет метаданные в БД. При ошибке COMMIT — компенсацияdelete_object(best-effort). Обратный порядок (сначала БД, потом S3) дал бы «висячие» метаданные без байтов, что хуже для чтения.Idempotency-Keyдля сообщений (lab3) сохранён;attachment_idsвходит в хэш тела, поэтому повтор с другим набором вложений даёт 409.filenameне используется как путь/ключ S3.s3:GetObject/PutObject/DeleteObjectна bucket).attachments,message_attachments, полеattachment_idsвMessage, роутерattachments, S3-клиент, bootstrap bucket, сервисs3в compose.Соответствие
.env.example:S3_ENDPOINT,S3_REGION,S3_BUCKET,S3_ACCESS_KEY_ID_FILE,S3_SECRET_ACCESS_KEY_FILE,MAX_UPLOAD_BYTES,MAX_IMAGE_PIXELS,UPLOAD_CHUNK_SIZE— читаются вapp/config.py.S3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEY— только для локального стенда SeaweedFS.Доказательства критериев
make testevidence/smoke.txtdocker compose ps;docker compose exec s3 wget -qO- http://127.0.0.1:8333/s3healthy; объекты в bucketevidence/compose-ps.txtpython3 tests/test_attachments.py::AttachmentTests::test_upload_and_download_roundtripevidence/attachments-roundtrip.txttest_message_with_attachmentattachment_idsв ответеevidence/attachments-message.txttest_outsider_cannot_readevidence/attachments-outsider.txttest_oversized_rejected,test_mime_spoof_rejected,test_corrupted_image_rejectedevidence/attachments-limits.txttest_dangerous_filename_rejectedevidence/attachments-filename.txtmake test-failover ACTION_SCRIPT=scripts/stop-one.shevidence/failover.txtmake test-persistence ACTION_SCRIPT=scripts/restart.shevidence/persistence.txtpython3 tests/test_attachments.pyevidence/attachments-all.txtapp/routers/attachments.py(try/except +delete_object)evidence/compensation.mdtest_concurrent_uploads_memory+docker statsevidence/memory.txtdocker compose up s3-initдваждыevidence/bootstrap.txtcurl http://localhost:8333/messenger-attachments/<key>без подписиevidence/private-bucket.txtЭксперименты и отказы
Эксперимент 1: одновременные загрузки и память.
/attachmentsс fixture 111817 байт, 1 API-реплика,docker statsкаждые 0.5 с.Эксперимент 2: отказ S3.
docker compose stop s3.POST /attachments→ 503unavailable;GET /attachments/{id}/content→ 503;/health/readyостаётся 200 (S3 не критичен для синхронного пути чтения метаданных).Эксперимент 3: failover API.
make test-failover ACTION_SCRIPT=scripts/stop-one.sh— PASS, подтверждённые сообщения и вложения сохранены, дублей нет.stop s3stop api-1restart.sh(postgres + s3 + api)stop postgres/health/readyunavailableОграничения и следующие шаги
Принято. Закрываю МР.
Pull request closed