Files
mtusi2026lab4/REPORT.md
Ilya a97c35fc12 выполнение ЛР4 на 4
- S3: SeaweedFS 4.51 (MinIO-образы недоступны), приватный bucket,
  отдельные ограниченные ключи API, служебные порты закрыты;
  идемпотентный s3-init с проверкой приватности и прогревом записи
- вложения: потоковая загрузка PNG/JPEG, лимиты 10 MiB / 40 Мпикс,
  тип по содержимому, проверка filename, скачивание только участникам
- согласованность PG/S3: pending -> PUT -> ready, компенсация, sweeper
  с grace и dry-run; attachment_ids в сообщениях, FK по чату
- back-pressure на S3 PUT после найденного OOM SeaweedFS
- тесты student-tests, evidence, REPORT.md, DEMO.md
2026-10-28 18:06:07 +03:00

31 KiB
Raw Permalink Blame History

Отчёт — лабораторная 4

  • Автор, группа: Кошелев, БВТ2304
  • Целевая оценка: 4 (трек 5 не заявлен)
  • Commit/PR: ветка solution/bvt2304-koshelev, PR в mtusi2026/mtusi2026lab4 (main)
  • Использованные источники, библиотеки и помощь ИИ: FastAPI, uvicorn, pydantic, asyncpg, redis-py, argon2-cffi (из lab3); boto3 (S3-клиент), Pillow (проверка изображений); SeaweedFS 4.51 (документация S3 API, -s3.config identities/actions, concurrentUploadLimitMB); AWS S3 docs (PutObject, x-amz-checksum-sha256); Go runtime GOMEMLIMIT. Код перенесён из собственной lab3. При доработке, тестах и отчёте использовался ИИ-ассистент Claude (Anthropic); решения проверены и объяснимы автором.

Запуск из чистого clone

Требования: Docker Engine + Compose v2 (проверено: Docker Desktop 28.0.1, Compose 2.33.1), Python 3.9+ для тестов (проверено 3.14), make. Стенд: Apple M3, 8 CPU, 16 GiB, Docker VM 8 CPU / 7.6 GiB.

Роль Service Образ Health/readiness Volume Сеть / порт Credentials
Балансировщик lb haproxy:3.2.4-alpine monitor-uri /lb-health — edge; единственный опубликованный порт 127.0.0.1:${APP_PORT:-8080} нет
API × N api (replicas: ${API_REPLICAS:-2}) mtusi-messenger:lab4 (сборка из Dockerfile, python:3.12.8-slim-bookworm) /health/ready (PostgreSQL) нет (временный spool загрузки удаляется в конце запроса) edge + data, 8080 не публикуется secrets database_url, cache_url, s3_access_key_id, s3_secret_access_key
S3 s3 chrislusf/seaweedfs:4.51 /healthz S3 и зарегистрированный volume-сервер в топологии master s3data:/data data (internal), S3 на :9000; master/filer/volume слушают только 127.0.0.1 внутри контейнера secret seaweedfs_s3_config (identities)
Bootstrap bucket s3-init (one-shot) mtusi-messenger:lab4 exit 0 — data secrets s3_admin_* (только здесь)
Миграции migrate (one-shot) mtusi-messenger:lab4 exit 0 — data database_url
Очистка sweeper mtusi-messenger:lab4 heartbeat-файл не старше 3 интервалов — data database_url, API-ключи S3
БД (источник истины) postgres postgres:17.6-alpine3.22 pg_isready pgdata data postgres_password
Кэш сессий valkey valkey/valkey:8.1.4-alpine3.22 valkey-cli ping нет data valkey_conf

Почему SeaweedFS, а не MinIO. Образы minio/minio и quay.io/minio/minio в Docker Hub/Quay на момент работы недоступны (pull access denied / manifest not found), поэтому закрепить проверенную версию MinIO нельзя. SeaweedFS 4.51 даёт: статическую конфигурацию S3-identities с правами на конкретный bucket (ограниченные credentials API), запрет анонимного доступа по умолчанию и возможность убрать с сети все служебные HTTP-интерфейсы (-ip.bind=127.0.0.1, наружу только -s3.ip.bind=0.0.0.0).

./scripts/init-secrets.sh            # ./secrets/* (в .gitignore): пароли PG/Valkey, 2 пары S3-ключей, seaweedfs_s3.json
cp .env.example .env                 # при занятом 8080 поменяйте APP_PORT (у автора 8088)
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
#   postgres, valkey, s3 -> s3-init (bucket + проверка приватности + прогрев записи) и migrate -> api x2, sweeper -> lb
make test                                               # BASE_URL=http://localhost:8088 при другом порту
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover    ACTION_SCRIPT=scripts/stop-one.sh ; ./scripts/restore.sh
make test-student     # attachments, s3-security, upload-failover, consistency (останавливает/запускает s3), idempotency
make memory           # эксперимент с параллельными загрузками
make chaos            # из lab3: остановка каждой реплики под нагрузкой
  • Короткие цели: make up (= secrets + up -d --build --wait), make restore, make rolling-update, make sweep-dry-run, make down. Сценарий защиты — DEMO.md.
  • Bootstrap и миграции идемпотентны и выполняются при каждом up: docker compose run --rm --no-deps s3-init → «bucket already exists», migrate → «0 applied now» (evidence/bootstrap-idempotent.txt).
  • Безопасная остановка: docker compose stop или down (volumes сохраняются). Намеренное удаление учебных данных: docker compose down -v (удаляет pgdata и s3data).

Соответствие .env.example: S3_ENDPOINT=http://s3:9000 (порт S3-шлюза SeaweedFS выбран 9000 под пример), S3_REGION, S3_BUCKET → API/sweeper/s3-init; S3_ACCESS_KEY_ID_FILE, S3_SECRET_ACCESS_KEY_FILE → Docker secrets; MAX_UPLOAD_BYTES=10485760, MAX_IMAGE_PIXELS=40000000 → API. Остальные переменные — как в lab3. Дополнительно (значения по умолчанию в compose.yaml): UPLOAD_CONCURRENCY=16, DECODE_CONCURRENCY=1, S3_PUT_CONCURRENCY=4, UPLOAD_SPOOL_BYTES=1048576, ORPHAN_GRACE_SECONDS=900, SWEEP_INTERVAL_SECONDS=60.

Архитектура и решения

client ─► lb (HAProxy :8080) ─round-robin─► api-1 ┐                 ┌─► postgres: users, chats, messages, sessions,
                                └─────────► api-2 ┼── сеть data ────┤             idempotency_keys, attachments (метаданные),
              сеть edge                            │   (internal)    │             message_attachments
                                     sweeper ──────┤                 ├─► valkey: кэш сессий
                                     s3-init ──────┘                 └─► s3 (SeaweedFS :9000): приватный bucket, только байты

Из lab3 перенесено без изменений: балансировка, сессии в PostgreSQL + кэш Valkey, идемпотентность сообщений, X-Instance-Id, graceful shutdown, hooks restart/stop-one/restore/rolling-update, chaos_load.py, idempotency_test.py.

Новое в lab4:

  1. Модель данных (migrations/0003_attachments.sql). attachments(id, chat_id, owner_id, filename, content_type, size_bytes, sha256, width, height, object_key, status, …) — только метаданные. object_key = originals/<случайный 128-битный hex> назначает сервер; он не связан ни с id, ни с filename и наружу не отдаётся. filename — только отображаемое имя. message_attachments(message_id, attachment_id, chat_id, position) с составными FK (message_id, chat_id) → messages и (attachment_id, chat_id) → attachments: даже в обход API БД не позволит привязать файл другого чата. Ограничение длины текста сообщения ослаблено до ≤ 4000 (пустой текст допустим только с вложениями — проверяет API). Миграция аддитивна, старые сообщения получают attachment_ids=[].

  2. Загрузка POST /chats/{id}/attachments?filename= (app/main.py, app/images.py). Порядок: аутентификация → членство (иначе 404) → filename (1–255, без / \, NUL, управляющих и bidi-символов, не ./..; иначе 400) → Content-Type ∈ {png, jpeg} (иначе 415) → Content-Length > 10 MiB → 413 до чтения тела. Тело читается потоком в SpooledTemporaryFile (в RAM ≤ 1 MiB на загрузку, дальше — временный файл) с подсчётом размера и SHA-256; превышение лимита во время потока (chunked без Content-Length) → 413. Тип определяется по сигнатуре и должен совпасть с заявленным (иначе 415). Затем Pillow: размеры читаются из заголовка, w×h > 40 000 000 → 413 до декодирования; потом PNG verify() (CRC всех чанков) и полное декодирование (JPEG — с DCT-масштабированием 1/8, весь поток всё равно проверяется); ошибка → 415. Декодирование выполняется в пуле потоков под семафором DECODE_CONCURRENCY=1 — это единственный шаг, чья память растёт с числом пикселей.

  3. Когда честно вернуть 201. Только после того как (а) S3 подтвердил PUT, причём S3 сам сверил x-amz-checksum-sha256 с нашей суммой, и (б) в PostgreSQL зафиксирован status='ready'. Порядок записи:

    1. INSERT attachments … status='pending' (намерение; pending не видно через API — для всех запросов это 404);
    2. PUT объекта в S3 (под семафором S3_PUT_CONCURRENCY);
    3. UPDATE … SET status='ready' WHERE status='pending' RETURNING ….
  4. Что если S3 PUT прошёл, а COMMIT — нет (и другие сбои):

    Сбой Что остаётся Кто чинит
    Клиент оборвал тело / таймаут 60 с ничего (S3 не трогали, строки нет) —
    S3 недоступен при PUT компенсация: delete объекта + delete pending-строки, ответ 503 если компенсация не дошла — sweeper
    PUT прошёл, UPDATE ready упал (БД) компенсирующий delete объекта; pending-строка sweeper удалит строку (и объект, если delete не дошёл)
    Процесс API убит между шагами pending-строка (± объект) sweeper
    Объект без строки (строка удалена, delete не дошёл) orphan в S3 sweeper (сверка листинга originals/ с БД)

    Sweeper (app/sweeper.py, сервис sweeper, раз в 60 с, pg_try_advisory_lock против параллельных запусков): удаляет pending-строки и их объекты старше grace = 900 с, затем перечисляет originals/ и удаляет объекты старше grace, на которые нет строки. Grace на порядки больше максимальной длительности живой загрузки (таймаут тела 60 с + S3 таймауты 2+5 с), поэтому незавершённая, но живая загрузка не может быть удалена; ready-строки и объекты, на которые ссылается строка, не удаляются никогда. Шаги идемпотентны (сначала объект, потом строка), есть --dry-run, минимальный grace защищён (< 60 с запрещено).

  5. Скачивание GET /attachments/{id} и /content: метаданные и байты отдаются только участнику чата (JOIN с chat_members), иначе 404; без redirect, байты потоково проксируются из S3 кусками по 64 KiB (StreamingResponse), Content-Type — истинный тип, Content-Length, X-Content-Type-Options: nosniff, Cache-Control: private, no-store. variant=original по умолчанию; thumbnail/crop/optimized в lab4 → 404, неизвестное имя → 400. S3 недоступен → 503.

  6. Сообщения с attachment_ids: 0–10 уникальных UUID, по умолчанию []; text="" разрешён при ≥1 вложении. Внутри той же транзакции, что и идемпотентный ключ, проверяется, что все id существуют, ready и принадлежат этому чату; иначе 404 (ключ не фиксируется). Порядок вложений сохраняется. Отпечаток идемпотентности считается от канонического JSON после применения default, поэтому отсутствующий attachment_ids ≡ [].

  7. Readiness = только PostgreSQL. S3 критичен лишь для загрузки/скачивания файлов; если включить его в readiness, отказ S3 вывел бы из LB все реплики и остановил бы ещё и текстовые сообщения. Поэтому при недоступном S3: /health/ready 200, сообщения 201, метаданные 200, upload/content — быстрый 503 (evidence/consistency.txt).

  8. S3: приватность и минимальные права. init-secrets.sh генерирует две identity: bootstrap-admin (только для s3-init: создание bucket) и messenger-api с действиями Read/Write/List только на messenger-attachments. API этими ключами не может создать/удалить bucket, выставить публичную policy или ACL (AccessDenied). Анонимные GET/LIST → 403. Порты master 9333, filer 8888, volume 8080 изнутри сети недоступны (слушают loopback), портов на хосте у s3 нет, lb (сеть edge) до S3 не достаёт (evidence/s3-security.txt).

  9. Bootstrap (app/s3_bootstrap.py): создание bucket идемпотентно (BucketAlreadyOwnedByYou = успех), затем проверка, что анонимный доступ запрещён (иначе exit 1 и API не стартует), затем прогрев записи: put/get/delete пробного объекта health/…, пока операция не займёт < 0.5 с. Без прогрева первый PUT после рестарта SeaweedFS ждал 2.5–5 с, и публичный failover-тест с таймаутом клиента 2 с падал сразу после persistence-теста.

  10. Ограничение памяти и back-pressure: UPLOAD_CONCURRENCY=16 одновременных загрузок на реплику (остальные ждут, их тело остаётся в сокете), spool 1 MiB, DECODE_CONCURRENCY=1, S3_PUT_CONCURRENCY=4. У SeaweedFS: -s3/-filer/-volume.concurrentUploadLimitMB=128, GOMEMLIMIT=450MiB, лимит 768M. Зачем — см. эксперимент ниже (OOM S3).

  11. LB: timeout server увеличен с 10 до 30 с (это таймаут бездействия, а декодирование 40 Мпикс занимает до ~1 с; запас для медленного S3).

Транзакционные границы: pending-строка, S3 PUT и ready — три отдельных шага (распределённой транзакции между PostgreSQL и S3 нет; согласованность обеспечивает порядок записи + компенсация + sweeper). Сообщение + ключ идемпотентности + ссылки на вложения — одна транзакция PostgreSQL.

Доказательства критериев

Критерий README Команда/сценарий Наблюдаемый результат Файл
Публичный smoke make test PASS lab4 (upload 201 ready, message с attachment_ids, download bob, SHA-256, 404 eve) evidence/smoke.txt
(3) Возможности lab3 сохранены, S3 в общем стенде, метаданные в PG, байты в приватном bucket docker compose ps, make test-failover, chaos, idempotency_test.py 2 API, LB, PG, Valkey, SeaweedFS; failover/идемпотентность PASS; pgdata + s3data evidence/topology.txt, failover.txt, idempotency.txt, failover-load/*.json
(3) 201 ready после сохранения, побайтное скачивание, чужой не видит make test-attachments png+jpeg byte-identical, metadata стабильны, outsider 404 на metadata/content/upload evidence/attachments.txt
(3) Реальные PNG/JPEG ≤10 MiB, ≤40 Мпикс, MIME по содержимому, опасные filename, лимиты до неограниченного чтения make test-attachments ровно 40 000 000 px → 201; 8000×5001 → 413; заголовок 20000×20000 → 413 без декодирования; 10 MiB+1 → 413 (и с Content-Length, и chunked) evidence/attachments.txt
(3) Upload → остановка обслужившей реплики → download через другую make test-upload-failover 2 раунда: остановлены api-1, затем api-2 — каждая сразу после того, как сама приняла файл; 10/10 скачиваний через другую реплику, SHA-256 совпал evidence/upload-failover.txt, evidence/stop-one.txt
(3) Restart всего стенда с volumes make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS (тест сверяет и файл); StartedAt сменился у api, lb, sweeper, postgres, valkey, s3; volumes те же evidence/persistence.txt
(3) На API нет локального файла оригинала docker compose ps / compose.yaml у api нет volumes; после остановки загрузившей реплики файл отдаёт другая evidence/topology.txt, upload-failover.txt
(4) Слишком большой файл, повреждённое изображение, подмена MIME, чужой attachment_id, файл другого чата; ошибки не 500 make test-attachments (47 случаев) 413 / 415 (обрезанный PNG/JPEG, повреждённый IDAT, PNG как jpeg, JPEG как png, текст, GIF, SVG, пустое тело, octet-stream, multipart) / 404 (чужой чат, чужой/неизвестный id в сообщении) / 400; ни одного 500; составной FK отверг привязку через psql evidence/attachments.txt
(4) Прерывание загрузки и отказ между S3/БД без вечных объектов make test-consistency обрыв на 1.1 из 5 MiB — ни объекта, ни строки; S3 down — 503, pending не остаётся; внедрены: orphan-объект, pending+объект, pending без объекта (старше grace) и «свежие» — dry-run нашёл 2+1 и ничего не тронул, реальный проход удалил 2+1, свежие и ready целы, повтор — 0 evidence/consistency.txt
(4) Недоступность S3 make test-consistency upload 503 за 0.8 с, content 503, metadata 200, сообщения 201, ready 200; после старта S3 — файл цел evidence/consistency.txt
(4) Потоковая обработка, лимиты; ≥10 одновременных загрузок с пиком памяти student-tests/upload_memory.py см. таблицу ниже: прирост памяти API не зависит от числа параллельных загрузок evidence/memory/*.json
(4) Идемпотентный bucket bootstrap повторный s3-init и migrate «already exists», «0 applied now» evidence/bootstrap-idempotent.txt
(4) Отдельные ограниченные S3 credentials; консоль не открыта; проверка private bucket вне API make test-s3-security anonymous GET/LIST 403; API: CreateBucket/PutBucketPolicy/PutObjectAcl/DeleteBucket → AccessDenied; 9333/8888/8080 refused; host-портов нет; lb до S3 не достаёт evidence/s3-security.txt
Базовая нагрузка (регрессия lab3) tests/load.py --duration 30 --concurrency 4 471 успешных RPS, 0 ошибок, p50/p95/p99 = 7.4/13.0/32.7 мс evidence/load.json

Эксперименты и отказы

Память при параллельных загрузках

Гипотеза: при потоковом приёме (spool 1 MiB) и одном декодировании за раз пик анонимной памяти реплики не растёт с числом одновременных загрузок; если держать тело целиком в RAM, рост линейный.

Методика (student-tests/upload_memory.py): N потоков одновременно загружают через LB один и тот же PNG 9.6 MiB из случайного шума (несжимаемый, близко к лимиту); профиль «40 Мпикс» — PNG 7000×5714 RGB (117 KB файл, 120 MB после декодирования). Каждый контейнер опрашивается 4–5 раз в секунду: anon из memory.stat cgroup v2 (память процесса; memory.current включает ещё и reclaimable page cache временных файлов). API пересоздаётся перед каждым прогоном (одинаковая база ≈ 64 MiB). Контраст «тело в RAM» — тот же код с UPLOAD_SPOOL_BYTES=16 MiB (spool не сбрасывается на диск). Лимиты: api 0.5 CPU / 384M, s3 1 CPU / 768M. Один прогон на точку — демонстрация, не статистика.

Профиль N Результат Время, с API anon: прирост (api-1 / api-2), MiB S3 anon пик, MiB
поток, шум 9.6 MiB 10 10×201 2.7 +38.5 / +32.4 380
поток, шум 9.6 MiB 20 20×201 5.2 +32.1 / +37.3 422
поток, шум 9.6 MiB 40 40×201 9.2 +49.1 / +45.9 403
поток, 40 Мпикс 10 10×201 3.2 +161.8 / +163.7 325
тело в RAM, шум 10 10×201 3.9 +83.1 / +77.3 426
тело в RAM, шум 20 20×201 6.0 +137.6 / +142.5 449
тело в RAM, шум 40 40×201 9.9 +194.0 / +220.8 434

Вывод: гипотеза подтверждена. При потоковом приёме прирост ~32–49 MiB почти не меняется от 10 к 40 загрузкам (это одно декодирование 9.6 MB RGB + чтение IDAT в verify() + буферы boto3/аллокатор); при теле в RAM рост линейный (+5 MiB на каждую одновременную загрузку на реплике) и ограничен лишь UPLOAD_CONCURRENCY. Худший случай — изображение на границе 40 Мпикс: +162 MiB, но это одно декодирование (семафор), десять таких параллельно памяти не умножают. Верхняя оценка на реплику: база 64 + 16×1 MiB spool + 1 декодирование ≤ 160 MiB (RGBA 40 Мпикс) ≈ 240 MiB < 384M.

Найденный отказ: OOM SeaweedFS (до исправления)

Первая версия без S3_PUT_CONCURRENCY и лимитов SeaweedFS при 20 параллельных 10 MiB загрузках дала 16 из 20 ответов 503: memory.current S3 упирался в 512 MiB, процесс weed убивался без panic, контейнер перезапускался и при старте «re-indexed» хвосты volume-файлов (evidence/s3-oom-before-fix.txt). Потерь не было: клиенты получили 503 (не 201), компенсация/sweeper убрали pending-строки. Исправление в две стороны: API ограничивает параллельные PUT (4 на реплику, остальные ждут), SeaweedFS получил concurrentUploadLimitMB=128 и GOMEMLIMIT=450MiB (без него Go-heap доходил до 726 из 768 MiB). После: 20 и 40 параллельных — все 201, пик S3 anon 403–422 MiB, рестартов 0.

Отказы

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Остановка API-реплики, принявшей файл файл отдаёт другая 2/2 раунда, 10/10 скачиваний, SHA-256 совпал ≤ 3 с (вывод из LB); потерь нет
Публичный failover ×2 (сразу после persistence) запись ≤ 10 с 0 failed attempts, recovery 3.3 / 1.8 с данные, файл и токен сохранены
docker stop api-1 / api-2 под нагрузкой (make chaos) без ошибок 8858 и 6790 запросов, 0 ошибок, p99 96 / 149 мс, max 1.03 с ≤ 3 с; потерь и дублей нет
Restart всего стенда (restart.sh) метаданные, байты, сессия живы PASS ≈ 27 с от старта S3 до готовности API (ожидание volume-сервера + прогрев записи в s3-init); потерь нет
S3 остановлен 503 только на файлах upload 503 за 0.8 с, content 503, остальное работает сразу после start S3
Обрыв клиента посреди тела ничего не сохранено 0 объектов, 0 строк —
Внедрённые orphan/pending на обеих сторонах обнаружение и безопасная очистка dry-run: 2 pending + 1 orphan, ничего не изменено; реальный проход удалил их, свежие/ready не тронуты; повтор — 0; проход ~0.2 с на 27 объектов —
20 параллельных 10 MiB до исправления — OOM SeaweedFS, 16/20 → 503 см. выше; исправлено

Ограничения и следующие шаги

  • Выдерживается отказ одной API-реплики и кратковременная недоступность S3 (файлы — 503, остальное работает). Не выдерживаются: отказ PostgreSQL, LB, Docker-host; SeaweedFS — один узел без репликации (replication 000), потеря volume = потеря байтов.
  • Sweeper обрабатывает только незавершённые загрузки и orphan-объекты. «Missing» (ready-строка без объекта) он не ищет и ничего не чинит — скачивание такого файла даёт 503 и ошибку в логе. Полный reconciler с отчётом о missing — это трек 5.2, не заявлен. Обход листинга линейный по числу объектов (~0.2 с на десятки объектов, на миллионах нужен инкрементальный обход).
  • Вложения, загруженные, но так и не привязанные к сообщению, не удаляются: контракт не задаёт срок жизни непривязанных файлов.
  • Временный spool пишется в writable-слой контейнера и удаляется в конце запроса; при жёстком убийстве процесса файл в /tmp контейнера остаётся до пересоздания контейнера (это не оригинал и не источник истины).
  • Декодирование 40 Мпикс PNG (до 160 MiB для RGBA) выполняется по одному на реплику; при массовой загрузке таких файлов они ждут друг друга (латентность растёт, память — нет). Асинхронная обработка — lab5.
  • Повтор загрузки после неопределённого ответа может создать второе вложение (по контракту идемпотентности для загрузки нет); HAProxy не повторяет POST с большим телом.
  • SeaweedFS предупреждает, что внутренний IAM gRPC на filer без JWT; он слушает только loopback внутри контейнера и недоступен из сети, но полноценная защита (security.toml/JWT, TLS) — задача lab7.
  • 471 RPS в базовой нагрузке ниже 840 RPS из lab3 при том же профиле; прогон одиночный, на хосте одновременно работали sweeper и другие контейнеры, причину не исследовал — не делаю вывода о деградации.
  • Тестовый порт у автора 8088 (8080 занят посторонним контейнером); по умолчанию — 8080.