# 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//original`, живёт до фиксации `ready`, а у `failed` — до конца срока хранения (`storage-consistency`, «Очистка staging»); - конечный оригинал — `<база>/attachments//original`; - вариант — `<база>/attachments//v-<вариант>`. 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`