16 KiB
Отчёт — лабораторная 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 и брокер не реализованы.
Источники
- Контракт API, OpenAPI, критерии задания.
- SeaweedFS исходники и запуск, релиз 4.17. Параметры закреплённого образа дополнительно проверены через
docker run --rm chrislusf/seaweedfs:4.17 server -help. - Pillow Image API: lazy open, размеры, verify/load и decompression bomb limits.
- Boto3 S3 PutObject: запись оригинала в S3.