Files
mtusi2026lab4/REPORT.md
T
2026-11-05 19:36:11 +03:00

14 KiB
Raw Blame History

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

  • Автор, группа: Нурлыгаянова Екатерина, БПИ2302.
  • Целевая оценка: 5, трек 1 — прямой upload.
  • Commit/PR: после публикации; проверки выполнялись на рабочем дереве.
  • Источники: README задания и семантика contracts/README.md. Библиотеки: Echo, pgx, go-redis, minio-go, google/uuid; миграции goose. Помощь ИИ: Claude Code — исходная реализация, Codex — прямой upload, проверки и оформление отчёта.

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

Нужны Docker Compose и Python 3.9+. Образы закреплены: PostgreSQL 17.6, Valkey 8.1.3, SeaweedFS 4.00, HAProxy 3.2.9; Go 1.26 используется при сборке приложения.

cp .env.example .env
sh scripts/init-secrets.sh
docker compose --env-file .env up -d --build --wait
make test BASE_URL=http://localhost:8080

Миграции и подготовку приватного bucket выполняют одноразовые сервисы migrate и s3-init. Повторная подготовка не удаляет данные. Пароли и ключи создаются локально в secrets/, значения в отчёт не включены.

Порт API задаётся через API_PUBLISH_PORT; на проверявшемся стенде использовался 18080, по умолчанию — 8080. Порты PostgreSQL и Valkey задаются через POSTGRES_PORT и VALKEY_PORT. Для прямого PUT открыт только S3-порт шлюза 127.0.0.1:19090; подписываемый адрес задаёт S3_PUBLIC_ENDPOINT.

# Проверки на уже запущенном стенде; для :18080 замените BASE_URL.
make check
python3 -m venv .venv
.venv/bin/pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python
BASE_URL=http://localhost:8080 sh scripts/level3-evidence.sh
BASE_URL=http://localhost:8080 sh scripts/level4-evidence.sh
python3 student-tests/direct_upload.py --base-url http://localhost:8080
(cd app && go test -count=1 -race ./...)

Скрипты уровней 3–4 временно останавливают сервисы и возвращают их. Для дополнительного замера JPEG 40 Мп нужен .venv/bin/pip install pillow. Вернуть остановленные сервисы можно через docker compose up -d --wait.

Безопасная остановка: docker compose stop. Остановка с удалением контейнеров и сохранением томов: docker compose down. Намеренное удаление учебных данных: docker compose down -v.

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

Клиент → HAProxy → две реплики Go API → PostgreSQL, Valkey и приватный S3. PostgreSQL хранит пользователей, чаты, сообщения, метаданные вложений и ключи идемпотентности; Valkey — сессии; SeaweedFS — байты файлов. Из lab3 сохранены авторизация, балансировка, общие данные и идемпотентная отправка сообщений. Добавлены вложения, связи с сообщениями, S3 и очиститель.

Обязательный proxy POST /api/v1/chats/{chat_id}/attachments принимает сырые PNG/JPEG. Проверяются доступ, filename, MIME, размер до 10 МиБ и число пикселей до 40 млн. Тело поступает потоком во временный файл; сначала сохраняется объект S3, затем метаданные. 201 ready означает сохранение обеих частей. Download авторизован и возвращает исходные байты через API.

При ошибке БД выполняется безопасная компенсация. Объекты без метаданных удаляет отдельный janitor после grace period: по умолчанию 3600 с, минимум 300 с. Ошибка проверки БД не считается отсутствием строки. API и очиститель используют разные ограниченные S3 credentials; служебные интерфейсы SeaweedFS из общей сети закрыты.

Прямой upload, трек 1:

  1. POST /api/v1/chats/{chat_id}/attachments/direct/init с Bearer и JSON {"filename":"a.png","content_type":"image/png","size_bytes":1234,"sha256":"<64 hex>"} возвращает url, headers, token, expires_in: 60.
  2. Клиент отправляет файл методом PUT непосредственно в S3 с полученными заголовками. Content-Length включён в подпись и должен совпадать с заявленным размером.
  3. POST /api/v1/chats/{chat_id}/attachments/direct/complete, JSON {"token":"..."}, проверяет владельца, чат, фактический размер, SHA-256 и корректность изображения. После этого возвращается 201 Attachment.

Временный ключ — случайный UUID. HMAC-ticket связан с владельцем и чатом, действует 120 с и проверяется любой репликой. Готовая копия получает другой ключ: повторный PUT по старой ссылке её не меняет. Повторный complete возвращает прежнее вложение. Заброшенные временные объекты остаются без строки в БД и удаляются janitor; используется одиночный PUT, multipart-сессий нет.

MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS и MAX_CONCURRENT_UPLOADS ограничивают загрузки; JANITOR_* управляют очисткой. Для небольшого стенда настроено выделение одного внутреннего тома SeaweedFS за раз; S3_MAX_VOLUMES=64. Обязательные contracts/openapi.json, публичные тесты и README задания сохранены без изменений. Прямой flow — отдельное расширение API.

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Контракт и обязательный API make check validate, openapi_contract.py --scenario smoke, go test -race ./... PASS; 14 обязательных операций, 37 обменов; исходный OpenAPI не изменён recheck.txt
Proxy, ready, checksum, сообщения с вложением make test, student-tests/attachments.py PASS; скачанные байты совпали, сообщение читает второй участник level3.txt, recheck.txt
Ограничения PNG/JPEG, размера, пикселей и filename student-tests/attachments.py, memory_peak.py 10 МиБ принято; превышение размера/пикселей — 413; опасные имена — 400 level4.txt, manual-checks.txt
Upload → остановка загрузившей реплики → download student-tests/upload_failover.py Для каждой из двух реплик: файл скачан через другую, SHA-256 совпал recheck.txt
Restart сохраняет файл, метаданные и сессию make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS с прежним токеном; hook перезапускает API, LB, PostgreSQL, Valkey, S3 и его шлюз recheck.txt
Недоступность S3 student-tests/s3_outage.py Вложения — 503; метаданные и сообщения работают; после возврата файл совпал recheck.txt
Повреждение, подмена MIME, чужое вложение/чат openapi_contract.py --scenario attachments PASS: 415/404/400 по сценарию; 58 обменов соответствуют OpenAPI recheck.txt
Компенсация, обрыв, безопасная очистка student-tests/orphans.py, Go-тесты janitor Старый полный прогон PASS; в последнем повторе компенсация PASS, дальнейшая проверка прервана level4.txt, recheck.txt
≥10 параллельных загрузок, ограниченная RAM student-tests/memory_concurrent.py, memory_peak.py В старом прогоне 16/24 загрузки без OOM и рестартов level4.txt, memory-peak.txt
Bootstrap, отдельные credentials, private bucket, закрытые консоли Двойной s3-init, s3check, проверка сетей/портов PASS в повторе после исправления лимита томов recheck.txt
Трек 1: подпись, принадлежность, checksum, незавершённые загрузки student-tests/direct_upload.py, Go-тест TestDirectSizeExpiryAndCleanup Негативные сценарии PASS; истёкший PUT — 403, complete — 409; очистка проверена с продвижением часов level5-direct.txt, recheck.txt

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

Гипотеза трека 1: прямой PUT уменьшит трафик и RAM API. Стенд: Darwin arm64, Docker; две API-реплики, каждой выделены 1 CPU и 1 ГиБ RAM. Один последовательный прогон без отдельного прогрева. Один маленький PNG дополнен до 1 и 8 МиБ: влияние размера тела отделено от затрат на декодирование. RX/TX суммируются по репликам; RAM — максимум anon среди реплик при опросе каждые 0,2 с.

Размер Режим RX API, байт TX API, байт RAM до → максимум, МиБ
1 МиБ proxy 1 057 362 1 060 683 43,50 → 43,50
1 МиБ direct 1 058 909 1 061 230 43,50 → 43,52
8 МиБ proxy 8 450 669 8 436 929 43,51 → 43,56
8 МиБ direct 8 433 327 8 431 340 43,56 → 43,59

Гипотеза не подтвердилась для суммарного трафика: complete читает оригинал из S3 и сохраняет проверенную копию, поэтому через API проходит примерно 2 × размер файла. RAM почти одинакова: proxy уже потоковый. Малые различия — шум и служебный трафик; опрос может пропустить короткий пик. RPS и p95 этим экспериментом не измерялись.

В старом нагрузочном прогоне выполнены три раунда по 16 и 24 параллельных PNG около 10 МиБ: 48/72 успешные загрузки, пик anon 51/54 МиБ, без OOM. Для JPEG 40 Мп пик anon достигал 794 МиБ; из 24 запросов 23 получили 201, один — 429. Эти числа относятся к версии до добавления прямого flow.

Воздействие Что ожидаем Что наблюдали Восстановление / потеря данных
Остановка одной API-реплики Обслуживание другой Failover PASS; запись восстановилась за 3,19 с Подтверждённые сообщения и файл сохранены
Остановка S3 Ошибки вложений, остальное API работает Upload 503 за 8,01 с; download 503 за 5,42 с Download восстановился за 23,7 с после старта; файл совпал
Блокировка INSERT после PUT 503 и компенсация 503 за 3 с; число объектов/строк не выросло Лишний объект удалён
SIGKILL между PUT и INSERT Временный orphan, затем очистка В последнем повторе orphan найден и оставлен свежим Прогон остановлен до окончания grace period
Подмена token/ключа/размера/checksum Отказ без готового вложения 400/403 по сценарию; неверное изображение — 415 Готовая копия не меняется повторным PUT
Истечение подписи/ticket PUT/complete отклоняются 403 после 60 с и 409 после 120 с Метаданные незавершённой загрузки не создаются

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

Подтверждены остановка одной API-реплики и штатный перезапуск хранилищ. PostgreSQL, Valkey, S3 и LB существуют в одном экземпляре: отказ всего хоста не выдерживается. Потеря питания и заполнение диска не проверены. Очиститель удаляет объекты без метаданных, но не восстанавливает потерянные байты для существующей строки.