18 KiB
Отчёт — лабораторная 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/получены запуском команд на локальном стенде; секреты и токены в отчёт не включены.