235 lines
18 KiB
Markdown
235 lines
18 KiB
Markdown
# Лабораторная 5 — Маслов, БВТ2301
|
||
|
||
Цель: **5, трек 2 — идемпотентность versioned pipeline**. Собственная ЛР4
|
||
перенесена в независимую историю текущего teacher skeleton; обязательные
|
||
contracts/tests/check/validate сохранены. API принимает исходник, а отдельный
|
||
worker публикует original/thumbnail/crop/optimized. Исследование проверяет
|
||
дубли, reorder и реальные SIGKILL, а не моделирует их ответами mock.
|
||
|
||
Результаты полного fault-injection и clean clone будут внесены после запуска.
|
||
Промежуточный public smoke уже PASS; итоговые evidence ниже обновляются
|
||
только фактическими командами. Первый запуск HTTP suite ошибочно обращался
|
||
к порту предыдущей лабы; `http-initial-environment.json` честно отмечает
|
||
INVALID_ENVIRONMENT, это не проверка корректности API.
|
||
|
||
## Воспроизведение
|
||
|
||
Нужны Git, Docker Desktop с Compose v2, uv0.13.7. Версии Python3.14.7,
|
||
PostgreSQL18.3, Valkey8.1.3, HAProxy3.2.1, Pillow13.0.0 закреплены;
|
||
MinIO/mc собираются из точных upstream commits в infra/s3.Dockerfile,
|
||
Go module checksum проверяется GoSumDB. Сборка требует доступа к registries,
|
||
Go module proxy и PyPI; наличие сети нельзя заменить уже установленной БД.
|
||
|
||
```sh
|
||
uv sync --locked
|
||
make bootstrap
|
||
VCS_REF=$(git rev-parse HEAD) docker compose up -d --build --wait
|
||
make check validate PYTHON=.venv/bin/python
|
||
make lint unit
|
||
NO_PROXY=localhost,127.0.0.1 no_proxy=localhost,127.0.0.1 make test PYTHON=.venv/bin/python
|
||
BASE_URL=http://127.0.0.1:8085 make test-student
|
||
```
|
||
|
||
URL: http://127.0.0.1:8085. API не имеет persistent volume/host port.
|
||
Bootstrap создаёт только отсутствующие secrets и .env; не печатает значения,
|
||
не перезаписывает существующие. `secrets/`0700, файлы0644 нужны UID10001
|
||
через readonly Docker secrets mounts; сам каталог недоступен другим users.
|
||
`docker compose down` сохраняет volumes. Удаление volumes — отдельное
|
||
осознанное действие над своим синтетическим стендом.
|
||
|
||
Для автоматических отказов включается только явный test override:
|
||
|
||
```sh
|
||
export COMPOSE_FILE=compose.yaml:compose.test.yaml
|
||
export NO_PROXY=localhost,127.0.0.1 no_proxy=localhost,127.0.0.1
|
||
VCS_REF=$(git rev-parse HEAD) docker compose up -d --build --wait
|
||
uv run --locked python -m scripts.verify_cleanup seed --seed evidence/gc-seed-repeat.json
|
||
uv run --locked python -m scripts.verify_pipeline --output evidence/pipeline-repeat.json --repeats 2
|
||
uv run --locked python -m scripts.verify_cleanup verify --seed evidence/gc-seed-repeat.json --output evidence/gc-repeat.json
|
||
uv run --locked python -m scripts.verify_cluster --output evidence/cluster-repeat.json
|
||
```
|
||
|
||
Проверки, меняющие состояние контейнеров, выполняются последовательно.
|
||
Seed и результат — разные файлы; нельзя использовать seed с уже удалённым
|
||
orphan. Verify ожидает настоящий возраст S3 не менее302s; часы/LastModified
|
||
не подменяются. Для нового полного чистого повторения:
|
||
|
||
```sh
|
||
# Перед стартом весь проверяемый source должен быть закоммичен и git clean.
|
||
uv run --locked python scripts/verify_clean.py --output evidence/clean-clone-repeat.json
|
||
```
|
||
|
||
Этот verifier создаёт отдельные secrets/env/volumes/image/project, собирает,
|
||
запускает static/unit/public smoke/HTTP, cluster, всю fault matrix и cleanup,
|
||
сверяет source hashes и OCI revision обоих API, worker, relay, reconciler и
|
||
тестового controller; после удаляет только временный проект и его volumes.
|
||
|
||
## Границы устойчивости
|
||
|
||
1. API проверяет фактические bytes≤10MiB, MIME PNG/JPEG, декодирование,
|
||
filename и ≤40M pixels до полной распаковки. Временный spool≤1MiB в RAM,
|
||
затем bounded tmpfs; upload slots2/API, decode slot1/API, срок запроса20s.
|
||
2. Устойчивый upload reservation120s COMMIT предшествует PUT в приватный
|
||
`objects/staging/<UUID>/original`. После PUT одна PG transaction проверяет
|
||
reservation с FOR UPDATE, создаёт Attachment queued + logical Job + Outbox,
|
||
удаляет reservation и COMMIT. Только затем202 с захваченным queued-снимком.
|
||
Быстрый worker не превращает upload-ответ в ready. Сам upload не имеет
|
||
Idempotency-Key: потерянный HTTP-ответ нельзя безопасно повторять вслепую.
|
||
3. API зависит от PG и S3 для ready, cache используется как необязательный
|
||
read-through user cache. Broker не критичен для синхронного приёма:
|
||
работа остаётся в outbox. Relay имеет PG+broker secrets, не S3/root keys.
|
||
4. Relay читает due outbox FOR UPDATE SKIP LOCKED, XADD и WAITAOF1/0/2000
|
||
**на одной выделенной connection**. Подтверждён fsync локального AOF;
|
||
только затем published_at/COMMIT в PG. Crash в этом окне даёт дубль.
|
||
5. Отдельный Valkey Streams broker с persistent volume, AOF appendfsync always,
|
||
noeviction. Disposable cache — другой сервис/volume/policy. Нет Pub/Sub.
|
||
6. Worker consumer group, COUNT=1 на каждый из2 слотов; XAUTOCLAIM возвращает
|
||
зависшие PEL entries. PG атомарно переводит queued→processing, увеличивает
|
||
attempt/fence, сохраняет owner/lease. Duplicate active оставляется pending;
|
||
ready duplicate делает HEAD всех4вариантов/size/SHA metadata и ACK без resize.
|
||
7. Child получает ID/fence, trusted source берётся из PG, не из произвольного
|
||
URL или filename. До обработки проверяется исходный size/SHA. Все4 PUT идут
|
||
в `objects/<attachment>/v<version>/<variant>`. Original побайтно неизменён.
|
||
8. В одной PG transaction worker проверяет state/version/fence/live lease,
|
||
публикует metadata всех вариантов, unique effect_publication и ready.
|
||
Старый child может дописать свой version-prefix, но не подтвердить новый
|
||
результат. Стабильный алгоритм нельзя менять под тем же pipeline_version.
|
||
9. ACK только после устойчивой ready, failed/obsolete или решения queued retry.
|
||
Watchdog relay восстанавливает expired leases; pending outbox сохраняет retry.
|
||
Потерянные wakeups queued jobs переиздаются через15s без создания logical job.
|
||
|
||
## Состояния и варианты
|
||
|
||
GET показывает queued/processing/ready/failed. Queued/processing можно связать
|
||
с Message; failed —409. Все metadata/content проходят Bearer+membership,
|
||
чужой/неизвестный UUID —404, content до ready —409. У ready все3 производных
|
||
варианта и error_code=null; size/content_type/SHA описывают original.
|
||
Прямого redirect/public S3 URL нет. Atomic Message+Idempotency-Key сохранены.
|
||
|
||
EXIF orientation применяется; RGBA компонуется на белом. Thumbnail JPEG
|
||
вписан≤256×256 без увеличения, floor/min1;320×200→256×160. Crop — центральный
|
||
JPEG128×128 с допустимым увеличением маленького исходника. JPEGquality85,
|
||
subsampling0,LANCZOS. Optimized — WebP≤1280×1280 без увеличения, quality82(v1)
|
||
или76(v2), method4. EXIF/info удаляются из производных; metadata original
|
||
сохраняются в исходных bytes. Маленький WebP не обязательно меньше original.
|
||
|
||
Job соответствует contracts/jobs.schema.json: schema_version1,
|
||
type attachment.process.v1, UUID job/attachment, version, attempt>=1, RFC3339
|
||
created_at; возможен W3C carrier. Bytes/credentials/paths/URL запрещены.
|
||
Broker redelivery не меняет job_id; finite replay сохраняет job_id и увеличивает
|
||
cycle; новая pipeline version получает новый job_id. Idempotency effect key —
|
||
(attachment_id,pipeline_version,variant), PK в PG и детерминированный S3 key.
|
||
|
||
## Ограничение ресурсов и повторы
|
||
|
||
| Роль | CPU | RAM | Ограничение работы |
|
||
| --- | --- | --- | --- |
|
||
| API каждая из2 |0.5|768MiB|2uploads,1decode,128MiB tmpfs|
|
||
| Worker |2|1536MiB|2child,COUNT1/slot,child RLIMIT_AS768MiB|
|
||
| Relay |0.25|192MiB|один bounded publish/transaction|
|
||
| Broker |0.5|256MiB|192MiB maxmemory,noeviction,AOF volume|
|
||
| PostgreSQL |1|512MiB|pool10/API,4/worker-slot|
|
||
| S3 |1|1024MiB|persistent volume,private bucket|
|
||
| Reconciler |0.25|256MiB|inventory проход/60s|
|
||
|
||
Normal timeout20s / lease23s; test override12s/15s даёт время контроллеру
|
||
завершить v2 в другой slot пока v1 удерживается после PUT. Child действительно
|
||
killable: parent убивает процесс по timeout, а не лишь отменяет future/thread.
|
||
Весь container ограничен cgroup; лимит40M pixels не обещает, что всякий такой
|
||
файл уложится в память и срок — memory_limit/timeout приводят к safe failed/retry.
|
||
|
||
Максимум5attempts; временные ошибки/смерть worker/timeout → persisted next_at
|
||
с jitter uniform0.25…min(30,2^attempt)s. Постоянные decode/checksum/memory ошибки
|
||
сразу failed; временные после5→retry_exhausted. Публичные error_code безопасны,
|
||
без stack/SQL/key. Реестр failed и audited replay доступны только оператору:
|
||
|
||
```sh
|
||
docker compose exec worker python -m src.operator failed
|
||
docker compose exec worker python -m src.operator replay --job-id UUID --operator maslov --reason 'Synthetic recovery demonstration'
|
||
docker compose exec worker python -m src.operator version --job-id UUID --version 2 --operator maslov --reason 'Upgrade pipeline'
|
||
docker compose run --rm --no-deps reconciler python -m src.reconcile
|
||
docker compose run --rm --no-deps reconciler python -m src.reconcile --apply
|
||
```
|
||
|
||
Ready replay отвергается. Failed replay проверяет наличие source, оставляет
|
||
audit и новый finite cycle. После source_expired нельзя обещать обработку
|
||
отсутствующих bytes. New-version поддерживает реализованный переход1→2.
|
||
|
||
## Retention
|
||
|
||
Staging удаляется после безопасного COMMIT ready; сбой удаления не отменяет
|
||
результат, последующий GC уберёт остаток. Failed/unconfirmed source и orphan
|
||
живут минимум retention86400s, конфигурационный hard minimum300s. Cleanup
|
||
по умолчанию dry-run; --apply явный. Active queued/processing source и prefix,
|
||
действующий reservation и current published variants защищены. Перед delete
|
||
повторяются PG lock/recheck и HEAD реального возраста. Expired reservation
|
||
удаляется под lock; API не сможет поздно подтвердить удалённый source.
|
||
Старые версии после успешной новой могут удаляться; metadata/audit сохраняются.
|
||
Failed без source остаётся failed/source_expired и replay отвергается.
|
||
Текущий original не удаляется лишь из-за отсутствия Message links.
|
||
|
||
## Исследование: гипотеза и инварианты
|
||
|
||
Гипотеза: durable intent/outbox + PG version/fence/lease CAS + immutable
|
||
version keys сохраняют подтверждённую работу и не допускают publication старой
|
||
версии поверх новой при at-least-once delivery.
|
||
|
||
Проверяемые инварианты: каждый202 имеет durable Job; все принятые matrix jobs
|
||
доходят до ready или наблюдаемого failed; финальный ready имеет ровно4 variant
|
||
rows/keys и1effect_publication на версию; original SHA равен загрузке;
|
||
old version не меняет hashes текущей; конечный retry/replay наблюдаемы;
|
||
cleanup не удаляет current/active/fresh. До handoff crash не получает202.
|
||
|
||
`scripts/verify_pipeline.py --repeats2` использует отдельный test controller
|
||
с PG/S3/broker secrets (API не получает broker secrets), single-use hooks в PG
|
||
с durable hit_at, реальные container SIGKILL и повторный запуск. Hooks по
|
||
умолчанию выключены, публичного endpoint для них нет. Проверяются:
|
||
source-before-handoff, COMMIT-before-publish, confirmed broker SIGKILL/volume,
|
||
relay XADD-before-PG-marker, worker before_effect/after_effect/after_commit
|
||
каждый дважды; transient, timeout, permanent/replay,5attempt exhaustion/replay,
|
||
duplicates/reorder, held stalev1 послеv2 и старые notifications; malformed
|
||
notification, private IAM/anonymous denial и другая API после uploader stop.
|
||
|
||
Raw evidence сохраняет IDs, attempts, fences, events,4keys/checksums и
|
||
publications. Worker child_finished даёт elapsed/CPU/peakRSS; это длительность
|
||
child, не полный queue lag. Исследование про корректность, не максимальный RPS.
|
||
|
||
## Вопросы защиты
|
||
|
||
**Publisher confirm и consumer ACK?** Первый подтверждает durable приём брокером
|
||
(здесь локальный AOF fsync через WAITAOF), второй — устойчивое завершение или
|
||
сохранённое решение о повторе у consumer. Между PG/Valkey/S3 нет общей transaction.
|
||
|
||
**Что уже сохранено к202?** Полный проверенный original в private persistent
|
||
S3 staging плюс attachment/job/outbox в одной подтверждённой PG transaction.
|
||
Смерть API/worker не удаляет намерение. Перед202 тяжёлого resize нет.
|
||
|
||
**Почему дубли нормальны?** Producer/consumer могут потерять ответ после
|
||
успешного действия. Отправитель повторяет, поскольку не знает исход. Logical
|
||
job_id и effect tuple/version/fence позволяют повторить доставку безопасно.
|
||
Ровно одна publication в PG не означает exactly-once delivery в broker.
|
||
|
||
**Как отличить зависший worker от долгого?** Совершенно точно нельзя: lease —
|
||
выбранный бюджет. Parent timeout убивает child; watchdog восстанавливает работу
|
||
после lease, новый fence делает старое завершение недействительным. Ограничение
|
||
slots/COUNT сдерживает конкуренцию. Возможен лишний PUT, но не старый COMMIT.
|
||
|
||
## Источники, помощь, ограничения
|
||
|
||
Использованы текущие teacher contracts, собственная ЛР4, pinned dependencies,
|
||
[Valkey WAITAOF](https://valkey.io/commands/waitaof/),
|
||
[Valkey XAUTOCLAIM](https://valkey.io/commands/xautoclaim/),
|
||
[Pillow ImageOps](https://pillow.readthedocs.io/en/stable/reference/ImageOps.html).
|
||
При проектировании, реализации, тестах и отчёте использована помощь ИИ.
|
||
Код/данные/история других студентов не использовались; результаты — реальные
|
||
локальные запуски, а remote CI отдельно не считается прошедшим.
|
||
|
||
Один host/LB/PG/S3/broker — SPOF, AOF/fsync/volume не заменяет backup и защиту
|
||
от потери диска. HTTP допустим для локальных синтетических данных; удалённый
|
||
доступ требует TLS. Строгого production exactly-once нет. HEAD metadata не
|
||
заменяет полный periodic checksum audit. Удалённые bytes не восстановить по SHA.
|
||
Весь inventory GC хранится в RAM, outbox/events/audit требуют retention при
|
||
долгой эксплуатации. Нет global admission quota: при долгой недоступности
|
||
worker/broker PG outbox может расти; исследование перегрузки — другой трек.
|
||
Short synthetic fixtures и повторы ограничивают обобщение на большие файлы.
|