Files
mtusi2026lab4-fork/REPORT.md
T

13 KiB
Raw Blame History

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

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

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

Реализация подготовлена, но полный Docker-прогон ещё не выполнен. В среде подготовки нет доступа к Docker socket. Проверены структура задания, Python-синтаксис, Compose-конфигурация и пять локальных тестов валидации изображений. Фактические локальные результаты находятся в evidence/offline.txt. Smoke, сохранность, отказ реплики, доступ к приватному bucket, очистка после сбоя и эксперимент с 10 загрузками необходимо выполнить приведённой ниже командой. До этого выполнение всех критериев оценки 4 не подтверждено.

Запуск

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

cd labs/mtusi2026lab4
python3 scripts/bootstrap.py
docker compose config --quiet
docker compose up -d --build --wait
BASE_URL=http://localhost:8084 python3 scripts/verify.py

Команды выполняются из корня этой лабораторной. Если репозиторий склонирован отдельно, первую команду замените на переход в его каталог. 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.

Архитектура

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/.

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

Критерий Проверка Статус на момент подготовки
Структура и синтаксис 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 требуется запуск Docker
Ошибки файлов и ACL, конкуренция ключа BASE_URL=http://localhost:8084 python3 student-tests/verify.py требуется запуск Docker
Приватность bucket и безопасная очистка student-tests/storage_checks.py внутри API через общий runner требуется запуск Docker
Обрыв загрузки и отказ S3 student-tests/outage.py требуется запуск Docker
Повторный bootstrap повтор docker compose run --rm s3-init требуется запуск Docker
Перезапуск всех сервисов persistence + scripts/restart.sh требуется запуск Docker
Остановка обслужившей реплики failover + scripts/stop-one.sh требуется запуск Docker
10 одновременных загрузок и RSS student-tests/memory.py измерения ещё не получены

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

Memory-тест создаёт PNG примерно 9 MiB и одновременно запускает 10 запросов. Он пишет коды ответов, длительность, выборки VmRSS процессов API и измеренный максимум. Отказы 503 из-за ограничения слотов учитываются явно; они не записываются как успешные загрузки. Последовательная выборка /proc/1/status может пропустить короткий пик, поэтому результат — максимум наблюдений, а не гарантированный абсолютный пик. Числа не подставлены заранее.

Ограничения

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