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>
682 lines
42 KiB
Markdown
682 lines
42 KiB
Markdown
# 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` совпадают с файлом
|