Files
mtusi2026lab4/REPORT.md
T
2026-10-20 17:24:32 +03:00

16 KiB
Raw Blame History

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

  • Автор, группа: Матвей Козырев, БВТ2301.
  • Целевая оценка: 3 — работающий минимум.
  • Ветка: solution/BVT2301-Kozyrev.
  • Проверки: 20 октября 2026 года. Базовый commit и SHA-256 исходников проверенного рабочего дерева — evidence/environment.json.
  • Использованные библиотеки: FastAPI, Uvicorn, asyncpg, argon2-cffi, boto3, Pillow. Помощь ИИ: Codex — перенос основы lab3, реализация вложений, тесты и документация.

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

Нужны Docker Engine с Compose v2, Python 3.12+ и свободный порт 8080.

python3 scripts/init-secrets.py
docker compose config --quiet
docker compose up -d --build --wait
curl --fail http://localhost:8080/health/ready
make test

init-secrets.py создаёт локальные случайные credentials в игнорируемом каталоге secrets/, не выводит значения и сохраняет существующие файлы при повторном запуске. .env не требуется для стандартного Compose: параметры и пути к secrets заданы в compose.yaml. Для переопределения TTL можно скопировать .env.example в .env. S3 endpoint, bucket и лимиты стандартного стенда заданы непосредственно в Compose; API_REPLICAS, SESSION_STORE и CACHE_URL_FILE из шаблона не управляют этой топологией. Реплик две, сессии в PostgreSQL, Redis не используется.

Последовательность запуска: PostgreSQL → migrate → API; SeaweedFS → s3-init → API; здоровые API → HAProxy. Миграции и bootstrap — одноразовые сервисы; их успешное состояние — Exited (0). Bucket messenger-attachments создаётся bootstrap-сервисом, ему устанавливается private ACL и удаляется публичная policy, если она существовала. Повторный bootstrap безопасен:

docker compose run --rm --no-deps s3-init

Вход только через http://127.0.0.1:8080. Порты PostgreSQL, API и SeaweedFS на host не публикуются. Остановка с сохранением данных: docker compose down; повторный запуск — docker compose up -d --wait. Намеренное удаление всех учебных данных lab4: docker compose down -v. Секреты следует сохранять вместе с volumes, иначе существующая БД может перестать принимать подключение.

Версии runtime и зависимостей закреплены в Dockerfile, pyproject.toml и uv.lock. Python контейнера — 3.12.12, uv — 0.11.28; boto3 — 1.43.115, Pillow — 13.0.0.

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

Клиент → HAProxy → api-a / api-b → PostgreSQL (метаданные)
                              → SeaweedFS S3 (оригиналы)
Роль / service Версия Готовность Persistent storage Доступ и credentials
API / api-a, api-b Python 3.12.12, исходники репозитория /health/ready: PostgreSQL SELECT + S3 HeadBucket Нет Внутренний 8080; DB URL, cursor secret, отдельные S3 credentials из файлов
PostgreSQL / postgres 17.6-alpine pg_isready postgres_data Внутренний 5432; password file
LB / load_balancer HAProxy 3.0.11-alpine readiness API, активные backend checks Нет Host 127.0.0.1:8080
S3 / s3 SeaweedFS 4.17, digest в Compose master cluster status; bootstrap дополнительно проверяет S3 s3_data: файлы и LevelDB filer Внутренний 8333; identity config из secret
Bootstrap / s3-init Тот же Python-образ exit 0 Нет Отдельные административные S3 credentials

SeaweedFS закреплён digest sha256:186de7ef977a20343ee9a5544073f081976a29e2d29ecf8379891e7bf177fbe9. Настройка filer LevelDB в infra/filer.toml сохраняет его метаданные в /data/filer на том же volume. S3 identity api имеет Read/Write/List для одного bucket; anonymous identity отсутствует. Административные credentials доступны bootstrap, но не API. Внутренняя Docker-сеть считается доверенной; это не защита от компрометации контейнера.

Лимиты Compose: каждая API — 0,5 CPU / 512 MiB; PostgreSQL — 0,75 CPU / 512 MiB; SeaweedFS — 1 CPU / 512 MiB; HAProxy — 0,25 CPU / 128 MiB. Это учебный стенд на одном Docker-host, без высокой доступности БД, S3, LB и самого host.

Перенос lab3 и модель вложений

Из lab3 сохранены пользователи, чаты, общие PostgreSQL-сессии, Argon2 password hashing, keyset-пагинация, подпись cursor общим ключом, X-Request-Id, X-Instance-Id, идемпотентность сообщений и две реплики за HAProxy. Исходные публичные tests/ и contracts/ lab4 не изменены.

Миграция 004_attachments.sql добавляет таблицу Attachment: ID, чат, владелец, отображаемое имя, MIME, размер, SHA-256, внутренний object key и время. Байты в PostgreSQL не записываются. messages.attachment_ids — массив UUID, по умолчанию пустой. При создании сообщения в одной транзакции проверяются членство в чате и принадлежность всех вложений этому чату, затем записываются сообщение и результат идемпотентности. У массива нет отдельного внешнего ключа: связь проверяет приложение; удаления вложений и изменения состава чата в API нет.

Пустой текст разрешён только с вложением. Пропущенное attachment_ids и [] эквивалентны; hash текстовых сообщений сохранён совместимым с lab3. Для сообщения с вложениями hash также включает упорядоченный список нормализованных UUID. История и повтор POST возвращают те же attachment IDs.

Загрузка и скачивание

attachments.py принимает raw PNG/JPEG. Сначала проверяются Bearer-сессия и членство в чате. filename не используется как путь; запрещены /, \, управляющие символы и недопустимая длина. Сервер генерирует ключ originals/<UUID>.

Лимит 10 MiB = 10 × 1024 × 1024 = 10 485 760 байт проверяется по Content-Length и повторно при чтении каждого блока, в том числе для chunked upload. До декодирования Pillow определяет фактический формат и размеры; максимум 40 000 000 пикселей. Проверяются целостность PNG и декодирование пикселей PNG/JPEG. MIME должен совпадать с содержимым. Анимированный PNG не поддерживается: ответ 415.

Во время приёма используется удаляемый временный файл; он не является хранилищем оригиналов и не используется при скачивании. На одну API-реплику допускается одна одновременная загрузка/проверка изображения, ожидание вместе с загрузкой ограничено 30 секундами. SDK и декодирование выполняются вне event loop. S3 connect timeout — 2 с, read timeout — 5 с, автоматические повторы выключены. Это ограничения отдельного запроса, не доказательство устойчивости при произвольной нагрузке.

Порядок фиксации: валидация → S3 PUT → INSERT метаданных PostgreSQL → 201, status=ready, variants=[], error_code=null. GET метаданных и оригинала снова проверяет членство. Для постороннего — 404; без сессии — 401. GET content читает оригинал из S3, проверяет размер и SHA-256 и возвращает байты через API без redirect. Object key и credentials не входят в публичную модель.

Недоступность S3: upload/download и readiness возвращают 503 в формате Error; liveness остаётся 200. HAProxy исключает unready backend, поэтому при недоступности обеих реплик сам LB может вернуть собственный 503. Проверка формата ошибки API при таком отказе выполняется напрямую внутри Docker-сети.

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

Для собственных image-тестов и полной OpenAPI-валидации нужны локальные зависимости:

uv sync --frozen
uv pip install -r requirements-dev.txt
make check validate PYTHON=.venv/bin/python
make test
make test-attachments PYTHON=.venv/bin/python
python3 student-tests/idempotency_concurrency.py
python3 student-tests/review_regressions.py
make test-private
make test-upload-failover
make test-s3-outage
python3 scripts/verify-persistence.py
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
docker compose start api-a api-b

Сценарии отказов выполняются последовательно на учебном стенде: они временно останавливают контейнеры. Собственные проверки возвращают остановленные сервисы в работу; публичный test-failover оставляет реплику остановленной, поэтому последняя команда нужна для восстановления. Все данные синтетические, токены не сохраняются. Тесты добавляют данные; автоматического удаления нет.

Критерий Команда / наблюдение Результат
Структура и OpenAPI make check validate PYTHON=.venv/bin/python PASS
Обязательный API lab4, checksum, ACL make test PASS
PNG/JPEG, сообщение с вложением, чужой чат, неверный MIME/filename, лимиты, chunked make test-attachments PYTHON=.venv/bin/python PASS
Приватность bucket вне API make test-private: anonymous GET существующего объекта → 403 PASS
Отказ именно загрузившей API make test-upload-failover: загрузка через api-b, остановка api-b, те же байты через другую реплику PASS
Недоступность S3 make test-s3-outage: 503, восстановление, прежний оригинал PASS
Перезапуск всех компонентов, сохранение действующей сессии, метаданных и файла python3 scripts/verify-persistence.py; StartedAt каждого сервиса изменился PASS
Публичный failover, сообщения без дублей и сохранение файла make test-failover ACTION_SCRIPT=scripts/stop-one.sh Результат
Конкурентная идемпотентность и регрессии lab3 Собственные проверки lab3 Результат
Повторный bootstrap bucket docker compose run --rm --no-deps s3-init Результат

Точные границы проверены отдельно: PNG с trailing bytes доведён до 10 485 760 байт и скачан без изменений; PNG 8000 × 5000 = 40 000 000 пикселей принят; заголовок 8001 × 5000 = 40 005 000 пикселей отклонён до декодирования. Это функциональные тесты, не исследование RPS или памяти уровня 4/5.

Ограничения

  • Между S3 PUT и COMMIT PostgreSQL нет общей транзакции. Сбой после PUT может оставить orphan object. Автоматическая сверка/очистка с grace period относится к следующему уровню и здесь не реализована. При неопределённом исходе COMMIT объект намеренно не удаляется, чтобы не повредить возможную подтверждённую запись.
  • API буферизует скачивание не более 10 MiB, чтобы проверить checksum до ответа. Ограничение общего количества скачиваний и нагрузочный эксперимент для 10 одновременных upload не выполнены; оценка 4 не заявляется.
  • Readiness проверяет доступность БД и bucket, но не наличие каждого отдельного объекта. Потеря одного объекта при доступном S3 обнаруживается при скачивании как 503.
  • Перезапуск с volumes и отказ API подтверждены на одном Docker-host. Потеря volumes/host не покрывается, резервное копирование не реализовано.
  • HTTP предназначен для локального учебного стенда. Presigned flow, обработка thumbnail и брокер не реализованы.

Источники