Files
mtusi2026lab5-fork/REPORT.md
T

150 lines
9.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
Отчёт — лабораторная 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):**
Для запуска стенда выполните следующие команды в корне проекта:
```sh
# 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:
```powershell
$env:PYTHONUTF8 = "1"
make test
# или
python -X utf8 tests/smoke.py
```
Безопасная остановка и удаление данных:
```sh
# Остановить контейнеры
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: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.