forked from mtusi2026/mtusi2026lab5
Archive the asynchronous attachments change
Grade 3 of lab 5 is closed. Upload answers 202 queued only after the original is staged in the private bucket and the attachment, its job and the outbox row are committed together; a separate relay publishes the outbox to a durable quorum queue with publisher confirms and returns expired leases; a separate FastStream worker claims a job under a lease, publishes the original and the 256 px JPEG thumbnail, commits fenced by the lease token and acks only after the commit. Transient errors retry up to JOB_MAX_ATTEMPTS and end in retry_exhausted, undecodable images fail at once with invalid_image, and a redelivered job changes nothing. The defence demonstration (worker down, upload, message, API, relay and broker restarts, worker up, ready) and the lab 4 minimum pass on a stand raised from empty volumes. The lab5-attachment-pipeline and lab5-job-delivery capabilities join the main specs, and the upload, content, message and restart requirements of lab 1, lab 3 and lab 4 are updated in place. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
a55bc716c4
commit
adb29a2afc
+2
@@ -1,2 +1,4 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-29
|
||||
archived: 2026-10-29
|
||||
lab: 5
|
||||
@@ -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
|
||||
|
||||
@@ -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` после прогона позже, чем до него
|
||||
|
||||
|
||||
@@ -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: Клиент оборвал загрузку
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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, а объект оригинала читается из конечного префикса
|
||||
|
||||
@@ -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": "<uuid>"}`
|
||||
- **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` нет
|
||||
|
||||
Reference in New Issue
Block a user