Добавить отчёт и доказательства ЛР 5

This commit is contained in:
2026-11-17 19:36:41 +03:00
parent 3ed3046df1
commit 1b793384b6
2 changed files with 208 additions and 17 deletions
+115 -17
View File
@@ -1,37 +1,135 @@
# Отчёт — лабораторная 5
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа: заполнить перед сдачей.
- Целевая оценка: 4.
- Commit/PR: заполнить после финального commit/push.
- Библиотеки: FastAPI, SQLAlchemy/asyncpg, aio-pika, Pillow, boto3, Redis.
При реализации использовалась помощь ИИ; решения проверены тестами из репозитория.
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Требуются Docker с Compose v2, Make и Python 3.9+ для внешних smoke-скриптов.
Образы закреплены в Compose: Python 3.13.15, PostgreSQL 17.4, Redis 7.4.2,
RabbitMQ 4.1.4, HAProxy 3.2.26 и MinIO по digest.
```sh
cp .env.example .env
# Заменить все change-me-* локальными значениями; .env не коммитить.
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
docker compose --env-file .env ps
make test BASE_URL=http://localhost:8080
make test-pipeline-smoke BASE_URL=http://localhost:8080
```
Миграции выполняет отдельный `migrate` service до старта API/publisher/worker.
Обычная остановка сохраняет данные:
```sh
docker compose --env-file .env down
```
Намеренное удаление всех учебных данных выполняется только явной командой
`docker compose --env-file .env down -v`. Она необратимо удаляет volumes PostgreSQL,
Redis, RabbitMQ и MinIO.
Для воспроизводимых тестов используется изолированный стенд:
```sh
docker compose -f compose.tests.yaml up -d --build --wait
docker compose -f compose.tests.yaml run --rm tests
```
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab4, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
Поток данных:
```text
HTTP API -> private S3 staging -> PostgreSQL attachment/job/outbox -> 202
|
v
outbox publisher -> RabbitMQ
|
v
worker pool
|
final S3 objects <- variants/original -> PostgreSQL ready
```
PostgreSQL — источник истины для состояния job, failed registry и решения о replay.
RabbitMQ обеспечивает durable очередь, publisher confirms, manual consumer ack и DLQ.
Сообщение содержит только versioned IDs и номера попытки, без байтов, credentials и
клиентского пути. Ответ 202 отправляется лишь после записи исходника в private staging
и одной транзакции `attachment + job + outbox`; broker может быть временно недоступен.
Идемпотентность основана на уникальной паре `(attachment_id, pipeline_version)` и
детерминированных S3 keys. Варианты upsert-ятся по
`(attachment_id, pipeline_version, name)`. `ready` проверяет полноту эффекта и не
исполняется повторно. Это at-least-once, а не exactly-once: delivery может повториться,
но логический результат остаётся один.
Worker создаёт неизменённый original, JPEG thumbnail в bounding box 256×256 без
увеличения, центрированный JPEG crop 128×128 и WebP optimized в bounding box
1280×1280 без увеличения. EXIF orientation применяется перед resize; alpha
компонуется на белый, входные metadata не копируются. Quality задаются через
`THUMBNAIL_JPEG_QUALITY=85`, `CROP_JPEG_QUALITY=85` и
`OPTIMIZED_WEBP_QUALITY=82`.
Временные ошибки повторяются с exponential backoff и jitter до `JOB_MAX_ATTEMPTS`.
Постоянные ошибки сразу переходят в `failed` с безопасным code и RabbitMQ DLQ.
Lease возвращает брошенный `processing` в очередь. Обработка изображения вынесена в
дочерний процесс с timeout и лимитом адресного пространства 512 MiB; дополнительно
ограничены upload bytes, decoded pixels, worker concurrency и prefetch.
Staging удаляется только после DB commit состояния `ready`. Отдельный cleanup удаляет
лишь terminal staging старше retention; `--dry-run` включён для операторской проверки.
Replay разрешён только для failed job с существующим staging, записывается в audit и
повторный replay ready job отклоняется.
Из lab4 сохранены auth/session, чаты/сообщения, идемпотентность HTTP, private S3 и
доступ к attachment только членам чата. Изменён только объявленный контракт upload
`201 -> 202` и асинхронные состояния. Старые lab4 benchmark/evidence и проверки
S3 outage/failover не копировались: они не доказывают новые критерии lab5; вместо них
добавлены pipeline/outbox/broker/worker/DLQ fault tests.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
Полный журнал команд и кратких результатов находится в
[`evidence/lab5-grade4.md`](evidence/lab5-grade4.md).
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
| Критерий | Команда/сценарий | Наблюдаемый результат |
| --- | --- | --- |
| Контракт и unit/negative | `make check`; Docker pytest | PASS; 19 passed |
| Публичный API | `python3 tests/smoke.py ...` | upload 202, polling ready, original/thumbnail и прежний API проходят |
| Grade-4 variants | `tests/pipeline_smoke.py`; `tests/test_pipeline.py` | original + thumbnail/crop/optimized, EXIF/alpha/no-upscale/checksum и большой IPC-result |
| COMMIT → publish | `tests/outbox_recovery.py` | после старта publisher прежняя job стала ready без нового upload |
| Confirm → outbox mark | `tests/publisher_confirm_crash.py` | повтор publish дал один логический результат |
| Worker outage | `tests/worker_outage.py` | stop → 202 → message → API restart → worker → ready |
| Broker persistence | `tests/broker_persistence.py` | durable delivery пережила restart broker с volume |
| Crash до ack | `tests/worker_crash.py`, оба режима | recovery после записи S3 и после DB commit; без дублей |
| failed/DLQ/replay | `tests/failed_replay.py`; `rabbitmqctl list_queues` | failed + safe code, DLQ=1, replay → ready, второй replay отклонён |
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
Целевая оценка 4, поэтому performance-исследование уровня 5 не заявляется. Числа RPS,
latency и RSS не приводятся: короткие функциональные fault tests для таких выводов
недостаточны.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| Воздействие | Ожидание | Наблюдение | Потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
| Publisher выключен после DB commit | pending outbox публикуется после восстановления | job дошла до ready без нового upload | 0 подтверждённых job |
| Worker выключен и API перезапущен | 202 не означает зависимость от процесса API | после запуска worker получен ready | 0 |
| Broker restart с volume | durable delivery остаётся | исходная job обработана | 0 |
| Worker crash после S3 effects | lease/retry повторяет идемпотентно | один original и три варианта | 0 |
| Worker crash после DB commit до ack | stale redelivery распознаётся | ready не откатился, дублей нет | 0 |
| Постоянная ошибка | failed registry + DLQ | safe `fault_injected`, DLQ message, guarded replay | 0; staging сохранён |
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
- Это single-host Compose: отказ хоста, quorum broker/DB и multi-AZ не проверялись.
- RLIMIT_AS зависит от ОС; основной внешний предел остаётся Docker memory limit.
- Cleanup запускается оператором/планировщиком, отдельный scheduler service не добавлен.
- DLQ используется для наблюдаемости, а replay берёт решение из PostgreSQL; stale DLQ
сообщения намеренно не являются источником истины.
- Для оценки 5 нужны отдельный нагрузочный эксперимент или расширенная матрица reorder и
смены pipeline version; здесь такие выводы не заявляются.
+93
View File
@@ -0,0 +1,93 @@
# Lab 5 grade 4 — результаты проверки
Дата: 2026-11-16, дополнено 2026-11-17. Среда: macOS host, Docker Desktop Linux containers.
Секреты, session tokens и содержимое `.env` не сохранялись.
```text
$ make check
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
$ docker compose -f compose.tests.yaml run --rm \
-v "$PWD/app:/tests/app:ro" -v "$PWD/tests:/tests/tests:ro" \
tests python -m pytest -q
................... [100%]
19 passed in 1.22s
$ docker compose -f compose.tests.yaml run --rm --no-deps \
-v "$PWD/app:/tests/app:ro" -v "$PWD/tests:/tests/tests:ro" \
tests python -m pytest -q tests/test_pipeline.py
....... [100%]
7 passed in 0.94s
$ docker compose -f compose.tests.yaml run --rm --no-deps \
-v "$PWD/scripts:/tests/scripts:ro" \
tests python scripts/validate_openapi.py
PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested.
$ python3 tests/smoke.py --base-url http://127.0.0.1:18080
PASS: lab5 public API scenario; infrastructure and grading evidence remain separate.
$ python3 tests/pipeline_smoke.py --base-url http://127.0.0.1:18080
PASS: original plus thumbnail/crop/optimized variants are valid
$ COMPOSE_FILE_PATH=compose.tests.yaml python3 tests/outbox_recovery.py \
--base-url http://127.0.0.1:18080 \
--stop-publisher-script scripts/stop-publisher.sh \
--start-publisher-script scripts/start-publisher.sh
PASS: COMMIT-before-publish recovered without a new upload
$ COMPOSE_FILE_PATH=compose.tests.yaml python3 tests/worker_outage.py \
--base-url http://127.0.0.1:18080 \
--stop-worker-script scripts/stop-worker.sh \
--restart-api-script scripts/restart-api.sh \
--start-worker-script scripts/start-worker.sh
PASS: worker stopped -> 202 -> message -> API restart -> worker -> ready
$ COMPOSE_FILE_PATH=compose.tests.yaml python3 tests/broker_persistence.py \
--base-url http://127.0.0.1:18080 \
--stop-worker-script scripts/stop-worker.sh \
--restart-broker-script scripts/restart-broker.sh \
--start-worker-script scripts/start-worker.sh
PASS: confirmed durable message survived broker restart with its volume
$ COMPOSE_FILE_PATH=compose.tests.yaml python3 tests/publisher_confirm_crash.py \
--base-url http://127.0.0.1:18080 \
--stop-publisher-script scripts/stop-publisher.sh \
--crash-publisher-script scripts/crash-publisher-after-confirm.sh
PASS: confirm-before-outbox-mark duplicate produced one logical result
$ COMPOSE_FILE_PATH=compose.tests.yaml python3 tests/worker_crash.py \
--base-url http://127.0.0.1:18080 \
--stop-worker-script scripts/stop-worker.sh \
--crash-worker-script scripts/crash-worker.sh \
--mode objects
PASS: worker crash mode=objects recovered one logical result
$ COMPOSE_FILE_PATH=compose.tests.yaml python3 tests/worker_crash.py \
--base-url http://127.0.0.1:18080 \
--stop-worker-script scripts/stop-worker.sh \
--crash-worker-script scripts/crash-worker.sh \
--mode commit
PASS: worker crash mode=commit recovered one logical result
$ COMPOSE_FILE_PATH=compose.tests.yaml python3 tests/failed_replay.py \
--base-url http://127.0.0.1:18080 \
--stop-worker-script scripts/stop-worker.sh \
--crash-worker-script scripts/crash-worker.sh \
--replay-script scripts/replay-attachment.sh
REPLAYED job_id=c9e77317-0803-4a23-bfa6-ab1113e47ed3
REJECTED job_id=c9e77317-0803-4a23-bfa6-ab1113e47ed3 reason=not_failed_or_staging_missing
PASS: permanent failure reached failed/DLQ and guarded replay reached ready
$ docker compose -f compose.tests.yaml exec -T broker rabbitmqctl list_queues name messages messages_ready
attachments.process 0 0
attachments.failed 1 1
$ git diff --check
(no output, exit 0)
```
Fault scripts управляют реальными Compose services (`api`, `publisher`, `worker`,
`broker`) и не создают новую attachment/job для восстановления уже принятой работы.
В тесте lease используется 3 секунды для быстрого воспроизведения; штатное значение —
90 секунд.