Files
mtusi2026lab2/openspec/specs/lab4-attachments/spec.md
T
ArtyomandClaude Opus 5.5 64d5c6746e Archive the crop, optimized, worker limits and job recovery change
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>
2026-10-29 03:39:39 +03:00

184 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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