The change add-lab5-variants-and-recovery is archived as 2026-10-29-add-lab5-variants-and-recovery with archived and lab: 5 in .openspec.yaml. Specs are synced: lab5-image-variants and lab5-job-recovery are created, lab5-attachment-pipeline (four requirements) and lab4-attachments (metadata and download) are updated. Level 4 is closed by make level4 (evidence/level4.json) and the rows 4.1-4.4 of REPORT.md. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
184 lines
16 KiB
Markdown
184 lines
16 KiB
Markdown
# lab4-attachments Specification
|
||
|
||
## Purpose
|
||
Определяет вложения-изображения чата: синхронную загрузку оригинала PNG/JPEG с лимитами и проверкой содержимого, метаданные, скачивание оригинала через API, доступ только участникам чата, порядок записи PostgreSQL ↔ S3 и поведение при недоступном S3.
|
||
## Requirements
|
||
### Requirement: Загрузка оригинала в чат
|
||
|
||
Сервис 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** ответ `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** ответ `202`, `content_type` `image/jpeg`
|
||
|
||
#### Scenario: Worker остановлен
|
||
|
||
- **WHEN** worker остановлен, а участник загружает файл
|
||
- **THEN** ответ `202` приходит за время, не зависящее от размера изображения в пикселях, вложение остаётся `queued`
|
||
|
||
#### Scenario: Посторонний загружает в чужой чат
|
||
|
||
- **WHEN** пользователь, не входящий в чат, или любой пользователь в несуществующий чат отправляет корректное изображение
|
||
- **THEN** ответ `404` с кодом `not_found`, ничего не сохраняется
|
||
|
||
#### Scenario: Доступ проверяется раньше содержимого
|
||
|
||
- **WHEN** посторонний отправляет в чужой чат тело, не являющееся изображением, или опасный `filename`
|
||
- **THEN** ответ `404`, а не `400` или `415`
|
||
|
||
#### Scenario: Без аутентификации
|
||
|
||
- **WHEN** upload приходит без `Authorization` или с `Basic`
|
||
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
|
||
|
||
### Requirement: Лимиты размера до неограниченного чтения и декодирования
|
||
|
||
Тело SHALL быть не больше `MAX_UPLOAD_BYTES` (10 485 760) байт, а изображение — не больше `MAX_IMAGE_PIXELS` (40 000 000) пикселей по заголовку. Превышение SHALL давать `413` с кодом `payload_too_large`. Объявленный `Content-Length` больше лимита SHALL отклоняться без чтения тела, тело без `Content-Length` SHALL читаться не дальше лимита плюс один байт, а число пикселей SHALL проверяться по заголовку изображения до декодирования. Реплика SHALL NOT записывать тело на свой диск.
|
||
|
||
#### Scenario: Ровно 10 MiB
|
||
|
||
- **WHEN** загружается корректный PNG размером ровно 10 485 760 байт
|
||
- **THEN** ответ `201` и `size_bytes` 10485760
|
||
|
||
#### Scenario: На байт больше с Content-Length
|
||
|
||
- **WHEN** загружается тело размером 10 485 761 байт с заголовком `Content-Length`
|
||
- **THEN** ответ `413` с кодом `payload_too_large`
|
||
|
||
#### Scenario: На байт больше без Content-Length
|
||
|
||
- **WHEN** тело размером 10 485 761 байт передаётся chunked, без `Content-Length`
|
||
- **THEN** ответ `413` с кодом `payload_too_large`, вложение не создаётся
|
||
|
||
#### Scenario: Ровно 40 млн пикселей
|
||
|
||
- **WHEN** загружается корректный PNG 8000×5000
|
||
- **THEN** ответ `201`
|
||
|
||
#### Scenario: Больше 40 млн пикселей
|
||
|
||
- **WHEN** загружается PNG 8001×5000 или сжатый PNG огромных размеров весом несколько килобайт
|
||
- **THEN** ответ `413` с кодом `payload_too_large`, изображение не декодируется
|
||
|
||
### Requirement: Тип определяется по содержимому
|
||
|
||
Сервис SHALL принимать только `Content-Type` `image/png` и `image/jpeg` (параметры заголовка и регистр не важны) и SHALL проверять, что сигнатура и структура файла соответствуют заявленному типу, а файл читается без ошибок. Иной или отсутствующий `Content-Type`, несовпадение заявленного типа и содержимого, пустое тело, обрезанный или повреждённый файл, GIF, WebP и текст SHALL давать `415` с кодом `unsupported_media_type`.
|
||
|
||
#### Scenario: Подмена MIME
|
||
|
||
- **WHEN** JPEG, GIF или текст отправлены с `Content-Type: image/png`
|
||
- **THEN** ответ `415` с кодом `unsupported_media_type`
|
||
|
||
#### Scenario: Обрезанное изображение
|
||
|
||
- **WHEN** отправлена первая половина корректного PNG или JPEG с верным `Content-Type`
|
||
- **THEN** ответ `415`
|
||
|
||
#### Scenario: Неподдерживаемый Content-Type
|
||
|
||
- **WHEN** корректный PNG отправлен с `Content-Type: application/octet-stream` или без `Content-Type`
|
||
- **THEN** ответ `415`
|
||
|
||
### Requirement: Безопасное отображаемое имя
|
||
|
||
`filename` SHALL быть обязательным параметром длиной 1–255 Unicode code points после percent-декодирования, SHALL NOT состоять только из пробельных символов и SHALL NOT содержать `/`, `\`, NUL и другие управляющие символы. Нарушение SHALL давать `400` с кодом `invalid_request`. Имя SHALL использоваться только для отображения и возвращаться без изменений.
|
||
|
||
#### Scenario: Опасное имя
|
||
|
||
- **WHEN** `filename` равен `../a.png`, `a/b.png`, `a\b.png`, содержит `%00`, `%01` или `%7F`
|
||
- **THEN** ответ `400` с кодом `invalid_request`
|
||
|
||
#### Scenario: Пустое, пробельное, длинное или отсутствующее имя
|
||
|
||
- **WHEN** `filename` пустой, из пробелов, длиной 256 code points или не передан
|
||
- **THEN** ответ `400`
|
||
|
||
#### Scenario: Имя на кириллице
|
||
|
||
- **WHEN** `filename` равен `фото 1.png` длиной до 255 code points
|
||
- **THEN** ответ `201` и `filename` в ответе совпадает с переданным
|
||
|
||
### 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=original` (по умолчанию) — исходные байты оригинала, для `variant=thumbnail`, `crop` и `optimized` — байты варианта опубликованной версии, описанного в метаданных. Для вложения в `queued`, `processing` или `failed` `/content` SHALL отвечать `409` с кодом `conflict` для любого допустимого `variant`, включая `original`. Для `ready`-вложения, у опубликованной версии которого нет запрошенного варианта (вложение, готовое до лабы 5), 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`
|
||
- **THEN** ответ `200`, `Content-Type: image/png`, байты совпадают с загруженными, SHA-256 равен `sha256` метаданных
|
||
|
||
#### Scenario: Второй участник скачивает thumbnail
|
||
|
||
- **WHEN** второй участник чата запрашивает `/content?variant=thumbnail` готового вложения
|
||
- **THEN** ответ `200`, `Content-Type: image/jpeg`, длина и SHA-256 равны метаданным варианта
|
||
|
||
#### Scenario: Crop и optimized
|
||
|
||
- **WHEN** второй участник запрашивает `/content?variant=crop` и `/content?variant=optimized` готового вложения
|
||
- **THEN** ответы `200` с `Content-Type: image/jpeg` и `image/webp`, длина и 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` вложения, ставшего `ready` в лабе 4 без вариантов
|
||
- **THEN** ответ `404` с кодом `not_found`
|
||
|
||
#### Scenario: Неизвестный вариант
|
||
|
||
- **WHEN** запрошен `/content?variant=preview`
|
||
- **THEN** ответ `400` с кодом `invalid_request`
|
||
|
||
#### Scenario: Объект пропал из хранилища
|
||
|
||
- **WHEN** метаданные готового вложения есть, а объекта в bucket нет
|
||
- **THEN** `/content` отвечает `404`, событие пишется в журнал без ключа объекта
|
||
|
||
### Requirement: Порядок записи PostgreSQL и S3
|
||
|
||
Сервис SHALL фиксировать намерение (метаданные со статусом, невидимым клиентам) до записи оригинала в staging и SHALL переводить вложение в `queued` вместе с записью задания только после подтверждённой записи объекта. Сбой на любом шаге SHALL NOT давать `202` и SHALL NOT оставлять видимого клиентам вложения без объекта. Обрыв клиента до конца тела SHALL NOT оставлять ни объекта, ни строки. Намерение и объект, оставшиеся после сбоя, SHALL удаляться компенсацией сразу или уборкой по истечении grace period (capability `lab4-upload-resilience`), поэтому объект без строки-намерения в bucket не остаётся.
|
||
|
||
#### Scenario: S3 отказал при записи
|
||
|
||
- **WHEN** запись объекта в staging завершилась ошибкой
|
||
- **THEN** ответ `503` с кодом `unavailable`, вложение не видно ни в метаданных, ни в сообщениях, задания нет, а строка-намерение удаляется уборкой после grace period
|
||
|
||
#### Scenario: Клиент оборвал загрузку
|
||
|
||
- **WHEN** клиент закрыл соединение, отправив часть тела
|
||
- **THEN** в bucket нет нового объекта и в PostgreSQL нет новой строки вложения
|
||
|
||
### Requirement: Недоступный S3
|
||
|
||
Недоступность S3 SHALL превращаться в `503 unavailable` в общем формате ошибки за ограниченное время (меньше `REQUEST_TIMEOUT_SECONDS`) для upload и скачивания. Метаданные, тексты сообщений и `GET /health/ready` SHALL продолжать работать: готовность реплики от S3 не зависит. После возврата S3 ранее загруженные файлы SHALL скачиваться без изменений.
|
||
|
||
#### Scenario: S3 остановлен
|
||
|
||
- **WHEN** выполняется `docker compose stop s3` и клиент загружает и скачивает файл, отправляет текст и проверяет готовность
|
||
- **THEN** upload и `/content` отвечают `503` с `X-Request-Id` и `X-Instance-Id` быстрее `REQUEST_TIMEOUT_SECONDS`, текстовое сообщение — `201`, метаданные и `/health/ready` — `200`
|
||
|
||
#### Scenario: S3 вернулся
|
||
|
||
- **WHEN** S3 снова запущен
|
||
- **THEN** ранее загруженный файл скачивается с тем же SHA-256
|
||
|