forked from mtusi2026/mtusi2026lab5
102 lines
18 KiB
Markdown
102 lines
18 KiB
Markdown
# Отчёт — лабораторная 5
|
||
|
||
- Автор и группа — Ситосенко, БВТ2303.
|
||
- Целевая оценка — **5**, трек 2 «Доказанная идемпотентность pipeline».
|
||
- Реализация основана на собственном коде lab4. Codex использовался для переноса кода, реализации очереди, подготовки эксперимента и проверки.
|
||
- Источники — [Valkey Streams](https://valkey.io/commands/xautoclaim/), [Valkey AOF](https://valkey.io/topics/persistence/), [условная запись S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/conditional-writes.html), [Pillow](https://pypi.org/project/pillow/).
|
||
|
||
## Запуск
|
||
|
||
Нужны Docker с Linux-контейнерами, Compose v2 и Python 3.9+ для клиентских проверок. Для сборки нужен доступ к реестру образов, Go modules и PyPI. Команды запуска в PowerShell из корня clone.
|
||
|
||
```powershell
|
||
python -X utf8 scripts/bootstrap.py
|
||
docker compose --env-file .env config --quiet
|
||
docker compose --env-file .env up -d --build --wait --wait-timeout 150
|
||
$env:BASE_URL = "http://127.0.0.1:8080"
|
||
python -X utf8 scripts/check_contract.py
|
||
python -X utf8 tests/smoke.py
|
||
python -X utf8 student-tests/image_rules.py
|
||
python -X utf8 student-tests/pipeline_faults.py
|
||
```
|
||
|
||
На Unix эквиваленты проверки контракта и публичного smoke — `make check` и `make test`. Проверки перезапуска выполняются последовательно на выделенном учебном стенде.
|
||
|
||
```sh
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
|
||
docker compose start api
|
||
```
|
||
|
||
Bootstrap генерирует локальные секреты и `.env` при их отсутствии. Миграции `001`–`005` применяет одноразовый сервис `migrate`. Старые записи lab4 с исходником в `original/<id>` читаются по этому ключу с `result_version=0`. Сервис `s3-init` создаёт приватный бакет и ограниченные учётные записи. API доступны через HAProxy на `127.0.0.1:8080`. `APP_PORT` задаёт внешний порт. При его изменении задайте тестам соответствующий `BASE_URL`.
|
||
|
||
`docker compose down` останавливает стенд и сохраняет volumes. `docker compose down --volumes` предназначена для намеренного удаления данных **своего учебного проекта** после завершения проверок.
|
||
|
||
Стек использует Go 1.27.3, PostgreSQL 17.6, Valkey 8.1.3, HAProxy 3.2.6, MinIO из фиксированного коммита `9e49d5e7a648`, Python 3.13.18 и Pillow 13.0.0. `compose.yaml` задаёт лимиты сервисов. Worker получает 1 vCPU, 640 MiB памяти, 32 MiB tmpfs и обрабатывает одно задание за раз с prefetch 1. Локальный HTTP используется для синтетических данных.
|
||
|
||
## Архитектура
|
||
|
||
1. API проверяет Bearer-сессию, членство в чате, filename, MIME, целостность изображения и лимиты 10 MiB и 40 млн пикселей. Исходные байты и SHA-256 передаются в приватный S3 staging под серверным UUID. Принятие до `202 queued` включает завершившийся S3 PUT и commit строки вложения вместе с записью задания в PostgreSQL.
|
||
2. `image_jobs` служит реестром заданий и transactional outbox. Dispatcher отправляет JSON одним полем `job` через XADD, затем фиксирует признак публикации. JSON несёт поля `schema_version`, `job_id`, `type`, `attachment_id`, `pipeline_version`, `attempt`, `created_at` по `jobs.schema.json`. Valkey для очереди имеет собственный volume, AOF с `appendfsync always` и `noeviction`.
|
||
3. Worker читает Streams через consumer group, захватывает задание с lease и сверяет ID, версию и номер попытки с PostgreSQL. Истёкшие lease восстанавливает dispatcher. `XAUTOCLAIM` возвращает потерянные pending delivery. После устойчивого завершения либо записи retry/failed worker подтверждает доставку и удаляет запись из Streams одной командой Lua. Дубли завершённых и устаревших попыток подтверждаются по сохранённому состоянию.
|
||
4. Worker проверяет SHA-256 и длину исходника и запускает ограниченный по времени процесс Pillow. Thumbnail — JPEG качества 85, вписанный в 256×256, с округлением вниз и без увеличения. Crop — JPEG качества 85, центрированный квадрат 128×128. Optimized — WebP качества 80 в v1 и 90 в v2, до 1280×1280 без увеличения. Для вариантов применяется EXIF orientation, прозрачность компонуется на белый фон, а EXIF, ICC и текстовые метаданные удаляются. Исходник сохраняется побайтно.
|
||
5. Эффект привязан к `(attachment_id, pipeline_version, variant)`. S3 PUT с `If-None-Match: *` исключает повторную запись уже существующего объекта. При 412 сверяются размер, MIME и SHA-256 из метаданных объекта. После записи всех объектов одна транзакция фиксирует результат с проверкой активной версии и lease. GET использует атомарно опубликованную версию. Читатели видят v1 в ходе подготовки v2 и переключаются на v2 после commit.
|
||
6. Невалидное изображение и нарушение целостности считаются постоянными ошибками. Временный отказ возвращает задание в очередь с экспоненциальной задержкой и jitter от 100% до 200% базового интервала, с базой от 1 до 32 секунд. По исчерпании лимита выдаётся `retry_exhausted`. Dispatcher очищает staging после публикации результата, для failed — после retention, для orphan — после часа и повторной проверки строки под тем же lock, что использует upload.
|
||
7. Разрешения S3 разделены для API и фоновой обработки. API пишет staging и читает опубликованные варианты, фоновая учётная запись может записывать результаты и удалять staging. API сохраняет регистрацию, Argon2id, постоянные сессии Valkey, права чата, keyset-пагинацию и идемпотентность сообщений из lab4. Broker, worker и dispatcher работают независимо от синхронной readiness API, которая проверяет PostgreSQL, Valkey сессий и S3.
|
||
|
||
`JOB_MAX_ATTEMPTS` задаёт число попыток за цикл (5 по умолчанию), `JOB_TIMEOUT_SECONDS` — время обработки (30 секунд). Lease длиннее на 5 секунд. `STAGING_RETENTION_SECONDS` — срок хранения failed-исходника для replay (86400 секунд). `WORKER_CONCURRENCY=1` закрепляет один слот в контейнере. Лимиты байт и пикселей зафиксированы в коде по контракту. Настройки endpoint, region и bucket в Compose относятся к встроенному локальному S3.
|
||
|
||
Команды оператора доступны через Compose и используют доступ к PostgreSQL.
|
||
|
||
```sh
|
||
docker compose run --rm --no-deps dispatcher jobs failed
|
||
docker compose run --rm --no-deps dispatcher jobs replay <job-id>
|
||
docker compose run --rm --no-deps dispatcher jobs upgrade <attachment-id>
|
||
```
|
||
|
||
Replay разрешён для текущего failed-задания, пока staging может использоваться. Он сохраняет `job_id`, увеличивает attempt, начинает новый цикл и добавляет запись в аудит. Для v2 источником служит опубликованный оригинал v1. Upgrade переводит готовый результат v1 на v2 без изменения публичного HTTP API.
|
||
|
||
## Эксперимент
|
||
|
||
**Гипотеза.** Подтверждённая загрузка доходит до ready после каждого моделируемого сбоя. Переотправка или переупорядочивание заданий сохраняет по одному набору объектов на версию и оставляет опубликованную v2 неизменной.
|
||
|
||
Скрипт `student-tests/pipeline_faults.py` использует синтетический PNG 320×200 и последовательно проводит сценарии на одном стенде. Каждый сценарий получает новый attachment ID. Для сбоя запускается отдельный контейнер нужной роли с failpoint, привязанным к этому ID. Скрипт проверяет код завершения 86 и маркер точки сбоя. Через HTTP, PostgreSQL, Streams и S3 проверяются статусы, попытки, опубликованные версии, размеры, контрольные суммы и время записи объектов. Время в JSON отсчитывается от получения 202 и включает запуск контейнеров и ожидание подтверждений. Это последовательная проверка корректности, без нагрузочного прогона.
|
||
|
||
| Критерий | Проверка | Доказательство |
|
||
| --- | --- | --- |
|
||
| Публичный контракт и smoke | `scripts/check_contract.py`, `tests/smoke.py` | [contract.txt](evidence/contract.txt), [openapi.txt](evidence/openapi.txt), [smoke.txt](evidence/smoke.txt) |
|
||
| Отправка сообщения с queued-вложением, перезапуск API и broker при остановленном worker | Сценарий `api_broker_restart_with_worker_stopped`, сверка StartedAt, записи Streams и оригинала | [pipeline.json](evidence/pipeline.json) |
|
||
| Геометрия, EXIF, alpha, форматы и лимиты | `student-tests/image_rules.py` | [image-rules.txt](evidence/image-rules.txt) |
|
||
| COMMIT до XADD и сбой после XADD | Сценарии `before_publish` и `after_publish` | [pipeline.json](evidence/pipeline.json) |
|
||
| Lease и сбой до/после записи S3 и после commit до ack | `before_effect`, `after_effect`, `after_commit`, проверка pending и LastModified/ETag | [pipeline.json](evidence/pipeline.json) |
|
||
| Ограниченный retry, failed и операторский replay | `invalid_image_replay`, `temporary_replay`, проверка backoff и записи аудита | [pipeline.json](evidence/pipeline.json) |
|
||
| Reorder и поздняя доставка старой версии | `reorder_and_stale_version`, проверка версии и неизменности S3 | [pipeline.json](evidence/pipeline.json) |
|
||
|
||
Прогон выполнялся в Docker Desktop на Windows, движок Docker 29.3.0, Compose 5.1.0, Linux amd64. Docker VM предоставляла 12 логических CPU и 3,68 GiB памяти. Дополнительного прогрева не было, перед экспериментом прошли smoke и проверка форматов. Для каждого воздействия использовалась одна загрузка и отдельный набор ожидаемых переходов.
|
||
|
||
## Результаты прогона
|
||
|
||
| Воздействие | Наблюдение | Время сценария |
|
||
| --- | --- | --- |
|
||
| Перезапуск API и брокера | Та же запись Streams сохранилась после перезапуска трёх контейнеров. Сообщение было создано с queued-вложением. Исходник и варианты доступны после запуска worker. | 39,9 с |
|
||
| Сбой до XADD | В Streams было 0 записей. Dispatcher восстановил задание из outbox, после чего загрузка стала ready. | 29,0 с |
|
||
| Сбой после XADD | Dispatcher опубликовал тот же job_id повторно. Две доставки завершились одним набором вариантов и одной попыткой. | 29,0 с |
|
||
| Сбой до записи S3 | В S3 результата ещё не было. Истечение lease запустило вторую попытку, вложение стало ready. | 60,8 с |
|
||
| Сбой после записи S3 | До сбоя был записан оригинал. Вторая попытка сохранила его ETag и LastModified, дописала варианты и опубликовала результат. | 88,9 с |
|
||
| Сбой после commit до ack | Была pending-доставка при ready. Повтор подтвердил её без дополнительной попытки и перезаписи объекта. | 49,0 с |
|
||
| Постоянная ошибка | Одна попытка, затем invalid_image. Операторский replay завершился ready с одной записью аудита. | 42,2 с |
|
||
| Временная ошибка | После 5 попыток получен retry_exhausted. После replay вложение стало ready. | 73,7 с |
|
||
| Переупорядочивание и поздний дубль | Последовательность версий 2, 1, 2, 1, 2 сохранила один результат на версию и итоговую v2. Проверены контрольные суммы, ETag и LastModified. | 62,4 с |
|
||
|
||
Во всех девяти сценариях подтверждённая загрузка дошла до ready. Сырые результаты с ID и длительностью сохранены в [pipeline.json](evidence/pipeline.json). Прогон выполнен с настройками из `.env.example` и именем проекта `mtusi-lab5`.
|
||
|
||
Для сборки Linux amd64 `govulncheck` не нашёл достижимых уязвимостей в Go-коде. Проверка охватывает Go-пакеты приложения. [go-vuln.txt](evidence/go-vuln.txt)
|
||
|
||
Публичные persistence и failover прошли с неизменёнными тестами и сессией. Сценарии сохранили подтверждённые сообщения и оригинал вложения. Прогон failover через localhost на Windows дал около 2 с задержки клиента на запрос и исчерпал окно записи. При первом прогоне по IPv4 холодный запуск Argon2id превысил таймаут регистрации. Зачётный прогон через 127.0.0.1 после двух синтетических регистраций и входов дал 115 успешных записей, 4 переходных ошибки и первую успешную запись после остановки через 3,881 с. [persistence.txt](evidence/persistence.txt), [failover.txt](evidence/failover.txt), [до перезапуска](evidence/restart-before.txt), [после перезапуска](evidence/restart-after.txt), [до остановки реплики](evidence/stopped-before.txt), [после остановки реплики](evidence/stopped-after.txt)
|
||
|
||
## Границы
|
||
|
||
XADD и commit в PostgreSQL — отдельные операции. Подтверждение XADD означает приём брокером. Consumer ack относится к отдельной доставке и может потеряться после успешной фиксации результата. Поэтому Streams доставляет at least once, а единственность эффекта обеспечивают условная запись S3 и проверка состояния в PostgreSQL.
|
||
|
||
Эксперимент проверяет отказы процессов и рестарт broker с сохранённым volume. Потеря хоста или постоянного хранилища, сетевой split-brain и максимальная пропускная способность за пределами методики. Старые конечные версии сохраняются для чтения и анализа. MinIO CE унаследован из lab4 и ограничен внутренним сегментом и фильтрацией HAProxy. Стенд рассчитан на локальный учебный запуск.
|