diff --git a/openspec/changes/lab5-critical-review-fixes/.openspec.yaml b/openspec/changes/lab5-critical-review-fixes/.openspec.yaml new file mode 100644 index 00000000..8a94d769 --- /dev/null +++ b/openspec/changes/lab5-critical-review-fixes/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-06 diff --git a/openspec/changes/lab5-critical-review-fixes/design.md b/openspec/changes/lab5-critical-review-fixes/design.md new file mode 100644 index 00000000..52800c62 --- /dev/null +++ b/openspec/changes/lab5-critical-review-fixes/design.md @@ -0,0 +1,27 @@ +## Context + +Причины и область — в proposal.md. Затронут только адаптер изображений зоны attachments и топология её брокера. `VariantRenderer` остаётся портом, `ProcessVariantRenderer`/Pillow — адаптером, `attachments/ioc.py` — сборкой; FastStream consumer остаётся в entrypoints. БД хранит состояния, S3 — байты, RabbitMQ — доставку. SQL и схема не меняются. + +## Goals / Non-Goals + +**Goals:** не терять доставку принятого задания при недоступной БД; накладывать все поддерживаемые формы PNG-прозрачности на белый фон. + +**Non-Goals:** новые очереди, миграции, изменение ack/lease/fencing и исправление minor. Docker и нагрузка запрещены этапу исправлений: динамическое подтверждение передаётся финальному агенту, не считается выполненным при архивации. + +## Decisions + +1. Политика рабочей очереди получает `delivery-limit=-1`. [RabbitMQ 4.1](https://www.rabbitmq.com/docs/4.1/quorum-queues#poison-message-handling) допускает отключение лимита политикой без пересоздания очереди. Это предотвращает помещение валидного задания в DLQ до получения доступа к PostgreSQL. Сохраняются секундная задержка nack и журнал `job.requeued`, ограниченный prefetch, reject невалидных сообщений в DLX, `JOB_MAX_ATTEMPTS` и backoff/jitter для ошибок обработки после claim. Альтернативы: периодическая переотправка queued потребовала бы нового запроса/индекса и создаёт дополнительные дубли; удержание unacked ограничено consumer timeout и повторными падениями процесса. Транспортный повтор не увеличивает application `attempt`. +2. Порядок устойчивой записи сохраняется: staging → COMMIT attachment/job/outbox → publisher confirm → отметка outbox; worker claim COMMIT → запись S3 → COMMIT результата → ack. При отказе до claim сообщение остаётся в очереди; после claim аренда восстанавливается relay; после записи S3 повтор пользуется ключом эффекта `(attachment_id, pipeline_version, variant)`; после COMMIT повтор — no-op. Публикация версий остаётся монотонной. +3. В Pillow наличие `info.transparency` учитывается независимо от режима RGB/L/P/1: преобразование в RGBA перед существующей композицией. Для 16-битного grayscale точное сравнение с tRNS делается до нормализации, через LUT 65536 значений и одноканальную маску; прозрачные пиксели заменяются белым, затем сохраняется прежнее преобразование оттенков. Это не смешивает соседние исходные значения. [Документация Pillow 13.0.0](https://github.com/python-pillow/pillow/blob/13.0.0/docs/handbook/concepts.rst), полученная через Context7, описывает прозрачность без alpha band в `info`. Новых зависимостей нет. +4. Проверки: offline-вызов реального обработчика на 12 ошибках и последующем успехе, политика очереди, все варианты v1/v2 для tRNS и непрозрачных контрольных пикселей. Реальный RabbitMQ-тест расширяется до 12 повторов и проверки неизменности DLQ; запуск на этом этапе исключён. + +## Risks / Trade-offs + +- Неустранимая ошибка до claim может повторяться неограниченно → сообщение сохраняется, каждый повтор виден в журнале; ошибки обработки после claim по-прежнему конечны. Это цена сохранности при отказе БД произвольной длительности. +- Смена политики не возвращает автоматически сообщения, уже попавшие в DLQ при старой конфигурации → на финальном стенде проверить DLQ и зафиксировать её исходную глубину; не удалять данные. +- Для grayscale с tRNS нужна дополнительная маска 1 байт/пиксель и LUT; прежние ограничения пикселей, памяти процесса и времени действуют. Динамические проверки лимитов для этого пути остаются финальному этапу. +- Ранее измеренные JPEG/PNG без tRNS сохраняют байты и параметры рендера; новые результаты tRNS нельзя объявлять проверенными по старому evidence. + +## Migration Plan + +При следующем разрешённом старте применить definitions к RabbitMQ 4.1.8 с сохранением volume, подтвердить эффективный `delivery-limit=-1` для существующей очереди и повторить отказ БД дольше десяти доставок. Пересобрать worker для Pillow-исправления. Очереди, volumes и схема не пересоздаются. Откат старой политики возвращает риск потери транспорта, поэтому его нельзя считать безопасным исправлением. diff --git a/openspec/changes/lab5-critical-review-fixes/proposal.md b/openspec/changes/lab5-critical-review-fixes/proposal.md new file mode 100644 index 00000000..9b6b680d --- /dev/null +++ b/openspec/changes/lab5-critical-review-fixes/proposal.md @@ -0,0 +1,30 @@ +## Why + +Ревью snapshot `544b9c78d39d0e9dd07f841894c390895896605a` обнаружило два major: принятое задание теряет транспорт после десяти повторов при недоступной БД, а PNG с tRNS получает цветной или чёрный фон вместо белого. Это нарушает обязательные критерии «3» (сохранность принятой работы, thumbnail) и «4» (crop/optimized). + +## What Changes + +- Отключить транспортный delivery-limit для рабочей очереди, сохранив задержку nack, DLX для невалидных сообщений и ограниченные повторы обработки в PostgreSQL. +- Учитывать tRNS при композиции на белый фон, включая grayscale до потери точности при преобразовании 16 → 8 бит. +- Добавить offline-регрессии и расширить существующую проверку реального брокера; последнюю передать финальному агенту без запуска Docker. +- Сохранить команды, результаты и перечень обязательных затронутых динамических проверок в evidence для отдельного отчётного этапа. + +## Capabilities + +### New Capabilities + +Нет. + +### Modified Capabilities + +- `lab5-job-delivery`: инфраструктурные повторы не исчерпывают доставки до восстановления PostgreSQL. +- `lab5-job-recovery`: DLQ предназначена для отклонённых сообщений; транспортный лимит больше не отправляет туда принятые задания. +- `lab5-image-variants`: прозрачность tRNS применяется во всех вариантах обеих версий pipeline. + +## Impact + +Зона attachments: адаптер Pillow, конфигурация RabbitMQ, собственные тесты. Порты, SQLAlchemy/Alembic, порядок COMMIT/ack и ключ эффекта сохраняются. Нормы: `contracts/README.md` (thumbnail и прозрачность), `contracts/attachment-states.md` (окна отказа), рубрика `README.md` «3»/«4». Материалы для строк будущего REPORT «at-least-once и восстановление» и «варианты на белом фоне» будут в `evidence/review-fixes-2026-11-06/`; сам REPORT оформляет отдельный агент. + +## Non-goals + +Minor из ревью остаются ограничениями отчёта. Out of scope из `openspec/config.yaml` сохраняется. Нагрузку, Docker, публикацию, другие лабораторные и runner/state этот этап не затрагивает. diff --git a/openspec/changes/lab5-critical-review-fixes/specs/lab5-image-variants/spec.md b/openspec/changes/lab5-critical-review-fixes/specs/lab5-image-variants/spec.md new file mode 100644 index 00000000..fcd93547 --- /dev/null +++ b/openspec/changes/lab5-critical-review-fixes/specs/lab5-image-variants/spec.md @@ -0,0 +1,25 @@ +## MODIFIED Requirements + +### Requirement: Crop и optimized + +Worker SHALL строить для каждого задания, кроме `thumbnail`, вариант `crop` — JPEG, центрированный квадрат 128×128 после применения EXIF orientation, с увеличением маленьких исходников, — и вариант `optimized` — WebP, вписанный в 1280×1280 с сохранением пропорций, без увеличения, размеры округлены вниз и не меньше 1 px. Прозрачность (альфа-канал и PNG tRNS) во всех вариантах обеих версий pipeline SHALL компоноваться на белый фон согласно `contracts/README.md` («Вложения»). Варианты SHALL NOT содержать EXIF, ICC и XMP; параметры кодирования SHALL быть документированы (`crop` — JPEG `quality` 85, `optimized` — WebP с потерями `quality` 80, `method` 4). Метаданные каждого варианта (`content_type`, `size_bytes`, `width`, `height`, `sha256`) SHALL совпадать с байтами, которые отдаёт `/content?variant=<имя>`. + +#### Scenario: Fixture 320×200 + +- **WHEN** обработана `tests/fixtures/sample.png` +- **THEN** у вложения варианты `crop` 128×128 `image/jpeg`, `optimized` 320×200 `image/webp` и `thumbnail` 256×160, каждый `/content?variant=<имя>` отдаёт настоящий файл этого формата длиной `size_bytes` с SHA-256 из метаданных и реальными размерами из метаданных + +#### Scenario: Большой и вытянутый исходник + +- **WHEN** обработаны JPEG 4000×3000 и PNG 3000×2 +- **THEN** `optimized` 1280×960 и 1280×1 соответственно, `crop` в обоих случаях 128×128 + +#### Scenario: Ориентация и прозрачность + +- **WHEN** обработаны JPEG 400×200 с EXIF orientation 6 и PNG RGBA с прозрачным фоном +- **THEN** `optimized` первого 200×400, прозрачные области `crop` и `optimized` второго белые, ни в одном варианте нет EXIF + +#### Scenario: Прозрачность tRNS без альфа-канала + +- **WHEN** загружен допустимый PNG RGB, L, 1-битный или 16-битный grayscale с tRNS +- **THEN** прозрачные пиксели `thumbnail`, `crop` и `optimized` белые, непрозрачные сохраняют цвет с учётом кодирования; соседнее непрозрачное значение 16-битного grayscale не становится прозрачным при округлении до 8 бит diff --git a/openspec/changes/lab5-critical-review-fixes/specs/lab5-job-delivery/spec.md b/openspec/changes/lab5-critical-review-fixes/specs/lab5-job-delivery/spec.md new file mode 100644 index 00000000..c4d0b7f0 --- /dev/null +++ b/openspec/changes/lab5-critical-review-fixes/specs/lab5-job-delivery/spec.md @@ -0,0 +1,20 @@ +## MODIFIED Requirements + +### Requirement: Брокер и отдельные процессы в стенде + +Стенд SHALL содержать сервисы `broker` (RabbitMQ с volume и фиксированным именем узла), `relay` и `worker`, запускаемые из того же образа, что и API, но отдельными процессами. Очередь заданий SHALL быть durable quorum-очередью с dead-letter exchange. Повторные доставки при инфраструктурной ошибке до фиксации результата SHALL NOT исчерпываться транспортным лимитом; обработка задания SHALL оставаться ограниченной `JOB_MAX_ATTEMPTS` согласно уровню «3» `README.md`. Наружу SHALL публиковаться только UI брокера на `127.0.0.1`; AMQP, relay и worker портов на хосте не имеют. API SHALL NOT иметь учётных данных брокера. + +#### Scenario: Топология + +- **WHEN** выполняется `rabbitmqctl list_queues -p messenger name type durable` и `list_consumers -p messenger` +- **THEN** `attachments.process` и `attachments.process.dlq` — `quorum`, durable; у `attachments.process` один consumer worker с `prefetch_count` равным `WORKER_CONCURRENCY` + +#### Scenario: Сервисы + +- **WHEN** выполняется `docker compose ps` после `make up` +- **THEN** `broker`, `relay`, `worker` в состоянии `healthy`, процессы не от root, опубликованы только порты `lb` и UI брокера на `127.0.0.1` + +#### Scenario: БД недоступна дольше десяти доставок + +- **WHEN** принятое задание опубликовано, а PostgreSQL недоступен при захвате более десяти повторных доставок +- **THEN** сообщение остаётся доступным в рабочей очереди с теми же `job_id` и `attempt`, DLQ не пополняется из-за этого отказа; после восстановления БД вложение становится `ready` без replay, с одним набором вариантов diff --git a/openspec/changes/lab5-critical-review-fixes/specs/lab5-job-recovery/spec.md b/openspec/changes/lab5-critical-review-fixes/specs/lab5-job-recovery/spec.md new file mode 100644 index 00000000..3149cff2 --- /dev/null +++ b/openspec/changes/lab5-critical-review-fixes/specs/lab5-job-recovery/spec.md @@ -0,0 +1,20 @@ +## MODIFIED Requirements + +### Requirement: Реестр failed и явный replay + +Задания в `failed` SHALL быть доступны оператору списком с `attachment_id`, `job_id`, `error_code`, `attempt`, классом последней ошибки и временем. Команда `python -m messenger.admin replay --attachment-id ` SHALL переводить вложение `failed` в `queued` тем же `job_id` с `attempt` 1 и новой публикацией, записывая в журнал задания событие `replayed` с оператором; для вложения в `ready`, `queued` или `processing` SHALL отвечать `noop` и записывать `replay_noop`, не создавая работы; для `failed`, чей staging уже удалён по retention, — `expired`. Последняя строка вывода команды SHALL быть JSON с полем `result`. Сообщения не по схеме SHALL попадать в dead-letter очередь, которую оператор просматривает без извлечения. Недоступность БД SHALL NOT отправлять принятое задание в DLQ по числу доставок; ограничение попыток обработки и реестр failed SHALL сохраняться согласно уровню «3»/«4» `README.md`. + +#### Scenario: Replay после retry_exhausted + +- **WHEN** вложение `failed` с `retry_exhausted`, оператор выполняет replay +- **THEN** вывод `{"result": "replayed", ...}`, вложение становится `ready`, `attempt` не превышает `JOB_MAX_ATTEMPTS`, в журнале есть `replayed` + +#### Scenario: Replay готового вложения + +- **WHEN** оператор повторяет replay уже `ready`-вложения +- **THEN** вывод `{"result": "noop", ...}`, в очередь ничего не публикуется, метаданные и строки вариантов не меняются + +#### Scenario: Реестр + +- **WHEN** оператор выполняет `python -m messenger.admin failed` +- **THEN** вывод — JSON-список `failed`-заданий без текста исключений, ключей S3 и учётных данных diff --git a/openspec/changes/lab5-critical-review-fixes/tasks.md b/openspec/changes/lab5-critical-review-fixes/tasks.md new file mode 100644 index 00000000..80292673 --- /dev/null +++ b/openspec/changes/lab5-critical-review-fixes/tasks.md @@ -0,0 +1,15 @@ +## 1. Доставка уровня «3» + +- [ ] 1.1 Изменить политику рабочей очереди для инфраструктурных повторов, сохранив DLX и конечные application retries. +- [ ] 1.2 Добавить offline-регрессию consumer и политики; расширить реальный RabbitMQ-тест до 12 ошибок, не запуская Docker. Проверить offline consumer через pytest. + +## 2. Прозрачность вариантов уровней «3»/«4» и версий трека «5» + +- [ ] 2.1 Исправить tRNS в Pillow до композиции на белый фон, сохранив непрозрачные оттенки. +- [ ] 2.2 Добавить и выполнить offline-регрессии всех вариантов v1/v2 для RGB/L/1/16-bit PNG, а также прежние renderer/domain тесты. + +## 3. Проверки и передача + +- [ ] 3.1 Выполнить make check, make validate, make lint и строгую валидацию OpenSpec; сохранить реальные результаты offline-проверок. +- [ ] 3.2 Зафиксировать обязательные динамические проверки для финального агента и прежние minor для отчёта; не объявлять их исправленными или проверенными. +- [ ] 3.3 Синхронизировать specs и архивировать завершённый цикл с датой и lab: 5; проверить отсутствие активного change.