Files
mtusi2026lab5-fork/REPORT.md
T

13 KiB
Raw Blame History

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

  • Автор, группа: Гадяцкий Л. Е., БПИ2302
  • Целевая оценка: 3
  • Commit/PR: solution/BPI2302-Gadiatskiy
  • Использованные источники и библиотеки:
    • контракт и семантика: contracts/openapi.json, contracts/README.md, contracts/attachment-states.md, README.md, COURSE.md
    • перенос из lab4: FastAPI, PostgreSQL/сессии, SQLAlchemy, миграции, Nginx LB, идемпотентность, MinIO/S3, вложения
    • runtime: FastAPI 0.115.6, Uvicorn 0.34.0, Pydantic 2.10.4, SQLAlchemy 2.0.36, psycopg 3.2.4, argon2-cffi 23.1.0, boto3 1.35.76, Pillow 11.0.0, pika 1.3.2
    • PostgreSQL: postgres:16-alpine; LB: nginx:1.27-alpine; S3/MinIO: alpine/minio:RELEASE.2025-10-15T17-29-55Z; broker: rabbitmq:3.13.7-alpine
  • Помощь ИИ использована при переносе lab4, частичной реализации брокера/worker-а и при заполнении отчёта. Результаты подтверждаются сохранёнными запусками.

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

Prerequisites: Docker и Docker Compose. Python 3.9+ нужен только для публичных проверок (make check / make test / tests/resilience.py). Runtime приложения — внутри образа.

Версии:

  • API/worker: базовый образ python:3.12.8-slim-bookworm → локальный mtusi-messenger:lab5
  • PostgreSQL: postgres:16-alpine
  • Nginx: nginx:1.27-alpine
  • MinIO: alpine/minio:RELEASE.2025-10-15T17-29-55Z (community image; официальный minio/minio с Docker Hub недоступен)
  • RabbitMQ: rabbitmq:3.13.7-alpine
  • зависимости: requirements.txt

Конфигурация: секретов в Git нет. Локальный .env создаётся из примера и не коммитится:

cp .env.example .env

Соответствие .env.example:

  • APP_HOST / APP_PORT — bind uvicorn внутри контейнеров API
  • HOST_PORT — порт LB на host (по умолчанию 8080; если занят — например 8085)
  • APP_ENV — среда запуска (lab)
  • SESSION_TTL_SECONDS — TTL сессии (по умолчанию 3600; для обычного smoke ≥ 300)
  • SESSION_STORE=postgres — сессии в PostgreSQL (общие для всех реплик)
  • DATABASE_URL — строка подключения API/migrate/worker к PostgreSQL в compose-сети
    (приложение также поддерживает DATABASE_URL_FILE)
  • IDEMPOTENCY_TTL_SECONDS — срок хранения идемпотентных записей (по умолчанию 86400)
  • API_REPLICAS=2 — в compose.yaml зафиксированы сервисы api1 и api2
  • S3_ENDPOINT / S3_REGION / S3_BUCKET — доступ API/worker к MinIO в compose-сети
  • S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY — учебные credentials MinIO (также *_FILE)
  • MAX_UPLOAD_BYTES=10485760, MAX_IMAGE_PIXELS=40000000 — лимиты загрузки/декодирования
  • BROKER_URL — AMQP URL RabbitMQ (также BROKER_URL_FILE)
  • WORKER_CONCURRENCY — prefetch consumer worker (по умолчанию 2)
  • JOB_MAX_ATTEMPTS=5 — лимит управляемых попыток обработки
  • JOB_TIMEOUT_SECONDS, STAGING_RETENTION_SECONDS — параметры эксплуатации (зафиксированы в .env)

Учебные credentials compose (messenger / messenger, MinIO minioadmin / minioadmin, RabbitMQ messenger / messenger) только для локального синтетического стенда.

Сборка и запуск:

docker compose --env-file .env up -d --build

Миграции migrations/*.sql применяет one-shot сервис migrate до старта api1/api2/worker (учёт в schema_migrations). Приватный bucket S3_BUCKET идемпотентно создают API и worker при старте (ensure_bucket). Реплики API миграции SQL при старте не выполняют.

Готовность через LB (подставьте свой HOST_PORT):

curl -i http://127.0.0.1:8080/health/ready

Ожидается HTTP 200, тело {"status":"ok"}, заголовки X-Request-Id и X-Instance-Id (api1 или api2). /health/ready требует доступности PostgreSQL, S3 (MinIO) и RabbitMQ.

Публичный smoke (при уже запущенном стенде):

python tests/smoke.py --base-url http://127.0.0.1:8080
# или: make test BASE_URL=http://127.0.0.1:8080

Проверка сохранности (включая исходный файл вложения):

# Unix:
chmod +x scripts/restart.sh
python tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080

# Windows:
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8080

Hook выполняет docker compose --env-file .env restart для postgres, s3, broker, api1, api2, worker, lb без удаления volumes (down -v не используется).

Проверка отказа одной API-реплики:

# Unix:
chmod +x scripts/stop-one.sh
python tests/resilience.py --mode failover --action-script scripts/stop-one.sh --base-url http://127.0.0.1:8080

# Windows:
python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://127.0.0.1:8080

TARGET_INSTANCE_ID = X-Instance-Id (api1/api2); hook делает docker compose stop только этой реплики и оставляет её остановленной. После теста: docker compose --env-file .env start api1 (или api2). Для защиты повторить на второй реплике после восстановления первой.

Демо остановки worker (уровень 3):

docker compose --env-file .env stop worker
# upload → 202 queued; GET /content → 409; сообщение с attachment_ids допускается
docker compose --env-file .env restart api1 api2
docker compose --env-file .env start worker
# опросить GET /attachments/{id} до ready; thumbnail доступен

Остановка:

docker compose --env-file .env down

Намеренное удаление учебных данных (volumes):

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

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

HTTP-клиент
  → lb (Nginx)
      → api1 / api2 (uvicorn + FastAPI)
          → PostgreSQL
             users, chats, chat_members, messages, message_attachments,
             attachments (+ staging_object_key), attachment_jobs,
             attachment_variants, sessions, idempotency_records
          → MinIO (S3)
             staging/{chat_id}/{attachment_id}
             attachments/{chat_id}/{attachment_id}/original
             attachments/{chat_id}/{attachment_id}/variants/thumbnail.jpg
          → RabbitMQ (durable queue attachment.process)
      → worker (отдельный процесс)
          читает staging → пишет final original + thumbnail → status=ready → ack
  • Источник истины для метаданных — PostgreSQL; байты — только в S3. В сообщениях брокера только ID/служебные поля по jobs.schema.json, без bytes и credentials.
  • До 202: оригинал в durable staging (S3), запись attachments со status=queued, запись attachment_jobs, затем publish с publisher confirm. Остановка API после ответа не удаляет принятую работу.
  • Worker отделён от API: переносит оригинал в конечный S3-prefix, строит JPEG thumbnail (вписан в 256×256, без увеличения; EXIF orientation; alpha на белый). Fixture 320×200 → 256×160.
  • Состояния queued/processing/ready/failed видны в API. GET .../content для queued/processing/failed → 409; отсутствующий variant у ready → 404.
  • Сообщение может ссылаться на queued/processing вложение; failed → 409.
  • Retry ограничен JOB_MAX_ATTEMPTS (по умолчанию 5); исчерпание → failed/retry_exhausted. Повтор уже ready-задачи — no-op с ack; variant thumbnail не размножается.
  • Ack — после устойчивой записи результата; delivery at-least-once (persistent messages, durable queue, manual ack).
  • Сессии в PostgreSQL; X-Instance-Id стабилен на жизнь процесса; Idempotency-Key на POST сообщений сохранён из lab3/lab4.
  • Compose: lb + api1 + api2 + worker + postgres + s3 + broker + migrate, volumes pgdata, miniodata, brokerdata.

Перенесено из lab4: auth Basic→Bearer, Argon2id, чаты/сообщения, LB, две реплики, идемпотентность, MinIO, upload/download.
Изменено в lab5: upload 201/ready → 202/queued; staging + jobs; RabbitMQ; worker; thumbnail variant; link queued вложений.

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke (202 → ready, thumbnail 256×160) python tests/smoke.py --base-url http://127.0.0.1:8085 PASS: lab5 public API scenario... evidence/smoke.txt
Стенд: ≥2 API, LB, Postgres, MinIO, broker, worker docker compose --env-file .env ps lb, api1, api2, postgres, s3, broker, worker; migrate Exited 0 evidence/compose-ps.txt
Persistence: рестарт без удаления volumes python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8085 PASS: persistence preserved... evidence/restart.txt
Failover: остановка одной API-реплики python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://127.0.0.1:8085 failover PASS; first_recovery_seconds≈2.89 evidence/failover.txt
Worker stop → upload 202 → restart API → start worker → ready python evidence/worker_stop_demo.py upload queued; content 409; после старта worker — ready + thumbnail 256×160 evidence/worker-stop.txt

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

Для оценки 3 отдельный нагрузочный трек не выполнялся. Проверены сохранность (БД+S3+broker), отказ API-реплики и остановка worker:

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker compose --env-file .env restart (postgres+s3+broker+api1+api2+worker+lb), volumes сохранены /health/ready ok; прежний Bearer; тот же оригинал по /content persistence PASS в бюджете теста; потери данных нет
docker compose stop одной API-реплики LB обслуживает живую реплику failover PASS; first_recovery_seconds≈2.89 подтверждённые сообщения на месте
docker compose stop worker → upload → restart API → start worker 202 queued сохраняется; после worker — ready/thumbnail demo PASS; attachment 49100060-... стал ready сообщение в durable queue пережило остановку worker; потери нет

Локальная проверка автора выполнялась на HOST_PORT=8085. На Windows для публичных тестов задайте PYTHONUTF8=1 (иначе чтение contracts/openapi.json может упасть на cp1251).

Аппаратный профиль: локальный Docker Desktop на Windows; 2 API + worker + Nginx + PostgreSQL + MinIO + RabbitMQ без CPU/RAM limits.

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

  • transactional outbox, DLQ/replay, crop/optimized WebP, lease зависшего processing — не реализованы (уровень 4).
  • Единственный PostgreSQL, MinIO, RabbitMQ и Nginx — SPOF; отказ host/узла не выдерживается.
  • При сбое между COMMIT задания и publisher confirm возможна запись queued без сообщения в брокере до ручного вмешательства.
  • Basic по HTTP допустим только на локальном учебном стенде с синтетическими данными.