Files
mtusi2026lab4/REPORT.md
T

21 KiB
Raw Blame History

Отчёт — лабораторная 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.

Источники