From de686d1956c4f2e47184eb4b8958ef52b0943e04 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=93=D0=BE=D0=BB=D0=B8=D0=BA=D0=BE=D0=B2=20Maximillian?= =?UTF-8?q?=20=D0=90=D0=BD=D1=82=D0=BE=D0=BD?= Date: Fri, 13 Nov 2026 13:12:32 +0300 Subject: [PATCH] docs(lab5): add initial report structure, setup guide and architecture diagram --- REPORT.md | 126 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 119 insertions(+), 7 deletions(-) diff --git a/REPORT.md b/REPORT.md index e98f75e..3498125 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,17 +1,129 @@ -# Отчёт — лабораторная 5 + Отчёт — лабораторная 5 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор, группа: Голиков А.П., БВТ2303 +- Целевая оценка; выбранный трек 5, если нужен: Оценка 5, Трек 2 +- Commit/PR: будет добавлено после публикации. +- Использованные источники, библиотеки и помощь ИИ: Документация RabbitMQ (Publisher Confirms, DLX), документация Go (pgx, Gin), библиотека `disintegration/imaging` для ресайза, `gen2brain/webp` для WebP. При написании кода использовалась помощь ИИ для генерации boilerplate-кода и архитектурных консультаций. ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +**Требования (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). + -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab4, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. ## Доказательства критериев