Files
mtusi2026lab6/openspec/specs/attachments/spec.md
T
ricoromaandClaude Opus 5.5 9cc6c0c7a6 chore: port lab 5 solution into the lab 6 skeleton
Source: mtusi2026lab5-safronov, solution/bvt2301-safronov, 046ec9e.
Contracts, public tests and evidence of lab 5 are not carried over.
The compose project, image and CI prefix are renamed to lab6; the first
broker start defect is recorded in KNOWN_ISSUES.md; PLAN.md outlines the
OpenSpec changes of lab 6.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 04:46:56 +03:00

797 lines
52 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.
# attachments Specification
## Purpose
Вложения-изображения в чатах с лабы 4. Здесь описано:
- загрузка PNG и JPEG с лимитами до чтения и распаковки;
- проверка типа и целостности по содержимому, правила `filename`;
- доступ только участникам чата, метаданные и побайтный download;
- где лежат метаданные и байты, порядок записи и отказ S3;
- доступность файла через любую реплику и после рестарта стенда.
## Requirements
### Requirement: Загрузка вложения
`POST /api/v1/chats/{chat_id}/attachments?filename=<имя>` SHALL
принимать тело — сырые байты одного изображения PNG или JPEG, не
multipart и не JSON, с `Content-Type: image/png` или `image/jpeg`. При
успехе ответ SHALL быть 202 с объектом `Attachment` без других полей:
- `id` — новый UUID, его назначает сервер;
- `chat_id` — чат из пути, `owner_id` — текущий пользователь;
- `filename` — переданное имя без изменений;
- `content_type` — тип, определённый по содержимому;
- `size_bytes` и `sha256` (64 шестнадцатеричных символа в нижнем
регистре) — размер и SHA-256 принятых байтов;
- `status` — `queued`, `variants` — `[]`, `error_code` — null;
- `created_at` и `updated_at` — время сервера в RFC 3339 UTC.
Это снимок на момент приёма: быстрый worker мог закончить раньше ответа, и
готовность клиент SHALL узнавать по метаданным. Ответ 202 SHALL означать, что
устойчиво сохранены оригинал, метаданные и задание обработки (требование
«Порядок записи»). Загрузку может выполнить любой участник чата.
#### Scenario: Загрузка PNG
- **WHEN** Алиса загружает в свой чат публичный fixture
`tests/fixtures/sample.png` с `Content-Type: image/png` и
`filename=sample.png`
- **THEN** ответ 202, `status` `queued`, `variants` `[]`, `error_code`
null, `owner_id` — Алиса, `chat_id` — этот чат, `filename`
`sample.png`, `content_type` `image/png`, `size_bytes` 111817, а
`sha256` равен SHA-256 файла
#### Scenario: Загрузка JPEG
- **WHEN** Боб загружает в общий с Алисой чат настоящий JPEG с
`Content-Type: image/jpeg`
- **THEN** ответ 202, `content_type` `image/jpeg`, `owner_id` — Боб, а
`size_bytes` и `sha256` совпадают с размером и SHA-256 файла
#### Scenario: Разновидности PNG и JPEG
- **WHEN** участник загружает PNG с палитрой, с альфа-каналом, в
оттенках серого с альфа-каналом, 16 и 1 бит на канал, чересстрочный
(Adam7), а также JPEG прогрессивный, в оттенках серого, CMYK, с EXIF
и baseline без таблиц Хаффмана (кадр Motion JPEG)
- **THEN** каждый ответ 202 с `content_type` по формату файла
### Requirement: Лимит размера до чтения тела
Тело больше 10 485 760 байт (10 MiB) SHALL отклоняться ответом 413
`payload_too_large`, а тело ровно 10 485 760 байт проверку размера
SHALL проходить. Если `Content-Length` запроса больше лимита, ответ
SHALL отдаваться без чтения тела. Без `Content-Length` (передача
частями) тело SHALL читаться потоком со счётчиком. Ответ 413 SHALL
отдаваться, как только прочитано больше лимита, остаток тела MUST NOT
читаться. На одну загрузку процесс API MUST NOT держать в памяти больше
одной копии тела (не больше лимита) и блоков чтения — тела от клиента и
клиента S3. Это касается всех шагов загрузки, в том числе записи
объекта в S3: для отправки тело MUST NOT копироваться целиком. С
накладными расходами процесса рост пика памяти реплики — не больше 1,5
размера тела на загрузку (сценарий «Одна копия тела при записи в S3»).
#### Scenario: Граница размера
- **WHEN** участник загружает настоящий PNG размером ровно 10 485 760
байт, а затем такой же PNG на один байт длиннее
- **THEN** первый ответ 202, второй — 413 `payload_too_large`
#### Scenario: Заявленный размер больше лимита
- **WHEN** участник загружает 30 MiB с `Content-Length` 31 457 280
- **THEN** ответ 413 `payload_too_large` в формате ошибки, а клиент
получает его, не дожидаясь отправки всего тела
#### Scenario: Большое тело без Content-Length
- **WHEN** участник передаёт 30 MiB частями, без `Content-Length`
- **THEN** ответ 413 `payload_too_large` в формате ошибки
#### Scenario: Одна копия тела при записи в S3
- **WHEN** 10 клиентов одновременно загружают по 10 MiB в одну реплику,
у которой лимит одновременных загрузок выше 10 (профиль загрузок
стенда `bench/`, вариант «без лимита»)
- **THEN** пик памяти реплики выше её памяти до загрузок не больше чем
на 1,5 размера тела на каждую загрузку; что у кода до change
`upload-memory` больше — показано в отчёте лабы 4
(`mtusi2026lab4-safronov`, `REPORT.md`)
### Requirement: Лимит пикселей до распаковки
Ширину и высоту изображения сервис SHALL брать из заголовка до
распаковки данных: у PNG — из IHDR, у JPEG — из маркера кадра. Больше
40 000 000 пикселей — ответ 413 `payload_too_large`, ровно 40 000 000
проверку SHALL проходить. Проверка MUST NOT декодировать изображение в
память процесса API: распакованные данные PNG SHALL проверяться
потоком, их объём MUST NOT превышать следующего из размеров
изображения, и память проверки не зависит от числа пикселей. Данные
длиннее заявленных размеров — повреждённое изображение (требование
«Повреждённое изображение»).
#### Scenario: Огромные размеры в маленьком файле
- **WHEN** участник загружает PNG и JPEG по несколько килобайт, в
заголовке которых 40 000 001 пиксель и больше
- **THEN** каждый ответ 413 `payload_too_large`
#### Scenario: Ровно 40 млн пикселей
- **WHEN** участник загружает настоящий PNG 8000 × 5000 пикселей
- **THEN** ответ 202, и вложение становится `ready`
#### Scenario: Данные длиннее размеров
- **WHEN** участник загружает PNG 100 × 100, данные изображения
которого распаковываются в сотни мегабайт
- **THEN** ответ 415 `unsupported_media_type`, а сервис не
распаковывает данные дальше заявленного размера изображения
### Requirement: Тип по содержимому
Тип вложения SHALL определяться по первым байтам содержимого: сигнатура
PNG — `image/png`, маркер начала JPEG — `image/jpeg`. Ответ SHALL быть
415 `unsupported_media_type`, если:
- `Content-Type` запроса нет или его тип не `image/png` и не
`image/jpeg`; параметры типа и регистр букв не учитываются;
- содержимое не PNG и не JPEG, в том числе пустое тело;
- тип содержимого не совпадает с `Content-Type` запроса (подмена MIME).
#### Scenario: Не изображение
- **WHEN** участник загружает текст, тело GIF и пустое тело с
`Content-Type: image/png`
- **THEN** каждый ответ 415 `unsupported_media_type`
#### Scenario: Подмена MIME
- **WHEN** участник загружает настоящий JPEG с `Content-Type: image/png`
и настоящий PNG с `Content-Type: image/jpeg`
- **THEN** оба ответа 415 `unsupported_media_type`
#### Scenario: Неподходящий Content-Type
- **WHEN** участник загружает настоящий PNG с `Content-Type`
`application/octet-stream`, `text/plain` и без `Content-Type`, а затем
с `Content-Type: IMAGE/PNG; charset=binary`
- **THEN** первые три ответа 415, последний — 202
### Requirement: Повреждённое изображение
Сервис SHALL проверять целостность структуры изображения без
декодирования пикселей и отвечать 415 `unsupported_media_type` на
заведомо повреждённое.
- PNG:
- первым идёт IHDR с допустимыми полями;
- каждый чанк целиком в файле, и его CRC верна;
- неизвестных критичных чанков нет;
- данные изображения (IDAT) идут подряд, их поток zlib завершён и
распаковывается ровно в объём, который следует из размеров, глубины
цвета и чересстрочности;
- тип фильтра каждой строки допустим;
- IEND есть.
- JPEG:
- маркеры и длины сегментов разбираются до конца, у таблиц
квантования (DQT) и Хаффмана (DHT) допустимые номер и точность, и
таблицы заполняют сегмент ровно;
- кадр (SOF) один, с ненулевыми размерами, у каждой компоненты
выборка 1–4 и номер таблицы квантования 0–3;
- есть хотя бы один скан;
- компоненты скана есть в кадре и не повторяются в нём, у
прогрессивного скана допустимы полоса коэффициентов и сдвиги;
- к началу скана определены таблицы, которые он использует:
квантования — у его компонент (у кадра без потерь их нет), Хаффмана
— кроме таблиц 0 и 1 непрогрессивного кадра;
- у скана с кодами Хаффмана есть сжатые данные;
- есть маркер конца EOI.
Байты после IEND или EOI повреждением не считаются: они входят в
оригинал, в его размер и SHA-256. Искажения внутри сжатых данных
скана JPEG, которые не нарушают структуру, сервис не обнаруживает: у
формата нет контрольной суммы. Таблицы Хаффмана 0 и 1 непрогрессивного
кадра без DHT декодеры берут стандартные (кадры Motion JPEG), поэтому
такой JPEG принимается. Пустые данные скана с кодами Хаффмана —
обрыв: код даёт хотя бы бит на блок. Изображение, которое прошло эту
проверку, но не декодируется при обработке, становится `failed`
(`attachment-processing`, «Постоянные ошибки и коды»).
#### Scenario: Обрезанный файл
- **WHEN** участник загружает PNG и JPEG, обрезанные наполовину и без
последних байтов
- **THEN** каждый ответ 415 `unsupported_media_type`
#### Scenario: Испорченные данные PNG
- **WHEN** участник загружает `sample.png` с одним изменённым байтом
внутри IDAT и сигнатуру PNG, за которой случайные байты
- **THEN** оба ответа 415 `unsupported_media_type`
#### Scenario: Недекодируемый JPEG
- **WHEN** участник загружает с `Content-Type: image/jpeg` JPEG без
таблиц квантования (в том числе 27 байт: SOI, SOF0 1 × 1, SOS без
данных и EOI), прогрессивный JPEG без таблиц Хаффмана, JPEG со сканом
компоненты, которой нет в кадре, прогрессивный AC-скан трёх
компонент и JPEG без данных скана
- **THEN** каждый ответ 415 `unsupported_media_type`
#### Scenario: Хвост после конца изображения
- **WHEN** участник загружает PNG и JPEG, к которым дописаны байты
после IEND и EOI
- **THEN** оба ответа 202, `size_bytes` и `sha256` учитывают дописанные
байты, а скачанный оригинал готового вложения содержит их
### Requirement: Имя файла
`filename` SHALL содержать от 1 до 255 Unicode code points. Ответ SHALL
быть 400 `invalid_request`, если параметра нет, имя пустое, длиннее
255 code points, состоит из одних пробельных символов или содержит:
- `/` или `\`;
- управляющий символ — категория Unicode Cc: U+0000–U+001F, в том числе
NUL, или U+007F–U+009F.
Отказ ограничен этим списком контракта (`contracts/README.md`). Прочие
символы SHALL приниматься, в том числе:
- символы форматирования и управления направлением текста (категория
Cf, например U+202E и U+2066);
- разделители строк и абзацев U+2028 и U+2029.
Имя в строке запроса SHALL быть корректным UTF-8 после
процент-декодирования. Неверная последовательность байтов (например,
`%FF`, обрезанная или закодированный суррогат) и байт вне ASCII в
строке запроса — 400 `invalid_request`. Замена таких байтов символом
U+FFFD MUST NOT превращать отказ в принятое имя.
Принятое имя SHALL храниться и возвращаться без изменений, без обрезки
и нормализации. Имя только отображается: оно MUST NOT участвовать в
ключе объекта и в пути на диске. Как безопасно показать имя, решает
клиент.
#### Scenario: Имя не в UTF-8
- **WHEN** участник загружает настоящий PNG с `filename=a%FFb.png`,
`filename=a%C3.png` и `filename=a%ED%A0%80b.png`, а затем с
`filename=%C3%A9t%C3%A9.png`
- **THEN** первые три ответа 400 `invalid_request`, последний — 202 с
`filename` `été.png`
#### Scenario: Опасное имя
- **WHEN** участник загружает настоящий PNG с `filename`
`../x.png`, `a/b.png`, `a\b.png`, с NUL, с переводом строки, с DEL, с
управляющим символом C1 U+0085, пустым, из одних пробелов и из 256
code points
- **THEN** каждый ответ 400 `invalid_request`
#### Scenario: Имя в Unicode
- **WHEN** участник загружает файл с `filename` из 255 code points:
кириллица, emoji с ZWJ и пробелы по краям
- **THEN** ответ 202, а `filename` в ответе загрузки и в метаданных
совпадает с переданным
#### Scenario: Символы форматирования в имени
- **WHEN** участник загружает файлы, в `filename` которых есть U+202E,
U+2066 с U+2069, U+2028 и мягкий перенос U+00AD
- **THEN** каждый ответ 202, а `filename` в ответе загрузки и в
метаданных совпадает с переданным
### Requirement: Порядок проверок загрузки
Если у загрузки несколько ошибок, ответ SHALL определяться первой из
них по порядку:
1. 401 — нет действительной сессии;
2. 400 — неверный `chat_id` или `filename`;
3. 404 — чата нет или пользователь в нём не состоит;
4. 415 — `Content-Type` запроса;
5. 413 — `Content-Length` запроса;
6. 429 — незавершённых заданий не меньше предела (`queue-overload`, «Предел
незавершённых заданий»);
7. 429 — нет места для загрузки (требование «Одновременные загрузки
реплики»);
8. тело: 413 — прочитано больше лимита; 400 — тело не пришло за срок
(требование «Срок передачи тела») или клиент оборвал передачу;
9. 415 или 413 — содержимое: формат и целостность или число пикселей.
Тело MUST NOT читаться, пока не пройдены проверки 1–7. Загрузка,
отклонённая на проверках 1–6, MUST NOT ждать места и занимать его.
Ошибка клиента MUST NOT давать 500.
#### Scenario: Посторонний с большим файлом
- **WHEN** Ева загружает 30 MiB в чат Алисы и Боба
- **THEN** ответ 404 `not_found`, а не 413
#### Scenario: Без сессии с опасным именем
- **WHEN** загрузка без `Authorization` идёт с `filename` `a/b.png`, а
затем с допустимым именем
- **THEN** оба ответа 401 `unauthorized` с `WWW-Authenticate: Bearer`
#### Scenario: Неверный тип и большой размер
- **WHEN** участник загружает 30 MiB с `Content-Type: text/plain`
- **THEN** ответ 415 `unsupported_media_type`
#### Scenario: Отказ раньше очереди
- **WHEN** все места загрузки процесса заняты и очередь ожидания полна,
и посторонний загружает файл в чат, участник загружает 30 MiB с
`Content-Length` 31 457 280, а затем PNG с `Content-Type: text/plain`
- **THEN** ответы 404, 413 и 415 приходят сразу, без ожидания места, а
не 429
### Requirement: Доступ к вложению
Метаданные и байты вложения SHALL быть доступны любому участнику чата
вложения, а не только владельцу. Посторонний, неизвестный `id` и
вложение, загрузка которого не завершена (ответа 202 ещё не было),
SHALL получать одинаковый 404 `not_found`. Запрос без действительной
сессии — 401, `attachment_id` не UUID — 400 `invalid_request`.
#### Scenario: Другой участник
- **WHEN** Алиса загрузила вложение в чат с Бобом, оно стало `ready`, и Боб
запрашивает его метаданные и байты
- **THEN** оба ответа 200
#### Scenario: Посторонний и неизвестный id
- **WHEN** Ева запрашивает метаданные и байты вложения чата Алисы и
Боба, а Алиса — по случайному UUID
- **THEN** все ответы 404 `not_found` с одинаковым `message`
#### Scenario: Неверный id вложения
- **WHEN** участник запрашивает метаданные и байты по `attachment_id`
`123` и `abc`
- **THEN** каждый ответ 400 `invalid_request`
#### Scenario: Чтение без сессии
- **WHEN** метаданные и байты вложения запрашиваются без
`Authorization`
- **THEN** оба ответа 401 `unauthorized` с `WWW-Authenticate: Bearer`
### Requirement: Метаданные вложения
`GET /api/v1/attachments/{attachment_id}` SHALL отвечать 200 с объектом
`Attachment` во всех состояниях `queued`, `processing`, `ready` и `failed`
(`attachment-processing`, «Состояния вложения»). Поля `id`, `chat_id`,
`owner_id`, `filename`, `content_type`, `size_bytes`, `sha256` и `created_at`
SHALL совпадать с ответом на загрузку. `size_bytes`, `sha256` и `content_type`
всегда описывают оригинал, у вариантов — свои поля. `status`, `variants`,
`error_code` и `updated_at` SHALL отражать текущее состояние. У готового вложения
`variants` содержит каждый записанный вариант: у вложений этого уровня — `thumbnail`,
`crop` и `optimized`. Вложение, ставшее готовым до обработки вариантов, вариантов не
имеет, а ставшее готовым на уровне 3 — только `thumbnail`.
#### Scenario: Метаданные равны ответу загрузки
- **WHEN** Алиса загрузила вложение, а Боб запрашивает его метаданные
- **THEN** ответ 200, поля, описывающие оригинал, совпадают с ответом на
загрузку, а когда вложение становится `ready`, — `error_code` null и
непустые `variants`
### Requirement: Скачивание оригинала
`GET /api/v1/attachments/{attachment_id}/content` SHALL отвечать 200 с
байтами оригинала без изменений, если вложение `ready`: их размер и
SHA-256 равны `size_bytes` и `sha256` вложения. Заголовки ответа:
- `Content-Type` — `content_type` вложения без параметров;
- `Content-Length` — размер оригинала;
- `X-Content-Type-Options: nosniff`.
Байты SHALL отдавать API, ответ MUST NOT быть перенаправлением.
Параметр `variant` SHALL принимать `original`, `thumbnail`, `crop` и
`optimized`, по умолчанию `original`. Любое другое значение — 400
`invalid_request`. Ключ объекта, адрес и учётные данные S3 MUST NOT
попадать ни в тело, ни в заголовки ответов API.
Если вложение `queued`, `processing` или `failed`, ответ на любой `variant`
SHALL быть 409 `conflict` без обращения к S3.
Если у готового вложения нет объекта в S3 или его размер не равен
`size_bytes`, а сверка хранилищ это ещё не подтвердила, это
непредвиденное расхождение. Скачивание SHALL отвечать 500
`internal_error` без деталей, причина пишется в журнал. Если сверка уже
пометила оригинал потерянным (capability `storage-consistency`,
«Потерянный оригинал»), скачивание SHALL отвечать участнику 404
`not_found`, как отсутствующий вариант готового объекта, — без
обращения к S3. Метаданные такого вложения SHALL отвечать 200 тем же
`Attachment`, что и до пометки. Ссылка на него в новом сообщении
принимается, как на любое готовое вложение. Когда сверка снимает
пометку, скачивание снова отдаёт байты.
#### Scenario: Побайтный оригинал
- **WHEN** Боб скачивает готовые PNG и JPEG, загруженные Алисой
- **THEN** каждый ответ 200, не перенаправление, байты совпадают с
загруженными, `Content-Type` — `image/png` и `image/jpeg`,
`Content-Length` равен размеру, есть `X-Content-Type-Options: nosniff`
#### Scenario: Вариант original
- **WHEN** участник скачивает готовое вложение с `variant=original`, а
затем с `variant=big` и с пустым `variant`
- **THEN** первый ответ 200 с теми же байтами, остальные — 400
`invalid_request`
#### Scenario: Без следов хранилища в ответе
- **WHEN** участник загружает вложение, читает метаданные и скачивает
байты готового вложения и его thumbnail
- **THEN** в телах ответов нет полей вне схемы контракта, а в
заголовках нет `Location` и заголовков `x-amz-*`
#### Scenario: Потерянный оригинал
- **WHEN** объект готового вложения удалён мимо API, затем сверка с
`--apply` пометила его оригинал потерянным
- **THEN** скачивание до сверки — 500 `internal_error`, после неё — 404
`not_found`
- **AND** метаданные и до, и после — 200 с тем же JSON
#### Scenario: Скачивание до готовности
- **WHEN** участник скачивает вложение в `queued`, `processing` и `failed`,
без `variant`, с `variant=original` и с `variant=thumbnail`
- **THEN** каждый ответ 409 `conflict` в формате ошибки
### Requirement: Где хранятся вложения
Метаданные вложения SHALL храниться в PostgreSQL, байты — объектами в
приватном bucket S3 (`object-storage`). Байты MUST NOT храниться ни в
PostgreSQL, ни в файлах реплики API и worker. Ключ объекта назначает
сервер, `filename` в него MUST NOT входить:
- устойчивый staging — `<база>/staging/<id>/original`, живёт до фиксации `ready`, а
у `failed` — до конца срока хранения (`storage-consistency`, «Очистка staging»);
- конечный оригинал — `<база>/attachments/<id>/original`;
- вариант — `<база>/attachments/<id>/v<pipeline_version>-<вариант>`.
Staging и конечный префикс — один и тот же сервер S3 и bucket. Устойчивость
staging — устойчивость этого сервера. Граница называется в `REPORT.md`:
отказ диска или ВМ теряет и то, и другое.
Каждая загрузка SHALL создавать новое вложение и новые объекты, в том
числе повтор той же загрузки: прозрачных повторов загрузки нет
(`contracts/README.md`).
#### Scenario: Байты не в БД и не на диске API
- **WHEN** после загрузок через балансировщик вложения стали `ready`, и
проверяющий смотрит схему таблиц вложений, ключи объектов в PostgreSQL,
объекты в bucket и изменения файловой системы контейнеров реплик API и
worker
- **THEN** в таблицах нет колонки с байтами изображения, ключи объектов
имеют вид из требования и не содержат `filename`, объекты с этими
ключами есть в bucket, анонимный GET их ключей — 403, а в контейнерах
реплик и worker нет файлов оригиналов и вариантов
#### Scenario: Повторная загрузка
- **WHEN** участник дважды загружает один и тот же файл
- **THEN** оба ответа 202 с разными `id` и одинаковым `sha256`, и оба
вложения становятся `ready` и скачиваются
### Requirement: Порядок записи
Загрузка SHALL выполняться по шагам:
1. проверки и чтение тела;
2. запись метаданных в статусе «загружается» (`pending`) вместе с
ключами объектов, фиксация в PostgreSQL;
3. запись оригинала в staging;
4. статус `queued` и задание обработки — одной транзакцией;
5. ответ 202.
К брокеру загрузка MUST NOT обращаться: задание до него доводит relay
(`job-outbox`).
Объект, который записал API, SHALL быть известен PostgreSQL до записи в
S3: без зафиксированных метаданных объект не записывается. Вложение в
статусе `pending` MUST NOT быть видно через API: его метаданные и байты
— 404, ссылка на него в сообщении — 404.
Сбой после шага 2 из-за отказа хранилища SHALL давать 503
`unavailable`, а не 500. Отказ — S3 или PostgreSQL недоступен, не ответил
за срок или отказал. Метаданные «загружается» при этом
остаются. Их и объект убирает уборщик после grace period (capability
`storage-consistency`). Компенсация — сверх этого:
- объект записан, а шаг 4 не удался до того, как фиксация отправлена в
PostgreSQL. API SHALL удалить записанный объект до ответа. Удаление не
гарантировано: если оно не удалось, объект убирает уборщик;
- исход фиксации шага 4 неизвестен: связь оборвалась во время фиксации.
API MUST NOT удалять объект — вложение могло стать `queued`, и тогда его
доведёт до `ready` relay и worker, хотя клиент получил 503;
- к шагу 4 метаданных «загружается» уже нет или уборщик уже начал их
уборку, потому что загрузка длилась дольше grace. Ответ SHALL быть
503 `unavailable`, и API SHALL удалить записанный объект.
Если запись метаданных на шаге 2 не удалась, объект MUST NOT
записываться; отказ PostgreSQL при этом — 503 `unavailable`. Загрузка,
которую отклонили до шага 2 (401, 400, 404, 413, 415) или клиент оборвал
посреди тела, MUST NOT оставлять ни метаданных, ни объекта.
#### Scenario: Запись в S3 не удалась
- **WHEN** S3 остановлен, и участник загружает настоящий PNG
- **THEN** ответ 503 `unavailable`, в PostgreSQL появилось одно новое
вложение — в статусе «загружается», заданий и принятых не прибавилось
- **AND** текстовое сообщение в тот же чат — 201, а после возврата S3
та же загрузка — 202
#### Scenario: Отклонённая загрузка ничего не оставляет
- **WHEN** участник и посторонний отправляют загрузки, которые
отклоняются с 404, 413 по `Content-Length`, 413 по счётчику, 413 по
пикселям, 415 по типу и 415 по целостности
- **THEN** в PostgreSQL не появилось ни одного нового вложения, а в
bucket — ни одного нового объекта вложения
#### Scenario: Незавершённая загрузка не видна
- **WHEN** загрузка при остановленном S3 оставила вложение в статусе
«загружается», и участник чата по его `id` запрашивает метаданные и
байты и отправляет сообщение со ссылкой на него
- **THEN** все три ответа 404 `not_found` с тем же `message`, что у
неизвестного `id`
#### Scenario: Сбой записи метаданных
- **WHEN** PostgreSQL отказывает при записи метаданных новой загрузки
- **THEN** ответ 503 `unavailable`, а нового вложения нет ни в
PostgreSQL, ни в bucket
#### Scenario: Фиксация задания не удалась
- **WHEN** объект вложения записан в staging, а PostgreSQL отказывает при
переводе вложения в `queued`
- **THEN** ответ 503 `unavailable`, а не 500, и объекта этого вложения
в bucket уже нет, а задания у него нет
- **AND** вложение остаётся в статусе «загружается» до уборщика, а по
API его не видно
#### Scenario: Фиксация ready не удалась
- **WHEN** worker записал объекты вложения, а PostgreSQL отказывает при
фиксации `ready`
- **THEN** вложение не готово: метаданные — `queued` или `processing`,
скачивание — 409 `conflict`, а следующая попытка доводит его до `ready`
#### Scenario: Исход фиксации неизвестен
- **WHEN** объект вложения записан в staging, а фиксация перевода в
`queued` обрывается отказом PostgreSQL
- **THEN** ответ 503 `unavailable`, вложение в статусе «загружается» и
по API не видно, а его объект в bucket остаётся: API его не удаляет
- **AND** после grace уборщик убирает и метаданные, и объект, а в bucket
нет объектов вложений без метаданных
#### Scenario: Брокер не подтвердил задание
- **WHEN** брокер остановлен, и участник загружает настоящий PNG
- **THEN** ответ 202, а не 503, вложение `queued`, у его задания нет времени
подтверждения брокером, а объект — в staging
- **AND** после запуска брокера вложение становится `ready`
#### Scenario: Обрыв передачи тела
- **WHEN** клиент обрывает соединение посреди тела загрузки
- **THEN** нового вложения нет ни в PostgreSQL, ни в bucket, а следующая
загрузка того же участника — 202
### Requirement: Недоступность S3
Если S3 недоступен, не ответил за срок вызова или отказал
(`object-storage`), загрузка и скачивание байтов SHALL отвечать 503
`unavailable` в формате ошибки. Ответ SHALL приходить не позже срока
вызова S3 с запасом, а не 500 и не зависанием. Без S3 SHALL работать:
- метаданные вложения;
- история чата с `attachment_ids`;
- отправка сообщений, в том числе со ссылкой на готовое вложение;
- `/health/ready`.
После возврата S3 загрузка и скачивание SHALL проходить без перезапуска
API. Что делает при этом worker — `attachment-processing`, «Ограниченные
повторы».
503 на загрузке и скачивании SHALL означать только такой отказ S3:
недоступен, не ответил за срок или отказал. Доступный S3 MUST NOT давать
503 из-за того, что реплика какое-то время не обращалась к нему, в том
числе после скачивания больших оригиналов.
#### Scenario: S3 остановлен
- **WHEN** вложение стало `ready`, затем S3 остановлен, и участник
скачивает байты, читает метаданные, отправляет сообщение с этим
вложением и запрашивает `/health/ready`
- **THEN** скачивание — 503 `unavailable`, метаданные — 200, сообщение
— 201, готовность — 200
- **AND** после возврата S3 скачивание — 200 с теми же байтами
#### Scenario: S3 завис
- **WHEN** контейнер S3 заморожен (`docker pause`), и участник
загружает файл и скачивает байты готового вложения
- **THEN** оба ответа 503 `unavailable` не позже срока вызова S3 с
запасом, а после разморозки скачивание — 200
#### Scenario: Загрузка после простоя S3
- **WHEN** участники одновременно скачали оригинал в несколько MiB,
затем реплика дольше срока вызова S3 не обращалась к S3, а S3 всё это
время доступен, и участник одну за другой загружает файлы
- **THEN** каждая загрузка — 202, ни одной 503
- **AND** скачанные байты совпадают с загруженными
### Requirement: Вложение доступно через любую реплику
Метаданные любого принятого вложения и байты готового SHALL читаться
через любую реплику API за балансировщиком, в том числе после остановки
реплики, которая его приняла. Метаданные, оригинал и варианты SHALL
переживать перезапуск стенда (`scripts/restart.sh`, вместе с S3) с
сохранёнными volumes и читаться прежним токеном.
#### Scenario: Скачивание через другую реплику
- **WHEN** вложение загружено через балансировщик, ответ дала реплика
с одним `X-Instance-Id`, и оно стало `ready`
- **THEN** байты скачиваются через реплику с другим `X-Instance-Id` и
совпадают с загруженными
#### Scenario: Принявшая реплика остановлена
- **WHEN** вложение загружено через балансировщик, затем реплика с
`X-Instance-Id` ответа на загрузку остановлена `scripts/stop-one.sh`
- **THEN** метаданные — 200 от другой реплики, вложение становится `ready`,
байты через балансировщик — 200, SHA-256 совпадает с загруженным,
посторонний получает 404
#### Scenario: Рестарт стенда
- **WHEN** вложение стало `ready`, затем выполнен `scripts/restart.sh`
- **THEN** прежним токеном метаданные — 200, а байты совпадают с
загруженными по SHA-256
### Requirement: Одновременные загрузки реплики
Каждый процесс API SHALL обрабатывать одновременно не больше `[uploads]
max_concurrent` загрузок (`service-configuration`, «Параметры
загрузок»): у процесса столько мест загрузки. Загрузка занимает место
после проверок 1–5 требования «Порядок проверок загрузки» и до чтения
тела. Место SHALL освобождаться при любом исходе загрузки: 202, ошибка,
обрыв клиента, истёкший срок, отмена запроса.
Загрузка, которой места нет, SHALL ждать его в очереди процесса по
порядку прихода, но не дольше `[uploads] wait_timeout_seconds`. В
очереди SHALL быть не больше `[uploads] max_waiting` загрузок. Если
очередь полна, ответ SHALL отдаваться сразу. Если за срок ожидания
место не освободилось, ответ SHALL отдаваться по его истечении. Ответ в
обоих случаях — 429 `rate_limited` в формате ошибки с заголовком
`Retry-After` — положительным целым числом секунд. Такая загрузка MUST
NOT оставлять ни метаданных, ни объекта. Ожидающая загрузка MUST NOT
держать соединение с PostgreSQL.
Места считает каждый процесс отдельно. Балансировщик ответ 429 на другой
реплике не повторяет (`load-balancing`), загрузку повторяет клиент после
`Retry-After`.
Память загрузок процесса SHALL ограничиваться числом мест, а не числом
клиентов. Ожидающее или отклонённое соединение SHALL держать в памяти
процесса и в буферах его сокетов не больше 1 MiB, каким бы ни было
тело.
#### Scenario: Загрузки в пределах лимита
- **WHEN** 10 участников одного чата одновременно загружают по
настоящему PNG около 1 MiB, а параметры загрузок — по умолчанию
- **THEN** все ответы 202 с разными `id`, и каждое вложение становится
`ready` и скачивается с тем же SHA-256
#### Scenario: Все места заняты
- **WHEN** все места загрузки процесса заняты загрузками, тела которых
ещё идут, приходит ещё одна загрузка, и место за срок ожидания не
освобождается
- **THEN** ответ 429 `rate_limited` с `Retry-After` не меньше 1 приходит
не раньше срока ожидания, а нового вложения нет ни в PostgreSQL, ни в
bucket
#### Scenario: Очередь ожидания полна
- **WHEN** все места загрузки процесса заняты, и очередь ожидания полна
- **THEN** следующая загрузка сразу получает 429 `rate_limited` с
`Retry-After`, без ожидания
#### Scenario: Ожидание места
- **WHEN** место занято загрузкой, которая заканчивается раньше срока
ожидания, а следующая загрузка ждёт его в очереди
- **THEN** ожидавшая загрузка получает 202, и её вложение становится `ready`
и скачивается с тем же SHA-256
#### Scenario: Место освобождается
- **WHEN** загрузка на единственном месте процесса заканчивается 413 по
счётчику, 415 по содержимому, 400 по сроку тела, обрывом клиента или
503 при остановленном S3
- **THEN** после каждой такой загрузки следующая получает место сразу:
ответ 202 без ожидания (после 503 — когда S3 вернулся)
#### Scenario: Память не растёт с числом загрузок
- **WHEN** 10, 20 и 40 клиентов одновременно и без пауз загружают по
10 MiB в одну реплику с параметрами по умолчанию (профиль загрузок
стенда `bench/`, вариант «с лимитом»)
- **THEN** пик памяти реплики в каждом случае не больше половины лимита
контейнера, при 20 и 40 клиентах он выше, чем при 10, не больше чем на
1 MiB на каждого клиента сверх 10, реплика не завершена из-за памяти,
лишние загрузки получают 429, а ответов 5xx нет
### Requirement: Срок передачи тела
Тело загрузки SHALL приходить целиком не позже `[uploads]
body_timeout_seconds` после того, как загрузка заняла место. Иначе
ответ SHALL быть 400 `invalid_request` в формате ошибки. Загрузка при
этом MUST NOT оставлять ни метаданных, ни объекта, и её место
освобождается. Тело, которое пришло в срок, SHALL приниматься, как бы
мелко его ни делил клиент и какие бы паузы ни делал.
#### Scenario: Медленный клиент
- **WHEN** участник шлёт настоящий PNG частями так, что тело идёт
дольше срока передачи
- **THEN** ответ 400 `invalid_request`, нового вложения нет ни в
PostgreSQL, ни в bucket, а следующая загрузка — 202 без ожидания места
#### Scenario: Медленная передача в срок
- **WHEN** участник шлёт настоящий PNG мелкими частями с паузами и
укладывается в срок передачи
- **THEN** ответ 202, а `size_bytes` и `sha256` совпадают с файлом
### Requirement: Скачивание варианта
`GET /api/v1/attachments/{attachment_id}/content?variant=<имя>` у готового вложения
SHALL отвечать 200 с байтами варианта `thumbnail`, `crop` или `optimized` через API, без
перенаправления. Заголовки ответа: `Content-Type` — `content_type` варианта,
`Content-Length` — его размер, `X-Content-Type-Options: nosniff`. Размер и
SHA-256 байтов равны полям варианта в метаданных. Доступ — как у оригинала
(требование «Доступ к вложению»).
Вариант, которого у готового вложения нет, SHALL давать 404 `not_found`. Это вложения,
ставшие готовыми раньше: до обработки вариантов — любой вариант, на уровне 3 — `crop` и
`optimized`. Нет объекта варианта в S3 или размер другой — 500 `internal_error` без деталей,
причина в журнале.
#### Scenario: Скачивание thumbnail
- **WHEN** Боб скачивает `variant=thumbnail` готового вложения, загруженного
Алисой
- **THEN** ответ 200, не перенаправление, `Content-Type: image/jpeg`,
`Content-Length` равен `size_bytes` варианта, есть `X-Content-Type-Options:
nosniff`, а SHA-256 равен `sha256` варианта
#### Scenario: Скачивание crop и optimized
- **WHEN** Боб скачивает `variant=crop` и `variant=optimized` готового вложения,
загруженного Алисой
- **THEN** оба ответа 200, не перенаправление, `Content-Type` — `image/jpeg` и
`image/webp`, `Content-Length` равен `size_bytes` варианта, есть
`X-Content-Type-Options: nosniff`, а SHA-256 равен `sha256` варианта
#### Scenario: Отсутствующий вариант
- **WHEN** у готового вложения нет метаданных варианта `crop`, потому что оно стало
готовым раньше этого уровня, и участник скачивает `variant=crop`
- **THEN** ответ 404 `not_found` в формате ошибки, а остальные варианты скачиваются
#### Scenario: Вариант для постороннего
- **WHEN** Ева скачивает `variant=thumbnail` вложения чата Алисы и Боба
- **THEN** ответ 404 `not_found` с тем же `message`, что у неизвестного `id`