Files
mtusi2026lab4/REPORT.md
T

25 KiB
Raw Blame History

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