Files
mtusi2026lab5-fork/REPORT.md
T
2026-11-10 07:44:19 +03:00

99 lines
8.5 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**, трек — **TODO**. Все пункты уровней **3 и 4** реализованы и проверены.
- Commit/PR: TODO после публикации.
- Использованные источники, библиотеки и помощь ИИ: Python 3.12, FastAPI, SQLAlchemy, Pillow, aio-pika; [RabbitMQ](https://www.rabbitmq.com/docs/reliability), [Pillow](https://pillow.readthedocs.io/en/stable/); помощь Codex при реализации и проверках.
## Запуск из чистого clone
Нужны Python 3.12, pip и Docker Compose. Версии зависимостей закреплены в requirements.txt;
основные образы — PostgreSQL 16.10, Redis 7.4.2, RabbitMQ 4.4.0 и nginx 1.28.0.
```sh
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt -r requirements-dev.txt
make init
make up
make test
make down
```
`make init` создаёт отсутствующие .env и secrets/, миграции и bootstrap выполняются
при запуске. Все настройки берутся из .env; образец — .env.example.
HTTP: http://localhost:18081. Внутренние хранилища и брокер наружу не открыты.
`make down` сохраняет данные; `docker compose down --volumes` намеренно удаляет их.
При обновлении схемы сначала остановить старые процессы, сохранив volumes.
## Архитектура и решения
API → приватный MinIO staging + PostgreSQL job/outbox → RabbitMQ → worker →
конечные объекты MinIO + PostgreSQL metadata. Redis хранит сессии.
Сохранены аутентификация, чаты, сообщения, пагинация и идемпотентность предыдущих работ.
Загрузка возвращает **202 queued** после устойчивого приёма. Состояния:
queued / processing / ready / failed; скачивание до ready возвращает 409.
RabbitMQ использует устойчивую очередь, сохранение сообщений на диск и подтверждения.
Publisher отмечает публикацию после подтверждения брокера; worker подтверждает доставку
после фиксации результата. Outbox восстанавливает разрыв COMMIT → publish.
Фиксированные ключи объектов, блокировка job и lease защищают от повторов и устаревшего worker.
Original не перекодируется. Варианты: JPEG thumbnail ≤256×256, центральный JPEG crop
128×128 и WebP ≤1280×1280. JPEG quality=85, WebP quality=80/method=4; EXIF orientation
учитывается, EXIF/ICC/XMP удаляются. Для JPEG alpha заменяется белой подложкой,
WebP сохраняет прозрачность. Лимиты: 10 MiB, 40 млн пикселей, timeout 60 секунд,
768 MiB и 20 секунд CPU на дочерний процесс; concurrency=2, prefetch=1, lease=90 секунд.
Повторы ограничены пятью попытками. Задержка со случайным разбросом:
c=min(120, 5×2^(n−1)), delay∈[c/2,c]. Постоянные ошибки завершаются сразу.
Реестр failed и аудит находятся в PostgreSQL; явный replay проверяет исходник,
выделяет новый бюджет и не запускает уже готовую job. Staging активных jobs сохраняется;
ready очищается через сутки, failed — через семь суток.
Операторские команды:
```sh
docker compose run --rm --no-deps worker python -m app.core.job_admin list-failed
docker compose run --rm --no-deps worker python -m app.core.job_admin replay JOB_ID --request-id REQUEST_UUID --actor operator --reason dependency_restored
```
JOB_ID и REQUEST_UUID заменить UUID. Повтор команды с тем же request-id безопасен.
## Доказательства критериев
`make test-suite` поднимает отдельный стенд, проверяет pipeline и удаляет контейнеры,
сети и volumes при завершении, включая ошибку. Полная сохранённая регрессия запускается
отдельно через `make test-unit`; отдельные сервисы — `test-nginx` и `test-storage`.
Проверки pipeline: 42 теста. Полная сохранённая регрессия: 201 тест.
Публичные smoke/persistence/failover прошли. Для отдельных pytest-прогонов нужен
`make test-stand-up`; после проверки — `make test-stand-destroy`.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | 202 → ready, неизменный original, JPEG thumbnail | evidence/verification.json |
| Устойчивый приём и сохранение возможностей lab4 | DOCKER_TESTS=1 make test-unit; make test-persistence | Данные и сессия сохранены, загрузка асинхронная | evidence/verification.json |
| Отдельные broker/worker, поздний ack | make test-jobs | Сообщения сохранены, очередь подтверждена | evidence/jobs.json |
| Состояния, ограниченные повторы, идемпотентность | make test-pipeline; make test-jobs | failed после бюджета, дубли не создают новые объекты | evidence/verification.json |
| Остановка worker и рестарт API/брокера | make test-jobs | То же вложение стало ready, сообщение пережило рестарт | evidence/jobs.json |
| Crop/WebP и ограничения worker | make test-pipeline; make test-jobs | Форматы/размеры, metadata и лимиты проверены | evidence/verification.json |
| Разрыв COMMIT → publish | make test-outbox | SIGKILL publisher, затем ready без нового upload | evidence/verification.json |
| Backoff/jitter, failed registry, replay | make test-jobs | Постоянные/временные ошибки различаются, replay безопасен | evidence/jobs.json |
| Crash после PUT до ack, lease и cleanup | make test-jobs; make test-pipeline | Тот же результат, prefetch=1; активный staging сохранён | evidence/jobs.json; evidence/verification.json |
| Выбранный трек 5 | TODO | TODO | TODO |
## Эксперименты и отказы
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| Crash после PUT до COMMIT | Повтор той же job | ready на второй попытке, те же четыре объекта и SHA-256 | После lease/retry; потерь нет |
| Crash после COMMIT до ack | Готовый дубль без обработки | Metadata и Last-Modified не изменились | После доставки; потерь нет |
| Временная / постоянная ошибка | Ограниченный retry / немедленный failed | Пять / одна попытка; явный replay завершился ready | В пределах бюджета; потерь нет |
Трек 5 — **TODO**: гипотеза, методика, измерения и выводы.
## Ограничения и следующие шаги
Один Docker-хост, без репликации хранилищ и защиты от потери диска. Очередь не имеет
admission control; pipeline фиксирован на версии 1. Доставка как минимум один раз,
с идемпотентным результатом. Исследование для уровня 5 — **TODO**.