forked from mtusi2026/mtusi2026lab5
99 lines
8.5 KiB
Markdown
99 lines
8.5 KiB
Markdown
# Отчёт — лабораторная 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**.
|