forked from mtusi2026/mtusi2026lab5
75 lines
6.0 KiB
Markdown
75 lines
6.0 KiB
Markdown
# Локальный pipeline lab5
|
||
|
||
Запуск: скопировать `.env.example` в `.env`, задать локальные пароли,
|
||
выполнить `docker compose up -d --build`. API: `http://localhost:8080`.
|
||
Миграции запускаются сервисом `migrate` перед API/worker.
|
||
|
||
Upload проверяет формат, bytes и пиксели, сохраняет неизменный оригинал
|
||
в приватный S3 `staging/`, затем одной транзакцией записывает вложение и job.
|
||
Ответ 202 содержит queued. Изменение размера выполняется только worker.
|
||
Job в PostgreSQL одновременно служит outbox: dispatcher отправляет его
|
||
в отдельный Redis Streams, после ответа XADD отмечает публикацию.
|
||
Redis использует volume, AOF и `appendfsync always`, eviction отключён.
|
||
Сбой до/после XADD даёт повторную доставку, а не потерю принятого задания.
|
||
Readiness API зависит от PostgreSQL, сессионного Redis и S3;
|
||
недоступность broker/worker не мешает сохранять работу в outbox.
|
||
При достижении `MAX_PENDING_ATTACHMENTS` (64 queued/processing суммарно
|
||
по всем репликам) upload получает 429 с `Retry-After`, без нового S3-объекта.
|
||
Лимит также проверяется при операторском replay. Описание и воспроизводимый
|
||
эксперимент перегрузки: [evidence/queue-method.md](../evidence/queue-method.md).
|
||
|
||
Worker: два потребителя, у каждого не больше одной выполняемой задачи.
|
||
Каждая попытка работает в отдельном процессе: timeout 60 секунд,
|
||
лимит адресного пространства 768 MiB, контейнер 2 GiB.
|
||
Настройки: `WORKER_CONCURRENCY` (1–4), `JOB_TIMEOUT_SECONDS`,
|
||
`JOB_MEMORY_MB`, `JOB_MAX_ATTEMPTS` (по умолчанию 5).
|
||
При повышении concurrency нужно соответственно увеличить память контейнера.
|
||
Lease равен timeout + 15 секунд. Dispatcher возвращает просроченный
|
||
processing в очередь. Токен lease и блокировка job защищают публикацию
|
||
от устаревшей попытки. ACK выполняется после устойчивого результата
|
||
либо сохранённого решения о retry/failed. Pending читаются через XAUTOCLAIM.
|
||
|
||
Оригинал публикуется в `originals/`, варианты — по стабильным ключам
|
||
`variants/<attachment_id>/v1/<variant>`. Готовность и метаданные трёх
|
||
вариантов фиксируются одной транзакцией после S3. Дубль ready — no-op.
|
||
JPEG thumbnail: вписывание в 256×256, округление вниз, без увеличения.
|
||
JPEG crop: центрированный квадрат 128×128. JPEG quality=85.
|
||
WebP optimized: вписывание в 1280×1280 без увеличения, quality=80.
|
||
Применяется EXIF orientation, прозрачность — на белом; EXIF/ICC удаляются.
|
||
Оригинал остаётся побайтно неизменным.
|
||
|
||
Временные ошибки получают backoff `min(60, 2^failures)` секунд с jitter
|
||
0.5–1.5. Повреждённое изображение/checksum — `invalid_image`, нехватка
|
||
памяти — `resource_limit`, без retry. Исчерпание попыток — `retry_exhausted`.
|
||
Последняя причина ошибки и время следующей попытки сохраняются в PostgreSQL.
|
||
Реестр failed и replay доступны только локальному оператору через Compose:
|
||
|
||
```sh
|
||
docker compose exec api python -m src.jobs failed
|
||
docker compose exec api python -m src.jobs replay JOB_UUID --reason "причина повтора"
|
||
```
|
||
|
||
Replay допускается только для failed с доступным staging, сохраняет audit,
|
||
job_id и общий номер попытки, выдаёт новый бюджет retry. Ready повторять нельзя.
|
||
Cleanup запускается раз в минуту: staging ready удаляется после публикации;
|
||
failed хранится `STAGING_RETENTION_SECONDS` (86400) после ошибки.
|
||
Частично записанные конечные объекты failed очищаются после того же срока.
|
||
Бесхозные объекты удаляются после того же retention. Queued/processing
|
||
не удаляются независимо от возраста. После удаления failed staging нужен
|
||
новый upload. Реестр ошибок остаётся в PostgreSQL.
|
||
|
||
Проверки (из корня проекта):
|
||
|
||
```sh
|
||
python -X utf8 tests/smoke.py --base-url http://127.0.0.1:8080
|
||
python -X utf8 student-tests/pipeline.py
|
||
python -X utf8 student-tests/edge_cases.py
|
||
docker compose run --rm --no-deps -v ./student-tests:/checks:ro worker python -m unittest discover -s /checks
|
||
```
|
||
|
||
Pipeline-тест останавливает/возвращает сервисы только этого Compose-проекта,
|
||
создаёт синтетические данные, проверяет разрыв COMMIT/publish, рестарт broker,
|
||
crash после S3 и после COMMIT до ack, lease, дубли, retry/replay и cleanup.
|
||
Точки `JOB_FAULT=after_objects|after_commit` используются только тестом,
|
||
в обычной конфигурации выключены. Контракты и публичные тесты не изменены.
|