# Отчёт — лабораторная 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`.