Files
mtusi2026lab4/REPORT.md
T

27 KiB
Raw Blame History

Отчёт — лабораторная 4

  • Автор, группа: Черненко, БПИ2301.
  • Целевая оценка: 5, трек 2 — согласованность двух хранилищ.
  • Ветка: solution/bpi2301-chernenko, основана на исходном main (ec540a1). В удалённом репозитории отдельной ветки skeleton нет. PR создаёт автор вручную; готовый текст — .github/pull_request_template.md. Commit: git rev-parse HEAD.
  • Дата испытаний: 6 ноября 2026. Использованы Python/FastAPI, psycopg, boto3, Pillow, Argon2id, PostgreSQL, HAProxy и MinIO. Исходники и инструкции подготовлены с помощью Codex; тесты выполнены на настоящем Docker Compose стенде. Предыдущее личное решение lab3 не предоставлялось: необходимый минимум lab1–3 реализован заново по контракту текущего skeleton, чужой код решения не переносился.

Запуск из чистого clone

Нужны Docker Engine/Desktop в режиме Linux containers, Compose v2 с --wait, доступ в Интернет для первой сборки и Python 3.9+ на host для управляющего скрипта. На Windows используется py -X utf8, на Linux/macOS — python3. Для первой сборки MinIO из исходников желательно 4+ GiB доступной Docker RAM.

Версии: Python 3.12.10, PostgreSQL 17.5-alpine, HAProxy 3.0.11-alpine; MinIO RELEASE.2025-04-22T22-12-26Z, mc RELEASE.2025-04-16T18-13-26Z, Go 1.24.2-alpine, Alpine 3.21.3. Прямые Python-зависимости закреплены в requirements.txt; установленные версии сохраняются в evidence/python-packages.txt. Официальные готовые образы MinIO/mc при проверке были недоступны, поэтому infra/Dockerfile.minio и infra/Dockerfile.mc собирают фиксированные upstream tags через Go module proxy с проверкой Go checksum database.

git clone https://gitea.privcloud.tech/quzzqq/mtusi2026lab4.git
cd mtusi2026lab4
git switch solution/bpi2301-chernenko
python3 scripts/setup.py
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait --wait-timeout 180
docker compose exec -T api1 make check validate PYTHON=python
docker compose exec -T api1 make test PYTHON=python BASE_URL=http://lb:8080
python3 scripts/run-all.py

Windows: заменить вызовы python3 ... на py -X utf8 .... Если секреты создавались контейнером со старыми правами, повторить setup в контейнере:

docker run --rm --mount "type=bind,source=$($PWD.Path),target=/app" -w /app python:3.12.10-slim python scripts/setup.py

setup.py создаёт локальные случайные secrets и .env, не печатает значения, не заменяет существующие секреты. Каталог secrets закрыт для других host-users, отдельные файлы доступны непривилегированному пользователю контейнера через mounts. Ни .env, ни secrets не входят в Git или Docker build context. Не подменять setup простым копированием логического .env.example: сначала нужны secrets.

Публикуется только LB на loopback. Порт по умолчанию 8080; при конфликте добавить в .env HOST_PORT=18084 и повторить docker compose up -d. При наших испытаниях использовался 18084, так как 8080 занят посторонним сервисом. run-all.py автоматически узнаёт фактический порт через docker compose port lb 8080. API, PostgreSQL, S3 и административная консоль не публикуют host-порты.

Миграции выполняет одноразовый migrate до API; SQL идемпотентен и защищён advisory lock. bootstrap создаёт приватный bucket, отдельного S3-пользователя и ограниченную policy. Повторный запуск bootstrap сохраняет данные и проходит успешно. Оператор ждёт --wait и HTTP readiness. Первая компиляция MinIO может занять несколько минут.

Полный run-all.py выполняет check/validate/smoke, собственные проверки, persistence, остановку каждой API, публичный failover, отказы S3 и PostgreSQL, исследование, загрузки и 30-секундную нагрузку сообщений. Он останавливает только сервисы Compose project chernenko-lab4, восстанавливает их после испытаний и сохраняет обезличенные результаты в evidence/. Повтор создаёт новые синтетические данные.

Отдельные публичные сценарии (Linux/macOS; Python на host, Docker CLI доступен):

chmod +x scripts/restart.sh scripts/stop-one.sh
make test-persistence PYTHON=python3 BASE_URL=http://localhost:18084 ACTION_SCRIPT=scripts/restart.sh
docker compose start api1 api2
make test-failover PYTHON=python3 BASE_URL=http://localhost:18084 ACTION_SCRIPT=scripts/stop-one.sh
docker compose start api1 api2

На Windows run-all.py выбирает .cmd hooks. Они делают те же реальные Docker-действия. restart перезапускает PostgreSQL, MinIO, обе API и LB с volumes; stop-one по TARGET_INSTANCE_ID останавливает именно соответствующую реплику и оставляет её выключенной. Для ручного запуска public tests на Windows задайте BASE_URL и используйте py -X utf8 tests/resilience.py --mode persistence --action-script scripts/restart.cmd.

Безопасная остановка: docker compose down (данные и сессии остаются в volumes). Восстановление: прежний docker compose up -d --wait с теми же secrets. Намеренное удаление всех учебных данных этого стенда: docker compose down --volumes. Эту последнюю команду не использовать для проверки persistence.

Архитектура и решения

Клиент → HAProxy → api1/api2 → PostgreSQL + MinIO. Один uvicorn process на реплику; балансировка round-robin с HTTP /health/ready каждую секунду. Live проверяет только процесс; ready — PostgreSQL и доступ к приватному bucket. Оба хранилища критичны для обязательного синхронного пути. При их общем отказе LB не обещает обслуживание текстовых операций через исключённые API.

PostgreSQL — источник истины для users, sessions, chats/members, messages, message_attachments, attachments и idempotency. Сессии переживают рестарт, TTL=3600 не продлевается при чтении/рестарте, logout удаляет hash токена. Токен имеет 256 бит случайности, в БД хранится его SHA-256. Пароли — Argon2id (time_cost=2, memory_cost=19456 KiB, parallelism=1), plaintext не сохраняется.

Сообщение, связи и idempotency результат фиксируются атомарно в PostgreSQL. Advisory lock по user/chat/key исключает дубли между процессами; 24 часа отсчитываются от успешной записи. Другой body даёт 409, отсутствие attachment_ids равно пустому массиву. Неопределённый POST messages повторяется с прежним ключом. Чтение идёт в общую БД без устаревающего кэша. Пагинация keyset по (created_at,id); cursor содержит ресурс, время, UUID. Snapshot между запросами не гарантируется.

Оригиналы — только messenger-attachments/originals/<UUID>. Filename не образует путь и не раскрывается как S3 key. Byte-stream ограничен 10 MiB до накопления, spool после 256 KiB переносится в ограниченный tmpfs; на API допускаются 2 загрузки и 1 декодирование одновременно. На приём body отведено 20 секунд, очередь загрузок ждёт до 15 секунд, connect/read S3 — 2/5 секунд без прозрачных retry; SQL connect=3 секунды, statement=15, lock=10. HAProxy client/server timeout=30 секунд. Изображение проверяется по формату и полностью декодируется после проверки 40 млн пикселей; оригинал не перекодируется. Download передаёт по 64 KiB через API. Tmpfs — временная копия для проверки, после запроса не используется для download.

Граница upload: проверка ACL → приём/проверка → shared DB advisory lock → S3 PUT → INSERT Attachment → COMMIT → 201 ready. Общей транзакции S3/SQL нет. При любой неопределённости COMMIT синхронное удаление S3 не выполняется: оно могло бы стереть уже зафиксированный оригинал. Дальнейшая компенсация — операторская сверка.

Reconciler по умолчанию dry-run; запуск:

docker compose exec -T api1 python -m src.reconcile
docker compose exec -T api1 python -m src.reconcile --apply

Оператор сначала оценивает dry-run, затем применяет. Grace по умолчанию 3600 секунд, минимум 60 — только для контролируемого теста. Полный LIST prefix выполняется до исправлений, с пагинацией. Exclusive advisory lock согласует сверку с PUT/COMMIT и привязкой сообщений. Любая запись Attachment защищает объект, даже без Message. Orphan после grace повторно проверяется через HEAD и SQL и удаляется; missing старше grace проверяется HEAD 404, метаданные и ссылки сохраняются, внутренний статус становится failed/missing_object. Неуспех LIST/HEAD/DB прерывает проход. Повторный запуск безопасен. Восстановление оригинала из копии проверяется по размеру и SHA-256 перед ready. Сверка сама не восстанавливает потерянные байты. Публичные успешные Attachment остаются ready согласно контракту; внутренний failed доступен через 409, после проверки ACL. Детали: contracts/extensions.md.

Соответствие .env.example: APP_HOST/APP_PORT реализованы аргументами uvicorn 0.0.0.0:8080, APP_ENV — только логическое описание; API_REPLICAS=2 реализовано двумя сервисами; SESSION_STORE=postgres, CACHE_URL_FILE не используется — Redis не обязателен для минимума предыдущих лабораторных. SESSION_TTL_SECONDS реально передаётся из .env. IDEMPOTENCY_TTL_SECONDS фиксирован контрактными 86400 секундами. DATABASE_URL_FILE и оба S3 credential FILE смонтированы как secrets. S3_ENDPOINT, S3_BUCKET, MAX_UPLOAD_BYTES/MAX_IMAGE_PIXELS заданы в Compose; S3_REGION=us-east-1 берётся по умолчанию. Лимиты можно только уменьшить относительно обязательных максимумов. Дополнительный HOST_PORT — host-порт LB. Другие логические переменные примера не выдаются за изменяемые Compose-настройки.

Доказательства критериев

Каждый пункт ниже проверяется python3 scripts/run-all.py; отдельные команды для app/student-tests выполняются через docker compose exec -T api1 python ....

  • Целостность skeleton, OpenAPI: make check validate PYTHON=python внутри API. Обе проверки PASS — evidence/check-validate.txt. Контракт, README задания, COURSE, CONTRIBUTING и публичные tests не изменялись.
  • Минимум lab1–3 и обязательный lab4 API: make test PYTHON=python BASE_URL=http://lb:8080. PASS, включая PNG checksum, attachment-only message, второго участника, 404 для третьего, сессии, пагинацию, idempotency — evidence/smoke.txt.
  • Реальные PNG/JPEG, лимиты, MIME и filename: student-tests/acceptance.py. PASS: повреждённые bytes и подмена MIME → 415, >10 MiB и 42 млн пикселей → 413, опасные имена → 400, корректный JPEG скачивается без изменений — evidence/acceptance.json.
  • Чужой attachment_id и файл другого чата: тот же сценарий, 404. Неверный cursor, UUID, sender_id — 400; 12 одновременных idempotency повторов → 1 Message.
  • Потеря API загрузившей реплики: остановка каждой API с последующим download и записью через вторую. SHA-256/байты совпадают — evidence/replica-directions.json.
  • Публичный failover с параллельными POST: tests/resilience.py --mode failover с собственным hook. PASS; восстановление ≤10 секунд, нет дубликатов/потерь, остановленная реплика отсутствует в конце — evidence/failover.txt, evidence/after-failover.json и evidence/after-failover-started.txt.
  • Рестарт API и PostgreSQL/MinIO/LB: tests/resilience.py --mode persistence. PASS, прежняя сессия, сообщения и оригинал сохранены. evidence/persistence.txt, before-restart-started.txt / after-restart-started.txt доказывают изменение StartedAt всех пяти реальных контейнеров. Volumes не удалялись.
  • Отказ S3 и PostgreSQL: student-tests/storage_outage.py при реальной остановке зависимости управляющим скриптом. Live=200, ready/upload/download=503, reconciler прекращает работу, после возврата хранилища исходные bytes совпадают — evidence/s3-outage.json, evidence/postgres-outage.json.
  • Прерванная загрузка: raw TCP request с неполным Content-Length и закрытием соединения, отсутствие новых метаданных — evidence/acceptance.json.
  • Сбой PUT → SQL: student-tests/research.py временно ставит trigger на тестовый filename, реальный API PUT проходит, INSERT падает, HTTP 500 не раскрывает SQL, остаётся ровно один orphan. После grace он обнаруживается и удаляется — evidence/research.json. Trigger удаляется в finally; production failpoints нет.
  • RAM при ≥10 загрузках: отдельный генератор, 2 размера, по 3 серии × 10, 20 ms cgroup/RSS sampling обеих API и Docker CPU stats — evidence/uploads.json, evidence/memory-peaks.json, evidence/memory.json.
  • Private bucket, scoped S3 credentials, закрытая консоль: анонимный GET существующего объекта → 403; API-пользователь не может создать bucket — evidence/acceptance.json. Публикация только LB подтверждается compose.yaml и evidence/final-state.json. Bootstrap выполнен повторно без удаления данных; вывод — evidence/bootstrap.txt.
  • Законченный трек 2: dry-run не меняет orphan, apply удаляет старый orphan, свежий и используемый оригиналы сохраняются, повтор не повторяет удаление, missing не выдаётся как ready, неверная копия не публикуется, правильная восстанавливается с прежними bytes, >1000 объектов обходятся несколькими LIST — evidence/research.json. Стоимость измерена, ограничения приведены ниже.

Эксперименты и отказы

Гипотеза трека 2: shared/exclusive DB locks, повторная проверка и grace позволяют безопасно убрать неучтённые старые S3-объекты и пометить missing без удаления живых метаданных; повторный проход не порождает новые повреждения.

Методика: создать synthetic chat и ready-вложения, одно привязать к Message. Внедрить SQL-ошибку в реальный upload после PUT и отдельно удалить оригинал второго ready-вложения. Проверить fresh orphan до grace, выждать настоящие 62 секунды S3-времени, создать ещё один свежий orphan, сравнить dry-run/apply/repeat. Missing-метаданные искусственно состарены на 2 часа SQL-командой в тесте, S3 LastModified не подделывается. Затем проверить плохую/правильную резервную копию. Добавить 1005 fresh keys по одному байту для проверки LIST pagination, замерить время и число запросов, убрать только точные служебные ключи этого сценария. Используемое вложение сохраняется побайтно после каждого ремонта.

Результаты трека, нагрузки и памяти записаны отдельным воспроизводимым численным итогом в evidence/SUMMARY.md; исходные JSON остаются рядом. Это измерения конкретного локального стенда, а не обещание производительности.

Окружение: Docker Desktop Linux VM, 16 vCPU, 7 950 495 744 bytes RAM, API по 1 CPU / 512 MiB, /tmp по 64 MiB, PostgreSQL и MinIO по 512 MiB, LB 64 MiB. Host Python — 3.14.3, внутри контейнеров — 3.12.10. Перед тестами readiness подтверждена, изображения прогреваются одной загрузкой каждого размера. PNG генерируются из случайных RGB bytes (размеры приблизительно 0,75 MiB и 9,28 MiB; точные bytes в JSON). По 3 closed-loop burst-серии на размер, concurrency=10, всего 60 измеряемых успешных загрузок плюс 2 прогревочных. Генератор работает отдельным временным контейнером migrate, его RAM не входит в измеряемые API. Duration, successful RPS, errors и p50/p95/p99 каждой серии находятся в uploads.json. При n=10 p95 и p99 — максимальная задержка серии.

Память: memory-peaks.json содержит baseline, максимум memory.current с шагом 20 ms, RSS PID 1 и kernel memory.peak до/после. Последний — максимум за всё время жизни контейнера, включая предыдущие тесты; его нельзя выдавать за чистый пик только загрузок. Sampling может пропустить короткий всплеск. Небольшой probe работает в том же cgroup и добавляет собственный overhead. docker stats из memory.json содержит CPU и контрольный замер RAM с более редким шагом.

Отдельно tests/load.py --duration 30 --concurrency 4 измеряет POST messages, не изображения. JSON включает successful RPS, долю ошибок, p50/p95/p99 успешных ответов. Этот closed-loop тест имеет coordinated omission и ограничения клиента; не определяет максимальную мощность сервера. Запуски добавляют данные, поэтому размер набора растёт; для сравнения на чистом наборе нужен отдельный volume.

Отказы: API-восстановление ожидается за ≤10 секунд; public test подтвердил это. Рестарт всех сервисов сохраняет подтверждённые данные и действующий токен. S3/PostgreSQL outages честно дают 503 до ручного возврата зависимости, без обещания HA. Orphan исправляется только явным запуском после grace; missing требует backup. В эксперименте не потеряны подтверждённые сообщения или исходные bytes, кроме специально удалённого S3-объекта, который восстановлен из тестовой копии.

Ограничения и следующие шаги

Один host, один PostgreSQL, один MinIO и один LB — единые точки отказа. Нет репликации БД/S3, автоматических резервных копий и восстановления потерянного диска; API failover не доказывает устойчивость ко всем инфраструктурным отказам. HTTP допустим только локально с синтетическими данными; для удалённого показа нужен TLS. UI, presigned flow, thumbnail/worker lab5 не входят в выбранную работу.

Reconciler удерживает exclusive lock на время полного прохода, хранит метаданные и LIST в RAM: стоимость O(A+O), время LIST ≈ceil(O/1000), дополнительные HEAD только для кандидатов. Восстановление failed читает файл для проверки checksum. На большом bucket это мешает записи; statement/lock timeout ограничивает ожидание, но весь проход не имеет отдельного wall-clock SLA. Для production нужна пакетная сверка с журналом/lease, отдельными правами оператора и метриками. Этого улучшения данные опыта не доказывают. Внешний root-оператор S3 может обойти DB lock: ручное восстановление согласовывать с обслуживанием.

Сверка не ищет побитовую порчу уже ready-файлов и не удаляет корректные, но давно не привязанные вложения. Это сознательные границы orphan/missing-трека. Глобальная корректность конкурентной истории при коррекции часов не гарантируется: между страницами нет snapshot, поздний COMMIT может попасть до cursor. Expired sessions и неиспользуемые просроченные idempotency rows не очищаются периодическим job; это следующий эксплуатационный шаг, expiry при доступе действует. Попытки входа не rate-limit-ятся. Полная защита lab7 здесь не заявляется.

Источники и подготовка к защите

Развёрнутые ответы на все вопросы README, объяснение основных функций и порядок демонстрации — DEFENSE.md. Использование ИИ раскрыто выше; автору необходимо самостоятельно понимать код и уметь изменить его на защите.