forked from mtusi2026/mtusi2026lab5
Добавить отчёт и доказательства ЛР 5
This commit is contained in:
@@ -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; здесь такие выводы не заявляются.
|
||||
|
||||
@@ -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 секунд.
|
||||
Reference in New Issue
Block a user