forked from mtusi2026/mtusi2026lab5
178 lines
26 KiB
Markdown
178 lines
26 KiB
Markdown
# Отчёт — лабораторная 5
|
||
|
||
- Автор, группа: Березин Герман / БВТ2304
|
||
- Целевая оценка: 4
|
||
- Commit/PR: после публикации
|
||
- Использованные источники, библиотеки и помощь ИИ: Go 1.26, pgx, go-redis (клиент Valkey Streams), minio-go v7, golang.org/x/image/draw (ресемплинг), github.com/gen2brain/webp (libwebp, транспилированный в Go), github.com/rwcarlsen/goexif (EXIF orientation); PostgreSQL 17, Valkey 8.1, SeaweedFS, HAProxy 3.0; документация RabbitMQ reliability и Redis Streams из README; код lab4 перенесён за основу; ИИ-ассистент использован при разработке
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Требуются Docker 29 с Compose v2 и Python 3.9+. Для `tests/variants.py` нужен Pillow (проверяет реальные пиксели JPEG/WebP).
|
||
|
||
```sh
|
||
cp .env.example .env
|
||
sh scripts/mksecrets.sh
|
||
docker compose --env-file .env up -d --build --wait
|
||
make check && make test
|
||
```
|
||
|
||
Порядок старта: postgres, valkey, broker, s3 → `migrate` → `s3-init` → `api` × 2, `worker`, `janitor` → `lb`. Публичный адрес: `http://localhost:8080`. После первого старта S3 запись становится доступна через 10–30 s.
|
||
|
||
Остановка без потери данных: `docker compose --env-file .env stop`. Намеренное удаление учебных данных: `docker compose --env-file .env down -v`.
|
||
|
||
Операторские команды:
|
||
|
||
```sh
|
||
docker compose --env-file .env stop worker
|
||
docker compose --env-file .env up -d --no-deps worker
|
||
docker compose --env-file .env run --rm --no-deps worker failed
|
||
docker compose --env-file .env run --rm --no-deps worker replay <attachment_id>
|
||
```
|
||
|
||
Проверки (стенд запущен):
|
||
|
||
```sh
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
|
||
python3 tests/variants.py
|
||
python3 tests/queue_recovery.py
|
||
python3 tests/faults.py
|
||
python3 tests/worker_load.py --output evidence/worker-load.json
|
||
python3 tests/attachments.py
|
||
python3 tests/s3_checks.py
|
||
python3 tests/upload_memory.py --output evidence/upload-memory.json
|
||
python3 tests/idempotency.py
|
||
python3 tests/session_revocation.py
|
||
python3 tests/scenario.py --mode failover-each --output evidence/failover-each.json
|
||
python3 tests/scenario.py --mode rolling --output evidence/rolling.json
|
||
```
|
||
|
||
После `make test-failover` реплику возвращают командой `docker compose --env-file .env up -d --wait api`. `faults.py`, `queue_recovery.py`, `worker_load.py` сами останавливают и пересоздают worker/api/broker/s3 и возвращают их в исходное состояние.
|
||
|
||
## Архитектура и решения
|
||
|
||
```
|
||
клиент → HAProxy → api ×2 ──(1) S3 staging/<id>
|
||
└──(2) PostgreSQL: attachments(queued) + jobs + outbox — одна транзакция → 202
|
||
api: outbox relay ──XADD──→ broker (Valkey Stream attachments.jobs, group workers)
|
||
worker ──XREADGROUP──→ claim (lease) → S3 attachments/<id>/... → COMMIT ready → XACK
|
||
```
|
||
|
||
| Роль | Сервис | Образ | Готовность | Volume | Сеть | Credentials |
|
||
| --- | --- | --- | --- | --- | --- | --- |
|
||
| api ×2 | `api` | собирается из исходников (`mtusi-messenger:lab5`) | `/health/ready` (PostgreSQL) | нет | backend, storage | secrets: database_url, cache_url, broker_url, S3-ключи API |
|
||
| worker | `worker` | тот же образ, команда `worker` | нет HTTP, healthcheck отключён | нет | backend, storage | database_url, broker_url, S3-ключи API |
|
||
| postgres | `postgres` | postgres:17-alpine@sha256:b0f9560a… | `pg_isready` | pg_data | backend | postgres_password |
|
||
| broker | `broker` | valkey/valkey:8.1-alpine@sha256:081c2f5c… | `valkey-cli ping` с паролем | broker_data | backend | broker.conf (`requirepass`) |
|
||
| s3 | `s3` | chrislusf/seaweedfs@sha256:c2658820… | `/dir/assign` выдаёт fid | s3_data | storage | s3_config.json |
|
||
| load_balancer | `lb` | haproxy:3.0-alpine@sha256:cf3af0fa… | проверки `/health/ready` бэкендов | нет | backend, 127.0.0.1:8080 | нет |
|
||
| Valkey (сессии проверяются только в PostgreSQL) | `valkey` | valkey/valkey:8.1-alpine | `valkey-cli ping` | valkey_data | backend | нет |
|
||
|
||
Bootstrap: `migrate` применяет `migrations/*.sql` под advisory lock, повторный запуск пропускает применённые. `s3-init` создаёт bucket, если его нет. Consumer group `workers` создают API (перед первой публикацией) и worker при старте (`XGROUP CREATE … 0 MKSTREAM`, ошибка BUSYGROUP игнорируется).
|
||
|
||
- **Брокер.** Valkey Streams в отдельном сервисе `broker` с `appendonly yes`, `appendfsync always`, `noeviction`. Доставка at least once: сообщение остаётся в pending (PEL) до `XACK`. Publisher confirm: ответ на `XADD` приходит после записи в AOF с fsync. Consumer ack: `XACK` после COMMIT результата в PostgreSQL. В сообщении только поля `jobs.schema.json` (поле `job` — JSON с `schema_version`, `job_id`, `type`, `attachment_id`, `pipeline_version`, `attempt`, `created_at`), без bytes, URL и credentials.
|
||
- **Что сохранено к 202.** Полный проверенный оригинал лежит в приватном S3-prefix `staging/<attachment_id>` (тот же bucket, volume s3_data). Одной транзакцией сохранены строки `attachments` (status `queued`, staging_key, sha256, размер), `jobs` (attempt 1) и `outbox`. Проверки на приёме те же, что в lab4: 413/415/400/404, хвост и заголовок изображения, не более 40 млн пикселей.
|
||
- **Transactional outbox.** В каждой API-реплике работает relay: `select … from outbox where published_at is null and available_at <= now() for update skip locked`, затем `XADD` и `published_at = now()` в той же транзакции. Падение между COMMIT и publish оставляет неопубликованную строку, её публикует любая живая реплика. Падение после `XADD` до COMMIT пометки даёт повторную публикацию: это дубль, worker обработает его как no-op.
|
||
- **Worker.** Отдельный процесс (`messenger worker`), `WORKER_CONCURRENCY=2` потребителя, у каждого `COUNT 1`: prefetch 1, не больше двух задач одновременно. При старте потребитель дочитывает свои pending-сообщения (`XREADGROUP … 0`), каждые 15 s забирает зависшие чужие (`XAUTOCLAIM` с min-idle = lease).
|
||
- **Ключ идемпотентности.** Логическая работа — `jobs.id` (job_id), он один на вложение и не меняется при redelivery. Ключ эффекта — `(attachment_id, pipeline_version, name)`: первичный ключ `attachment_variants`, вставка через `on conflict do update`. S3-ключи детерминированы: `attachments/<id>/original`, `attachments/<id>/v1/{thumbnail.jpg,crop.jpg,optimized.webp}`. Повтор перезаписывает те же объекты и не создаёт второго набора.
|
||
- **Захват и lease.** `update jobs set status='processing', lease_owner, lease_until = now() + lease where status='queued' and next_attempt_at <= now()`. Сообщение для задачи в любом другом состоянии подтверждается без работы (`job delivery skipped`), поэтому повторная доставка ready-задачи — no-op. Lease = `JOB_TIMEOUT_SECONDS` + 15 s. Фиксация результата и перевод в retry/failed выполняются только при совпадении `lease_owner` и `attempt`. Worker, потерявший lease, не перезапишет состояние (`lease lost, result discarded`).
|
||
- **Зависший или долгий.** Задача ограничена контекстом `JOB_TIMEOUT_SECONDS` (60 s), поэтому живой worker не может законно работать дольше lease. Каждые 5 s reaper в worker переводит задачи с истёкшим lease в `queued` со следующей попыткой или в `failed`. Новый захват получает новый `attempt`. Старый процесс не сможет зафиксировать результат из-за fencing. Запись тех же детерминированных объектов безвредна.
|
||
- **Retry.** Временные ошибки (S3, PostgreSQL, timeout, истёкший lease) дают `queued` с `attempt+1`, новой строкой outbox с `available_at = now() + delay` и записью причины в `jobs.last_error`. Задержка `d = min(JOB_BACKOFF_BASE_MS·2^(n−1), JOB_BACKOFF_MAX_MS)` выбирается случайно в `[d/2, d]` (equal jitter). Всего `JOB_MAX_ATTEMPTS = 5` попыток, затем `failed` с `retry_exhausted`. Постоянные ошибки сразу дают `failed` без повторов: `invalid_image` (файл не декодируется, превышен лимит пикселей), `processing_failed` (staging отсутствует или не совпадает sha256/размер).
|
||
- **Реестр failed и replay.** Реестр — `jobs` со статусом `failed` (`worker failed` выводит attachment_id, attempt, error_code, last_error). `worker replay <attachment_id>` переводит в `queued` только задачу в `failed`: даёт новый бюджет из `JOB_MAX_ATTEMPTS` попыток, пишет аудит в `job_replays` и строку outbox. Для `ready`/`queued`/`processing` результат `skipped_<status>`, дубля нет.
|
||
- **Варианты.** Все варианты строятся из пикселей и кодируются заново, поэтому EXIF и прочие метаданные не копируются. EXIF orientation (JPEG) применяется, alpha компонуется на белый, ресемплинг Catmull-Rom. Изображения больше 2560 px сначала уменьшаются вдвое блоком 2×2, чтобы ограничить промежуточный буфер. Итоговые размеры считаются от исходных.
|
||
- `thumbnail`: JPEG q=85, вписан в 256×256, без увеличения, размеры округляются вниз, минимум 1 px; fixture 320×200 → 256×160.
|
||
- `crop`: JPEG q=85, центральный квадрат, 128×128, маленькие исходники увеличиваются.
|
||
- `optimized`: WebP lossy, quality 80, method 4, вписан в 1280×1280 без увеличения. Уменьшение каждого маленького файла не обещается.
|
||
- **Состояния API.** POST upload → 202 `queued`. GET метаданных возвращает `queued` / `processing` / `ready` / `failed`. Для `ready` в `variants` три записи с размерами и sha256 реального файла. `/content` для не-ready → 409. `variant=` с неизвестным именем → 400. Отсутствующий вариант ready-объекта → 404. Прикрепить `failed`-вложение к сообщению → 409, `queued`/`processing` можно. Ready ставится одной транзакцией после записи оригинала и всех трёх вариантов.
|
||
- **Staging.** Удаляется worker'ом после COMMIT ready. Если удаление не прошло, `janitor` удаляет staging ready-вложений и staging без строки (старше `CLEANUP_GRACE_SECONDS`). Staging `failed` хранится `STAGING_RETENTION_SECONDS` (24 ч) ради replay. Staging `queued`/`processing` не удаляется.
|
||
- **Критичные зависимости.** `/health/ready` проверяет только PostgreSQL. Брокер не нужен синхронному пути: при его недоступности загрузки принимаются, задания копятся в outbox. Upload и download требуют S3 (иначе 503).
|
||
- **Внедрение отказов.** `FAULT_POINT` по умолчанию пуст. В тестах через `API_FAULT_POINT=after_commit` (выход процесса после COMMIT, до ответа и publish) и `WORKER_FAULT_POINT=after_store|before_ack` (выход после записи в S3 до COMMIT / после COMMIT до ack).
|
||
- Перенесено из lab4 без изменения смысла: сессии, идемпотентность сообщений, HAProxy, приватный bucket и отдельные ключи, janitor (дополнен очисткой staging), лимиты загрузки. Изменено: upload 201 → 202, `attachments.object_key` заполняется worker'ом, добавлена миграция `0004_jobs.sql`.
|
||
|
||
### Окна отказа
|
||
|
||
| Окно | Что происходит | Восстановление |
|
||
| --- | --- | --- |
|
||
| после staging до записи задания | объект в `staging/` без строки, клиент получает 503 или обрыв | janitor удаляет его после grace period |
|
||
| после COMMIT до publish | строка outbox не опубликована | relay любой API-реплики публикует; проверено (`faults.py`, 1) |
|
||
| после publish до confirm/пометки | сообщение в stream, строка outbox не помечена | повторная публикация → дубль → no-op при захвате |
|
||
| после записи S3 до COMMIT результата | задача `processing`, объекты записаны | lease истекает → reaper → попытка 2 перезаписывает те же ключи; проверено (`faults.py`, 2) |
|
||
| после COMMIT результата до ack | ready, сообщение в PEL | после рестарта worker дочитывает pending → no-op → ack; проверено (`faults.py`, 3) |
|
||
|
||
### Соответствие .env.example
|
||
|
||
| Переменная | Где используется |
|
||
| --- | --- |
|
||
| `API_REPLICAS` | `deploy.replicas` сервиса api |
|
||
| `S3_REGION`, `S3_BUCKET` | api, worker, janitor, s3-init, генерация прав в `mksecrets.sh` |
|
||
| `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS` | api (приём) и worker (повторная проверка) |
|
||
| `WORKER_CONCURRENCY` | число потребителей worker |
|
||
| `JOB_MAX_ATTEMPTS` | api записывает в `jobs.max_attempts`, replay выдаёт новый бюджет |
|
||
| `JOB_TIMEOUT_SECONDS` | таймаут задачи, lease = значение + 15 s |
|
||
| `JOB_BACKOFF_BASE_MS`, `JOB_BACKOFF_MAX_MS` | backoff повторов |
|
||
| `STAGING_RETENTION_SECONDS` | хранение staging failed-вложений (janitor) |
|
||
| `CLEANUP_GRACE_SECONDS`, `CLEANUP_INTERVAL_SECONDS` | janitor |
|
||
| `BROKER_URL_FILE`, `DATABASE_URL_FILE`, `S3_*_FILE` | задаются в compose как пути к secrets |
|
||
|
||
### Лимиты worker
|
||
|
||
| Ограничение | Значение |
|
||
| --- | --- |
|
||
| Bytes | размер staging должен совпасть с метаданными; чтение не более `MAX_UPLOAD_BYTES`, sha256 сверяется |
|
||
| Пиксели | `image.DecodeConfig` до декодирования, не более `MAX_IMAGE_PIXELS` (40 млн), иначе `invalid_image` |
|
||
| Время | `JOB_TIMEOUT_SECONDS` на задачу (S3, БД, проверки между этапами) |
|
||
| Память | 2 задачи одновременно, `GOMEMLIMIT=600MiB`, лимит контейнера 768 MiB, CPU 1.0 |
|
||
| Конкуренция | `WORKER_CONCURRENCY=2`, prefetch (`COUNT`) 1 на потребителя |
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||
| --- | --- | --- | --- |
|
||
| Публичный smoke (202 → ready, оригинал, настоящий JPEG 256×160) | `make check && make test` | PASS | evidence/smoke.txt |
|
||
| Отозванная сессия не воскресает после перезапуска Valkey | `tests/session_revocation.py` | Valkey остановлен → logout 204 → Valkey запущен → прежний токен 401 | evidence/session-revocation.txt |
|
||
| Минимум lab4 сохранён (валидация, доступ, приватный bucket, отказ S3, идемпотентность) | `tests/attachments.py`, `tests/s3_checks.py`, `tests/idempotency.py` | PASS: 413/415/400/404, анонимный доступ 403, 503 при остановленном S3 | evidence/attachments.txt, evidence/s3-checks.txt, evidence/idempotency.txt |
|
||
| Restart всех stores с volumes | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS; перезапущены postgres, valkey, broker, s3, api, lb, janitor, worker (состояния до/после в файле) | evidence/persistence.txt |
|
||
| Failover каждой API-реплики | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | PASS для api-1 и api-2, 0–1 неуспешная попытка, восстановление 3.5 s | evidence/failover-1.txt, evidence/failover-2.txt |
|
||
| Worker остановлен → upload 202 → сообщение → content 409 → рестарт broker и API → worker запущен → ready | `tests/queue_recovery.py` | задача есть в stream до и после рестарта broker, статус `queued` без worker, после старта ready, attempt 1, 3 варианта | evidence/queue-recovery.txt |
|
||
| Повторная доставка не размножает варианты | `tests/queue_recovery.py` (ручной `XADD` дубля) | `job delivery skipped`, ack, `updated_at` не изменился, 3 варианта | evidence/queue-recovery.txt |
|
||
| Thumbnail, crop 128×128, optimized WebP, качество/метаданные | `tests/variants.py` | размеры и форматы по реальным байтам, sha256 совпадает, без увеличения, alpha → белый, EXIF orientation 6 применена, EXIF в вариантах нет | evidence/variants.txt |
|
||
| Crash между COMMIT и publish | `tests/faults.py`, сценарий 1 | API упал после COMMIT (202 не получен), outbox опубликован другой репликой, ready attempt 1 | evidence/faults.txt |
|
||
| Остановка worker после записи объекта до COMMIT, timeout/lease | `tests/faults.py`, сценарий 2 | lease истёк, reaper вернул в очередь, ready attempt 2, вариантов 3 | evidence/faults.txt |
|
||
| Остановка worker после COMMIT до ack | `tests/faults.py`, сценарий 3 | после рестарта pending доставлен повторно, no-op, attempt 1, PEL пуст | evidence/faults.txt |
|
||
| Backoff с jitter, ограниченный retry, failed, replay | `tests/faults.py`, сценарий 4 | S3 остановлен: 4 повтора с задержками 931/1284/2760/7484 мс (окна [d/2, d]), `retry_exhausted`, задача в реестре, content и прикрепление → 409; replay → ready, повторный replay → `skipped_ready`, аудит 1 строка | evidence/faults.txt |
|
||
| Постоянная ошибка без повторов | `tests/faults.py`, сценарий 5 | PNG с повреждённым IDAT (проходит проверку API) → `invalid_image` на попытке 1 | evidence/faults.txt |
|
||
| Ограничение конкуренции, памяти и времени worker | `tests/worker_load.py` | 6 изображений по 39.9 млн пикселей + 20 малых: одновременно не более 2 processing, пик RSS 617 MiB при лимите 768 MiB, без OOM; при `JOB_TIMEOUT_SECONDS=1` — `context deadline exceeded`, 5 попыток, `retry_exhausted` | evidence/worker-load.json |
|
||
| Очистка staging после безопасной фиксации | `tests/s3_checks.py` | staging ready-вложения удалён, staging queued-задачи сохранён janitor'ом, staging без строки удалён | evidence/s3-checks.txt |
|
||
| Память API при загрузках | `tests/upload_memory.py` | 12 потоков × 3 файла по 9.3 MiB, 36/36 → 202, пик api 119 / 100 MiB при лимите 192 | evidence/upload-memory.json |
|
||
| Отказ реплики и rolling update под нагрузкой | `tests/scenario.py` | см. эксперименты | evidence/failover-each.json, evidence/rolling.json |
|
||
|
||
## Эксперименты и отказы
|
||
|
||
Стенд: один хост, Docker 29.9.2, Compose 5.6.1, лимиты контейнеров как выше. Нагрузка сообщений — 8 потоков, closed-loop, повтор с тем же ключом. Нагрузка worker — 6 PNG 6320×6320 (116 545 байт, однотонные: проверка лимита пикселей, а не сети) и 20 копий fixture.
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| Worker остановлен, upload | 202, работа ждёт | `queued`, content 409, текст работает | после старта worker ready, потерь нет |
|
||
| Restart broker и API с volumes при остановленном worker | задача не теряется | job_id в stream до и после | потерь нет |
|
||
| Падение API после COMMIT | задача не теряется без ручного вмешательства | outbox опубликован живой репликой | ready в пределах секунд, потерь нет |
|
||
| Падение worker после записи S3 | повтор того же результата | ready с attempt 2 после истечения lease 25 s (тест с `JOB_TIMEOUT_SECONDS=10`) | ≈ lease + 5 s, дублей нет |
|
||
| Падение worker после COMMIT | повторная доставка = no-op | skipped, ack | сразу после рестарта |
|
||
| S3 недоступен для worker | ограниченные повторы, failed | 5 попыток за ≈ 13 s, `retry_exhausted`, replay → ready | после replay, потерь нет |
|
||
| 6×40 Мп + 20 малых | не более 2 задач одновременно, память в лимите | все ready за 13.1 s, пик RSS 617 MiB / 768 | без OOM и рестартов |
|
||
| Остановка каждой API-реплики под нагрузкой | запись продолжается | 2 и 0 неуспешных попыток, RPS 439 / 447 против 524 до отказа | возврат реплики около 6.5 s |
|
||
| Rolling update | без простоя | 4 неуспешные попытки, RPS 615 | старые реплики не отвечают |
|
||
|
||
Первая версия без предварительного уменьшения упиралась в лимит 512 MiB (RSS 780 MiB при двух 40-Мп задачах). Причина — промежуточный буфер Catmull-Rom размером ширина_цели × высота_источника × 32 байта. После уменьшения блоком 2×2 пик стал около 600 MiB, а время двух таких задач сократилось с 11 до 4.6 s.
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
- Декодирование и ресемплинг одного этапа нельзя прервать: timeout проверяется между этапами и на S3/БД-операциях. Длительность этапа ограничена лимитом пикселей (около 2 s на 40 Мп).
|
||
- Broker, PostgreSQL, S3 и HAProxy — единичные экземпляры. `appendfsync always` надёжнее, но медленнее everysec. Stream не обрезается (`XTRIM` не реализован), он растёт на одну запись на попытку.
|
||
- Relay работает только в API: если остановлены обе реплики API, принятые задания ждут в outbox. Задержка relay до 300 ms.
|
||
- Имена потребителей привязаны к hostname контейнера: после пересоздания worker старые pending переходят к новым через `XAUTOCLAIM` только после lease (75 s), а старые consumer'ы остаются в группе.
|
||
- EXIF orientation читается только у JPEG; eXIf-чанк PNG не учитывается.
|
||
- `pipeline_version` фиксирован (1). Версионирование нескольких pipeline (трек 5) не делалось.
|
||
- Replay — операторская CLI-команда без HTTP API. `last_error` хранит внутренний текст ошибки только в БД и наружу не выдаётся.
|
||
- WebP кодируется транспилированным libwebp (без CGo): медленнее нативного, но без системных библиотек.
|
||
- Секреты лежат в `./secrets` вне Git. Для чтения процессом с UID 10001 у них права 644: это допустимо только для локального стенда.
|