Files
mtusi2026lab5/REPORT.md
T

235 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Лабораторная 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 и повторы ограничивают обобщение на большие файлы.