# Лабораторная 4 — файлы в S3 Автор: Саламатин, БПИ-2304. Целевая оценка: **4**, включая весь минимум на 3. Треки на 5 не выполнялись. ## Как запустить Нужны Docker Desktop с Linux containers и Compose. Из корня репозитория в PowerShell: ```powershell ./start.ps1 ``` Или вручную, если установлен Python 3.9+: ```powershell 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`. ```powershell 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 помог с реализацией, тестами и объяснением работы.