Files
mtusi2026lab4/REPORT.md
drunkdiente 935307d412 Реализовать ЛР4: S3-хранилище и вложения на оценку 3
Стенд: PostgreSQL 16 + две API-реплики за HAProxy + SeaweedFS S3 в приватном bucket. Метаданные вложений в PostgreSQL, байты в S3, object key назначает сервер. Лимиты 10 MiB и 40 млн пикселей, MIME по магическим байтам, проверка filename. Добавлены smoke/негативные тесты, хуки restart/stop-one, сценарий отказа S3 и отчёт с доказательствами.
2026-11-08 14:29:02 +03:00

20 KiB
Raw Permalink Blame History

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

  • Автор, группа: Ким Владимир, БВТ2302
  • Целевая оценка; 3
  • Commit/PR: ветка solution/bvt2302-kim; PR в исходный репозиторий открывается после push.
  • Использованные источники, библиотеки и помощь ИИ: контракт и рубрика репозитория; документация S3 (upload/presigned), SeaweedFS (S3 gateway, s3.json identities), boto3/botocore, psycopg 3, Pillow, HAProxy.

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

Версии закреплены:

Роль Образ Версия
API python:3.12.7-slim-bookworm (digest sha256:60d9996b6a8a3689d36db740b49f4327be3be09a21122bd02fb8895abb38b50d) + requirements.txt boto3 1.35.36, Pillow 11.0.0, psycopg 3.2.3, psycopg_pool 3.2.3
PostgreSQL postgres:16.4-alpine 16.4
S3 chrislusf/seaweedfs:3.71 3.71
Load balancer haproxy:3.0.8-alpine 3.0.8
# 1. Локальная конфигурация: секреты только в .env, файл в Git не попадает.
cp .env.example .env
# Отредактировать пароли/секреты. Для локального стенда достаточно синтетических значений.

# 2. Проверка структуры и конфигурации Compose.
python scripts/check_contract.py
python scripts/validate_openapi.py          # требует requirements-dev.txt
# На Windows глобальный Python может не иметь openapi-spec-validator;
# полная валидация выполнялась интерпретатором из .venv:
#   .\.venv\Scripts\python.exe scripts/validate_openapi.py
docker compose --env-file .env config --quiet

# 3. Сборка и запуск. Bucket создаёт one-shot контейнер `bootstrap`; схему
#    PostgreSQL мигрирует каждая API-реплика при старте (идемпотентно, под
#    advisory lock).
docker compose --env-file .env up -d --build

# 4. Готовность (PostgreSQL + S3). LAB4_PORT по умолчанию 8080;
#    на машине автора порт 8080 занят стендом lab3, поэтому в .env стоит 8081.
curl -fsS http://127.0.0.1:8081/health/ready

# 5. Публичный smoke и собственные проверки.
python tests/smoke.py --base-url http://127.0.0.1:8081
python -m unittest discover -s student-tests -v
python student-tests/test_api_negative.py --base-url http://127.0.0.1:8081

# 6. Сценарии отказов (явные, останавливают инфраструктуру).
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8081
python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://127.0.0.1:8081
python scripts/evidence_s3_outage.py

scripts/restart.sh / scripts/stop-one.sh — POSIX-варианты для Linux/macOS (chmod +x нужен перед запуском). scripts/restart.cmd / scripts/stop-one.cmd — эквиваленты для Windows: тест запускает hook без shell interpolation, поэтому на Windows нужен исполняемый файл с расширением .cmd.

Безопасная остановка (данные сохраняются):

docker compose --env-file .env stop

Намеренное удаление учебных данных (необратимо, только для локального стенда):

docker compose --env-file .env down -v

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

клиент ──HTTP──> HAProxy :8080 ──> api1:8080 ─┐
                     │                        ├──> PostgreSQL (users, chats, members,
                     └────────> api2:8080 ────┘     messages, attachments, idempotency)
                                              └──> SeaweedFS S3 :8333 (приватный bucket,
                                                   только байты изображений)
  • Источник истины — PostgreSQL. Метаданные вложения (id, chat_id, owner_id, filename, content_type, size_bytes, sha256, object_key, status, variants, error_code, таймстемпы) хранятся только там. Байты — только в приватном bucket; локального каталога с оригиналами у API нет.
  • Object key назначает сервер: chats/<chat_id>/<attachment_id>/original. filename — только отображаемое имя, в путь/ключ не попадает.
  • Транзакционные границы. Upload: проверка доступа и лимитов → проверка изображения → PUT в S3 → INSERT метаданных в PostgreSQL. Если INSERT не удался, объект удаляется компенсацией (app/server.py, _upload_attachment), поэтому неучтённых объектов не остаётся. Обратный случай (метаданные без объекта) виден как 404 на download и не превращается в 500.
  • 201 ready возвращается только после успешной записи объекта и метаданных, то есть когда оригинал действительно доступен любой реплике.
  • Идемпотентность сообщений. Таблица idempotency(user_id, chat_id, key) + транзакционный advisory lock по SHA-256 области уникальности; сообщение и запись результата создаются в одной транзакции, повтор с другим body — 409.
  • Сессии. Непрозрачный токен (32 случайных байта, base64url), в БД только SHA-256 токена и expiry. TTL — SESSION_TTL_SECONDS (по умолчанию 3600).
  • Пароли — scrypt (N=2^14, r=8, p=1) с солью, сравнение hmac.compare_digest; для неизвестного username выполняется фиктивная проверка, чтобы не выдавать существование пользователя по времени.
  • Курсоры пагинации — HMAC-подписанный base64url JSON с (created_at, id) и привязкой к ресурсу (kind, chat_id); чужой/испорченный курсор — 400.
  • Readiness. /health/ready проверяет PostgreSQL и S3, потому что обязательный синхронный путь включает скачивание оригинала. При недоступности S3 реплики исключаются из LB, клиент получает 503; это осознанный выбор, зафиксированный в app/server.py.
  • Лимиты. Content-Length/chunked чтение ограничены MAX_UPLOAD_BYTES (10 MiB) до чтения тела; MIME проверяется по магическим байтам, число пикселей — по заголовку изображения до полного декодирования (MAX_IMAGE_PIXELS = 40 млн). Полное тело ограничено 10 MiB, поэтому RAM одной загрузки ограничена сверху; download идёт чанками по 64 KiB.
  • Инфраструктура. SeaweedFS запускается одним процессом weed server с master/volume/filer/S3. Административная идентичность (S3_ADMIN_*) используется только one-shot bootstrap; API использует отдельную идентичность с действиями Read/Write/List/Tagging. Bucket создаётся идемпотентно (app/bootstrap_s3.py: head_bucket → create_bucket, повторный запуск безопасен). Порт S3 и внутренние порты API не публикуются на хост; наружу открыт только LB (loopback).
  • LB. HAProxy в режиме HTTP с option http-server-close: без него клиентские keep-alive соединения закреплялись за одной репликой и roundrobin не наблюдался. Имена реплик разрешаются через DNS Docker (resolvers docker, init-addr none) с периодическим переразрешением: иначе HAProxy запоминал IP, полученный при одновременном старте, и после пересоздания контейнера мог ходить не туда. timeout connect 500ms, retries 2, option redispatch и частые health-check дают переключение на живую реплику за единицы секунд.

Соответствие переменных .env.example реальной конфигурации:

Переменная Где используется
APP_HOST, APP_PORT адрес прослушивания API (app/config.py)
DATABASE_URL строка подключения psycopg (в Compose собирается из POSTGRES_*)
POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB сервис PostgreSQL и сборка DATABASE_URL
S3_ENDPOINT, S3_REGION, S3_BUCKET клиент S3 и bootstrap
S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY идентичность API в s3.json SeaweedFS
S3_ADMIN_ACCESS_KEY_ID, S3_ADMIN_SECRET_ACCESS_KEY идентичность one-shot bootstrap
SESSION_TTL_SECONDS, IDEMPOTENCY_TTL_SECONDS TTL сессий и окно идемпотентности
MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS лимиты загрузки
CURSOR_SECRET HMAC-подпись курсоров, одинаковый у всех реплик
LAB4_PORT host-порт LB (по умолчанию 8080, у автора 8081)

Приложение также поддерживает *_FILE-варианты секретов (DATABASE_URL_FILE, S3_SECRET_ACCESS_KEY_FILE и т.д.) на случай запуска вне Compose.

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Офлайн-структура контракта python scripts/check_contract.py PASS: offline skeleton structure... evidence/check-contract.txt
Полная валидация OpenAPI 3.1 python scripts/validate_openapi.py (после requirements-dev.txt) PASS: full OpenAPI 3.1 and JSON Schema validation evidence/validate-openapi.txt
Compose-конфигурация docker compose --env-file .env config --quiet exit 0, ошибок нет вывод команды в логе работы
Публичный smoke (health, users, sessions, chats, messages, pagination, idempotency, upload/download, SHA-256, чужой доступ, logout) python tests/smoke.py --base-url http://127.0.0.1:8081 PASS: lab4 public API scenario evidence/smoke.txt
S3-сервер в общем стенде, приватный bucket docker compose ps; python scripts/verify_private_bucket.py (внутри сети) объекты в bucket есть; анонимный GET объекта — 403, анонимный list — 403 evidence/docker-ps.txt, evidence/private-bucket.txt
Метаданные в PostgreSQL, байты не в БД/локальном каталоге \d attachments; поиск файлов в контейнере API таблица attachments без BLOB-колонок; в /app только код, оригиналов нет evidence/db-schema.txt
201 ready после сохранения; побайтное скачивание PNG и JPEG smoke + student-tests/test_api_negative.py status=ready, SHA-256 и размер совпадают, скачанные байты идентичны; отдельный сценарий реального JPEG 640×480 проходит загрузку и скачивание evidence/smoke.txt, evidence/negative.txt
Message с attachment_ids читается участниками чата student-tests/test_api_negative.py (сценарий attachment_ids survive message history) элемент истории совпадает с ответом POST, attachment_ids сохранены evidence/negative.txt
PNG/JPEG ≤10 MiB и ≤40 млн пикселей; MIME по содержимому; опасные filename; лимиты до декодирования python student-tests/test_api_negative.py --base-url ... 12/12 сценариев PASS: 413 на размер и пиксели, 415 на битый файл/подмену MIME, 400 на /, \, NUL, LF evidence/negative.txt
Чужой чат и чужое вложение smoke (eve → 404), test_api_negative.py 404 на метаданные и bytes, 404 при привязке вложения другого чата, сообщение не создаётся evidence/smoke.txt, evidence/negative.txt
Upload → остановка обслужившей реплики → download через другую tests/resilience.py --mode failover --action-script scripts/stop-one.cmd 2 реплики до отказа, 112 успешных записей, 0 неопределённых ошибок, восстановление 2.33 с, остановленная реплика не обслуживает, вложение скачано через другую evidence/failover.txt
Restart стенда с сохранением volumes tests/resilience.py --mode persistence --action-script scripts/restart.cmd сессия и данные живы, оригинал скачан побайтно после рестарта всех сервисов evidence/persistence.txt
Недоступность S3 python scripts/evidence_s3_outage.py readiness 503, upload/download 503 (в т.ч. JSON unavailable с X-Request-Id от реплики), после старта S3 оригинал идентичен evidence/s3-outage.txt
Unit-проверки валидаторов python -m unittest discover -s student-tests -v 6 тестов OK (пароли, курсоры, изображения, filename) evidence/unit-tests.txt

Дополнительно: make test BASE_URL=http://127.0.0.1:8081, make test-negative, make student-tests — те же сценарии через Makefile. make check требует UTF-8 режим Python на Windows (PYTHONUTF8=1), иначе contracts/openapi.json читается в cp1251. На машине автора make не установлен, поэтому все результаты выше получены прямыми командами из блока «Запуск из чистого clone»; цели Makefile — эквивалентные обёртки для POSIX-окружения.

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

Аппаратура: AMD Ryzen 7 7700 (8C/16T), 31.1 GiB RAM, Docker Desktop 29.4.3, Windows 11. Лимиты CPU/RAM контейнерам не задавались (учебный локальный стенд). Данные синтетические.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker stop обслужившей API-реплики во время потока POST LB уводит трафик на вторую реплику, подтверждённые сообщения не теряются, дублей нет 2 реплики наблюдались до отказа; 112 успешных записей за 15 с, 0 ошибок; первая успешная запись после старта hook — 2.33 с; остановленная реплика отсутствует в последних ответах. В более ранних прогонах (до настройки timeout connect/health-check) было 58–59 записей и 2–4 ошибки переходного периода, дублей не возникало ни разу восстановление 2.3 с (ранее 5.3–7.4 с); потерь подтверждённых данных нет
Рестарт postgres, seaweedfs, haproxy, api1, api2 с теми же volumes сессия, чат, сообщения, метаданные и оригинал сохраняются PASS: persistence preserved confirmed data and existing session; download после рестарта побайтно совпал простой на время рестарта (~10–20 с); потерь нет
Остановка S3 (docker stop lab4-seaweedfs) attachment endpoints отвечают 503, метаданные остаются, данные не теряются LB /health/ready → 503; upload и download → 503; прямой запрос к реплике: метаданные 200, content 503 с error_code=unavailable; после старта S3 оригинал идентичен после старта S3 готовность вернулась; потерь нет
Повторная загрузка с тем же Idempotency-Key и другим body 409 без второго сообщения 409 conflict в smoke —

Ограничения измерений: отдельный нагрузочный эксперимент (RPS/p50/p95/p99, пик RAM при ≥10 одновременных загрузках) не проводился, так как он относится к уровню 4. Числа failover — это наблюдения нескольких локальных прогонов, а не гарантия SLA: LB, PostgreSQL и S3 развёрнуты на одном Docker-host, поэтому потеря хоста не выдерживается.

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

  • Заявлен и реализован уровень 3. Инженерно закрыты отдельные практики уровня 4 (компенсация при сбое между S3 и PostgreSQL, отдельная ограниченная идентичность API, проверка приватности bucket, расширенные негативные тесты), но полный уровень 4 не заявляется: нет документированного reconciler с grace period и эксперимента с ≥10 одновременными загрузками и измерением пика RAM.
  • Изображение читается в память целиком, но не более 10 MiB на запрос; потоковая обработка тела загрузки и вынесение декодирования в отдельный процесс — следующий шаг.
  • Rate limiting (429) не реализован: схема допускает код, но рубрика уровня 3 его не требует.
  • Сессии хранятся в PostgreSQL; отдельный Redis/Valkey не используется.
  • Один Docker-host: отказ диска/host/сети не выдерживается; HA PostgreSQL и LB не заявляются.
  • Компенсация покрывает сбой между PUT в S3 и COMMIT в PostgreSQL. Полная сверка «БД ↔ S3» (reconciler с dry-run и grace period) — трек 2 уровня 5, он не реализован.
  • Ключи и пароли в .env — синтетические локальные значения; .env в Git не попадает.