From 5175ccb676130f0c7c402588dbf09a5a6353f227 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 22:14:09 +0300 Subject: [PATCH] docs(lab5):final --- .github/pull_request_template.md | 68 ++++++++++++++++++----- REPORT.md | 92 ++++++++++++++++---------------- 2 files changed, 101 insertions(+), 59 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 7d1ff4a..b6f7683 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,18 +1,58 @@ ## Лабораторная 5 -Автор / группа: TODO -Целевая оценка (3/4/5): TODO -Трек 5, если заявлен: TODO +Автор / группа: Голиков А.П., БВТ2303 +Целевая оценка (3/4/5): 5 +Трек 5, если заявлен: Трек 2 (Доказанная идемпотентность pipeline) -Что реализовано и что перенесено: TODO -Команды запуска из чистого clone: TODO -Результаты проверок и ссылка на REPORT.md: TODO -Ограничения / известные ошибки: TODO -Источники и использование ИИ: TODO +**Что реализовано и что перенесено:** +* **Перенесено из Lab 4:** Базовая структура пользователей, чатов, сообщений, аутентификация (Bearer/Basic), идемпотентность сообщений, загрузка вложений (изменен HTTP-код на 202 Accepted). +* **Реализовано в Lab 5:** + * **Архитектура:** Выделен отдельный Worker, внедрен RabbitMQ. API больше не делает тяжелый ресайз, а только валидирует заголовок. + * **Transactional Outbox:** Запись в `attachments` и `outbox` происходит атомарно в одной транзакции. Publisher (горутина в API) надежно перекладывает задачи в RabbitMQ с Publisher Confirms. + * **Обработка:** Worker генерирует Thumbnail (256x160), Crop (128x128) и Optimized WebP (до 1280x1280, без EXIF) с лимитами по времени и памяти. + * **Отказоустойчивость (Level 4):** Экспоненциальный Retry с jitter для временных ошибок. DLQ (`failed_jobs`) для постоянных ошибок. Ручка `POST /replay` для восстановления. Reconciler чистит Staging и спасает "зависшие" задачи (Lease Recovery). + * **Идемпотентность (Level 5):** Защита от дублей на уровне БД (`ClaimForProcessing`) и защита от гонки версий пайплайна (`pipeline_version`). -- [ ] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами. -- [ ] Контракт и публичные тесты не ослаблены. -- [ ] make check и make test выполнены; приложен реальный вывод. -- [ ] Сценарии отказов/безопасности своего уровня воспроизведены. -- [ ] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens. -- [ ] README задания сохранён, REPORT.md содержит инструкцию именно моего решения. +**Команды запуска из чистого clone:** +```sh +cp .env.example .env +chmod +x setup_secrets.sh +./setup_secrets.sh +docker compose up -d --build +# Ожидаем healthcheck: docker compose ps +$env:PYTHONUTF8 = "1" # Для Windows +python -X utf8 tests/smoke.py +``` +Результаты проверок и ссылка на REPORT.md: + + Публичный смоук tests/smoke.py пройден (лог в evidence/smoke.log). + + Скрипт student-tests/fault_injection.py показывает 2 PASS (дубликаты и старая версия), доказывая Трек 2 (лог в evidence/fault_injection.log). + + Все логи и доказательства (включая восстановление Worker'а после рестарта RabbitMQ) собраны в папке evidence/. + + Подробное описание, схема и результаты экспериментов в REPORT.md. + +Ограничения / известные ошибки: + + На ОС Windows скрипт make test-persistence может падать на этапе проверки API из-за специфики перезапуска Docker Desktop сетей (API временно отдает 503). Логи восстановления Worker'а и API при этом подтверждают успешное переподключение. + + Файлы staging хранятся в том же S3-бакете, что и финальные файлы (разделение по префиксам). В production лучше использовать отдельный бакет с Lifecycle Policy. + + Трассировка OpenTelemetry не реализована (хотя ID для этого в сообщениях передаются). + +Источники и использование ИИ: + + Документация RabbitMQ (Publisher Confirms, DLX), Go (pgx, Gin). + + Библиотеки: disintegration/imaging, gen2brain/webp. + + ИИ использовался для генерации boilerplate-кода, написания bash-скриптов для Chaos Engineering и структурирования отчета. + +Чек-лист (проверено): +- [x] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами. +- [x] Контракт и публичные тесты не ослаблены. +- [x] make check и make test выполнены; приложен реальный вывод. +- [x] Сценарии отказов/безопасности своего уровня воспроизведены. +- [x] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens. +- [x] README задания сохранён, REPORT.md содержит инструкцию именно моего решения. \ No newline at end of file diff --git a/REPORT.md b/REPORT.md index 3498125..0adb6c4 100644 --- a/REPORT.md +++ b/REPORT.md @@ -2,7 +2,7 @@ - Автор, группа: Голиков А.П., БВТ2303 - Целевая оценка; выбранный трек 5, если нужен: Оценка 5, Трек 2 -- Commit/PR: будет добавлено после публикации. +- Commit/PR: ... - Использованные источники, библиотеки и помощь ИИ: Документация RabbitMQ (Publisher Confirms, DLX), документация Go (pgx, Gin), библиотека `disintegration/imaging` для ресайза, `gen2brain/webp` для WebP. При написании кода использовалась помощь ИИ для генерации boilerplate-кода и архитектурных консультаций. ## Запуск из чистого clone @@ -33,7 +33,6 @@ docker compose up -d --build Запуск тестов (Windows / PowerShell): Для корректной работы Python на Windows с кириллицей в JSON-контрактах необходимо указать кодировку UTF-8: ```powershell - $env:PYTHONUTF8 = "1" make test # или @@ -41,7 +40,6 @@ python -X utf8 tests/smoke.py ``` Безопасная остановка и удаление данных: ```sh - # Остановить контейнеры docker compose stop @@ -85,65 +83,69 @@ docker compose down -v │ COMMIT TX └──(12) ACK сообщения в RabbitMQ ``` -Источник истины и транзакционные границы - Источник истины: PostgreSQL. Только база данных является авторитетным хранилищем состояний (queued, processing, ready, failed) и метаданных. +**Источник истины и транзакционные границы** +* **Источник истины:** 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`. - Транзакционные границы: Для преодоления проблемы «двойной записи» (Dual-Write) между базой данных и брокером сообщений используется паттерн Transactional Outbox. Запись INSERT attachments и INSERT outbox происходит в рамках одной ACID-транзакции PostgreSQL. Это гарантирует, что если клиент получил 202 Accepted, задача сохранена на диске и не будет потеряна, даже если RabbitMQ временно недоступен (Publisher дослать её при восстановлении). +**Логика обработки ошибок и Retry (Level 4)** +В Worker реализована классификация ошибок. Постоянные ошибки (например, `decode_failed` при битом файле) сразу переводят задачу в `failed`. Временные ошибки (например, `storage_error` при недоступности S3) ретраятся. Используется экспоненциальный backoff: задержка рассчитывается как `2^attempts` секунд + случайный jitter (до 1 сек). Для отложенных ретраев используется Outbox. После исчерпания лимита попыток (`JOB_MAX_ATTEMPTS=5`) задача попадает в реестр `failed_jobs` (DLQ). Для восстановления предусмотрена ручка `POST /attachments/{id}/replay`. - Идемпотентность: Брокер гарантирует доставку at-least-once (минимум один раз). Защита от дублей реализована на уровне метода ClaimForProcessing (атомарный UPDATE ... WHERE status='queued'), а также через защиту pipeline_version в методе CompleteJob. +**Лимиты и защита** +Worker ограничен по памяти (лимит Docker 256 МБ), а обработка каждого изображения ограничена по времени (30 секунд через `context.WithTimeout`). Лимиты по размеру (10 МБ) и пикселям (40 млн) проверяются на уровне API. WebP генерируется с качеством 80 и удалением EXIF, JPEG (thumbnail и crop) — с качеством 85. -Что перенесено из 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). +**Что перенесено из 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 требует подтверждения, какие реальные процессы/хранилища перезапущены. +| Публичный smoke (Level 3) | `python -X utf8 tests/smoke.py` | `PASS: lab5 public API scenario` | `evidence/smoke.log` | +| Outbox + Async Worker (Level 3) | Загрузка файла через API | API отвечает 202, файл получает `ready` после Worker'а | `evidence/worker_logs.txt` | +| Переподключение Worker (Level 4) | `restart.sh` (рестарт БД/RabbitMQ) | Worker теряет связь, пишет ошибку, переподключается и продолжает работу | `evidence/worker_logs.txt` (строки 43-45) | +| Идемпотентность (Level 5) | `python -X utf8 student-tests/fault_injection.py` | `PASS` для дублей и устаревших версий. Лог воркера: "уже взята" | `evidence/fault_injection.log`, `evidence/worker_logs.txt` (строка 80) | +| Reconciler (Level 4) | Логи фонового процесса API | `reconciler: очистка завершена (удалено_staging=3...)` | `evidence/api_logs.txt` (строка 5) | +| DLQ / Failed jobs (Level 4) | Загрузка битого файла | Запись в `failed_jobs` создана | `evidence/failed_jobs.txt` | ## Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +**Track 2: Доказанная идемпотентность pipeline** + +- **Гипотеза:** Использование `pipeline_version` и транзакционного захвата задачи (`ClaimForProcessing`) гарантирует, что даже при at-least-once доставке сообщений от RabbitMQ, конечное состояние в БД будет корректным (effectively-once). +- **Методика:** Скрипт `fault_injection.py` отправляет дубликаты сообщений напрямую в RabbitMQ. Также скрипт меняет `pipeline_version` в БД и отправляет сообщение со старой версией. Дополнительно проверено восстановление после падения Worker'а (временное отключение БД/RabbitMQ через `restart.sh`) и обработка постоянных ошибок (битый файл). +- **Результаты:** + 1. При дублировании сообщений количество вариантов (thumbnail, crop, optimized) остается равным 3. В логах Worker'а видно, что дубль игнорируется (`задача уже взята...`). + 2. Задача со старой версией пайплайна игнорируется (статус остается `queued`). + 3. Worker успешно переподключается к брокеру и БД после рестарта, не теряя принятые задачи. +- **Ограничения:** Мы не достигаем exactly-once на уровне брокера (at-least-once — гарантия RabbitMQ), но достигаем exactly-once эффекта (идемпотентности) на уровне записи в БД. Это доказывает, что архитектура спроектирована правильно. | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| Дубль сообщения (RabbitMQ) | Игнорирование дубля, 3 варианта в БД | Игнорирование, 3 варианта | 0 сек / потерь нет | +| Устаревшая версия (pipeline) | Игнорирование сообщения, статус `queued` | Игнорирование, `queued` | 0 сек / потерь нет | +| Рестарт БД и RabbitMQ (`restart.sh`) | API и Worker переподключаются | API временно отдает 503, Worker перезапускает коннект и продолжает работу | ~5 сек / потерь нет | +| Неисправимый файл (битый PNG) | Задача падает в `failed`, запись в `failed_jobs` | Запись в `failed_jobs` создана | - / потерь нет | ## Ограничения и следующие шаги -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +- **Какие отказы выдерживаются:** Система выдерживает недоступность S3 (ретраи), недоступность RabbitMQ (задачи копятся в Outbox), падение Worker'а (аренда истекает, Reconciler спасает задачу). +- **Учебные упрощения:** Файлы staging хранятся в том же бакете MinIO, что и финальные (разделение по префиксам). Для production лучше использовать lifecycle policy. +- **Что не реализовано:** В полной мере не реализована распределенная трассировка (OpenTelemetry), однако в сообщениях есть все необходимые ID для нее. +- **Следующие шаги:** Добавление Grafana для мониторинга глубины очередей и health-метрик. \ No newline at end of file