Files
mtusi2026lab4/REPORT.md
T

18 KiB
Raw Blame History

Лабораторная 4 — файлы в S3

Автор: Саламатин, БПИ-2304. Целевая оценка: 4, включая весь минимум на 3. Треки на 5 не выполнялись.

Как запустить

Нужны Docker Desktop с Linux containers и Compose. Из корня репозитория в PowerShell:

./start.ps1

Или вручную, если установлен Python 3.9+:

python scripts/init_local.py
docker compose build api checks minio
docker compose up -d --no-build --wait --wait-timeout 180
curl.exe --noproxy "*" http://127.0.0.1:8084/health/ready

Каждый образ собираем один раз: сервисы migrate, api и cleanup используют общий образ. Первая сборка MinIO занимает несколько минут: готовые образы из реестров оказались недоступны, поэтому Dockerfile собирает официальный исходный релиз MinIO RELEASE.2025-09-07T16-13-09Z и mc RELEASE.2025-08-13T08-35-41Z. Версии Go и базовых образов зафиксированы в Dockerfile. Python и зависимости приложения закреплены в requirements.txt и Dockerfile. После успешной сборки Compose использует локальный образ mtusi-minio:2025-09-07.

init_local.py один раз создаёт случайные секреты и .env. Повторный запуск сохраняет значения. Секреты не добавляются в Git. Не менять пароли при сохранённых volumes без отдельной процедуры смены пароля хранилища.

По умолчанию доступен только балансировщик на 127.0.0.1:8084. Порт выбран отдельно от lab3. API_PORT меняет внешний порт, API_REPLICAS задаёт число API, SESSION_TTL_SECONDS — срок сессий, APP_VERSION — метку версии, APP_ENV — метку окружения. API внутри контейнера слушает 8080. Остальные настройки и пути secrets находятся в compose.yaml.

Остановить без потери данных: docker compose stop или docker compose down. Команда намеренного удаления учебных данных: docker compose down --volumes; в проверках она не используется.

Что сделано и зачем

Перенесена собственная реализация lab3: FastAPI, PostgreSQL, сессии Redis с TTL и AOF, scrypt, проверка членства в чате, история с cursor, идемпотентная отправка сообщений, HAProxy и две API-реплики. Публичные contracts и tests lab4 сохранены.

Клиент обращается к HAProxy, тот выбирает API. PostgreSQL хранит пользователей, чаты, сообщения и сведения о вложениях. Оригиналы находятся в приватном bucket MinIO. Redis хранит сессии. Все три хранилища используют отдельные именованные volumes. API не хранит подтверждённые оригиналы у себя.

Миграция 003 добавляет attachments и attachment_ids сообщения. Вложение заранее связано с чатом. object_key — случайный UUID с префиксом original/, имя клиента используется только в метаданных. Доступ к метаданным и байтам проверяется по членству в чате. Для чужого объекта возвращается 404. Один участник может прикрепить файл, загруженный другим участником того же чата.

POST вложения принимает сырое тело PNG/JPEG. Лимит — 10 MiB и 40 млн пикселей. Сначала проверяем заголовки, имя и доступ, затем читаем тело по частям во временный файл с подсчётом размера и SHA-256. Временный файл — только staging на время запроса, после него закрывается. Размеры проверяем до декодирования, MIME — по фактическому формату Pillow. verify проверяет структуру, load ловит ошибки декодирования. Оригинал не перекодируется.

Одна реплика одновременно декодирует один файл. Ожидание слота ограничено 10 s, чтение тела — 20 s, общий бюджет до формирования ответа — 35 s. S3 connect/read timeout — 2/3 s, автоматических повторов PUT нет. HAProxy даёт 40 s. При отмене запроса ждём завершения уже начатой операции в потоке, прежде чем закрыть временный файл и освободить SQL-блокировку. Контейнер API ограничен 512 MiB. Это ограничивает память, но не обещает постоянную задержку под любой нагрузкой.

201 ready возвращается после S3 PUT и SQL COMMIT. GET content сначала проверяет сессию и чат, затем читает оригинал из S3 кусками по 64 KiB, без redirect. variant=original — единственный вариант. Сбой во время уже начатого скачивания может оборвать ответ: заменить его JSON-ошибкой после отправки заголовков невозможно.

Отпечаток идемпотентности сообщения теперь учитывает attachment_ids; отсутствие поля и [] равны. Пустой текст допустим с вложениями. Чужие, неизвестные и принадлежащие другому чату ID отклоняются до вставки сообщения.

Если запись оборвалась

Общей транзакции PostgreSQL и S3 нет. Перед PUT отдельно фиксируем строку pending со случайным ключом. Затем блокируем эту строку, записываем S3 и меняем статус на ready одной SQL-транзакцией. Если процесс погибнет после PUT или SQL COMMIT завершится ошибкой, останется учтённая строка pending. Её нельзя прикрепить к сообщению или скачать через API.

Сервис cleanup раз в минуту берёт до 100 pending старше часа через FOR UPDATE SKIP LOCKED, удаляет объект S3 и затем строку БД. При ошибке S3 строка остаётся для следующего прохода. DELETE S3 повторяем, поэтому сбой между удалением объекта и COMMIT не мешает следующему запуску. Часовой grace period защищает свежие запросы, блокировка — выполняющуюся финализацию. Ready не очищаются, даже если ещё не прикреплены к сообщению: контракт разрешает прикрепить их позже.

Обрыв HTTP до завершения приёма тела не вызывает PUT. Используется одиночный PUT без multipart, незавершённые multipart-загрузки не создаются. Для всех PUT сначала существует запись в БД, поэтому полного обхода bucket для штатной очистки не нужно. Ручное изменение БД или загрузка объектов администратором вне приложения этим механизмом не покрывается.

Приватный bucket и права

bucket-init ждёт готовности MinIO, создаёт bucket с --ignore-existing, выключает anonymous access, создаёт отдельного пользователя messenger-api и назначает ему политику. Повторный bootstrap безопасен для существующих файлов. У API есть только ListBucket для attachments и GetObject/PutObject/DeleteObject для original/*. Нет прав создавать bucket, менять политику или пользователей. У cleanup такие же ограниченные credentials. Корневой пароль доступен только MinIO и bootstrap.

MinIO не публикует порты на хост, административная консоль слушает только 127.0.0.1 внутри его контейнера. Проверка приватности выполняется напрямую по внутреннему адресу S3 без API и без подписи; проверяется и листинг bucket, и GET существующего объекта. Отдельно проверяется запрет административных операций с API credentials.

Проверки

Полный прогон: python scripts/verify.py. На этом компьютере также можно использовать ../.tools/python/python.exe -X utf8 scripts/verify.py.

docker compose run --rm --no-deps checks make check test
docker compose run --rm --no-deps checks make test-student
docker compose run --rm --no-deps checks sh -ec 'chmod +x scripts/restart.sh; make test-persistence ACTION_SCRIPT=scripts/restart.sh'
docker compose run --rm --no-deps checks sh -ec 'chmod +x scripts/stop-one.sh; make test-failover ACTION_SCRIPT=scripts/stop-one.sh'
docker compose start api

Failover оставляет выбранную реплику остановленной; восстановление выполняется отдельно. verify.py делает это сам. Restart перезапускает API, PostgreSQL, Redis, MinIO и LB без удаления volumes; cleanup продолжает работу и переподключается к БД.

Проверки выполнены 17 ноября 2026 года. Ветка solution/bpi-2304-salamatin; исходный skeleton ec540a1. Проверенная реализация — commit 372471a. Реализация находится в локальном репозитории; fork/PR ещё не публиковались.

Требование Проверка Результат Доказательство
Минимум lab3 и API lab4 make check test, make test-student Публичный smoke и 17 собственных тестов прошли smoke.txt, student-tests.txt
Оригинал, checksum, сообщение с attachment_ids, доступ участника Публичный smoke и test_validation_and_acl Побайтовое совпадение, чужому пользователю 404 smoke.txt, student-tests.txt
Ограничения bytes, pixels, MIME, filename test_validation_and_acl 413 / 415 / 400, без 500 student-tests.txt
Чужой attachment_id и файл другого чата test_validation_and_acl 404, сообщение не создаётся student-tests.txt
Обрыв тела и ошибка после S3 PUT test_failed_commit_cleanup_and_abort Обрыв не создаёт строку; PUT + ошибка SQL оставляют pending student-tests.txt
Grace period и повторяемая очистка Тот же тест Свежий pending сохранён; старый удалён из S3 и БД; повтор безопасен student-tests.txt
Недоступность S3 test_s3_outage live 200, ready/upload/download 503; после запуска прежний файл читается student-tests.txt
Приватность и ограничение прав test_private_bucket_and_bootstrap Anonymous list/GET существующего объекта 403; create bucket и запись вне prefix 403 student-tests.txt
Bootstrap можно повторять Два запуска существующего bucket-init Без ошибок, ранее загруженный файл сохранён student-tests.txt
Сохранность после restart make test-persistence, сравнение контейнеров Прежняя сессия и оригинал сохранены; изменился StartedAt у API, PostgreSQL, Redis, MinIO и LB; volumes те же persistence.txt, restart.json
Публичный failover Два make test-failover Обе проверки прошли, восстановление 2.309 и 2.320 s failover-1.txt, failover-2.txt, stop-1.json, stop-2.json
Остановка именно загрузившей API python scripts/check_uploader_failover.py в checks Upload instance остановлен, download instance другой, SHA-256 совпал uploader-failover.json
10 одновременных загрузок и память test_ten_parallel_uploads_memory 10 из 10 загружены и скачаны; контрольные суммы совпали uploads-memory.json

Все файлы доказательств находятся в evidence/. Итоговый smoke после отказов — smoke-final.txt. Проверки инфраструктуры выполнялись с сохранением volumes.

Условия опыта с памятью

Docker Desktop 28.5.1, x86_64, 16 доступных CPU, 7.47 GiB RAM виртуальной машины Docker. У каждой API-реплики лимит 1 CPU и 512 MiB. Две реплики, HAProxy round-robin. Один прогон без отдельного прогрева; до опыта выполнялись функциональные проверки. Barrier запускает 10 HTTP-загрузок одновременно. Каждый файл — PNG 1700×1600 со случайными RGB-пикселями, 8173157 байт. Каждый клиент после upload скачивает файл и проверяет SHA-256. Время всего опыта с загрузкой и скачиванием — 3.776 s.

Cgroup memory.current опрашивалась в отдельном потоке через docker exec последовательно для двух API, пауза между циклами 0.1 s; реальный интервал выше из-за накладных расходов команд. Выборочные пики — 248.3 MiB, 217.6 MiB. В JSON также сохранена memory.peak за всю жизнь контейнера: она включает предыдущие тесты и не выдается за чистый пик только этого опыта. CPU-потребление в этом опыте отдельно не измерялось. Это функциональная проверка ограниченной памяти при 10 клиентах, а не поиск максимального RPS.

Первые прогоны выявили ошибки проверочного окружения: запуск нового Compose-контейнера из checks разрешал bind mount относительно /checks, а restart.sh имел CRLF. Повторный bootstrap теперь запускает уже созданный init-контейнер; shell-скрипты сохранены с LF. Проверки повторены после исправлений. Бизнес-ошибки файлов не маскировались изменениями публичных tests.

MinIO собран через go install из закреплённого тега исходников; команда minio --version у такой сборки выводит DEVELOPMENT.GOGET. Версия исходного кода закреплена в infra/s3/Dockerfile, а фактический image ID сохранён в verification.json. Это не готовый upstream Docker-образ.

Ограничения

Стенд учебный, на одном компьютере. Один PostgreSQL, Redis, MinIO и балансировщик остаются точками отказа. Проверяется отказ API, а не потеря всего хоста. Нет резервного копирования, HTTPS для удалённого доступа и обработки изображений в фоне. Эксперимент загрузок — один функциональный прогон на локальном Docker Desktop, не оценка предельной производительности. Измерение cgroup учитывает память процесса и файловый кэш; memory.peak относится ко всей жизни контейнера.

Источники и инструменты

Задание и контракт: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab4

Исходники S3: https://github.com/minio/minio и https://github.com/minio/mc

Проверка изображений: https://pillow.readthedocs.io/en/stable/reference/Image.html

S3 SDK: https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html

Использованы FastAPI, Pydantic, Uvicorn, Psycopg, redis-py, boto3, Pillow, HAProxy. Codex помог с реализацией, тестами и объяснением работы.