21 KiB
Отчёт — лабораторная 4
- Автор, группа: Осокин Глеб, БВТ2302, Gitea
glebossokin. - Целевая оценка: 3. Уровни 4/5 и исследовательские треки не заявлены.
- Ветка решения:
solution/BVT2302-Osokin. Запрос на слияние направляется вmtusi2026/mtusi2026lab4:main. - Дата полного прогона: 16.11.2026.
- Перенос: собственная ЛР3, исходники приложения, миграции 001/002, Dockerfile, конфигурация HAProxy/Redis, проверка общей идемпотентности. Rolling update и исследования нагрузки предыдущей работы не переносились.
- Помощь ИИ: OpenAI Codex — реализация, подготовка отчёта и запуск проверок. Наблюдения получены на реально работающем Docker-стенде. Библиотеки: psycopg, Redis client, boto3, Pillow; первичные источники приведены ниже.
Запуск из чистого clone
Нужны Git, Python 3.9+ для публичных проверок, Docker Engine с Compose v2+ и Linux containers. На Windows использованы Python 3.14.3 и Docker Desktop. Свободный порт 127.0.0.1:8084; остальные порты не публикуются. При первой сборке нужен доступ к Docker Hub и PyPI.
git clone --branch solution/BVT2302-Osokin https://gitea.privcloud.tech/glebossokin/mtusi2026lab4.git
cd mtusi2026lab4
python -X utf8 scripts/bootstrap.py
docker compose --env-file .env config --quiet
docker compose build api
docker compose --env-file .env up -d --no-build
python -X utf8 scripts/wait_ready.py
python -X utf8 scripts/verify.py
На Linux заменить python -X utf8 на python3. У hooks scripts/restart.sh и scripts/stop-one.sh executable bit сохранён в Git; при необходимости выполнить chmod +x scripts/restart.sh scripts/stop-one.sh. Если Docker Desktop ещё не настроен на Linux engine, выбрать его командой docker context use desktop-linux.
bootstrap.py создаёт локальные .env и secrets/: случайные пароль PostgreSQL, ключ HMAC cursor и credentials MinIO. Существующие значения сохраняются. Эти файлы исключены из Git и Docker build context; их содержимое не печатается. Не менять secrets при повторном использовании прежних volumes.
migrate применяет SQL в одной транзакции с блокировкой и проверкой контрольных сумм. bucket создаёт приватный bucket перед API; anonymous/public policy не устанавливается. API запускаются после миграций, bootstrap bucket и готовности Redis. HAProxy проверяет readiness обеих реплик. После запуска LB нужно дождаться wait_ready.py.
Отдельные публичные проверки на Windows:
python -X utf8 scripts/check_contract.py
python -X utf8 tests/smoke.py --base-url http://127.0.0.1:8084
python -X utf8 tests/resilience.py --mode persistence --base-url http://127.0.0.1:8084 --action-script scripts/restart.cmd
python -X utf8 tests/resilience.py --mode failover --base-url http://127.0.0.1:8084 --action-script scripts/stop-one.cmd
python -X utf8 scripts/labctl.py restore
Это прямые эквиваленты make check, make test BASE_URL=http://127.0.0.1:8084 и make test-persistence/test-failover с соответствующим ACTION_SCRIPT. На Linux передавать .sh hooks. Контракт и публичные тесты не изменялись. Полный verify.py сохраняет результаты в evidence/, останавливает/восстанавливает API и MinIO, перезапускает работающий стенд. Все данные синтетические. После ручного failover реплика остаётся остановленной до labctl.py restore.
Для другого host-порта изменить APP_PORT в .env, задать BASE_URL для wait_ready.py, verify.py, grade3.py и явно передать его публичным тестам. Безопасная остановка с сохранением данных: docker compose down. Намеренное удаление всех учебных данных этого Compose-проекта: docker compose down --volumes. При проверках отказов volumes не удаляются. У ЛР4 отдельное имя проекта mtusi-lab4-osokin.
Закреплённые версии образов: Python 3.13.7-slim-bookworm, PostgreSQL 17.6-bookworm, Redis 7.4.5-bookworm, HAProxy 3.0.16-alpine, MinIO RELEASE.2025-04-22T22-12-26Z. Зависимости в requirements.txt, в том числе psycopg 3.2.10, psycopg-pool 3.2.6, Redis client 6.4.0, boto3 1.40.6, Pillow 11.3.0. Фактическое окружение и digest инфраструктурных образов: environment.json.
Архитектура и решения
Клиент → 127.0.0.1:8084 → HAProxy → API × 2
├─ PostgreSQL → pgdata
├─ Redis → redisdata (сессии, AOF always)
└─ MinIO → s3data (приватный bucket)
PostgreSQL — источник истины для пользователей, чатов, участников, сообщений, результатов идемпотентных запросов и метаданных вложений. Общий Redis хранит серверные сессии с абсолютным expiry и AOF appendfsync always; restart не продлевает TTL. У API нет volume с оригиналами или обязательного локального состояния. Все зависимости находятся в общем compose.yaml, backend-сеть внутренняя. Публичный порт есть только у LB. Реальные процессы, порты, лимиты и mounts: processes.txt.
Сохранён минимум ЛР3: Bearer-сессии, scrypt, миграции PostgreSQL, keyset pagination по (created_at,id), общие данные, X-Instance-Id и общий Idempotency-Key минимум на 24 часа. Advisory transaction lock защищает одновременные повторы: создание сообщения и сохранение результата атомарны. Отсутствующий attachment_ids и [] дают одинаковый fingerprint. Повтор заново проверяет сессию и участие в чате.
Новое в ЛР4:
003_attachments.sql: Attachment с UUID, chat/owner, отображаемым filename, внутренним object_key, MIME, размером, SHA-256 и временем. В Message добавлен массив UUID вложений с пустым default, старые текстовые сообщения валидны. Приложение проверяет существование всех вложений именно этого чата внутри транзакции создания Message. Удаление вложений в обязательный API не входит.- Binary POST принимает PNG/JPEG. До чтения body проверяются сессия, доступ к чату, filename и Content-Length ≤10 MiB. Transfer-Encoding и неправильная длина отклоняются. Чтение ограничено; временных файлов нет. Pillow открывает header лениво: формат и ≤40 млн пикселей проверяются до decode, MIME сверяется с содержимым; далее
verify()иload()проверяют изображение. Filename 1–255 code points, без/,\, NUL и управляющих символов. - Сервер независимо от filename генерирует случайный S3 key
originals/<uuid>, считает lowercase SHA-256 и отправляет неизменённые bytes в приватный bucket. После успешного PUT выполняются INSERT metadata и COMMIT. Только после этого возвращается 201 ready,variants=[],error_code=null. - Metadata/content читаются только участником чата через JOIN с chat_members. Посторонний/неизвестный объект — 404. Download через авторизованный API, без redirect, с истинным MIME и проверкой размера/hash.
variant=originalподдерживается, других вариантов нет. Публичный API не раскрывает object key и credentials.
Общей распределённой транзакции PostgreSQL/S3 нет. Если PUT не состоялся, metadata не создаются и 201 не выдаётся. После PUT до COMMIT возможен orphan. Потерянный HTTP-ответ может скрывать уже завершённую операцию; самостоятельный повтор upload может создать второй объект. Автоматическая компенсация, сверка и очистка с grace period не реализованы — это дополнительный уровень 4/5.
/health/live проверяет процесс. /health/ready проверяет PostgreSQL, Redis и доступность bucket MinIO, поскольку S3 участвует в обязательном синхронном пути. Ошибки S3 преобразуются в 503 общего формата. При потере S3 HAProxy может исключить обе реплики; это консервативная readiness. В таком сценарии ответ самого API проверяется из контейнера без публикации порта в обход LB.
Переменные .env.example |
Использование |
|---|---|
| APP_HOST / APP_PORT / APP_ENV | API внутри слушает 0.0.0.0:8080; APP_PORT задаёт host-порт LB (bootstrap: 8084); APP_ENV=lab |
| SESSION_TTL_SECONDS | TTL сессии 3600 s |
| SESSION_STORE / CACHE_URL_FILE | В Compose выбран redis вместо postgres из примера; адрес из secret-файла |
| DATABASE_URL_FILE | DSN из /run/secrets/database_url |
| API_REPLICAS | scale API, default 2 |
| IDEMPOTENCY_TTL_SECONDS | минимум 86400 s |
| S3_ENDPOINT / S3_REGION / S3_BUCKET | http://s3:9000 / us-east-1 / messenger-attachments |
| S3_ACCESS_KEY_ID_FILE / S3_SECRET_ACCESS_KEY_FILE | credentials через Compose secrets |
| MAX_UPLOAD_BYTES / MAX_IMAGE_PIXELS | 10485760 / 40000000; повышать сверх контракта нельзя |
Дополнительно CURSOR_KEY_FILE задаёт общий ключ HMAC. У каждой API 4 workers и очередь до 32 соединений. Используются credentials учебного MinIO без отдельной ограниченной S3-роли уровня 4.
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Целостность skeleton | python -X utf8 scripts/check_contract.py |
PASS | check.txt |
| Публичный smoke | python -X utf8 tests/smoke.py --base-url http://127.0.0.1:8084 |
PASS: базовый API, upload ready, checksum и ACL | smoke.txt |
| Минимум ЛР3: две реплики, общая сессия, идемпотентность | docker compose exec -T api python student-tests/test_idempotency.py |
16 одновременных повторов через 2 процесса создали 1 Message | idempotency.txt |
| PostgreSQL metadata, private S3 bytes, persistent volumes | scripts/labctl.py state и private probe в grade3.py |
API без volume оригиналов, три data volumes; anonymous S3 GET=403 | processes.txt, private-and-formats.json |
| Реальные PNG/JPEG и byte-identical download | python -X utf8 student-tests/grade3.py |
Оба формата приняты, оригиналы скачаны без изменения | private-and-formats.json |
| Лимиты bytes/pixels до чтения/decode, filename | docker compose exec -T api python student-tests/test_limits.py |
Точно 10 MiB и 40 млн пикселей приняты; превышение отклонено до read/decode; опасные имена отклонены | limits.txt |
| Upload → остановка именно загрузившей API → download другой | python -X utf8 student-tests/grade3.py |
Разные X-Instance-Id, uploader exited, оригинал и Message доступны второму участнику | upload-failover.json |
| Чужой пользователь | Public smoke и grade3.py | Metadata/content возвращают 404 | upload-failover.json, smoke.txt |
| Restart всего стенда | Публичный persistence с scripts/restart.cmd |
PASS с прежним токеном, metadata/bytes и сообщениями; StartedAt изменён, volumes прежние | persistence.txt, restart.json |
| Публичный failover с записью | Failover с scripts/stop-one.cmd |
PASS, 99 записей, 4 переходные ошибки, восстановление 5.198 s, без потерь подтверждённых записей и дублей | failover.txt, stop-one.json |
| Недоступность S3 | python -X utf8 student-tests/grade3.py |
live/metadata 200, ready/upload/content 503; после start прежний файл доступен | s3-outage.json |
| Стенд восстановлен | Финальный public smoke полного verify | PASS | smoke-after.txt |
Публичные tests/, обязательные contracts/, README и COURSE сохранены. Проверки выполнены на реальных контейнерах. Уровни 4/5 не заявлены. Результаты полного прогона — в evidence/.
Эксперименты и отказы
Исследования производительности уровня 4/5 не проводились. Функциональные проверки выполнялись с синтетическими данными. Граничные изображения проверены последовательно: PNG 10 MiB с сохранением trailing bytes и PNG 8000×5000. Это проверка допустимого входа, не исследование параллельной загрузки.
Docker VM: 8 CPU, примерно 7.7 GiB RAM, Linux x86_64, Engine 29.8.2; host Windows. Лимиты: каждая API 1 CPU / 768 MiB; PostgreSQL 2 CPU / 512 MiB; Redis 0.5 CPU / 128 MiB; HAProxy 0.5 CPU / 128 MiB; MinIO 1 CPU / 512 MiB. Версии/digest/kernel — в environment.json. Перед отказами выполнены ожидание readiness и smoke, отдельного нагрузочного прогрева не было.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
| Остановить uploader API | Скачать оригинал через другую | X-Instance-Id различается, bytes совпадают, attached Message прочитан | Без потери подтверждённого файла; затем явный restore |
| Остановить MinIO | Не вернуть ложный 201, корректно сообщить недоступность | ready/upload/content=503; live/metadata=200; после start прежний токен скачал тот же файл | 20.312 s на весь сценарий с Docker CLI, проверками и восстановлением LB; original сохранён |
| Restart API, PostgreSQL, Redis, MinIO, LB | Сохранить сессию, metadata, bytes и сообщения | Public persistence PASS; StartedAt всех работающих сервисов изменён, volumes те же | Данные не потеряны, публичный тест дождался готовности в своём бюджете 90 s |
| Остановить API во время 15 s записи | Восстановить запись ≤10 s, сохранить подтверждения | Public failover PASS, 99 успешных записей, 4 переходные ошибки | 5.198 s; потерь подтверждённых сообщений/дублей нет |
Public failover последовательно отправляет сообщения с паузой 0.1 s; неопределённый POST повторяет с прежним ключом. Эти результаты не выдаются за RPS-бенчмарк, p50/p95/p99 или пик производительности. 20.312 s для S3 включает команды Docker и проверки, а не только время восстановления S3.
Ограничения и следующие шаги
- Один Docker-host и одиночные PostgreSQL/Redis/LB/MinIO: потерю host или volume две API не перекрывают.
- Между S3 PUT и DB COMMIT возможен orphan. Автоматическая компенсация, reconciler и очистка с grace period не реализованы.
- Body буферизуется до 10 MiB, decode ограничен 40 млн пикселей. Нет эксперимента ≥10 одновременных uploads и измерения пика памяти; RAM-лимит контейнера не гарантирует успех любой комбинации больших конкурентных decode.
- API использует root credentials учебного MinIO. Отдельных ограниченных S3 credentials уровня 4 нет. S3/консоль не опубликованы на host в соответствии с общей изоляцией стенда.
- Presigned upload, thumbnails, worker, варианты изображений и исследовательские треки не реализованы. Дополнительная полная матрица негативных тестов уровня 4 не заявлена.
- HTTP допускается только для локального учебного стенда. Это обязательный минимум на 3 без заявления о production-ready/HA.
Источники
- Задание ЛР4, локальные COURSE/CONTRIBUTING, OpenAPI, contracts/README и tests/README.
- Собственная ЛР3.
- Pillow Image: open/verify/load и pixel limits.
- Boto3 S3 PutObject.
- MinIO.