Propose completing the versioned attachment pipeline
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-11-06
|
||||
@@ -0,0 +1,26 @@
|
||||
## Context
|
||||
|
||||
PostgreSQL — источник истины, RabbitMQ с FastStream/aio-pika — at-least-once транспорт. Имеются уникальные jobs(attachment_id,pipeline_version), attachment_variants(attachment_id,pipeline_version,name), lease_token и условная публикация только большей версии. Нет оператора версии и различимых recipe.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
Завершить трек 2 без изменения HTTP-контракта. Подтвердить отсутствие потери 202, дублей эффектов и перезаписи v2 результатом v1. Уровни 3/4 остаются действующими. Не менять shared и другие зоны, не переписывать готовые механизмы.
|
||||
|
||||
## Decisions
|
||||
|
||||
- ReprocessAttachment принадлежит attachments; AdminProvider связывает обработчик с AttachmentsUnitOfWork/JobRepository, Clock и IdGenerator. Команда reprocess принимает только 1/2; неизвестное вложение → not_found, pending/failed → conflict (failed обслуживает replay), существующая/опубликованная версия → noop, новая → queued. Ready всё время остаётся ready и доступна текущая опубликованная версия.
|
||||
- Под блокировкой строки attachment проверяется уникальный индекс jobs_effect_key. Только отсутствующая версия получает job+outbox+аудит одной транзакцией. Это сериализует одновременные операторские команды ценой короткой row lock. SELECT существующего job не берёт его блокировку: нет инверсии lock job→attachment с worker. Уникальный индекс остаётся последним ограничением целостности. SQLAlchemy Core с bound parameters, AsyncSession/UoW. Схема и старые данные не меняются.
|
||||
- Ошибка одной версии не должна ставить attachment в failed, пока другая версия queued/processing. После фиксации job failure берётся блокировка attachment и отдельным запросом проверяются активные jobs; сериализация двух одновременных failures позволяет последнему выставить failed. Ready не меняется. Цена — короткая дополнительная блокировка на редком пути ошибки.
|
||||
- v1 сохраняет JPEG 85/WebP 80; v2 использует JPEG 90/WebP 85. Размеры, EXIF transpose, white alpha, metadata removal и max bytes/pixels/time/memory одинаковы. Ключ S3 содержит версию и digest: старый PUT не адресует объект новой версии, оригинал неизменен. Версии recipe после выпуска не редактируются; для нового recipe нужна новая версия.
|
||||
- Worker: claim+COMMIT → read/PUT S3 → variants+условная publication+COMMIT → manual ack. Сбой до PUT восстанавливается lease/outbox, после PUT повтор пишет те же ключи, после COMMIT повтор становится noop. Relay: durable outbox → publish mandatory/persistent с confirm → mark published+COMMIT; потерянный confirm создаёт повтор. Это идемпотентный эффект, не exactly-once доставка.
|
||||
- Staging после ready может быть убран при другой активной версии: следующий claim читает original; transient S3 read использует ограниченный retry. Исходные bytes остаются сохранены. Провал v2 не скрывает уже готовую v1.
|
||||
- Reorder доказывается принудительно: relay остановлен, вручную публикуется только v2, ожидается published=2, затем relay выпускает v1 и дубль v2. Stale after v2 сравнивает публичный снимок, SQL и реально отдаваемые bytes. Старый работник после нового покрывается конкурентным тестом.
|
||||
- Suite инвентаризует S3 только по IDs этого запуска, проверяет отсутствие лишних объектов и наличие всех ожидаемых ключей. Старые volumes и DLQ не очищаются. Каждый crash фиксирует фактический контейнер; retention меняет возраст только своей синтетической строки.
|
||||
|
||||
## Method
|
||||
|
||||
Гипотеза: один эффект на (attachment_id,version,variant), published_version монотонна, ready не откатывается и все 202 сохраняются при заданных отказах. Контроль — smoke_pipeline без fault; воздействия — дубли до/после ready, reorder attempts/versions, crashes до эффекта/после S3/после COMMIT, SIGKILL, stale v1 после v2. Три независимых последовательных запуска с новыми synthetic IDs. Сырые JSON содержат SHA/UTC/снимки/инварианты; таблица сравнивает контроль и faults, версии и все повторы. Длительность сценария включает Docker restart/healthcheck и не является latency SLA.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
Две фиксированные версии, один Docker host и один broker node не доказывают отказоустойчивость к потере диска/кластера. Наблюдаемые API состояния дискретны; SQL conditional update и конкурентные тесты дополняют выборку. Minor limits.py и legacy reconcile demo сохраняются. Отдельный агент пишет итоговый REPORT. Containers non-root/read-only, закреплённые версии, healthcheck, порты и ресурсы не меняются. Перед окончанием все свои стенды остановить без удаления volumes.
|
||||
@@ -0,0 +1,23 @@
|
||||
## Why
|
||||
|
||||
README, оценка «5», трек 2 требует versioned pipeline и доказательство идемпотентности при duplicate/reorder/crash/stale job. Уровни 3/4 подтверждены, но CLI не имеет reprocess, renderer игнорирует pipeline_version, а сценарий reorder не гарантирует завершение v2 до v1.
|
||||
|
||||
## What Changes
|
||||
|
||||
Добавить явную операторскую постановку версии 1/2, два детерминированных recipe и сохранение опубликованного результата при работе другой версии. Автоматизировать сильный reorder, дубли и crashes с инвентаризацией объектов только синтетических вложений. Выполнить три последовательных повтора и подготовить методику, сырые данные, сравнение и ограничения для строки трека 2 будущего REPORT.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- lab5-versioned-pipeline: явная постановка версии, монотонное опубликование и воспроизводимые инварианты при сбоях.
|
||||
|
||||
### Modified Capabilities
|
||||
Нет: существующие требования и внешний API продолжают действовать.
|
||||
|
||||
## Impact
|
||||
|
||||
Только зона attachments: команда/обработчик, JobRepository, SQLAlchemy адаптер, Pillow renderer, admin entrypoint/DI, собственные тесты, suite/Makefile, evidence и OpenSpec. Поля версии, уникальные ключи и fencing уже есть в Alembic; новая схема не нужна. Нормативные файлы и REPORT не меняются.
|
||||
|
||||
## Non-goals
|
||||
|
||||
Out of scope из openspec/config.yaml: OTel/ЛР6, TLS/ЛР7, трек 1 и публикация. Не заявляется exactly-once доставка или производительность production.
|
||||
+45
@@ -0,0 +1,45 @@
|
||||
## Purpose
|
||||
|
||||
Определяет наблюдаемые гарантии versioned pipeline и воспроизводимое доказательство идемпотентности для трека 2 оценки «5» README лабораторной 5.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Явная постановка версии
|
||||
|
||||
Оператор SHALL иметь команду reprocess с attachment-id и pipeline-version 1 или 2. Повтор той же версии SHALL возвращать noop без новой job или outbox. Для неизвестного вложения возвращается not_found, для pending/failed — conflict без изменения состояния; failed восстанавливается существующим replay. Успех queued SHALL означать durable job и outbox. Требование трассируется на README, трек 2.
|
||||
|
||||
#### Scenario: Одновременные операторские запросы
|
||||
- **WHEN** несколько команд запрашивают версию 2 одного вложения
|
||||
- **THEN** ровно одна получает queued, остальные noop; создаётся одна job версии 2 и одно намерение доставки
|
||||
|
||||
#### Scenario: Ошибочный запрос
|
||||
- **WHEN** указана неподдерживаемая версия, неизвестный id или failed-вложение
|
||||
- **THEN** новая работа не создаётся, оператор получает явную ошибку/результат отказа
|
||||
|
||||
### Requirement: Монотонная публикация различимых версий
|
||||
|
||||
Версии 1 и 2 SHALL давать детерминированные варианты с различимыми recipe при сохранении форматов/размеров контракта. API SHALL отдавать только опубликованную версию, published_version SHALL возрастать, а ready SHALL NOT откатываться. Работа или ошибка старой версии SHALL NOT перезаписывать новую. Ошибка одной версии SHALL NOT завершать всё вложение в failed, пока остаётся активная версия. Требование трассируется на README, трек 2 и contracts/attachment-states.md.
|
||||
|
||||
#### Scenario: Новая версия завершилась первой
|
||||
- **WHEN** версия 2 достигла ready до доставки версии 1
|
||||
- **THEN** последующая версия 1 не меняет опубликованные варианты; оригинал и байты версии 2 сохраняются
|
||||
|
||||
#### Scenario: Старый держатель завершился позже
|
||||
- **WHEN** worker версии 1 задержан после записи объектов, а версия 2 опубликована
|
||||
- **THEN** завершение версии 1 не перезаписывает опубликованный результат версии 2
|
||||
|
||||
#### Scenario: Ошибка при нескольких версиях
|
||||
- **WHEN** одна версия завершилась ошибкой, другая ещё обрабатывается
|
||||
- **THEN** вложение не становится failed до завершения оставшейся работы, а уже ready продолжает скачиваться
|
||||
|
||||
### Requirement: Воспроизводимые инварианты при отказах
|
||||
|
||||
Одна команда make track2 SHALL запускать контроль без отказа и автоматические duplicate, reorder, crash до/после эффекта, SIGKILL и stale job после версии 2. Результат SHALL включать UTC/SHA, фактические контейнеры, отсутствие потери подтверждённых 202, лишних эффектов и отката ready/версии, соответствие байтов метаданным и объектов собственных вложений ожидаемым ключам. Исследование SHALL содержать три последовательных повтора, сравнение, ограничения и объяснение at-least-once доставки. Требование трассируется на README, трек 2; унаследованные негативные сценарии остаются в спецификациях уровней 3/4.
|
||||
|
||||
#### Scenario: Повтор после эффекта
|
||||
- **WHEN** worker падает после PUT либо после COMMIT до ack и получает ту же job снова
|
||||
- **THEN** итоговое вложение доступно, лишнего набора вариантов нет, принятая job не потеряна
|
||||
|
||||
#### Scenario: Проверяемая серия
|
||||
- **WHEN** три раза последовательно выполняется make track2 с разными output paths
|
||||
- **THEN** каждый отчёт проверяет собственные принятые IDs, содержит реальные результаты и не удаляет данные предыдущих прогонов
|
||||
@@ -0,0 +1,15 @@
|
||||
## 1. Предпосылки
|
||||
- [x] 1.1 Подтвердить уровни 3/4 на SQLAlchemy отдельными циклами (grade3/NOTES.md, grade4/NOTES.md).
|
||||
- [x] 1.2 Проверить существующие ограничения/Alembic: новой схемы не требуется; Context7 SQLAlchemy и FastStream проверены.
|
||||
|
||||
## 2. Версии в attachments
|
||||
- [ ] 2.1 Добавить команду/результат, handler и SQLAlchemy JobRepository с сериализацией постановки и безопасным failure нескольких версий.
|
||||
- [ ] 2.2 Добавить recipe v1/v2 и передачу версии в отдельный render process.
|
||||
- [ ] 2.3 Связать операторский CLI, аудит и DI; проверить конкурентность, reorder, старого держателя и ошибки собственными тестами.
|
||||
|
||||
## 3. Доказательства
|
||||
- [ ] 3.1 Усилить suite: принудительное v2→v1, snapshots/hashes, scoped S3 inventory, фактический SIGKILL; make track2.
|
||||
- [ ] 3.2 make check/validate/lint/student-test, сборка и публичные smoke/persistence/failover/restore на финальном коде.
|
||||
- [ ] 3.3 Полный level4 на финальном коде и три последовательных track2 с сырыми результатами.
|
||||
- [ ] 3.4 Сохранить методику/гипотезу/сравнение/ограничения, синхронизировать specs, архивировать завершённый change после make lint.
|
||||
- [ ] 3.5 Остановить свои стенды без удаления volumes и завершить с чистым деревом.
|
||||
Reference in New Issue
Block a user