diff --git a/openspec/changes/add-lab5-async-attachments/.openspec.yaml b/openspec/changes/archive/2026-10-29-add-lab5-async-attachments/.openspec.yaml similarity index 58% rename from openspec/changes/add-lab5-async-attachments/.openspec.yaml rename to openspec/changes/archive/2026-10-29-add-lab5-async-attachments/.openspec.yaml index 5c99d6d7..ee5b24ea 100644 --- a/openspec/changes/add-lab5-async-attachments/.openspec.yaml +++ b/openspec/changes/archive/2026-10-29-add-lab5-async-attachments/.openspec.yaml @@ -1,2 +1,4 @@ schema: spec-driven created: 2026-10-29 +archived: 2026-10-29 +lab: 5 diff --git a/openspec/changes/add-lab5-async-attachments/design.md b/openspec/changes/archive/2026-10-29-add-lab5-async-attachments/design.md similarity index 100% rename from openspec/changes/add-lab5-async-attachments/design.md rename to openspec/changes/archive/2026-10-29-add-lab5-async-attachments/design.md diff --git a/openspec/changes/add-lab5-async-attachments/proposal.md b/openspec/changes/archive/2026-10-29-add-lab5-async-attachments/proposal.md similarity index 100% rename from openspec/changes/add-lab5-async-attachments/proposal.md rename to openspec/changes/archive/2026-10-29-add-lab5-async-attachments/proposal.md diff --git a/openspec/changes/add-lab5-async-attachments/specs/lab1-messenger-history/spec.md b/openspec/changes/archive/2026-10-29-add-lab5-async-attachments/specs/lab1-messenger-history/spec.md similarity index 100% rename from openspec/changes/add-lab5-async-attachments/specs/lab1-messenger-history/spec.md rename to openspec/changes/archive/2026-10-29-add-lab5-async-attachments/specs/lab1-messenger-history/spec.md diff --git a/openspec/changes/add-lab5-async-attachments/specs/lab3-load-balancing/spec.md b/openspec/changes/archive/2026-10-29-add-lab5-async-attachments/specs/lab3-load-balancing/spec.md similarity index 100% rename from openspec/changes/add-lab5-async-attachments/specs/lab3-load-balancing/spec.md rename to openspec/changes/archive/2026-10-29-add-lab5-async-attachments/specs/lab3-load-balancing/spec.md diff --git a/openspec/changes/add-lab5-async-attachments/specs/lab4-attachments/spec.md b/openspec/changes/archive/2026-10-29-add-lab5-async-attachments/specs/lab4-attachments/spec.md similarity index 100% rename from openspec/changes/add-lab5-async-attachments/specs/lab4-attachments/spec.md rename to openspec/changes/archive/2026-10-29-add-lab5-async-attachments/specs/lab4-attachments/spec.md diff --git a/openspec/changes/add-lab5-async-attachments/specs/lab4-upload-resilience/spec.md b/openspec/changes/archive/2026-10-29-add-lab5-async-attachments/specs/lab4-upload-resilience/spec.md similarity index 100% rename from openspec/changes/add-lab5-async-attachments/specs/lab4-upload-resilience/spec.md rename to openspec/changes/archive/2026-10-29-add-lab5-async-attachments/specs/lab4-upload-resilience/spec.md diff --git a/openspec/changes/add-lab5-async-attachments/specs/lab5-attachment-pipeline/spec.md b/openspec/changes/archive/2026-10-29-add-lab5-async-attachments/specs/lab5-attachment-pipeline/spec.md similarity index 100% rename from openspec/changes/add-lab5-async-attachments/specs/lab5-attachment-pipeline/spec.md rename to openspec/changes/archive/2026-10-29-add-lab5-async-attachments/specs/lab5-attachment-pipeline/spec.md diff --git a/openspec/changes/add-lab5-async-attachments/specs/lab5-job-delivery/spec.md b/openspec/changes/archive/2026-10-29-add-lab5-async-attachments/specs/lab5-job-delivery/spec.md similarity index 100% rename from openspec/changes/add-lab5-async-attachments/specs/lab5-job-delivery/spec.md rename to openspec/changes/archive/2026-10-29-add-lab5-async-attachments/specs/lab5-job-delivery/spec.md diff --git a/openspec/changes/add-lab5-async-attachments/tasks.md b/openspec/changes/archive/2026-10-29-add-lab5-async-attachments/tasks.md similarity index 100% rename from openspec/changes/add-lab5-async-attachments/tasks.md rename to openspec/changes/archive/2026-10-29-add-lab5-async-attachments/tasks.md diff --git a/openspec/specs/lab1-messenger-history/spec.md b/openspec/specs/lab1-messenger-history/spec.md index f49594d8..950c3b6d 100644 --- a/openspec/specs/lab1-messenger-history/spec.md +++ b/openspec/specs/lab1-messenger-history/spec.md @@ -5,7 +5,7 @@ ## Requirements ### Requirement: Отправка сообщения -Сервис SHALL принимать `POST /api/v1/chats/{chat_id}/messages` от участника чата с телом `{"text":..., "attachment_ids":[...]}` и обязательным заголовком `Idempotency-Key` и возвращать `201` с объектом `Message`. Отправитель SHALL выводиться из предъявленной идентификации; поле `sender_id` в теле запроса SHALL NOT приниматься. `text` SHALL быть обязательным, содержать не более 4000 Unicode code points и SHALL NOT состоять только из пробельных символов; пустая строка допустима только при хотя бы одном вложении. `attachment_ids` SHALL быть необязательным списком из 0–10 уникальных UUID (по умолчанию `[]`); каждое вложение SHALL принадлежать этому чату и быть готовым, иначе ответ `404`. Порядок `attachment_ids` SHALL сохраняться, а одно вложение SHALL допускаться в нескольких сообщениях. Каждый `Message` в ответе SHALL содержать `attachment_ids`, у текстового — `[]`. `id` и `created_at` SHALL назначаться сервером. Правила ключа описаны в `lab3-idempotent-messages`. +Сервис SHALL принимать `POST /api/v1/chats/{chat_id}/messages` от участника чата с телом `{"text":..., "attachment_ids":[...]}` и обязательным заголовком `Idempotency-Key` и возвращать `201` с объектом `Message`. Отправитель SHALL выводиться из предъявленной идентификации; поле `sender_id` в теле запроса SHALL NOT приниматься. `text` SHALL быть обязательным, содержать не более 4000 Unicode code points и SHALL NOT состоять только из пробельных символов; пустая строка допустима только при хотя бы одном вложении. `attachment_ids` SHALL быть необязательным списком из 0–10 уникальных UUID (по умолчанию `[]`); каждое вложение SHALL принадлежать этому чату, иначе ответ `404`; вложение в `queued`, `processing` или `ready` SHALL прикрепляться сразу после upload, а вложение в `failed` SHALL давать `409` с кодом `conflict`, и сообщение не сохраняется. Порядок `attachment_ids` SHALL сохраняться, а одно вложение SHALL допускаться в нескольких сообщениях. Каждый `Message` в ответе SHALL содержать `attachment_ids`, у текстового — `[]`. `id` и `created_at` SHALL назначаться сервером. Правила ключа описаны в `lab3-idempotent-messages`. #### Scenario: Сообщение отправлено @@ -15,7 +15,7 @@ #### Scenario: Сообщение с вложением без текста -- **WHEN** участник отправляет `{"text":"","attachment_ids":[id]}`, где `id` — готовое вложение этого чата +- **WHEN** участник отправляет `{"text":"","attachment_ids":[id]}`, где `id` — вложение этого чата в `queued`, `processing` или `ready` - **THEN** ответ `201`, `attachment_ids` равен `[id]` #### Scenario: Порядок вложений сохраняется @@ -28,6 +28,11 @@ - **WHEN** `attachment_ids` содержит вложение другого чата того же пользователя или несуществующий UUID - **THEN** ответ `404` с кодом `not_found`, сообщение не сохраняется +#### Scenario: Вложение в failed + +- **WHEN** `attachment_ids` содержит вложение этого чата в состоянии `failed` +- **THEN** ответ `409` с кодом `conflict`, сообщение не сохраняется + #### Scenario: Слишком много, повторы или не UUID - **WHEN** `attachment_ids` содержит 11 элементов, повторяющийся UUID или строку не в формате UUID diff --git a/openspec/specs/lab3-load-balancing/spec.md b/openspec/specs/lab3-load-balancing/spec.md index f5852c69..271d8140 100644 --- a/openspec/specs/lab3-load-balancing/spec.md +++ b/openspec/specs/lab3-load-balancing/spec.md @@ -75,10 +75,10 @@ ### Requirement: Рестарт стенда -Хук `scripts/restart.sh` SHALL перезапускать балансировщик, все реплики API, PostgreSQL, Valkey и S3-сервер с сохранением volumes, без удаления и повторного заполнения данных, и SHALL завершаться кодом 0 не позднее 90 секунд, когда стенд, включая S3, снова готов: первое же чтение метаданных и байтов вложения после хука SHALL проходить без повторов. +Хук `scripts/restart.sh` SHALL перезапускать балансировщик, все реплики API, relay, worker, PostgreSQL, Valkey, S3-сервер и брокер с сохранением volumes, без удаления и повторного заполнения данных, и SHALL завершаться кодом 0 не позднее 90 секунд, когда стенд, включая S3, снова готов: первое же чтение метаданных и байтов вложения после хука SHALL проходить без повторов. #### Scenario: Полный рестарт сохраняет сессию - **WHEN** выполняется `make test-persistence ACTION_SCRIPT=scripts/restart.sh` -- **THEN** тест печатает `PASS: persistence preserved confirmed data and existing session`, а `StartedAt` контейнеров `lb`, `api`, `postgres`, `valkey` и `s3` после прогона позже, чем до него +- **THEN** тест печатает `PASS: persistence preserved confirmed data and existing session`, а `StartedAt` контейнеров `lb`, `api`, `relay`, `worker`, `postgres`, `valkey`, `s3` и `broker` после прогона позже, чем до него diff --git a/openspec/specs/lab4-attachments/spec.md b/openspec/specs/lab4-attachments/spec.md index c981e3b7..bb26403b 100644 --- a/openspec/specs/lab4-attachments/spec.md +++ b/openspec/specs/lab4-attachments/spec.md @@ -5,17 +5,22 @@ ## Requirements ### Requirement: Загрузка оригинала в чат -Сервис SHALL принимать `POST /api/v1/chats/{chat_id}/attachments?filename=<имя>` от участника чата с телом из сырых байтов одного изображения (не multipart, не JSON) и заголовком `Content-Type: image/png` или `image/jpeg` и возвращать `201` с объектом `Attachment`: `status` `ready`, `variants` `[]`, `error_code` `null`, `chat_id` из пути, `owner_id` вызывающего, `size_bytes` равен длине тела, `sha256` — lowercase hex SHA-256 тела, `content_type` — тип, определённый по содержимому, `filename` — переданное имя. Ответ `201` SHALL выдаваться только после того, как оригинал записан в приватный bucket и метаданные зафиксированы в PostgreSQL. Ключ объекта SHALL назначаться сервером и SHALL NOT зависеть от `filename` и попадать в ответ. Повтор того же запроса SHALL создавать новое вложение. +Сервис SHALL принимать `POST /api/v1/chats/{chat_id}/attachments?filename=<имя>` от участника чата с телом из сырых байтов одного изображения (не multipart, не JSON) и заголовком `Content-Type: image/png` или `image/jpeg` и возвращать `202` с объектом `Attachment` — снимком в момент приёма: `status` ровно `queued`, `variants` `[]`, `error_code` `null`, `chat_id` из пути, `owner_id` вызывающего, `size_bytes` равен длине тела, `sha256` — lowercase hex SHA-256 тела, `content_type` — тип, определённый по содержимому, `filename` — переданное имя. Ответ `202` SHALL выдаваться только после того, как полный проверенный оригинал записан в приватный staging-префикс bucket, а вложение и задание его обработки зафиксированы в PostgreSQL; снимок SHALL NOT перечитываться после фиксации, даже если worker уже взял задание. API SHALL NOT обрабатывать изображение (строить варианты) в запросе. Ключ объекта SHALL назначаться сервером и SHALL NOT зависеть от `filename` и попадать в ответ. Повтор того же запроса SHALL создавать новое вложение. #### Scenario: Fixture загружена - **WHEN** участник загружает `tests/fixtures/sample.png` с `Content-Type: image/png` и `?filename=sample.png` -- **THEN** ответ `201`, тело соответствует схеме `Attachment`, `status` `ready`, `size_bytes` 111817, `sha256` равен SHA-256 файла, `chat_id` и `owner_id` — чат и загрузивший +- **THEN** ответ `202`, тело соответствует схеме `Attachment`, `status` `queued`, `variants` `[]`, `error_code` `null`, `size_bytes` 111817, `sha256` равен SHA-256 файла, `chat_id` и `owner_id` — чат и загрузивший #### Scenario: JPEG загружен - **WHEN** участник загружает корректный JPEG с `Content-Type: image/jpeg` -- **THEN** ответ `201`, `content_type` `image/jpeg` +- **THEN** ответ `202`, `content_type` `image/jpeg` + +#### Scenario: Worker остановлен + +- **WHEN** worker остановлен, а участник загружает файл +- **THEN** ответ `202` приходит за время, не зависящее от размера изображения в пикселях, вложение остаётся `queued` #### Scenario: Посторонний загружает в чужой чат @@ -101,21 +106,41 @@ ### Requirement: Метаданные и скачивание только участникам -`GET /api/v1/attachments/{attachment_id}` SHALL возвращать `200 Attachment` участнику чата вложения. `GET /api/v1/attachments/{attachment_id}/content` SHALL возвращать участнику `200` с исходными байтами, `Content-Type` вложения и `Content-Length`, через API, без redirect, вне зависимости от заголовка `Accept`. Параметр `variant` SHALL принимать только `original` (по умолчанию). Посторонний, неизвестный id и ещё не готовое вложение SHALL получать `404` с кодом `not_found`, не раскрывающим существование вложения; невалидный UUID и неизвестный `variant` — `400`. Все ответы, включая бинарный `200`, SHALL нести `X-Request-Id` и `X-Instance-Id`. +`GET /api/v1/attachments/{attachment_id}` SHALL возвращать `200 Attachment` с текущим состоянием любому участнику чата вложения. `GET /api/v1/attachments/{attachment_id}/content` SHALL возвращать участнику `200` с байтами, истинным `Content-Type` и `Content-Length`, через API, без redirect, вне зависимости от заголовка `Accept`: для `variant=original` (по умолчанию) — исходные байты оригинала, для `variant=thumbnail` — байты варианта, описанного в метаданных. Для вложения в `queued`, `processing` или `failed` `/content` SHALL отвечать `409` с кодом `conflict` для любого допустимого `variant`, включая `original`. Для `ready`-вложения без запрошенного варианта (`crop`, `optimized` на уровне «3») SHALL отвечать `404`. Посторонний и неизвестный id SHALL получать `404` с кодом `not_found`, не раскрывающим существование вложения; невалидный UUID и `variant` вне `original|thumbnail|crop|optimized` — `400`. Все ответы, включая бинарный `200`, SHALL нести `X-Request-Id` и `X-Instance-Id`. #### Scenario: Второй участник скачивает оригинал -- **WHEN** второй участник чата запрашивает `/content` загруженного вложения с `Accept: application/json` +- **WHEN** второй участник чата запрашивает `/content` готового вложения с `Accept: application/json` - **THEN** ответ `200`, `Content-Type: image/png`, байты совпадают с загруженными, SHA-256 равен `sha256` метаданных +#### Scenario: Второй участник скачивает thumbnail + +- **WHEN** второй участник чата запрашивает `/content?variant=thumbnail` готового вложения +- **THEN** ответ `200`, `Content-Type: image/jpeg`, длина и SHA-256 равны метаданным варианта + +#### Scenario: Вложение ещё не готово + +- **WHEN** участник запрашивает `/content` или `/content?variant=thumbnail` вложения в `queued` или `processing` +- **THEN** ответ `409` с кодом `conflict` + +#### Scenario: Вложение в failed + +- **WHEN** участник запрашивает `/content?variant=original` вложения в `failed` +- **THEN** ответ `409` с кодом `conflict`, метаданные показывают `failed` и `error_code` + #### Scenario: Посторонний - **WHEN** пользователь вне чата запрашивает метаданные или `/content` - **THEN** оба ответа `404` с кодом `not_found` +#### Scenario: Варианта нет + +- **WHEN** запрошен `/content?variant=crop` готового вложения уровня «3» +- **THEN** ответ `404` с кодом `not_found` + #### Scenario: Неизвестный вариант -- **WHEN** запрошен `/content?variant=thumbnail` +- **WHEN** запрошен `/content?variant=preview` - **THEN** ответ `400` с кодом `invalid_request` #### Scenario: Объект пропал из хранилища @@ -125,12 +150,12 @@ ### Requirement: Порядок записи PostgreSQL и S3 -Сервис SHALL фиксировать намерение (метаданные со статусом, невидимым клиентам) до записи объекта и SHALL переводить вложение в готовое только после подтверждённой записи объекта. Сбой на любом шаге SHALL NOT давать `201` и SHALL NOT оставлять видимого клиентам вложения без объекта. Обрыв клиента до конца тела SHALL NOT оставлять ни объекта, ни строки. Намерение и объект, оставшиеся после сбоя, SHALL удаляться компенсацией сразу или уборкой по истечении grace period (capability `lab4-upload-resilience`), поэтому объект без строки-намерения в bucket не остаётся. +Сервис SHALL фиксировать намерение (метаданные со статусом, невидимым клиентам) до записи оригинала в staging и SHALL переводить вложение в `queued` вместе с записью задания только после подтверждённой записи объекта. Сбой на любом шаге SHALL NOT давать `202` и SHALL NOT оставлять видимого клиентам вложения без объекта. Обрыв клиента до конца тела SHALL NOT оставлять ни объекта, ни строки. Намерение и объект, оставшиеся после сбоя, SHALL удаляться компенсацией сразу или уборкой по истечении grace period (capability `lab4-upload-resilience`), поэтому объект без строки-намерения в bucket не остаётся. #### Scenario: S3 отказал при записи -- **WHEN** запись объекта завершилась ошибкой -- **THEN** ответ `503` с кодом `unavailable`, вложение не видно ни в метаданных, ни в сообщениях, а строка-намерение удаляется уборкой после grace period +- **WHEN** запись объекта в staging завершилась ошибкой +- **THEN** ответ `503` с кодом `unavailable`, вложение не видно ни в метаданных, ни в сообщениях, задания нет, а строка-намерение удаляется уборкой после grace period #### Scenario: Клиент оборвал загрузку diff --git a/openspec/specs/lab4-upload-resilience/spec.md b/openspec/specs/lab4-upload-resilience/spec.md index 98ac8bc3..49b3af75 100644 --- a/openspec/specs/lab4-upload-resilience/spec.md +++ b/openspec/specs/lab4-upload-resilience/spec.md @@ -5,17 +5,17 @@ ## Requirements ### Requirement: Компенсация сбоя после записи объекта -Если объект записан в bucket, а перевод вложения в готовое не зафиксирован, сервис SHALL ответить `503` с кодом `unavailable` и до ответа SHALL попытаться удалить объект и строку-намерение. Строку, которая к этому моменту уже готова, сервис SHALL NOT удалять вместе с её объектом. Если строку-намерение к моменту перевода в готовое уже убрали, сервис SHALL ответить `503` и удалить записанный объект, а не возвращать `201`. Неудача компенсации SHALL оставлять строку-намерение для уборки по grace period. +Если объект записан в staging, а перевод вложения в `queued` вместе с заданием не зафиксирован, сервис SHALL ответить `503` с кодом `unavailable` и до ответа SHALL попытаться удалить объект и строку-намерение. Строку, которая к этому моменту уже поставлена в очередь, сервис SHALL NOT удалять вместе с её объектом. Если строку-намерение к моменту фиксации уже убрали, сервис SHALL ответить `503` и удалить записанный объект, а не возвращать `202`. Неудача компенсации SHALL оставлять строку-намерение для уборки по grace period. #### Scenario: Отказ COMMIT после записи объекта -- **WHEN** запись объекта прошла, а фиксация статуса `ready` в PostgreSQL отклонена -- **THEN** ответ `503` с кодом `unavailable`, сразу после ответа нет ни строки вложения, ни объекта с его ключом, в журнале есть событие удаления намерения с причиной `compensation` +- **WHEN** запись объекта в staging прошла, а фиксация статуса `queued` и задания в PostgreSQL отклонена +- **THEN** ответ `503` с кодом `unavailable`, сразу после ответа нет ни строки вложения, ни задания, ни объекта с его ключом, в журнале есть событие удаления намерения с причиной `compensation` #### Scenario: Намерение снято раньше, чем загрузка завершилась - **WHEN** во время записи объекта строку-намерение удалили -- **THEN** ответ `503`, объект с ключом этой загрузки удалён, готового вложения не появилось +- **THEN** ответ `503`, объект с ключом этой загрузки удалён, вложения в очереди не появилось ### Requirement: Уборка брошенных загрузок по grace period diff --git a/openspec/specs/lab5-attachment-pipeline/spec.md b/openspec/specs/lab5-attachment-pipeline/spec.md new file mode 100644 index 00000000..5dabd991 --- /dev/null +++ b/openspec/specs/lab5-attachment-pipeline/spec.md @@ -0,0 +1,98 @@ +# lab5-attachment-pipeline Specification + +## Purpose +Определяет асинхронную обработку вложения после `202`: состояния `queued/processing/ready/failed`, работу отдельного worker, публикацию оригинала и thumbnail, ограниченные повторы с финальным `error_code`, идемпотентный эффект повторной доставки, аренду захваченного задания и уборку staging. +## Requirements +### Requirement: Состояния вложения в API + +Вложение после `202` SHALL проходить состояния `queued → processing → ready | failed`, а при временной ошибке или истёкшей аренде — `processing → queued`. `GET /api/v1/attachments/{attachment_id}` SHALL возвращать любому участнику чата текущее состояние: `variants` — `[]` до `ready` и варианты опубликованной версии у `ready`, `error_code` — `null` вне `failed` и короткий машинный код у `failed` (`invalid_image`, `processing_failed`, `retry_exhausted`), без текста исключения. Вложение в `ready` SHALL NOT возвращаться ни в `processing`, ни в `queued`, ни в `failed`. + +#### Scenario: Smoke доходит до ready + +- **WHEN** выполняется `make test` против стенда с работающим worker +- **THEN** второй участник видит `ready` не позднее 60 с после `202`, `error_code` равен `null`, тест печатает `PASS: lab5 public API scenario` + +#### Scenario: Ready не откатывается + +- **WHEN** после `ready` то же задание доставлено повторно +- **THEN** каждый последующий `GET` возвращает `ready` с теми же вариантами + +### Requirement: Worker публикует оригинал и thumbnail + +Worker SHALL обрабатывать задание отдельно от API: копировать проверенный оригинал из staging в конечный префикс без изменения байтов и строить один вариант `thumbnail` — JPEG, вписанный в 256×256 с сохранением пропорций, без увеличения маленьких исходников, после применения EXIF orientation, с альфа-каналом на белом фоне, с размерами, округлёнными вниз и не меньше 1 px. Метаданные варианта (`content_type`, `size_bytes`, `width`, `height`, `sha256`) SHALL совпадать с байтами, которые отдаёт `/content?variant=thumbnail`. Вложение SHALL становиться `ready` только после записи оригинала и thumbnail и фиксации их метаданных. + +#### Scenario: Fixture 320×200 + +- **WHEN** обработана `tests/fixtures/sample.png` (320×200) +- **THEN** у вложения ровно один вариант `thumbnail` 256×160 `image/jpeg`, `/content?variant=thumbnail` отдаёт настоящий JPEG 256×160 длиной `size_bytes` с SHA-256 из метаданных, `/content` оригинала побайтно равен загруженному файлу + +#### Scenario: Маленький и вытянутый исходник + +- **WHEN** обработаны PNG 64×64 и PNG 17×1000 +- **THEN** thumbnail 64×64 и 4×256 соответственно + +#### Scenario: Прозрачность и ориентация + +- **WHEN** обработаны PNG RGBA и JPEG с EXIF orientation 6 размером 400×200 +- **THEN** прозрачные области thumbnail белые, thumbnail JPEG 128×256 + +### Requirement: Ограниченные повторы и финальная ошибка + +Временная ошибка обработки (недоступный S3 или PostgreSQL) SHALL возвращать задание и вложение в `queued` с отложенной следующей попыткой и тем же `job_id`, увеличивая `attempt` на 1. Число попыток SHALL ограничиваться `JOB_MAX_ATTEMPTS` (5); после последней неудачной попытки вложение SHALL становиться `failed` с `error_code` `retry_exhausted`. Изображение, которое не удаётся декодировать, SHALL сразу давать `failed` с `invalid_image` без повторов. До исчерпания попыток вложение SHALL NOT показывать `failed`. + +#### Scenario: S3 недоступен во время обработки + +- **WHEN** worker обрабатывает задание при остановленном `s3`, а через несколько секунд `s3` запускают +- **THEN** вложение возвращается в `queued`, `attempt` растёт, после возврата S3 вложение становится `ready` без ручных действий + +#### Scenario: Попытки исчерпаны + +- **WHEN** каждая попытка завершается временной ошибкой +- **THEN** вложение становится `failed` с `error_code` `retry_exhausted`, `attempt` задания равен `JOB_MAX_ATTEMPTS`, `/content` отвечает `409` + +#### Scenario: Постоянная ошибка + +- **WHEN** worker не может декодировать изображение задания +- **THEN** вложение становится `failed` с `invalid_image` после первой попытки + +### Requirement: Повтор задания не создаёт второго набора вариантов + +Эффект задания SHALL определяться ключом `(attachment_id, pipeline_version, variant)`: повторная доставка того же `job_id` после `ready` SHALL подтверждаться без новых объектов и строк, а повторная обработка после сбоя до фиксации SHALL завершать тот же результат. Две копии одного задания одновременно SHALL давать один набор вариантов. Результат SHALL фиксироваться только держателем текущей аренды задания; опоздавший держатель SHALL NOT менять опубликованный результат. + +#### Scenario: Дубль после ready + +- **WHEN** оператор публикует в очередь копию сообщения уже выполненного задания +- **THEN** очередь опустевает, метаданные и строки вариантов до и после совпадают, в журнале задания есть событие `duplicate_noop` + +#### Scenario: Две копии в очереди + +- **WHEN** при остановленном worker в очереди лежат две копии одного задания, затем worker запускается +- **THEN** вложение становится `ready` с одним `thumbnail`, вторая копия подтверждается без эффекта + +### Requirement: Аренда захваченного задания + +Захват задания SHALL выдавать аренду на `JOB_TIMEOUT_SECONDS`. Задание в `processing` с истёкшей арендой SHALL без участия оператора возвращаться в `queued` (или в `failed` с `retry_exhausted`, если попытки исчерпаны) не позже `SWEEP_INTERVAL_SECONDS` после истечения аренды. + +#### Scenario: Worker убит посреди задания + +- **WHEN** worker получает `SIGKILL` во время обработки и затем запускается снова +- **THEN** вложение становится `ready`, у задания один набор вариантов + +### Requirement: Worker остановлен — приём продолжается + +Недоступность worker SHALL NOT мешать приёму: upload SHALL отвечать `202`, `/content` такого вложения — `409`, сообщения с ним — `201`, текстовые сообщения и история SHALL работать; API SHALL NOT обрабатывать изображение синхронно. Принятое задание SHALL переживать рестарт реплик API и relay и доходить до `ready` после запуска worker. + +#### Scenario: Демонстрация защиты + +- **WHEN** worker остановлен, загружен файл (`202 queued`), отправлено сообщение с ним, перезапущены API, relay и брокер с сохранением volume, затем запущен worker +- **THEN** до запуска worker `/content` отвечает `409`, задание лежит в очереди брокера и переживает его рестарт, после запуска worker вложение становится `ready` и thumbnail скачивается + +### Requirement: Staging убирается после публикации + +Оригинал SHALL оставаться в staging, пока результат не зафиксирован. После фиксации `ready` объект staging SHALL удаляться без участия оператора, а ссылка на него — обнуляться; вложения не в `ready` SHALL NOT терять staging. + +#### Scenario: Staging после ready + +- **WHEN** вложение стало `ready` +- **THEN** не позже чем через `SWEEP_INTERVAL_SECONDS` у него нет ключа staging, а объект оригинала читается из конечного префикса + diff --git a/openspec/specs/lab5-job-delivery/spec.md b/openspec/specs/lab5-job-delivery/spec.md new file mode 100644 index 00000000..82ac856f --- /dev/null +++ b/openspec/specs/lab5-job-delivery/spec.md @@ -0,0 +1,79 @@ +# lab5-job-delivery Specification + +## Purpose +Определяет доставку заданий обработки вложений: брокер с persistence в общем стенде, transactional outbox и отдельный relay с publisher confirm, формат сообщения по `jobs.schema.json`, at-least-once с подтверждением только после устойчивого эффекта, права клиентов брокера и переживание рестарта брокера. +## Requirements +### Requirement: Брокер и отдельные процессы в стенде + +Стенд SHALL содержать сервисы `broker` (RabbitMQ с volume и фиксированным именем узла), `relay` и `worker`, запускаемые из того же образа, что и API, но отдельными процессами. Очередь заданий SHALL быть durable quorum-очередью с dead-letter exchange и ограничением повторных доставок. Наружу 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` + +### Requirement: Намерение публикации сохраняется вместе с вложением + +Задание и намерение его публикации SHALL фиксироваться в PostgreSQL той же транзакцией, что и вложение `queued`. Публикацию в брокер SHALL выполнять relay: строка намерения SHALL помечаться опубликованной только после подтверждения брокером (publisher confirm) записи сообщения в очередь; невозможность доставить сообщение в очередь SHALL оставлять строку неопубликованной для повтора. Остановка API или relay после `202` SHALL NOT терять задание. + +#### Scenario: Брокер недоступен при upload + +- **WHEN** `broker` остановлен, а клиент загружает файл +- **THEN** upload отвечает `202`, строка намерения остаётся неопубликованной; после запуска брокера relay публикует её, и вложение становится `ready` + +#### Scenario: Relay перезапущен после 202 + +- **WHEN** worker остановлен, upload получил `202`, затем перезапущены реплики API и relay +- **THEN** задание лежит в очереди брокера ровно в одной копии и после запуска worker доходит до `ready` + +### Requirement: Формат сообщения задания + +Сообщение брокера SHALL содержать ровно поля `jobs.schema.json`: `schema_version` 1, `job_id`, `type` `attachment.process.v1`, `attachment_id`, `pipeline_version`, `attempt`, `created_at` (RFC 3339 с `Z`) — и SHALL NOT содержать байты, URL, ключи S3, `filename` и учётные данные. `job_id` SHALL NOT меняться при повторной доставке и повторной публикации; `attempt` SHALL расти только при управляемом повторе. Сообщения SHALL быть persistent. Сообщение не по схеме SHALL отклоняться worker без повторной постановки и попадать в dead-letter очередь. + +#### Scenario: Сообщение в очереди + +- **WHEN** worker остановлен, а оператор читает сообщение из `attachments.process` без подтверждения +- **THEN** тело валидно по `jobs.schema.json`, `delivery_mode` равен 2, `message_id` равен `job_id` + +#### Scenario: Сообщение не по схеме + +- **WHEN** в exchange `attachments` опубликовано `{"schema_version": 2, "job_id": ""}` +- **THEN** сообщение оказывается в `attachments.process.dlq`, worker продолжает работу + +### Requirement: Подтверждение после устойчивого эффекта + +Worker SHALL получать сообщения с ручным подтверждением и SHALL подтверждать сообщение только после фиксации результата (или решения о повторе либо финальной ошибке) в PostgreSQL. Сообщение, обработка которого прервана до фиксации, SHALL возвращаться брокером в очередь. Число одновременно обрабатываемых сообщений на процесс SHALL ограничиваться `WORKER_CONCURRENCY`. + +#### Scenario: Worker остановлен посреди очереди + +- **WHEN** worker получает `SIGTERM`, пока в очереди и в обработке есть задания +- **THEN** процесс завершается за ≤10 с с кодом 0, неподтверждённые сообщения возвращаются в очередь, после запуска worker все вложения становятся `ready` + +### Requirement: Задание переживает рестарт брокера + +Сообщение, подтверждённое брокером, SHALL переживать перезапуск контейнера брокера с сохранением volume, в том числе пересоздание контейнера; relay и worker SHALL переподключаться без ручных действий. + +#### Scenario: Рестарт брокера с volume + +- **WHEN** worker остановлен, в очереди лежит задание, выполняется `scripts/broker.sh restart`, затем запускается worker +- **THEN** после рестарта очередь по-прежнему содержит задание, а вложение становится `ready` + +### Requirement: Раздельные права клиентов брокера и S3 + +Relay SHALL иметь в брокере право только записи в exchange заданий, worker — только чтения очереди заданий; объявлять очереди и exchange SHALL может только операторская учётная запись. Worker SHALL ходить в S3 под отдельным ключом с правом чтения staging и записи только конечных префиксов оригиналов и вариантов. + +#### Scenario: Worker пытается публиковать + +- **WHEN** с учётными данными worker выполняется публикация в exchange `attachments` +- **THEN** брокер отвечает `ACCESS_REFUSED` + +#### Scenario: Гостевая учётная запись + +- **WHEN** выполняется `rabbitmqctl list_users` +- **THEN** пользователя `guest` нет +