Files
mtusi2026lab4/REPORT.md
T

120 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Лабораторная 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 помог с реализацией, тестами и объяснением работы.