139 lines
25 KiB
Markdown
139 lines
25 KiB
Markdown
# Отчёт — лабораторная 4
|
||
|
||
- Автор, группа: Саватеев Артём, группа TODO
|
||
- Целевая оценка: **4**; трек 5 не заявлен
|
||
- Commit/PR: TODO после публикации (ветка `feature/lab4-core-logic`)
|
||
- Использованные источники, библиотеки и помощь ИИ: FastAPI, asyncpg, redis-py, aiobotocore 3.9.1 (S3-клиент), Pillow 12.3.0 (проверка изображений), SeaweedFS 4.48 (S3-сервер); документация S3 API и SeaweedFS (identities, `-s3.config`)
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Prerequisites: Docker Engine 29 / Compose v2.40, Python 3.12 + Poetry 2.2 (для собственных тестов), Python 3.9+ (публичные тесты)
|
||
|
||
| Компонент | Образ / версия |
|
||
| --- | --- |
|
||
| API, migrate, s3-bootstrap, janitor | `mtusi-messenger:lab4` из `Dockerfile` (python:3.12.12-slim-bookworm) |
|
||
| PostgreSQL | `postgres:18.2-alpine3.22` |
|
||
| Valkey | `valkey/valkey:8.1.4-alpine3.22` |
|
||
| S3 | `chrislusf/seaweedfs:4.48` |
|
||
| LB | `nginx:1.28.0-alpine3.21` |
|
||
|
||
```sh
|
||
make init # .env из .env.example + секреты в secrets/ (повторный запуск ничего не меняет)
|
||
docker compose --env-file .env config --quiet
|
||
docker compose --env-file .env up -d --build --wait
|
||
# порядок: postgres, valkey, s3 → migrate (миграции) и s3-bootstrap (bucket)
|
||
# → api ×2, janitor → nginx; --wait ждёт healthy всех сервисов
|
||
make test # публичный smoke
|
||
make install && make student-test # собственные unit + black-box тесты
|
||
make test-storage # приватность bucket, права ключей, сверка janitor
|
||
make test-failures # отказы PostgreSQL/Valkey/S3 и реплики, принявшей файл
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh && ./scripts/restore.sh
|
||
make experiment-uploads # ≥10 одновременных загрузок, пик памяти → evidence/
|
||
make test-migrations # миграции с пустого volume (отдельный compose-проект)
|
||
```
|
||
|
||
Безопасная остановка: `make down` (volumes сохраняются). Намеренное удаление учебных данных: `make destroy-data` (`down -v`: PostgreSQL и S3). Секреты: `scripts/init-secrets.sh` создаёт `secrets/` (в `.gitignore`), значения не печатает и не перезаписывает — иначе объекты bucket станут недоступны. Оператору больше ничего делать не нужно: bucket создаётся сервисом `s3-bootstrap` автоматически.
|
||
|
||
Если порт 8080 занят другим стендом (например, lab3), задайте `LB_PORT` в `.env` и `BASE_URL=http://localhost:<порт>` для тестов.
|
||
|
||
## Архитектура и решения
|
||
|
||
```
|
||
клиент → nginx (edge) → api ×2 ─┬─ backend: PostgreSQL (метаданные, источник истины), Valkey (кэш сессий)
|
||
└─ storage: SeaweedFS S3 (байты оригиналов, приватный bucket)
|
||
janitor (backend + storage): сверка S3/БД
|
||
migrate, s3-bootstrap: одноразовые, до старта API
|
||
```
|
||
|
||
**Перенесено из lab3 без изменений:** пользователи, сессии (PostgreSQL + Valkey), чаты, история, Idempotency-Key, 2 реплики за nginx, graceful shutdown, `X-Instance-Id`, скрипты отказов. **Изменено:** сообщение получило `attachment_ids` (пустой текст разрешён только с вложениями); hash идемпотентности считается без полей по умолчанию, поэтому для текстовых сообщений он совпадает с lab3. Попутно исправлен Makefile lab3: потерянная строка цели `test-expiry`.
|
||
|
||
**Слои** (как в lab3): `domain` (схемы, ошибки) → `interfaces` (абстракции `AttachmentRepository`, `ObjectStorage`) → `infrastructure` (PostgreSQL/S3 реализации, `AttachmentService`, `StorageReconciler`, `ImageInspector`) → `application` (FastAPI endpoints). Сервисы зависят только от интерфейсов, поэтому отказы S3/БД проверяются unit-тестами на фейках.
|
||
|
||
**Хранилище.** MinIO не выбран: образы `minio/minio` и `minio/mc` больше не скачиваются из Docker Hub/quay, стенд не собрался бы из чистого clone. SeaweedFS 4.48 запускается одним контейнером `weed server`:
|
||
- master/volume/filer и их веб-интерфейсы слушают только `127.0.0.1` внутри контейнера; в сеть `storage` открыт лишь S3 API `:9000`. Порты наружу не публикуются, сеть `storage` — `internal`, в неё входят только api, janitor, s3-bootstrap.
|
||
- Identities (`secrets/s3_identities.json`): `bootstrap` (Admin) — только у `s3-bootstrap`; `messenger-api` — `Read/Write/List` **только своего bucket** — у API и janitor. Identity `anonymous` нет, поэтому любой неподписанный запрос получает 403.
|
||
- `s3-bootstrap` идемпотентен: `CreateBucket` с обработкой `BucketAlreadyOwnedByYou`, затем проверяет, что анонимный запрос получает 403. Иначе завершается ошибкой, и API не стартует.
|
||
|
||
**Модель данных** (`migrations/0003_attachments.sql`): `attachments` (метаданные + `object_key` + `status` pending/ready/deleting), `message_attachments` (порядок вложений). Составные FK гарантируют на уровне БД, что владелец — участник чата, а вложение и сообщение принадлежат одному чату. Используемое вложение удалить нельзя (FK без CASCADE). Ключ объекта `originals/<128 бит random>` назначает сервер; `filename` — только отображение.
|
||
|
||
**Загрузка** `POST /chats/{id}/attachments` (сырые байты):
|
||
1. Аутентификация → членство в чате (404) → filename (400) → Content-Type (415) → Content-Length > 10 MiB (413). Всё это до чтения тела.
|
||
2. Тело читается потоком: первые 1 MiB в RAM, остальное во временный файл запроса, который удаляется сразу. Чтение обрывается на байте 10 MiB+1 (413). SHA-256 считается по ходу.
|
||
3. `ImageInspector` в пуле из `IMAGE_INSPECT_WORKERS` потоков: формат по сигнатуре (подмена MIME → 415); размеры из заголовка до распаковки (> 40 Мпикс → 413); целостность: PNG — CRC всех chunk и IEND, JPEG — декодирование libjpeg в draft-режиме 1/8 (повреждено → 415).
|
||
4. Запись: строка `pending` (COMMIT) → один `PUT` в S3 с `x-amz-checksum-sha256` (S3 сверяет байты) → `pending → ready` → **201**. 201 возвращается только когда оригинал в S3 и метаданные подтверждены. PUT + подтверждение ограничены `ATTACHMENT_STORE_TIMEOUT_SEC=30`.
|
||
|
||
**Скачивание** — только через API, без redirect: проверка участника (чужое/неизвестное/незавершённое — одинаковый 404), затем поток из S3 по 64 KiB с истинным `Content-Type`, `Content-Length`, `X-Content-Type-Options: nosniff`, `Content-Disposition` (RFC 5987). Случайный ключ и приватный bucket не заменяют ACL: ключ мог бы утечь через логи или бэкап, а доступ к файлу определяется членством в чате, которое знает только приложение.
|
||
|
||
**Согласованность S3 ↔ PostgreSQL (уровень 4).** Инвариант: *у каждого объекта под `originals/` есть строка*. Строка коммитится до PUT, а удаляется только после удаления объекта.
|
||
- Сбой после записи строки (S3 PUT упал или неизвестен, COMMIT `ready` не прошёл, таймаут, отмена задачи при остановке реплики) компенсируется сразу: `pending → deleting` → `DeleteObject` → `DELETE` строки. Строку сначала *забирают*: если UPDATE в `ready` на самом деле прошёл, claim не сработает, и объект готового вложения уцелеет.
|
||
- Если компенсация не удалась (S3/БД недоступны, процесс убит), остаётся строка `pending` или `deleting`. Её дочищает **janitor** (`src/janitor.py`, отдельный сервис, раз в 60 с): `pending` старше `ATTACHMENT_PENDING_GRACE_SEC=900` атомарно переводится в `deleting` (`FOR UPDATE SKIP LOCKED`), затем удаляется объект (идемпотентно), затем строка. Прерванная очистка `deleting` повторяется при следующем проходе.
|
||
- **Безопасность grace period:** API подтверждает только строку моложе grace (`created_at > now() - grace` по часам БД), janitor забирает только старше grace. Граничную гонку сериализует блокировка строки. Загрузка длится ≤ 30 с + проверка, что на порядки меньше 900 с.
|
||
- Второй проход janitor — сверка bucket: объекты без строки старше grace удаляются. При соблюдении инварианта их нет; проход проверяет инвариант и страхует, например, от восстановления БД из старой копии. Свежие объекты и любые `ready` не трогаются. `--dry-run` только отчитывается.
|
||
- **«S3 PUT прошёл, COMMIT нет»:** объект учтён строкой `pending`. Клиент получил 503 и id не знает. Компенсация удалит объект сразу, а если не сможет — janitor через ≤ grace + интервал.
|
||
|
||
**Readiness** = PostgreSQL + S3 (`head_bucket` с таймаутом 2 с): с lab4 вложения входят в обязательный синхронный путь. Valkey не критичен, как и раньше. При падении S3 реплика честно отвечает 503 на `/health/ready`. nginx не исключает реплики по readiness, поэтому сообщения, сессии и метаданные продолжают работать, а загрузка и скачивание отвечают быстрым 503.
|
||
|
||
**Лимиты памяти по всей цепочке:** nginx (`proxy_request_buffering off` на upload, `client_max_body_size 11m`: тело 10 MiB+1 отклоняет сама реплика с 413 по контракту), API (spool 1 MiB RAM на загрузку, проверка изображений в 1 потоке на реплику, лимит контейнера 512M), SeaweedFS (`-s3.concurrentUploadLimitMB=128`, `GOMEMLIMIT=384MiB`, лимит 512M). Последние два пункта — исправления по итогам эксперимента (см. ниже).
|
||
|
||
**Переменные `.env.example` → конфигурация:** `S3_ENDPOINT/REGION/BUCKET` → клиент aiobotocore (path-style); `S3_ACCESS_KEY_ID_FILE`/`S3_SECRET_ACCESS_KEY_FILE` → compose secrets `/run/secrets/*` у api и janitor; `S3_ADMIN_*_FILE` → только у s3-bootstrap; `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS` → лимиты контракта; `UPLOAD_SPOOL_MEMORY_BYTES`, `IMAGE_INSPECT_WORKERS` → память на загрузку; `S3_CONNECT/READ_TIMEOUT_SEC`, `S3_MAX_ATTEMPTS`, `ATTACHMENT_STORE_TIMEOUT_SEC` → ограниченное время ответа; `ATTACHMENT_PENDING_GRACE_SEC`, `JANITOR_INTERVAL_SEC` → janitor.
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||
| --- | --- | --- | --- |
|
||
| Публичный smoke | `make test` | PASS: lab4 public API scenario | `evidence/tests.txt` |
|
||
| Lab3 сохранена | `make student-test` | 187 passed, 16 skipped (явные отказы и expiry запускаются своими целями) | `evidence/tests.txt` |
|
||
| S3 в стенде, метаданные в PG, байты в приватном bucket | `compose.yaml`, `test_storage_security.py`, `test_attachments.py::test_public_api_does_not_expose_storage_details` | Объекты только в SeaweedFS (volume `s3_data`), на API нет volume. Ответ API не раскрывает ключ, bucket и адрес | `evidence/tests.txt` |
|
||
| 201 ready, побайтный download, checksum, посторонний 404 | `test_attachments.py` (PNG fixture, JPEG baseline/progressive) | SHA-256 и байты совпадают у второго участника; посторонний и неизвестный id — одинаковый 404 | `evidence/tests.txt` |
|
||
| Сообщение с `attachment_ids` | `test_message_attachments.py` | Читается участником, порядок сохранён, `text=""` с вложением → 201 | `evidence/tests.txt` |
|
||
| PNG/JPEG ≤ 10 MiB, ≤ 40 Мпикс, MIME по содержимому, опасные имена | `test_attachments.py` | Ровно 10 485 760 байт → 201, +1 → 413 от API; 8000×5000 → 201, 8000×5001 → 413 (файл < 1 MiB, лимит до распаковки); 13 опасных filename → 400 | `evidence/tests.txt` |
|
||
| Failover upload → download | `test_attachment_failover.py`, `make test-failover` ×2 | `UPLOADED BY 5a67…, DOWNLOADED FROM [da68…]`; публичный: 0 ошибок, восстановление записи 2.06 с и 1.62 с | `evidence/failures.txt`, `evidence/failover.txt` |
|
||
| Restart с volumes | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS; uptime всех 7 контейнеров сброшен | `evidence/persistence.txt` |
|
||
| **4:** слишком большой файл, повреждённое, подмена MIME, чужое id, файл другого чата, без 500 | `test_attachments.py`, `test_message_attachments.py` | 413 / 415 (6 видов повреждений, 9 видов подмены) / 404 / 404, сообщение не создаётся; каждый ответ проверен `assert_not_server_error` | `evidence/tests.txt` |
|
||
| **4:** обрыв загрузки и отказ между S3/БД | `student-tests/unit/test_unit_attachment_service.py` (8 сценариев отказа на фейках), `test_storage_consistency.py` (стенд), `test_storage_failures.py` | Во всех сценариях итог — ни объектов, ни строк. На стенде janitor удалил 2 «упавшие» загрузки и 1 сироту, свежие и `ready` сохранены. Обрыв тела прямо в реплике — 0 строк | `evidence/tests.txt`, `evidence/failures.txt` |
|
||
| **4:** RAM ограничена, ≥ 10 одновременных загрузок | `make experiment-uploads` | см. раздел «Эксперименты» | `evidence/experiment-uploads.json` |
|
||
| **4:** идемпотентный bootstrap, отдельные ограниченные ключи, консоль закрыта, private bucket вне API | `make test-storage` (`test_storage_security.py`) | 2 запуска bootstrap: «уже существует», «приватен»; API-ключ: put/get/delete своего bucket — да, `CreateBucket/DeleteBucket/PutBucketPolicy/PutBucketAcl` — AccessDenied; у API нет админ-ключей; порты 9333/8888/8080/19333/18888/18080/8181/9101 закрыты; анонимный GET объекта, списка и сервиса — 403; nginx не видит S3 | `evidence/tests.txt` |
|
||
| Миграции с нуля | `make test-migrations` | 0001–0003 применяются; 3 повторных запуска идемпотентны; API без migrate не стартует | вывод команды |
|
||
|
||
## Эксперименты и отказы
|
||
|
||
**Гипотеза:** память API на загрузку ограничена (spool 1 MiB, потоковый PUT/GET, 1 поток декодирования на реплику), поэтому пик RSS не растёт как N × размер файла.
|
||
|
||
**Методика** (`scripts/upload_experiment.py`): 2 API-реплики (1 CPU / 512M каждая), Docker Desktop VM 10 CPU / 7.7 GiB, macOS arm64. Перед каждым раундом реплики перезапускаются, затем прогрев. N загрузок стартуют по одному барьеру через nginx. Память опрашивается внутри контейнеров каждые 0.2 с (VmRSS процесса, cgroup `memory.current`), плюс VmHWM. После раунда один файл скачивается и сверяется по SHA-256. Профили: PNG 9.19 MB из шума (приём тела, spool, S3) и progressive JPEG 8000×5000 = 40 Мпикс, 4.98 MB (худший случай декодера). Один прогон на точку, 2026-10-20.
|
||
|
||
| Профиль | N | 201 | p50 / p95 / max, с | RSS до → пик, МиБ (реплика 1 / 2) | cgroup пик, МиБ |
|
||
| --- | --- | --- | --- | --- | --- |
|
||
| PNG 9.19 MB | 10 | 10/10 | 2.01 / 2.09 / 2.09 | 99 → 122 / 126 | 153 / 166 |
|
||
| PNG 9.19 MB | 20 | 20/20 | 3.46 / 3.88 / 3.89 | 99 → 124 / 126 | 215 / 216 |
|
||
| PNG 9.19 MB | 30 | 30/30 | 4.62 / 4.98 / 7.21 | 99 → 127 / 142 | 255 / 280 |
|
||
| JPEG 40 Мпикс | 10 | 10/10 | 0.96 / 1.42 / 1.42 | 99 → 334 / 333 | 338 / 338 |
|
||
| JPEG 40 Мпикс | 20 | 20/20 | 1.77 / 2.59 / 2.74 | 94 → 336 / 336 | 362 / 362 |
|
||
| JPEG 40 Мпикс | 30 | 30/30 | 2.98 / 6.64 / 6.64 | 99 → 338 / 340 | 391 / 393 |
|
||
|
||
**Выводы.** При 15 одновременных PNG на реплику (135 МиБ данных) RSS вырос лишь на 28–43 МиБ. Пик для худшего JPEG (~335 МиБ, буфер коэффициентов libjpeg, ~6 Б/пиксель) не зависит от N: декодирование сериализовано одним потоком, остальные загрузки ждут в очереди, растёт только задержка. Рост cgroup сверх RSS — page cache временных файлов spool, он вытесняемый. Ни одного OOM.
|
||
|
||
**Что эксперимент нашёл и что исправлено:**
|
||
1. Первый прогон: при N = 10 PNG соединения обрывались. В `memory.events` nginx `oom_kill 4`: с `proxy_request_buffering on` nginx складывал тела во временные файлы, и грязный page cache выходил за лимит 64M. Исправлено отключением буферизации на upload-location: тело идёт потоком в API, где память на загрузку ограничена.
|
||
2. Затем при N = 20 все ответы 503. dmesg: `Killed process (weed) anon-rss:459380kB`, SeaweedFS держал тела в Go-куче. Исправлено `-s3.concurrentUploadLimitMB=128`, `-volume.concurrentUploadLimitMB=128`, `GOMEMLIMIT=384MiB`. Сверх лимита запросы ждут. После исправлений: N = 10/20/30 — 100 % успешно.
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| Остановка реплики, принявшей файл | Download через другую, тот же SHA-256 | 10/10 скачиваний с другой реплики, байты совпадают | Без перерыва / нет |
|
||
| `stop-one.sh` под записью сообщений (×2) | Восстановление ≤ 10 с, без дублей | 0 ошибок, 130 и 129 записей, 2.06 с и 1.62 с | ≤ 2.1 с / нет |
|
||
| Restart всего стенда с volumes | Данные, файл и прежний токен целы | PASS | ≈ 30 с (SeaweedFS останавливается ~25 с) / нет |
|
||
| Остановка S3 | Upload/download 503 < 6 с, сообщения и метаданные работают, ready 503 | Так и есть. Компенсация не смогла удалить объект → строка `deleting` → janitor дочистил | Сразу после старта S3 / нет |
|
||
| Падение API между PUT и COMMIT (внедрено в БД/S3) | janitor удаляет после grace, свежие и `ready` не трогает | `unfinished 2, orphans 1` удалены; свежие пережили первый проход и удалены вторым | grace + интервал / нет |
|
||
| Обрыв тела загрузки прямо в реплике | Ни строк, ни объектов | 0 строк; API журналирует 400 «Загрузка прервана клиентом» | Мгновенно / нет |
|
||
| PostgreSQL / Valkey (из lab3) | 503 ограниченно по времени / обход кэша | 4 passed | — |
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
- **Не выдерживается:** потеря Docker-host. Единственные экземпляры PostgreSQL, SeaweedFS (один volume-сервер без репликации) и nginx — точки отказа. HA хранилищ не заявляется.
|
||
- PNG проверяется по структуре и CRC без распаковки IDAT: файл с корректными CRC, но испорченным zlib-потоком будет принят. Полное декодирование появится в lab5 у worker (статус `failed`). JPEG декодируется в draft-режиме, это проверяет весь поток данных.
|
||
- Худший случай памяти на реплику ≈ 100 МиБ база + ~240 МиБ (один progressive JPEG 40 Мпикс) + 1 МиБ × число загрузок. `IMAGE_INSPECT_WORKERS > 1` требует соразмерно поднять лимит контейнера.
|
||
- Slow-client: после отключения буферизации nginx медленная загрузка держит в API корутину (не поток) до `client_body_timeout` nginx (10 с между чтениями). Отдельного глобального лимита одновременных загрузок на реплику нет: их ограничивают пул SeaweedFS и таймауты.
|
||
- Grace period 15 мин означает, что объект упавшей загрузки может занимать место до ~16 мин. Это осознанный компромисс в пользу безопасности.
|
||
- Эксперимент — по одному прогону на точку на ноутбуке. Числа задержек не переносятся на другую машину, переносимы выводы о форме роста памяти.
|
||
- **Перед сдачей:** повторить `make test-failures` и `make test-persistence` на финальной конфигурации. Последний повтор (12:32–12:33) недействителен: стенд lab4 был остановлен извне, и порт 8080 занял стенд lab3. Подробности в `evidence/*.txt`.
|