Lab5 - оценка 4 Шиян #40

Open
BVT2304_Shiyan wants to merge 2 commits from BVT2304_Shiyan/mtusi2026lab5:solution/BVT2304-Shiyan into main
First-time contributor

Лабораторная 5

Автор / группа: BVT2304-Shiyan
Целевая оценка (3/4/5): 4
Трек 5, если заявлен: не заявлен

Что реализовано и что перенесено

Перенесено из лабы 4 без регресса:

  • две stateless API-реплики за nginx с динамическим резолвингом upstream (resolver 127.0.0.11 valid=10s);
  • X-Instance-Id в каждом ответе, меняющийся при пересоздании реплики;
  • однократные миграции контейнером migrate -migrate-only; идемпотентность сообщений через Idempotency-Key;
  • лимиты CPU/RAM на всех сервисах; /health/live и /health/ready;
  • приватный бакет RustFS с фиксированным digest; ACL приложения (посторонний → 404);
  • лимиты загрузки (10 MiB до полного чтения, 40 Мп, MIME по содержимому, безопасное filename);
  • reconcile осиротевших объектов — обновлён под ключи лабы 5 (staging/..., {chat}/{att}/{variant}), чтобы не удалять живые варианты.

Реализовано в лабе 5:

  • переход контракта 201 ready → 202 queued; готовность через последующий GET /attachments/{id}; скачивание до готовности → 409;
  • брокер Redis Streams (consumer group workers, PEL, XAUTOCLAIM, AOF appendfsync everysec) — durable-сообщения, at-least-once доставка, в очередь идут только ID по contracts/jobs.schema.json;
  • отдельный сервис worker (-worker): claim с lease 60 c → чтение staging → сверка SHA-256 → построение вариантов → запись финальных объектов → COMMIT результата → удаление staging → XACK только после COMMIT;
  • варианты по контракту: thumbnail JPEG вписан в 256×256 без увеличения (EXIF orientation, alpha→белый; фикстура 320×200 → 256×160), crop JPEG 128×128 по центру, optimized WebP вписан в 1280×1280 без увеличения (q=80, EXIF не сохраняется);
  • transactional outbox: одна транзакция PostgreSQL фиксирует attachments(queued) + jobs + outbox; relay в каждой API-реплике публикует неопубликованные намерения и помечает published_at после успеха XADD — разрыв COMMIT→publish закрыт;
  • состояния queued/processing/ready/failed в API; машинный error_code в failed; реестр отказов job_failures (DLQ-аналог);
  • ограниченный retry (5 попыток) с backoff 0.5→8 c и jitter ±25%; задержка реально соблюдается планировщиком EnqueueDueRetries (Redis Streams не имеет отложенной доставки) + guard в ClaimJob по next_attempt_at;
  • различение постоянных (invalid_image, checksum_mismatch, attachment_missing) и временных ошибок; терминальный failed с retry_exhausted;
  • защита от зависшего processing: lease + ReapExpiredLeases (возврат в очередь или терминальный отказ) + XAUTOCLAIM для упавшего consumer;
  • идемпотентность эффекта: атомарный claim-гард, детерминированные ключи вариантов, CompleteJob только из processing/queued — повторная доставка не создаёт второго набора вариантов; повтор готовой задачи — no-op с ack;
  • миграция 0005_jobs_outbox.sql (jobs, outbox, job_failures, attachments.variants/pipeline_version/processing_started_at);
  • WebP через build-tag развилку (webp_cgo.go / webp_nocgo.go): Docker собирает с cgo+libwebp, локальная сборка Windows компилируется заглушкой; worker выполняется только в Docker;
  • .bat-набор студенческих проверок в scripts/ (11 сценариев, самодостаточные, без .ps1).

Команды запуска из чистого clone

Windows (CMD/PowerShell), из корня репозитория:

git clone <repo-url>
cd <repo-dir>
copy .env.example .env

docker compose --compatibility up -d --build
timeout /t 45 /nobreak >nul
docker compose ps

rem структурная проверка compose
docker compose --compatibility config --quiet

rem публичный smoke (эквивалент make test; make в Windows-окружении отсутствует)
set PYTHONUTF8=1
python -X utf8 tests\smoke.py --base-url http://localhost:8080
rem или: scripts\smoke.bat

Ожидаемое состояние: postgres/redis/api×2 healthy, rustfs/nginx/worker up, migrate Exited(0). Worker не имеет HTTP-эндпоинтов, поэтому его healthcheck отключён в compose осознанно (healthcheck: disable: true), живость — через docker compose ps.

Секреты создаются отдельно: реальные значения только в локальном .env (в .gitignore); в репозитории лишь .env.example с синтетическими данными. Безопасная остановка: docker compose --compatibility down (volumes сохраняются); намеренное удаление учебных данных: docker compose --compatibility down -v.

Linux/macOS: те же команды с cp .env.example .env, sleep 45 и python3 -X utf8 tests/smoke.py ...; при наличии make: make check, make test.

Результаты проверок и ссылка на REPORT.md

Подробный отчёт: REPORT.md. Фактические прогоны (Windows, Docker Desktop):

Проверка Команда Наблюдаемый результат
Публичный smoke лабы 5 scripts\smoke.bat PASS: lab5 public API scenario; infrastructure and grading evidence remain separate.
Позитив: 202 → ready → 3 варианта → sha256 scripts\manual-attachments.bat ALL MANUAL LAB5 CHECKS PASSED (thumbnail 256×160 jpeg, crop 128×128 jpeg, optimized webp; байты каждого варианта совпали с метаданными; eve 404)
Негатив: 413/415/400/404 + неизвестный вариант scripts\negative-attachments.bat ALL NEGATIVE CHECKS PASSED
Worker остановлен: API не обрабатывает синхронно scripts\worker-down.bat статус стоит queued, content → 409, после старта worker → ready; WORKER-DOWN CHECKS PASSED
Retry exhaustion + реестр failed scripts\retry-fail.bat error_code=retry_exhausted, job_failures contains 1 row(s), после восстановления RustFS статус терминален; RETRY-FAIL CHECKS PASSED
Приватность бакета (оригинал + thumbnail) scripts\private-bucket.bat прямой GET без кредов ≠ 200; PRIVATE BUCKET CHECKS PASSED
Persistence через рестарт persistence-attachment.bat → restart-stack.bat → persistence-verify.bat ALL PERSISTENCE CHECKS PASSED (метаданные, оригинал, 3 варианта, старый токен)
Failover API-реплики scripts\failover-attachment.bat upload 7af389c0cc10-c6182626, download после её остановки 5f8cae293618-93768753, sha256 99ea7533…bd75 совпал; PASS: original bytes available after stopping one replica
Reconcile осиротевших объектов scripts\reconcile-demo.bat 1-й прогон: 5 удалённых ключей (staging+original+thumbnail+crop+optimized); 2-й прогон: deleted: 0

make check/make test в моём Windows-окружении недоступны (make не установлен); публичные проверки запускались эквивалентными командами напрямую (python -X utf8 tests\smoke.py --base-url http://localhost:8080), структурная валидность compose — docker compose --compatibility config --quiet (без ошибок). Вывод приложен выше и продублирован в REPORT.md.

Ограничения / известные ошибки

  • Один экземпляр Redis (брокер и кэш), один nginx, один worker — единые точки отказа; Sentinel/Cluster и масштабирование worker вне рамок лабы. Backlog при простое worker накапливается и обрабатывается после восстановления.
  • RustFS не предоставляет гранулярных IAM-политик: основной контроль доступа — ACL приложения (проверка членства в чате), приватность бакета — defense-in-depth.
  • Reconcile запускается вручную (profiles: [tools]); в проде — по расписанию.
  • Направление «метаданные в БД есть, объекта в S3 нет» не восстанавливается автоматически (байты не реконструируются): скачивание честно отдаёт 503; обратный аудит в reconcile — названное расширение, не реализовано.
  • Окно потери сообщения брокером при уже помеченной опубликованной строке outbox (AOF everysec, ~1 c) может оставить задание в queued; лечится watchdog-переопубликацией застрявших queued — названо как расширение, не реализовано.
  • Загрузка и обработка буферизуют до 10 MiB в памяти (детерминированный потолок); streaming multipart для больших файлов вне рамок контракта.
  • WebP-энкодер требует cgo: локальная сборка Windows использует заглушку (!cgo), воркер выполняется только в Docker-образе с libwebp.
  • Публичный smoke не доказывает persistence/HA/безопасность сам по себе — для этого добавлены отдельные студенческие проверки (таблица выше); отказ одного Docker-host не выдерживается по построению стенда.

Источники и использование ИИ

  • ИИ использовался как помощник: проектирование архитектуры (outbox, lease, claim-гард), черновики Go-кода/миграций/compose/.bat-скриптов, отладка ошибок сборки и YAML, формулировки отчёта и объяснений. Все фрагменты проверены локально прогонами и приведены в соответствие контракту contracts/openapi.json, contracts/attachment-states.md, contracts/jobs.schema.json и требованиям COURSE.md/CONTRIBUTING.md.
  • Библиотеки: github.com/jackc/pgx/v5, github.com/redis/go-redis/v9, github.com/minio/minio-go/v7, github.com/disintegration/imaging v1.6.2, github.com/chai2010/webp v1.4.0 (cgo), github.com/google/uuid, golang.org/x/crypto. Материалы курса: Redis Streams, RabbitMQ reliability (семантика confirm/ack учтена в разделении границ: publisher confirm = приём брокером, ack = устойчивая обработка).
  • Реальные секреты и приватные ключи вне Git; .env в .gitignore, в репозитории только .env.example; отчёт и PR не содержат токенов (в выводах только синтетические ID и sha256 фикстуры).

  • Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами.
  • Контракт и публичные тесты не ослаблены.
  • make check и make test выполнены; приложен реальный вывод. (Примечание: в Windows-окружении без make публичные проверки запущены эквивалентными командами python -X utf8 tests\smoke.py --base-url http://localhost:8080; вывод приложен.)
  • Сценарии отказов/безопасности своего уровня воспроизведены. (worker-down, retry-fail, crash-имитация через удаление метаданных + reconcile, failover реплики, persistence; разрыв COMMIT→publish закрыт outbox и описан в REPORT.md.)
  • Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens.
  • README задания сохранён, REPORT.md содержит инструкцию именно моего решения.
## Лабораторная 5 Автор / группа: BVT2304-Shiyan Целевая оценка (3/4/5): 4 Трек 5, если заявлен: не заявлен ### Что реализовано и что перенесено **Перенесено из лабы 4 без регресса:** - две stateless API-реплики за nginx с динамическим резолвингом upstream (`resolver 127.0.0.11 valid=10s`); - `X-Instance-Id` в каждом ответе, меняющийся при пересоздании реплики; - однократные миграции контейнером `migrate -migrate-only`; идемпотентность сообщений через `Idempotency-Key`; - лимиты CPU/RAM на всех сервисах; `/health/live` и `/health/ready`; - приватный бакет RustFS с фиксированным digest; ACL приложения (посторонний → 404); - лимиты загрузки (10 MiB до полного чтения, 40 Мп, MIME по содержимому, безопасное `filename`); - reconcile осиротевших объектов — обновлён под ключи лабы 5 (`staging/...`, `{chat}/{att}/{variant}`), чтобы не удалять живые варианты. **Реализовано в лабе 5:** - переход контракта `201 ready` → `202 queued`; готовность через последующий `GET /attachments/{id}`; скачивание до готовности → `409`; - брокер **Redis Streams** (consumer group `workers`, PEL, `XAUTOCLAIM`, AOF `appendfsync everysec`) — durable-сообщения, at-least-once доставка, в очередь идут только ID по `contracts/jobs.schema.json`; - отдельный сервис `worker` (`-worker`): claim с lease 60 c → чтение staging → сверка SHA-256 → построение вариантов → запись финальных объектов → COMMIT результата → удаление staging → `XACK` только после COMMIT; - варианты по контракту: `thumbnail` JPEG вписан в 256×256 без увеличения (EXIF orientation, alpha→белый; фикстура 320×200 → 256×160), `crop` JPEG 128×128 по центру, `optimized` WebP вписан в 1280×1280 без увеличения (q=80, EXIF не сохраняется); - **transactional outbox**: одна транзакция PostgreSQL фиксирует `attachments(queued)` + `jobs` + `outbox`; relay в каждой API-реплике публикует неопубликованные намерения и помечает `published_at` после успеха `XADD` — разрыв COMMIT→publish закрыт; - состояния `queued/processing/ready/failed` в API; машинный `error_code` в `failed`; реестр отказов `job_failures` (DLQ-аналог); - ограниченный retry (5 попыток) с backoff 0.5→8 c и jitter ±25%; задержка реально соблюдается планировщиком `EnqueueDueRetries` (Redis Streams не имеет отложенной доставки) + guard в `ClaimJob` по `next_attempt_at`; - различение постоянных (`invalid_image`, `checksum_mismatch`, `attachment_missing`) и временных ошибок; терминальный `failed` с `retry_exhausted`; - защита от зависшего `processing`: lease + `ReapExpiredLeases` (возврат в очередь или терминальный отказ) + `XAUTOCLAIM` для упавшего consumer; - идемпотентность эффекта: атомарный claim-гард, детерминированные ключи вариантов, `CompleteJob` только из `processing/queued` — повторная доставка не создаёт второго набора вариантов; повтор готовой задачи — no-op с ack; - миграция `0005_jobs_outbox.sql` (jobs, outbox, job_failures, `attachments.variants/pipeline_version/processing_started_at`); - WebP через build-tag развилку (`webp_cgo.go` / `webp_nocgo.go`): Docker собирает с cgo+libwebp, локальная сборка Windows компилируется заглушкой; worker выполняется только в Docker; - `.bat`-набор студенческих проверок в `scripts/` (11 сценариев, самодостаточные, без `.ps1`). ### Команды запуска из чистого clone Windows (CMD/PowerShell), из корня репозитория: ```bat git clone <repo-url> cd <repo-dir> copy .env.example .env docker compose --compatibility up -d --build timeout /t 45 /nobreak >nul docker compose ps rem структурная проверка compose docker compose --compatibility config --quiet rem публичный smoke (эквивалент make test; make в Windows-окружении отсутствует) set PYTHONUTF8=1 python -X utf8 tests\smoke.py --base-url http://localhost:8080 rem или: scripts\smoke.bat ``` Ожидаемое состояние: `postgres/redis/api×2` healthy, `rustfs/nginx/worker` up, `migrate` Exited(0). Worker не имеет HTTP-эндпоинтов, поэтому его healthcheck отключён в compose осознанно (`healthcheck: disable: true`), живость — через `docker compose ps`. Секреты создаются отдельно: реальные значения только в локальном `.env` (в `.gitignore`); в репозитории лишь `.env.example` с синтетическими данными. Безопасная остановка: `docker compose --compatibility down` (volumes сохраняются); намеренное удаление учебных данных: `docker compose --compatibility down -v`. Linux/macOS: те же команды с `cp .env.example .env`, `sleep 45` и `python3 -X utf8 tests/smoke.py ...`; при наличии make: `make check`, `make test`. ### Результаты проверок и ссылка на REPORT.md Подробный отчёт: [`REPORT.md`](./REPORT.md). Фактические прогоны (Windows, Docker Desktop): | Проверка | Команда | Наблюдаемый результат | |---|---|---| | Публичный smoke лабы 5 | `scripts\smoke.bat` | `PASS: lab5 public API scenario; infrastructure and grading evidence remain separate.` | | Позитив: 202 → ready → 3 варианта → sha256 | `scripts\manual-attachments.bat` | `ALL MANUAL LAB5 CHECKS PASSED` (thumbnail 256×160 jpeg, crop 128×128 jpeg, optimized webp; байты каждого варианта совпали с метаданными; eve 404) | | Негатив: 413/415/400/404 + неизвестный вариант | `scripts\negative-attachments.bat` | `ALL NEGATIVE CHECKS PASSED` | | Worker остановлен: API не обрабатывает синхронно | `scripts\worker-down.bat` | статус стоит `queued`, content → `409`, после старта worker → `ready`; `WORKER-DOWN CHECKS PASSED` | | Retry exhaustion + реестр failed | `scripts\retry-fail.bat` | `error_code=retry_exhausted`, `job_failures contains 1 row(s)`, после восстановления RustFS статус терминален; `RETRY-FAIL CHECKS PASSED` | | Приватность бакета (оригинал + thumbnail) | `scripts\private-bucket.bat` | прямой GET без кредов ≠ 200; `PRIVATE BUCKET CHECKS PASSED` | | Persistence через рестарт | `persistence-attachment.bat` → `restart-stack.bat` → `persistence-verify.bat` | `ALL PERSISTENCE CHECKS PASSED` (метаданные, оригинал, 3 варианта, старый токен) | | Failover API-реплики | `scripts\failover-attachment.bat` | upload `7af389c0cc10-c6182626`, download после её остановки `5f8cae293618-93768753`, sha256 `99ea7533…bd75` совпал; `PASS: original bytes available after stopping one replica` | | Reconcile осиротевших объектов | `scripts\reconcile-demo.bat` | 1-й прогон: 5 удалённых ключей (staging+original+thumbnail+crop+optimized); 2-й прогон: `deleted: 0` | `make check`/`make test` в моём Windows-окружении недоступны (make не установлен); публичные проверки запускались эквивалентными командами напрямую (`python -X utf8 tests\smoke.py --base-url http://localhost:8080`), структурная валидность compose — `docker compose --compatibility config --quiet` (без ошибок). Вывод приложен выше и продублирован в REPORT.md. ### Ограничения / известные ошибки - Один экземпляр Redis (брокер и кэш), один nginx, один worker — единые точки отказа; Sentinel/Cluster и масштабирование worker вне рамок лабы. Backlog при простое worker накапливается и обрабатывается после восстановления. - RustFS не предоставляет гранулярных IAM-политик: основной контроль доступа — ACL приложения (проверка членства в чате), приватность бакета — defense-in-depth. - Reconcile запускается вручную (`profiles: [tools]`); в проде — по расписанию. - Направление «метаданные в БД есть, объекта в S3 нет» не восстанавливается автоматически (байты не реконструируются): скачивание честно отдаёт `503`; обратный аудит в reconcile — названное расширение, не реализовано. - Окно потери сообщения брокером при уже помеченной опубликованной строке outbox (AOF `everysec`, ~1 c) может оставить задание в `queued`; лечится watchdog-переопубликацией застрявших `queued` — названо как расширение, не реализовано. - Загрузка и обработка буферизуют до 10 MiB в памяти (детерминированный потолок); streaming multipart для больших файлов вне рамок контракта. - WebP-энкодер требует cgo: локальная сборка Windows использует заглушку (`!cgo`), воркер выполняется только в Docker-образе с libwebp. - Публичный smoke не доказывает persistence/HA/безопасность сам по себе — для этого добавлены отдельные студенческие проверки (таблица выше); отказ одного Docker-host не выдерживается по построению стенда. ### Источники и использование ИИ - ИИ использовался как помощник: проектирование архитектуры (outbox, lease, claim-гард), черновики Go-кода/миграций/compose/`.bat`-скриптов, отладка ошибок сборки и YAML, формулировки отчёта и объяснений. Все фрагменты проверены локально прогонами и приведены в соответствие контракту `contracts/openapi.json`, `contracts/attachment-states.md`, `contracts/jobs.schema.json` и требованиям `COURSE.md`/`CONTRIBUTING.md`. - Библиотеки: `github.com/jackc/pgx/v5`, `github.com/redis/go-redis/v9`, `github.com/minio/minio-go/v7`, `github.com/disintegration/imaging` v1.6.2, `github.com/chai2010/webp` v1.4.0 (cgo), `github.com/google/uuid`, `golang.org/x/crypto`. Материалы курса: Redis Streams, RabbitMQ reliability (семантика confirm/ack учтена в разделении границ: publisher confirm = приём брокером, ack = устойчивая обработка). - Реальные секреты и приватные ключи вне Git; `.env` в `.gitignore`, в репозитории только `.env.example`; отчёт и PR не содержат токенов (в выводах только синтетические ID и sha256 фикстуры). --- - [x] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами. - [x] Контракт и публичные тесты не ослаблены. - [x] make check и make test выполнены; приложен реальный вывод. *(Примечание: в Windows-окружении без make публичные проверки запущены эквивалентными командами `python -X utf8 tests\smoke.py --base-url http://localhost:8080`; вывод приложен.)* - [x] Сценарии отказов/безопасности своего уровня воспроизведены. *(worker-down, retry-fail, crash-имитация через удаление метаданных + reconcile, failover реплики, persistence; разрыв COMMIT→publish закрыт outbox и описан в REPORT.md.)* - [x] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens. - [x] README задания сохранён, REPORT.md содержит инструкцию именно моего решения.
BVT2304_Shiyan added 1 commit 2026-11-10 14:05:44 +03:00
Owner
  • Усечённый PNG принимается с 202 вместо 415, затем становится failed. helpers.go:91 проверяет только заголовок изображения. Проверять целостность файла до принятия задания, сохраняя ресурсные ограничения.
  • После истечения lease на пятой попытке остаётся processing:5, в логах — conn busy. В jobs.go:394 новый запрос выполняется при открытом результате предыдущего. Сначала прочитать и закрыть результат, затем фиксировать failed.
- Усечённый PNG принимается с 202 вместо 415, затем становится failed. [helpers.go:91](https://gitea.privcloud.tech/BVT2304_Shiyan/mtusi2026lab5/src/commit/e138dfb13d3395d01a3c5270a8823b852f365a81/src/internal/api/helpers.go#L91) проверяет только заголовок изображения. Проверять целостность файла до принятия задания, сохраняя ресурсные ограничения. - После истечения lease на пятой попытке остаётся processing:5, в логах — conn busy. В [jobs.go:394](https://gitea.privcloud.tech/BVT2304_Shiyan/mtusi2026lab5/src/commit/e138dfb13d3395d01a3c5270a8823b852f365a81/src/internal/store/jobs.go#L394) новый запрос выполняется при открытом результате предыдущего. Сначала прочитать и закрыть результат, затем фиксировать failed.
BVT2304_Shiyan added 1 commit 2026-11-13 10:34:32 +03:00
You are not authorized to merge this pull request.
This pull request can be merged automatically.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u https://gitea.privcloud.tech/BVT2304_Shiyan/mtusi2026lab5 solution/BVT2304-Shiyan:BVT2304_Shiyan-solution/BVT2304-Shiyan
git checkout BVT2304_Shiyan-solution/BVT2304-Shiyan
Sign in to join this conversation.
No Reviewers
No labels
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mtusi2026/mtusi2026lab5#40