diff --git a/REPORT.md b/REPORT.md index e98f75e9..2f13d739 100644 --- a/REPORT.md +++ b/REPORT.md @@ -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; здесь такие выводы не заявляются. diff --git a/evidence/lab5-grade4.md b/evidence/lab5-grade4.md new file mode 100644 index 00000000..c3411522 --- /dev/null +++ b/evidence/lab5-grade4.md @@ -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 секунд.