Source: mtusi2026lab5-safronov, solution/bvt2301-safronov, 046ec9e. Contracts, public tests and evidence of lab 5 are not carried over. The compose project, image and CI prefix are renamed to lab6; the first broker start defect is recorded in KNOWN_ISSUES.md; PLAN.md outlines the OpenSpec changes of lab 6. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
52 KiB
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,
statusqueued,variants[],error_codenull,owner_id— Алиса,chat_id— этот чат,filenamesample.png,content_typeimage/png,size_bytes111817, аsha256равен SHA-256 файла
Scenario: Загрузка JPEG
- WHEN Боб загружает в общий с Алисой чат настоящий JPEG с
Content-Type: image/jpeg - THEN ответ 202,
content_typeimage/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-Length31 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-Typeapplication/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/jpegJPEG без таблиц квантования (в том числе 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 определяться первой из них по порядку:
- 401 — нет действительной сессии;
- 400 — неверный
chat_idилиfilename; - 404 — чата нет или пользователь в нём не состоит;
- 415 —
Content-Typeзапроса; - 413 —
Content-Lengthзапроса; - 429 — незавершённых заданий не меньше предела (
queue-overload, «Предел незавершённых заданий»); - 429 — нет места для загрузки (требование «Одновременные загрузки реплики»);
- тело: 413 — прочитано больше лимита; 400 — тело не пришло за срок (требование «Срок передачи тела») или клиент оборвал передачу;
- 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идёт сfilenamea/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-Length31 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_id123и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_codenull и непустые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, после неё — 404not_found - AND метаданные и до, и после — 200 с тем же JSON
Scenario: Скачивание до готовности
- WHEN участник скачивает вложение в
queued,processingиfailed, безvariant, сvariant=originalи сvariant=thumbnail - THEN каждый ответ 409
conflictв формате ошибки
Requirement: Где хранятся вложения
Метаданные вложения SHALL храниться в PostgreSQL, байты — объектами в
приватном bucket S3 (object-storage). Байты MUST NOT храниться ни в
PostgreSQL, ни в файлах реплики API и worker. Ключ объекта назначает
сервер, filename в него MUST NOT входить:
- устойчивый staging —
<база>/staging/<id>/original, живёт до фиксацииready, а уfailed— до конца срока хранения (storage-consistency, «Очистка staging»); - конечный оригинал —
<база>/attachments/<id>/original; - вариант —
<база>/attachments/<id>/v<pipeline_version>-<вариант>.
Staging и конечный префикс — один и тот же сервер S3 и bucket. Устойчивость
staging — устойчивость этого сервера. Граница называется в REPORT.md:
отказ диска или ВМ теряет и то, и другое.
Каждая загрузка SHALL создавать новое вложение и новые объекты, в том
числе повтор той же загрузки: прозрачных повторов загрузки нет
(contracts/README.md).
Scenario: Байты не в БД и не на диске API
- WHEN после загрузок через балансировщик вложения стали
ready, и проверяющий смотрит схему таблиц вложений, ключи объектов в PostgreSQL, объекты в bucket и изменения файловой системы контейнеров реплик API и worker - THEN в таблицах нет колонки с байтами изображения, ключи объектов
имеют вид из требования и не содержат
filename, объекты с этими ключами есть в bucket, анонимный GET их ключей — 403, а в контейнерах реплик и worker нет файлов оригиналов и вариантов
Scenario: Повторная загрузка
- WHEN участник дважды загружает один и тот же файл
- THEN оба ответа 202 с разными
idи одинаковымsha256, и оба вложения становятсяreadyи скачиваются
Requirement: Порядок записи
Загрузка SHALL выполняться по шагам:
- проверки и чтение тела;
- запись метаданных в статусе «загружается» (
pending) вместе с ключами объектов, фиксация в PostgreSQL; - запись оригинала в staging;
- статус
queuedи задание обработки — одной транзакцией; - ответ 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, и тогда его доведёт доreadyrelay и 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, скачивание — 409conflict, а следующая попытка доводит его до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