Files
mtusi2026lab4/REPORT.md
T

18 KiB
Raw Blame History

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

  • Автор, группа: Чиняева, БВТ2301
  • Целевая оценка: 5; выбранный трек 5: Трек 1. Прямой upload (presigned PUT)
  • Commit/PR: коммит реализации f39ae06; MR !90 в mtusi2026/mtusi2026lab4 (ветка solution/BVT2301-Chinyaeva)
  • Использованные источники, библиотеки и помощь ИИ: контракт и публичные тесты репозитория; SeaweedFS 3.80 (S3 API), PostgreSQL 16.4, Redis 7.4, nginx 1.27.5, Flask 3.1, boto3 1.35.76, Pillow 11.0.0. ИИ использован как помощник при написании кода, тестов и текста; все команды и результаты ниже воспроизведены локально.

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

Требования: Docker Desktop/Engine с Compose v2, Python 3.9+ для тестов на хосте, свободные порты 8080 (API через LB) и 9000 (S3 API для presigned upload). Версии образов закреплены в compose.yaml: postgres:16.4-alpine, redis:7.4.0-alpine, chrislusf/seaweedfs:3.80, nginx:1.27.5-alpine.

git clone <fork-url> mtusi2026lab4-Chinyaeva
cd mtusi2026lab4-Chinyaeva
cp .env.example .env
# Замените все change-me значения в .env. Секреты в Git не попадают.
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# Дождитесь status=healthy у api и seaweedfs:
docker compose --env-file .env ps
curl -fsS http://localhost:8080/health/ready
python tests/smoke.py --base-url http://localhost:8080

Остановка без удаления данных:

docker compose --env-file .env down

Намеренное удаление только учебных данных (необратимо):

docker compose --env-file .env down -v

Секреты создаются локально в .env (файл в .gitignore). В репозитории нет паролей, ключей, токенов и подписанных URL. S3 credentials генерируются оператором; API получает ограниченную identity, а административная identity используется только одноразовым сервисом s3-init.

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

клиент ── HTTP :8080 ── nginx LB ── API-1 ─┐
                                  API-2 ─┤── PostgreSQL (метаданные)
                                         ├── Redis (сессии)
                                         └── SeaweedFS S3 (байты, private bucket)
клиент ── presigned PUT :9000 ─────────────┘  (только трек 1, optional)
  • Источник истины: PostgreSQL для пользователей, чатов, сообщений и метаданных вложений; Redis — только активные сессии; S3 — только байты. Локального постоянного каталога с оригиналами у API нет: временный файл загрузки удаляется в finally.
  • LB: nginx 1.27.5 с resolver 127.0.0.11 и server api:8080 resolve. Он видит все реплики Compose-сервиса api, пассивно исключает недоступную реплику и повторяет только безопасные ошибки соединения/502/504.
  • Реплики: две и более, общий PostgreSQL и Redis, X-Instance-Id в каждом ответе. Масштабирование: API_REPLICAS=3 docker compose ... up -d --scale api=3.
  • S3: SeaweedFS 3.80, master/volume/filer/S3 в одном контейнере. Bucket messenger-attachments создаётся идемпотентным s3-init; bucket приватный. API использует identity с Read/Write/List, без Admin; s3-init — с Admin. Порт S3 опубликован только для presigned PUT; master/filer UI (9333/8888) не публикуются.
  • Согласованность: proxy upload сначала пишет объект в S3, затем строку в PostgreSQL. Если COMMIT не удался, объект удаляется компенсацией; если процесс упал между шагами, объект остаётся orphan и удаляется reconciler'ом после grace period. Presigned upload создаёт pending-строку, а complete проверяет владельца, размер и SHA-256 и только затем переводит в ready.
  • Совместимость: обязательный контракт contracts/openapi.json не изменён. Новые endpoint'ы описаны в contracts/extensions.openapi.json и contracts/extensions.md; proxy endpoint остаётся обязательным fallback.

Переменные .env

DATABASE_URL, CACHE_URL, S3_ENDPOINT (внутренний), S3_PUBLIC_ENDPOINT (для подписи), S3_BUCKET, S3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEY (ограниченная identity), S3_ADMIN_* (только s3-init), MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS, MAX_DECODE_CONCURRENCY, PRESIGN_TTL_SECONDS, PRESIGN_GRACE_SECONDS, ORPHAN_GRACE_SECONDS. Все они проброшены в compose.yaml; *_FILE-варианты поддерживаются в app/config.py.

Обработка вложений и лимиты

  • Принимаются только image/png и image/jpeg; MIME сверяется с реальным форматом, а не только с заголовком. Несовпадение/повреждение — 415.
  • Тело читается чанками по 64 KiB во временный файл; лимит 10 485 760 байт проверяется и по Content-Length, и в потоке. Превышение — 413.
  • Image.open сначала проверяет размеры; width * height > 40 000 000 — 413 до полного декодирования. Полный verify()/load() ограничен семафором MAX_DECODE_CONCURRENCY (по умолчанию 1 на реплику).
  • filename — только display-метаданные: запрещены /, \, NUL, control characters, ./..; object key — chats/<chat_id>/<attachment_uuid>.
  • Скачивание идёт потоком через API с Content-Type из метаданных; redirect на S3 нет. Посторонний участник получает 404 и для метаданных, и для bytes.
  • Сообщение с attachment_ids проверяет, что каждое вложение существует, принадлежит этому чату и имеет status=ready; чужой чат/неизвестный id — 404, неготовое — 409. Пустой text разрешён только при наличии вложений.

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke python tests/smoke.py --base-url http://localhost:8080 PASS: lab4 public API scenario evidence/smoke.txt
Структура/контракт не сломаны python scripts/check_contract.py PASS: offline skeleton structure... evidence/check.txt
S3 в общем стенде, метаданные в PG, байты в private bucket docker compose ps; private_bucket.py SeaweedFS healthy; anonymous GET 403; API identity не может create/delete bucket evidence/compose-ps.txt, evidence/private-bucket.txt
POST вложения → 201 ready; оригинал побайтно; message с attachment_ids tests/smoke.py, presigned_flow.py SHA-256 и Content-Type совпадают; участник чата читает, посторонний — 404 evidence/smoke.txt, evidence/presigned-flow.txt
PNG/JPEG ≤10 MiB и ≤40 млн пикселей; MIME по содержимому; опасные filename student-tests/attachments_negative.py 413/415/400 на все негативные случаи, без 500 evidence/attachments-negative.txt
Upload → остановка обслужившей реплики → download через другую tests/resilience.py --mode failover --action-script scripts/stop-one.cmd 2 реплики до отказа; 89 успешных записей; recovery 3.667 s; данные и сессия сохранены evidence/failover.txt
Restart с volumes сохраняет метаданные и оригинал tests/resilience.py --mode persistence --action-script scripts/restart.cmd PASS; attachment скачан после restart evidence/persistence.txt
Уровень 4: тесты слишком большого файла, повреждения, MIME, чужого id, другого чата attachments_negative.py все сценарии PASS evidence/attachments-negative.txt
Уровень 4: компенсация/сверка/очистка с grace period student-tests/reconcile_orphans.py dry-run видит orphan; свежий объект не удаляется; --apply удаляет; stale pending удаляется evidence/reconcile.txt
Уровень 4: ≥10 одновременных загрузок, пик RAM student-tests/upload_memory.py --workers 10 10/10 успешно; рост ~22.5 MiB на реплику при файле 4.43 MB evidence/upload-memory.json, evidence/upload-memory.txt
Уровень 4: идемпотентный bootstrap, отдельные credentials, закрытая admin-консоль private_bucket.py; s3-init bucket создаётся повторно; API identity без Admin; опубликован только S3 API evidence/private-bucket.txt, evidence/compose-ps.txt
Трек 1: presigned upload, короткая подпись, unique key, ownership, size/checksum, incomplete student-tests/presigned_flow.py 201 presign, 200 PUT, 200 complete; wrong checksum/size 400; foreign complete 404; incomplete 409 evidence/presigned-flow.txt
Трек 1: сравнение трафика/RAM API на ≥2 размерах student-tests/transfer_compare.py proxy ≈ 2× file bytes через API; direct ≈ 1× (только verification read); RAM не растёт линейно evidence/transfer-compare.json, evidence/transfer-compare.txt
Общая репликация/идемпотентность lab3 сохранены instance_spread.py, idempotency_race.py ≥2 реплики; 20/20 replay → один Message evidence/instance-spread.txt, evidence/idempotency-race.txt

Эксперименты

1. 10 одновременных proxy-загрузок

Команда:

python student-tests/upload_memory.py --base-url http://localhost:8080 \
    --workers 10 --output evidence/upload-memory.json

Файл: синтетический PNG 1400×1000, 4 431 995 байт, 10 параллельных загрузок. API-контейнеры ограничены 512 MiB. Результат:

{"workers":10,"file_bytes":4431995,"elapsed_seconds":1.697,
 "baseline_mib":{"mtusi-lab4-api-1":83.17,"mtusi-lab4-api-2":85.38},
 "peak_mib":{"mtusi-lab4-api-1":105.7,"mtusi-lab4-api-2":107.9},
 "peak_growth_mib":{"mtusi-lab4-api-1":22.53,"mtusi-lab4-api-2":22.52},
 "successful_uploads":10}

Пик не растёт как 10×размер файла: тело на диске, декодирование ограничено семафором, поэтому рост ~22 MiB на реплику. Это измерение одного хоста; оно не доказывает отсутствие OOM при произвольном размере, но подтверждает заявленную границу для 10 MiB и 40 млн пикселей.

2. Proxy vs presigned direct (трек 1)

Команда:

python student-tests/transfer_compare.py --base-url http://localhost:8080 \
    --output evidence/transfer-compare.json

Измерялись суммарные RX+TX байты API-контейнеров через /proc/net/dev и пик памяти через docker stats. Результат:

Размер файла Proxy: API network Direct: API network Proxy: client→API Direct: client→S3
552 409 B 1 120 316 B 564 368 B 552 409 B 552 409 B
4 424 547 B 8 888 758 B 4 446 591 B 4 424 547 B 4 424 547 B

Proxy проводит тело через API дважды (вход от клиента и выход в S3); direct освобождает публичный ingress API, но complete один раз читает объект из S3 для проверки SHA-256. Поэтому direct ≈ 1× file bytes, proxy ≈ 2×. RAM API при direct не растёт: объект читается потоком, без буферизации всего файла (api_memory_growth_mib=0.0 в обоих размерах). Это честная цена проверки целостности; без неё direct был бы ещё дешевле, но weaker guarantee.

3. Нагрузка сообщений (регрессия lab3)

python tests/load.py --duration 30 --concurrency 4 --output evidence/load.json

30.07 s, 4 closed-loop воркера, 6 789 успешных запросов, 0 ошибок, 225.78 successful RPS, p50 14.8 ms, p95 33.8 ms, p99 66.7 ms. Это не пропускная способность production: closed-loop и один Docker-host.

Отказы

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Остановка одной API-реплики (stop-one.cmd) nginx исключает её, записи идут на вторую; сессия жива 2 реплики до отказа, 89 успешных записей, 3 неуверенных retry, first_recovery_seconds=3.667 ~3.7 s; подтверждённые сообщения и сессия сохранены
docker compose restart (PostgreSQL, Redis, SeaweedFS, API, LB) volumes сохраняют данные; API снова ready persistence PASS; attachment скачан после restart данные не потеряны; API поднялся после прогрева SeaweedFS
S3 недоступен /health/ready = 503, API не принимает новые вложения при старте API health был 503 до готовности S3; после готовности 200 зависит от S3; metadata не теряется
Обрыв между S3 PUT и INSERT объект не должен остаться навсегда proxy-компенсация удаляет объект; reconciler удаляет orphan после grace period потерян только незавершённый объект; метаданных нет
Незавершённый presigned upload pending не должен жить вечно reconciler с --pending-grace-seconds 0 удаляет строку и объект; повторный GET = 404 потерян только незавершённый upload
Чужой/неизвестный attachment_id 404, не 500 negative suite PASS нет
Слишком большой/битый файл, MIME spoof 413/415, не 500 negative suite PASS нет

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

  • Один Docker-host не даёт отказоустойчивости к потере host; nginx, PostgreSQL, Redis и SeaweedFS остаются single points of failure в учебном стенде.
  • complete читает объект из S3 для проверки SHA-256. Это осознанный компромисс: direct upload экономит публичный ingress API, но не убирает verification egress. В production можно использовать S3 checksum API или доверенный client checksum с отдельной моделью угроз.
  • reconcile — операторский инструмент, не фоновый демон. В lab5 его можно запускать по cron/worker с метриками; сейчас он запускается вручную и поддерживает dry-run/повторный apply.
  • Presigned URL публикует S3 API на localhost:9000; в другом окружении S3_PUBLIC_ENDPOINT нужно заменить на реальный публичный адрес. Bucket остаётся приватным, но сетевой доступ к S3 API должен быть ограничен firewall'ом/прокси в production.
  • Лимит 40 млн пикселей и 10 MiB — контрактные; при их увеличении нужно пересмотреть MAX_DECODE_CONCURRENCY и memory limit API.
  • Публичные тесты не заменяют защиту: сценарии ниже проверены вручную и студенческими тестами, но оценка выставляется преподавателем.

Источники и ИИ

  • contracts/openapi.json, contracts/README.md, tests/README.md — контракт и публичные проверки.
  • SeaweedFS S3 configuration and presigned URLs; PostgreSQL deferrable constraints; boto3 generate_presigned_url; Pillow decompression limits.
  • ИИ-помощник использован для генерации черновиков кода/тестов и текста отчёта. Все результаты в evidence/ получены запуском команд на локальном стенде; секреты и токены в отчёт не включены.