Mark a stale pending row in its own committed transaction before the cleaner deletes the object, and let mark_ready promote only unmarked rows, so a cleaner rollback after the object delete can no longer leave a ready attachment without its object. Add fault checks for an unknown COMMIT outcome, an upload outliving the grace period and a cleaner failure after the object delete; fix the cleaner entrypoint in rules. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
526 lines
31 KiB
Markdown
526 lines
31 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 держать в памяти больше
|
||
лимита и одного блока чтения тела.
|
||
|
||
#### 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` в формате ошибки
|
||
|
||
### 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. 413 — число прочитанных байтов;
|
||
7. 415 или 413 — содержимое: формат и целостность или число пикселей.
|
||
|
||
Тело MUST NOT читаться, пока не пройдены проверки 1–5. Ошибка клиента
|
||
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`
|
||
|
||
### 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.
|
||
|
||
#### 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-*`
|
||
|
||
### 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.
|
||
|
||
#### 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
|
||
|
||
### 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
|