Files
mtusi2026lab5-fork/REPORT.md
T

9.3 KiB
Raw Blame History

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

  • Автор, группа: Голиков А.П., БВТ2303
  • Целевая оценка; выбранный трек 5, если нужен: Оценка 5, Трек 2
  • Commit/PR: будет добавлено после публикации.
  • Использованные источники, библиотеки и помощь ИИ: Документация RabbitMQ (Publisher Confirms, DLX), документация Go (pgx, Gin), библиотека disintegration/imaging для ресайза, gen2brain/webp для WebP. При написании кода использовалась помощь ИИ для генерации boilerplate-кода и архитектурных консультаций.

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

Требования (Prerequisites):

  • Docker и Docker Compose (рекомендуется Docker Desktop).
  • Python 3.9+ (для запуска тестов).
  • OpenSSL (для генерации секретов, встроен в Git Bash).
  • ОС: Windows / Linux / macOS.

Быстрый старт (Bash / Git Bash): Для запуска стенда выполните следующие команды в корне проекта:

# 1. Создаем .env из шаблона
cp .env.example .env

# 2. Генерируем секреты и автоматически обновляем .env
chmod +x setup_secrets.sh
./setup_secrets.sh

# 3. Собираем и запускаем весь стенд
docker compose up -d --build

# 4. Ожидаем, пока все сервисы пройдут healthcheck
 Проверить статус: docker compose ps

Запуск тестов (Windows / PowerShell): Для корректной работы Python на Windows с кириллицей в JSON-контрактах необходимо указать кодировку UTF-8:


$env:PYTHONUTF8 = "1"
make test
# или
python -X utf8 tests/smoke.py

Безопасная остановка и удаление данных:


# Остановить контейнеры
docker compose stop

# Полностью удалить контейнеры и тома с учебными данными
docker compose down -v

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

[ Клиент ]
    │ POST /attachments (bytes)
    ▼
[ API (реплики) ] ───(1) быстрый sniff & DecodeConfig───> [ Проверка лимитов ]
    │
    ├──(2) PUT объект в S3 (prefix: staging/{id})
    │
    └──(3) BEGIN TX
           ├── INSERT INTO attachments (status='queued')
           └── INSERT INTO outbox (payload=JobMessage)
           COMMIT TX
    │
    ▼ HTTP 202 Accepted (статус queued)
    │
[ Outbox Publisher (горутина) ] ──(4) SELECT ... FOR UPDATE SKIP LOCKED──> [ PostgreSQL ]
    │
    ├──(5) Publish в RabbitMQ с Publisher Confirm
    └──(6) UPDATE outbox SET published_at = now()
    │
    ▼
[ RabbitMQ ] (Очередь attachments.process, durable)
    │
    ▼
[ Worker ] ──(7) ClaimForProcessing (status='processing', аренда 5 мин)
    │
    ├──(8) GET staging/{id} из S3
    ├──(9) Генерация вариантов: Thumbnail, Crop, Optimized(WebP)
    ├──(10) PUT оригинал и варианты в S3 (prefix: chats/{chat_id}/{id})
    ├──(11) BEGIN TX
    │        ├── UPDATE attachments SET status='ready'
    │        └── INSERT INTO attachment_variants
    │        COMMIT TX
    └──(12) ACK сообщения в RabbitMQ

Источник истины и транзакционные границы

Источник истины: PostgreSQL. Только база данных является авторитетным хранилищем состояний (queued, processing, ready, failed) и метаданных.

Транзакционные границы: Для преодоления проблемы «двойной записи» (Dual-Write) между базой данных и брокером сообщений используется паттерн Transactional Outbox. Запись INSERT attachments и INSERT outbox происходит в рамках одной ACID-транзакции PostgreSQL. Это гарантирует, что если клиент получил 202 Accepted, задача сохранена на диске и не будет потеряна, даже если RabbitMQ временно недоступен (Publisher дослать её при восстановлении).

Идемпотентность: Брокер гарантирует доставку at-least-once (минимум один раз). Защита от дублей реализована на уровне метода ClaimForProcessing (атомарный UPDATE ... WHERE status='queued'), а также через защиту pipeline_version в методе CompleteJob.

Что перенесено из lab4 и что изменено

Сохранено: Базовая структура БД (пользователи, чаты, сообщения), аутентификация (Bearer/Basic), идемпотентность создания сообщений, интерфейсы репозиториев.

Изменено:

    Отказ от синхронного ресайза: Метод Upload больше не делает полный image.Decode (который потреблял до 160 МБ RAM), теперь выполняется только быстрый image.DecodeConfig по заголовку.

    Код ответа: 201 Created заменен на 202 Accepted, так как обработка стала асинхронной.

    Staging: Оригинал при загрузке теперь сохраняется во временный префикс S3 (staging/), а не сразу в конечный (chats/).

    Состояния: Удален статус pending, добавлены queued и processing.

    Инфраструктура: Добавлены сервисы RabbitMQ и Worker. Появился фоновый процесс Outbox Publisher (внутри API) и Reconciler (сборка мусора и спасение зависших задач).

    Обработка: Добавлена генерация crop (128x128) и optimized (WebP до 1280x1280) с удалением метаданных.

Конфигурация и переменные (.env.example)

Переменные окружения разделены на логические блоки и передаются в контейнеры через compose.yaml:

API: APP_PORT, SESSION_TTL_SECONDS, API_REPLICAS (масштабирование).

Лимиты файлов: MAX_UPLOAD_BYTES (10 МБ), MAX_IMAGE_PIXELS (40 млн).

Outbox & Worker: OUTBOX_INTERVAL_MS (частота опроса таблицы outbox), WORKER_CONCURRENCY (количество параллельных обработчиков), JOB_MAX_ATTEMPTS (лимит попыток), JOB_TIMEOUT_SECONDS (лимит времени на одну картинку).

Инфраструктура: Строки подключения (DATABASE_URL, CACHE_URL, RABBITMQ_URL) и настройки S3/MinIO. Все пароли вынесены в Docker Secrets (генерация через setup_secrets.sh).

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make test TODO TODO
Остальные пункты уровня 3 TODO TODO TODO
Все пункты уровня 4, если заявлен TODO TODO TODO
Выбранный трек 5, если заявлен TODO TODO TODO

TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.

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

TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
TODO TODO TODO TODO

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

TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.