Files
mtusi2026lab4-fork/REPORT.md
T

17 KiB
Raw Blame History

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

Автор: Шурман А.Р., БПИ2302. Целевая оценка: 4. Исследовательские треки на 5 не выполнялись.

Статус проверки

Полный прогон выполнен 12 ноября 2026 года на macOS arm64 / Docker Desktop. make check, полная валидация OpenAPI, 5 unit-тестов и весь scripts/verify.py прошли. Реальные результаты находятся в evidence/: smoke, негативные сценарии, приватность bucket, безопасная очистка, обрыв upload, отказ S3, повторный bootstrap, persistence, failover и нагрузка. Контракт и публичные тесты не изменены. Первоначальный evidence/offline.txt сохранён как историческая проверка до запуска Docker.

Запуск

Нужны Docker с Compose, Python 3.9+ на хосте (для memory/unit — Pillow). API работает на Python 3.12.7. Новый стенд использует порт 8084, отдельные volumes и Compose project mtusi-lab4, поэтому не занимает порт предыдущих работ.

cd mtusi2026lab4-fork
python3 -m venv .venv
.venv/bin/pip install -r requirements-dev.txt Pillow==11.1.0
python3 scripts/bootstrap.py
docker compose config --quiet
docker compose up -d --build --wait
BASE_URL=http://localhost:8084 .venv/bin/python scripts/verify.py
make validate PYTHON=.venv/bin/python

Команды выполняются из корня этой лабораторной. Если репозиторий склонирован отдельно, первую команду замените на переход в его каталог. bootstrap.py генерирует локальные секреты, не выводит и не перезаписывает их. Повторный запуск сохраняет данные. Для локальных тестов при отсутствии Pillow: отдельное venv и pip install Pillow==11.1.0. Полная проверка OpenAPI: pip install -r requirements-dev.txt, затем make validate.

API: http://localhost:8084; Swagger: http://localhost:8084/docs. Остановка без потери данных: docker compose down (без -v). Возобновление: docker compose up -d --wait.

Готовые образы minio/minio и minio/mc оказались недоступны при проверке 12 ноября 2026 года (Docker Hub: pull access denied; Quay: 401). Поэтому infra/s3/Dockerfile собирает официальные исходники закреплённых релизов MinIO RELEASE.2025-04-22T22-12-26Z и mc RELEASE.2025-04-16T18-13-26Z в Go 1.24.2. Лицензии включены в образы. Первый запуск требует интернет и время на скачивание Go-зависимостей и компиляцию; следующие сборки используют Docker cache.

Архитектура

HAProxy → две FastAPI-реплики → общий PostgreSQL и приватный MinIO. Valkey кэширует публичные профили; сессии проверяются в PostgreSQL при каждом запросе. Исходная основа — собственная лабораторная 2: модели пользователей/чатов, аутентификация, SQL-хранилище и мигратор. Возможности лабораторной 3 добавлены здесь: балансировка, X-Instance-Id, общая таблица идемпотентности. Контракт и публичные тесты skeleton не изменены.

Каждая реплика возвращает api1 или api2. HAProxy проверяет readiness каждую секунду, исключает реплику после двух неудач. Он не повторяет POST автоматически. При потере ответа клиент повторяет сообщение с тем же Idempotency-Key. Advisory lock в PostgreSQL сериализует один ключ пользователя/чата, вставка сообщения и результата атомарны. Повтор в течение 24 часов возвращает исходный объект; другой текст/список вложений — 409. Отсутствующий список вложений и [] равны. Просроченная запись ключа заменяется при повторном использовании. История читается из primary без кэша. Keyset cursor не обеспечивает snapshot между страницами.

Метаданные Attachment находятся в PostgreSQL, байты — только в S3. Временный файл API существует исключительно во время приёма и проверки запроса и закрывается по выходу. Имя пользователя не используется как S3 key. Ключ — originals/<UUID>. Скачивание идёт через API после проверки членства, без redirect и публичных URL.

Валидация и ресурсы

Загрузка принимает сырые PNG/JPEG, максимум 10 MiB. Content-Length проверяется заранее, но фактические байты также считаются во время потока. Общий срок приёма — 30 секунд. Pillow проверяет формат, MIME, структуру и декодирование. Размер не выше 40 млн пикселей проверяется до загрузки пикселей. Анимированные PNG в этой реализации отклоняются. Оригинал сохраняется без преобразования; SHA-256 и размер вычисляются при чтении. Пустые/опасные filename, MIME-подмена и чужие вложения имеют ошибки контракта.

Одновременно каждая реплика обрабатывает максимум две загрузки. Ожидание слота до 0.5 s, затем явный 503. Две реплики ограничены по 768 MiB и 1 CPU. На диск пишется максимум 10 MiB на активную загрузку, декодирование занимает ограниченную память до размера изображения. S3: connect timeout 2 s, read timeout 10 s, автоматических повторов нет. Download читает S3 чанками по 64 KiB. Оригинал не загружается целиком в RAM при скачивании.

Согласованность S3 и БД

  1. API принимает и проверяет временный файл.
  2. Отдельная транзакция сохраняет pending и назначенный object key до S3 PUT.
  3. Новая транзакция блокирует строку, выполняет PUT и переводит её в ready.
  4. Ответ 201 отправляется только после COMMIT. pending не показывается публично.

При обрыве передачи клиента до PUT остаётся только автоматически закрываемый временный файл. При сбое PUT, падении процесса или неуспешном COMMIT остаётся учтённый pending. Фоновый cleaner раз в минуту выбирает pending старше 1 часа, блокируя строку FOR UPDATE SKIP LOCKED, удаляет соответствующий S3 key и затем запись БД. Активная транзакция пропускается. При ошибке S3 строка сохраняется для следующего прохода. При сбое COMMIT очистка повторит безопасный DELETE отсутствующего объекта. ready никогда не выбирается. Часовой grace period значительно больше таймаутов загрузки. Это не распределённая транзакция: некоторое время возможны pending-метаданные и лишние байты. Объекты, вручную записанные администратором без intent, вне модели очистки.

Приватность и запуск хранилища

MinIO, PostgreSQL, Valkey и API не публикуют порты на хост. Только HAProxy доступен на loopback. Консоль MinIO слушает 127.0.0.1 внутри его контейнера. Идемпотентный s3-init создаёт bucket, запрещает anonymous и назначает отдельному API user политику: ListBucket одного bucket и Get/Put/Delete исключительно в originals/*. Root credentials доступны только MinIO и init, API их не получает. Readiness зависит от PostgreSQL и MinIO. Valkey имеет fallback в PostgreSQL. Секреты находятся в исключённом из Git каталоге secrets/.

Роль / service Версия Готовность Постоянные данные Доступ / credentials
LB / lb HAProxy 3.0.8-alpine HTTP /health/ready обеих API нет только 127.0.0.1:8084
API / api1, api2 Python 3.12.7; app/requirements.txt PostgreSQL + MinIO нет внутренняя сеть; DB/S3 через secrets
БД / postgres PostgreSQL 16.6-bookworm pg_isready postgres-data внутренняя сеть; password secret
Кэш / valkey Valkey 8.0.2-alpine некритичен, fallback в БД valkey-data (AOF) внутренняя сеть
S3 / s3 MinIO RELEASE.2025-04-22T22-12-26Z /minio/health/live s3-data внутренняя сеть; root secrets
Bootstrap / s3-init mc RELEASE.2025-04-16T18-13-26Z успешное завершение bucket/policy в S3 root + API secrets
Миграции / migrate образ API успешное завершение schema_migrations в БД secrets, advisory lock, checksum миграций
Очистка / cleaner образ API повтор каждые 60 s pending в БД ограниченные API S3 credentials

Все сервисы находятся в отдельной Compose-сети mtusi-lab4_default. Повторный bootstrap.py сохраняет секреты; повторные migrate и s3-init не удаляют данные и выполняются при docker compose up.

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

Критерий Проверка Результат 12.11.2026
Структура и синтаксис make check, AST всех новых Python-файлов выполнено
Конфигурация docker compose config --quiet выполнено
Реальные PNG/JPEG, MIME, повреждение, пиксели python3 student-tests/unit.py 5 тестов пройдено
Обязательный API и checksum make test BASE_URL=http://localhost:8084 PASS; вывод в evidence/
Ошибки файлов и ACL, конкуренция ключа BASE_URL=http://localhost:8084 python3 student-tests/verify.py PASS; вывод в evidence/
Приватность bucket и безопасная очистка student-tests/storage_checks.py внутри API через общий runner PASS; вывод в evidence/
Обрыв загрузки и отказ S3 student-tests/outage.py PASS; вывод в evidence/
Повторный bootstrap повтор docker compose run --rm s3-init PASS; вывод в evidence/
Перезапуск всех сервисов persistence + scripts/restart.sh PASS; вывод в evidence/
Остановка обслужившей реплики failover + scripts/stop-one.sh PASS; 89 записей, 3 неудачные попытки, восстановление 2.8 s
Остановка именно загрузившей реплики student-tests/attachment_failover.py PASS; upload api1 → download api2; bytes совпадают
10 одновременных загрузок и RSS student-tests/memory.py 8 × 201, 2 × 503; пик RSS 132796 / 133912 KiB

.venv/bin/python scripts/verify.py выполняет проверки и сохраняет реальные результаты в evidence, останавливаясь при первом провале. Тест очистки создаёт только синтетические строки и объекты, моделирует rollback финализации после PUT, проверяет grace period и сохранность ready. Он удаляет только свои синтетические данные. До запуска убедитесь, что это учебный стенд.

Memory-тест создаёт PNG примерно 9 MiB и одновременно запускает 10 запросов. Он пишет коды ответов, длительность, выборки VmRSS процессов API и измеренный максимум. Отказы 503 из-за ограничения слотов учитываются явно; они не записываются как успешные загрузки. Последовательная выборка /proc/1/status может пропустить короткий пик, поэтому результат — максимум наблюдений, а не гарантированный абсолютный пик. Фактический эксперимент: 10 одновременных запросов по 9 201 866 байт, 8 ответов 201 и 2 ответа 503; время ответа 0.427–0.680 s. Наблюдаемый пик RSS: api1 — 132 796 KiB (129.7 MiB), api2 — 133 912 KiB (130.8 MiB), при лимите 768 MiB на реплику. Полные выборки сохранены в evidence/memory.json. Это проверка ограниченности ресурсов, а не обещание принять любую конкуренцию без 503.

Ограничения

Один host, HAProxy, PostgreSQL и MinIO остаются точками отказа. Это отказоустойчивость к остановке одной API-реплики, не полноценная HA-система. При отказе S3 readiness становится 503; после восстановления новые обращения повторяются клиентом. Обрыв S3 посреди уже начатого download закрывает поток, поэтому клиент проверяет длину/checksum. Нет UI, обработки изображений в очереди, presigned URL и исследовательских треков. Проверка реальных контейнеров выполнена; при переносе на другую машину её нужно повторить.

Источники и использование ИИ

Основа — собственные предыдущие лабораторные и skeleton преподавателя; API и критерии взяты из contracts/ и README.md. MinIO/mc собираются из официальных исходников по ссылкам выше. При проверке и исправлении работы использован Codex: анализ кода, исправление сборки S3, дополнительные тесты, запуск стенда и оформление фактических результатов. Результаты получены запуском, а не сгенерированы.