Files
mtusi2026lab4/openspec/specs/attachments/spec.md
T
ricoromaandClaude Opus 5.5 4cfaab0063 test: add idle S3 upload fault check on a short S3 timeout API
Fourth API of the failure stand (S3__TIMEOUT_SECONDS=1), slow streamed
download in the test client, test_upload_after_idle_s3 and the
fix-upload-put-flake spec deltas synced into the main specs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-23 01:05:00 +03:00

682 lines
42 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 быть 201 с объектом `Attachment` без других полей:
- `id` — новый UUID, его назначает сервер;
- `chat_id` — чат из пути, `owner_id` — текущий пользователь;
- `filename` — переданное имя без изменений;
- `content_type` — тип, определённый по содержимому;
- `size_bytes` и `sha256` (64 шестнадцатеричных символа в нижнем
регистре) — размер и SHA-256 принятых байтов;
- `status` — `ready`, `variants` — `[]`, `error_code` — null;
- `created_at` и `updated_at` — время сервера в RFC 3339 UTC.
Ответ 201 SHALL означать, что сохранены и оригинал, и метаданные
(требование «Порядок записи»). Загрузку может выполнить любой участник
чата.
#### Scenario: Загрузка PNG
- **WHEN** Алиса загружает в свой чат публичный fixture
`tests/fixtures/sample.png` с `Content-Type: image/png` и
`filename=sample.png`
- **THEN** ответ 201, `status` `ready`, `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** ответ 201, `content_type` `image/jpeg`, `owner_id` — Боб, а
`size_bytes` и `sha256` совпадают с размером и SHA-256 файла
#### Scenario: Разновидности PNG и JPEG
- **WHEN** участник загружает PNG с палитрой, с альфа-каналом, в
оттенках серого с альфа-каналом, 16 и 1 бит на канал, чересстрочный
(Adam7), а также JPEG прогрессивный, в оттенках серого, CMYK и с EXIF
- **THEN** каждый ответ 201 с `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** первый ответ 201, второй — 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 размера тела на каждую загрузку, а у кода до этого изменения
(вариант «до») — больше
### 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** ответ 201
#### 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, последний — 201
### Requirement: Повреждённое изображение
Сервис SHALL проверять целостность структуры изображения без
декодирования пикселей и отвечать 415 `unsupported_media_type` на
заведомо повреждённое.
- PNG:
- первым идёт IHDR с допустимыми полями;
- каждый чанк целиком в файле, и его CRC верна;
- неизвестных критичных чанков нет;
- данные изображения (IDAT) идут подряд, их поток zlib завершён и
распаковывается ровно в объём, который следует из размеров, глубины
цвета и чересстрочности;
- тип фильтра каждой строки допустим;
- IEND есть.
- JPEG:
- маркеры и длины сегментов разбираются до конца;
- кадр (SOF) один и с ненулевыми размерами;
- есть хотя бы один скан;
- есть маркер конца EOI.
Байты после IEND или EOI повреждением не считаются: они входят в
оригинал, в его размер и SHA-256. Искажения внутри сжатых данных
скана JPEG, которые не нарушают структуру, сервис не обнаруживает: у
формата нет контрольной суммы.
#### Scenario: Обрезанный файл
- **WHEN** участник загружает PNG и JPEG, обрезанные наполовину и без
последних байтов
- **THEN** каждый ответ 415 `unsupported_media_type`
#### Scenario: Испорченные данные PNG
- **WHEN** участник загружает `sample.png` с одним изменённым байтом
внутри IDAT и сигнатуру PNG, за которой случайные байты
- **THEN** оба ответа 415 `unsupported_media_type`
#### Scenario: Хвост после конца изображения
- **WHEN** участник загружает PNG и JPEG, к которым дописаны байты
после IEND и EOI
- **THEN** оба ответа 201, `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`, последний — 201 с
`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** ответ 201, а `filename` в ответе загрузки и в метаданных
совпадает с переданным
#### Scenario: Символы форматирования в имени
- **WHEN** участник загружает файлы, в `filename` которых есть U+202E,
U+2066 с U+2069, U+2028 и мягкий перенос U+00AD
- **THEN** каждый ответ 201, а `filename` в ответе загрузки и в
метаданных совпадает с переданным
### Requirement: Порядок проверок загрузки
Если у загрузки несколько ошибок, ответ SHALL определяться первой из
них по порядку:
1. 401 — нет действительной сессии;
2. 400 — неверный `chat_id` или `filename`;
3. 404 — чата нет или пользователь в нём не состоит;
4. 415 — `Content-Type` запроса;
5. 413 — `Content-Length` запроса;
6. 429 — нет места для загрузки (требование «Одновременные загрузки
реплики»);
7. тело: 413 — прочитано больше лимита; 400 — тело не пришло за срок
(требование «Срок передачи тела») или клиент оборвал передачу;
8. 415 или 413 — содержимое: формат и целостность или число пикселей.
Тело MUST NOT читаться, пока не пройдены проверки 1–6. Загрузка,
отклонённая на проверках 1–5, 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` и
вложение, загрузка которого не завершена, SHALL получать одинаковый 404
`not_found`. Запрос без действительной сессии — 401, `attachment_id` не
UUID — 400 `invalid_request`.
#### Scenario: Другой участник
- **WHEN** Алиса загрузила вложение в чат с Бобом, и Боб запрашивает
его метаданные и байты
- **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`, равным ответу на загрузку этого вложения.
#### Scenario: Метаданные равны ответу загрузки
- **WHEN** Алиса загрузила вложение, а Боб запрашивает его метаданные
- **THEN** ответ 200, JSON совпадает с ответом на загрузку во всех
полях
### Requirement: Скачивание оригинала
`GET /api/v1/attachments/{attachment_id}/content` SHALL отвечать 200 с
байтами оригинала без изменений: их размер и SHA-256 равны `size_bytes`
и `sha256` вложения. Заголовки ответа:
- `Content-Type` — `content_type` вложения без параметров;
- `Content-Length` — размер оригинала;
- `X-Content-Type-Options: nosniff`.
Байты SHALL отдавать API, ответ MUST NOT быть перенаправлением.
Параметр `variant` SHALL принимать только `original`, это и значение по
умолчанию. Любое другое значение — 400 `invalid_request`. Ключ объекта,
адрес и учётные данные S3 MUST NOT попадать ни в тело, ни в заголовки
ответов API.
Если у готового вложения нет объекта в 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=thumbnail` и с пустым `variant`
- **THEN** первый ответ 200 с теми же байтами, остальные — 400
`invalid_request`
#### Scenario: Без следов хранилища в ответе
- **WHEN** участник загружает вложение, читает метаданные и скачивает
байты
- **THEN** в телах ответов нет полей вне схемы контракта, а в
заголовках нет `Location` и заголовков `x-amz-*`
#### Scenario: Потерянный оригинал
- **WHEN** объект готового вложения удалён мимо API, затем сверка с
`--apply` пометила его оригинал потерянным
- **THEN** скачивание до сверки — 500 `internal_error`, после неё — 404
`not_found`
- **AND** метаданные и до, и после — 200 с тем же JSON, что у ответа на
загрузку
### Requirement: Где хранятся вложения
Метаданные вложения SHALL храниться в PostgreSQL, байты оригинала —
одним объектом в приватном bucket S3 (`object-storage`). Байты MUST
NOT храниться ни в PostgreSQL, ни в файлах реплики API. Ключ объекта
назначает сервер: имя базы, `/attachments/`, `id` вложения и
`/original`. Каждая загрузка SHALL создавать новое вложение и новый
объект, в том числе повтор той же загрузки: прозрачных повторов
загрузки нет (`contracts/README.md`).
#### Scenario: Байты не в БД и не на диске API
- **WHEN** после загрузок через балансировщик проверяющий смотрит
схему таблиц вложений, ключи объектов в PostgreSQL, объекты в bucket
и изменения файловой системы контейнеров реплик API
- **THEN** в таблицах нет колонки с байтами изображения, ключ каждого
объекта имеет вид `<база>/attachments/<id>/original` и не содержит
`filename`, объект с этим ключом есть в bucket, анонимный GET его
ключа — 403, а в контейнерах реплик нет файлов оригиналов
#### Scenario: Повторная загрузка
- **WHEN** участник дважды загружает один и тот же файл
- **THEN** оба ответа 201 с разными `id` и одинаковым `sha256`, и оба
вложения скачиваются
### Requirement: Порядок записи
Загрузка SHALL выполняться по шагам:
1. проверки и чтение тела;
2. запись метаданных в статусе «загружается» (`pending`) вместе с
ключом объекта, фиксация в PostgreSQL;
3. запись объекта в S3;
4. статус `ready`, фиксация;
5. ответ 201.
Объект, который записал API, SHALL быть известен PostgreSQL до записи в
S3: без зафиксированных метаданных объект не записывается. Вложение не
в статусе `ready` MUST NOT быть видно через API: его метаданные и байты
— 404, ссылка на него в сообщении — 404.
Сбой после шага 2 из-за отказа хранилища SHALL давать 503
`unavailable`, а не 500. Отказ — S3 или PostgreSQL недоступен, не
ответил за срок или отказал. Метаданные «загружается» при этом
остаются. Их и объект убирает уборщик после grace period (capability
`storage-consistency`). Компенсация — сверх этого:
- объект записан, а перевод в `ready` не удался до того, как фиксация
отправлена в PostgreSQL. API SHALL удалить записанный объект до
ответа. Удаление не гарантировано: если оно не удалось, объект убирает
уборщик;
- исход фиксации `ready` неизвестен: связь оборвалась во время
фиксации. API MUST NOT удалять объект — вложение могло стать `ready`;
- к шагу 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
та же загрузка — 201
#### 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: Фиксация ready не удалась
- **WHEN** объект вложения записан в S3, а PostgreSQL отказывает при
переводе вложения в `ready`
- **THEN** ответ 503 `unavailable`, а не 500, и объекта этого вложения
в bucket уже нет
- **AND** вложение остаётся в статусе «загружается» до уборщика, а по
API его не видно
#### Scenario: Исход фиксации неизвестен
- **WHEN** объект вложения записан в S3, а фиксация перевода в `ready`
обрывается отказом PostgreSQL
- **THEN** ответ 503 `unavailable`, вложение в статусе «загружается» и
по API не видно, а его объект в bucket остаётся: API его не удаляет
- **AND** после grace уборщик убирает и метаданные, и объект, а в bucket
нет объектов вложений без метаданных
#### Scenario: Обрыв передачи тела
- **WHEN** клиент обрывает соединение посреди тела загрузки
- **THEN** нового вложения нет ни в PostgreSQL, ни в bucket, а следующая
загрузка того же участника — 201
### Requirement: Недоступность S3
Если S3 недоступен, не ответил за срок вызова или отказал
(`object-storage`), загрузка и скачивание байтов SHALL отвечать 503
`unavailable` в формате ошибки. Ответ SHALL приходить не позже срока
вызова S3 с запасом, а не 500 и не зависанием. Без S3 SHALL работать:
- метаданные вложения;
- история чата с `attachment_ids`;
- отправка сообщений, в том числе со ссылкой на готовое вложение;
- `/health/ready`.
После возврата S3 загрузка и скачивание SHALL проходить без перезапуска
API.
503 на загрузке и скачивании SHALL означать только такой отказ S3:
недоступен, не ответил за срок или отказал. Доступный S3 MUST NOT давать
503 из-за того, что реплика какое-то время не обращалась к нему, в том
числе после скачивания больших оригиналов.
#### Scenario: S3 остановлен
- **WHEN** вложение загружено, затем 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** каждая загрузка — 201, ни одной 503
- **AND** скачанные байты совпадают с загруженными
### Requirement: Вложение доступно через любую реплику
Готовое вложение SHALL скачиваться через любую реплику API за
балансировщиком, в том числе после остановки реплики, которая его
приняла. Метаданные и оригинал SHALL переживать перезапуск стенда
(`scripts/restart.sh`, вместе с S3) с сохранёнными volumes и читаться
прежним токеном.
#### Scenario: Скачивание через другую реплику
- **WHEN** вложение загружено через балансировщик, ответ дала реплика
с одним `X-Instance-Id`
- **THEN** байты скачиваются через реплику с другим `X-Instance-Id` и
совпадают с загруженными
#### Scenario: Принявшая реплика остановлена
- **WHEN** вложение загружено через балансировщик, затем реплика с
`X-Instance-Id` ответа на загрузку остановлена `scripts/stop-one.sh`
- **THEN** метаданные и байты через балансировщик — 200 от другой
реплики, SHA-256 совпадает с загруженным, посторонний получает 404
#### Scenario: Рестарт стенда
- **WHEN** вложение загружено, затем выполнен `scripts/restart.sh`
- **THEN** прежним токеном метаданные — 200, а байты совпадают с
загруженными по SHA-256
### Requirement: Одновременные загрузки реплики
Каждый процесс API SHALL обрабатывать одновременно не больше `[uploads]
max_concurrent` загрузок (`service-configuration`, «Параметры
загрузок»): у процесса столько мест загрузки. Загрузка занимает место
после проверок 1–5 требования «Порядок проверок загрузки» и до чтения
тела. Место SHALL освобождаться при любом исходе загрузки: 201, ошибка,
обрыв клиента, истёкший срок, отмена запроса.
Загрузка, которой места нет, 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** все ответы 201 с разными `id`, и каждое вложение скачивается
с тем же SHA-256
#### Scenario: Все места заняты
- **WHEN** все места загрузки процесса заняты загрузками, тела которых
ещё идут, приходит ещё одна загрузка, и место за срок ожидания не
освобождается
- **THEN** ответ 429 `rate_limited` с `Retry-After` не меньше 1 приходит
не раньше срока ожидания, а нового вложения нет ни в PostgreSQL, ни в
bucket
#### Scenario: Очередь ожидания полна
- **WHEN** все места загрузки процесса заняты, и очередь ожидания полна
- **THEN** следующая загрузка сразу получает 429 `rate_limited` с
`Retry-After`, без ожидания
#### Scenario: Ожидание места
- **WHEN** место занято загрузкой, которая заканчивается раньше срока
ожидания, а следующая загрузка ждёт его в очереди
- **THEN** ожидавшая загрузка получает 201, и её вложение скачивается с
тем же SHA-256
#### Scenario: Место освобождается
- **WHEN** загрузка на единственном месте процесса заканчивается 413 по
счётчику, 415 по содержимому, 400 по сроку тела, обрывом клиента или
503 при остановленном S3
- **THEN** после каждой такой загрузки следующая получает место сразу:
ответ 201 без ожидания (после 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, а следующая загрузка — 201 без ожидания места
#### Scenario: Медленная передача в срок
- **WHEN** участник шлёт настоящий PNG мелкими частями с паузами и
укладывается в срок передачи
- **THEN** ответ 201, а `size_bytes` и `sha256` совпадают с файлом