Files
mtusi2026lab6/openspec/specs/attachments/spec.md
T
ricoromaandClaude Opus 5.5 9cc6c0c7a6 chore: port lab 5 solution into the lab 6 skeleton
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>
2026-11-11 04:46:56 +03:00

52 KiB
Raw Blame History

attachments Specification

Purpose

Вложения-изображения в чатах с лабы 4. Здесь описано:

  • загрузка PNG и JPEG с лимитами до чтения и распаковки;
  • проверка типа и целостности по содержимому, правила filename;
  • доступ только участникам чата, метаданные и побайтный download;
  • где лежат метаданные и байты, порядок записи и отказ S3;
  • доступность файла через любую реплику и после рестарта стенда.

Requirements

Requirement: Загрузка вложения

POST /api/v1/chats/{chat_id}/attachments?filename=<имя> SHALL принимать тело — сырые байты одного изображения PNG или JPEG, не multipart и не JSON, с Content-Type: image/png или image/jpeg. При успехе ответ SHALL быть 202 с объектом Attachment без других полей:

  • id — новый UUID, его назначает сервер;
  • chat_id — чат из пути, owner_id — текущий пользователь;
  • filename — переданное имя без изменений;
  • content_type — тип, определённый по содержимому;
  • size_bytes и sha256 (64 шестнадцатеричных символа в нижнем регистре) — размер и SHA-256 принятых байтов;
  • status — queued, variants — [], error_code — null;
  • created_at и updated_at — время сервера в RFC 3339 UTC.

Это снимок на момент приёма: быстрый worker мог закончить раньше ответа, и готовность клиент SHALL узнавать по метаданным. Ответ 202 SHALL означать, что устойчиво сохранены оригинал, метаданные и задание обработки (требование «Порядок записи»). Загрузку может выполнить любой участник чата.

Scenario: Загрузка PNG

  • WHEN Алиса загружает в свой чат публичный fixture tests/fixtures/sample.png с Content-Type: image/png и filename=sample.png
  • THEN ответ 202, status queued, variants [], error_code null, owner_id — Алиса, chat_id — этот чат, filename sample.png, content_type image/png, size_bytes 111817, а sha256 равен SHA-256 файла

Scenario: Загрузка JPEG

  • WHEN Боб загружает в общий с Алисой чат настоящий JPEG с Content-Type: image/jpeg
  • THEN ответ 202, content_type image/jpeg, owner_id — Боб, а size_bytes и sha256 совпадают с размером и SHA-256 файла

Scenario: Разновидности PNG и JPEG

  • WHEN участник загружает PNG с палитрой, с альфа-каналом, в оттенках серого с альфа-каналом, 16 и 1 бит на канал, чересстрочный (Adam7), а также JPEG прогрессивный, в оттенках серого, CMYK, с EXIF и baseline без таблиц Хаффмана (кадр Motion JPEG)
  • THEN каждый ответ 202 с content_type по формату файла

Requirement: Лимит размера до чтения тела

Тело больше 10 485 760 байт (10 MiB) SHALL отклоняться ответом 413 payload_too_large, а тело ровно 10 485 760 байт проверку размера SHALL проходить. Если Content-Length запроса больше лимита, ответ SHALL отдаваться без чтения тела. Без Content-Length (передача частями) тело SHALL читаться потоком со счётчиком. Ответ 413 SHALL отдаваться, как только прочитано больше лимита, остаток тела MUST NOT читаться. На одну загрузку процесс API MUST NOT держать в памяти больше одной копии тела (не больше лимита) и блоков чтения — тела от клиента и клиента S3. Это касается всех шагов загрузки, в том числе записи объекта в S3: для отправки тело MUST NOT копироваться целиком. С накладными расходами процесса рост пика памяти реплики — не больше 1,5 размера тела на загрузку (сценарий «Одна копия тела при записи в S3»).

Scenario: Граница размера

  • WHEN участник загружает настоящий PNG размером ровно 10 485 760 байт, а затем такой же PNG на один байт длиннее
  • THEN первый ответ 202, второй — 413 payload_too_large

Scenario: Заявленный размер больше лимита

  • WHEN участник загружает 30 MiB с Content-Length 31 457 280
  • THEN ответ 413 payload_too_large в формате ошибки, а клиент получает его, не дожидаясь отправки всего тела

Scenario: Большое тело без Content-Length

  • WHEN участник передаёт 30 MiB частями, без Content-Length
  • THEN ответ 413 payload_too_large в формате ошибки

Scenario: Одна копия тела при записи в S3

  • WHEN 10 клиентов одновременно загружают по 10 MiB в одну реплику, у которой лимит одновременных загрузок выше 10 (профиль загрузок стенда bench/, вариант «без лимита»)
  • THEN пик памяти реплики выше её памяти до загрузок не больше чем на 1,5 размера тела на каждую загрузку; что у кода до change upload-memory больше — показано в отчёте лабы 4 (mtusi2026lab4-safronov, REPORT.md)

Requirement: Лимит пикселей до распаковки

Ширину и высоту изображения сервис SHALL брать из заголовка до распаковки данных: у PNG — из IHDR, у JPEG — из маркера кадра. Больше 40 000 000 пикселей — ответ 413 payload_too_large, ровно 40 000 000 проверку SHALL проходить. Проверка MUST NOT декодировать изображение в память процесса API: распакованные данные PNG SHALL проверяться потоком, их объём MUST NOT превышать следующего из размеров изображения, и память проверки не зависит от числа пикселей. Данные длиннее заявленных размеров — повреждённое изображение (требование «Повреждённое изображение»).

Scenario: Огромные размеры в маленьком файле

  • WHEN участник загружает PNG и JPEG по несколько килобайт, в заголовке которых 40 000 001 пиксель и больше
  • THEN каждый ответ 413 payload_too_large

Scenario: Ровно 40 млн пикселей

  • WHEN участник загружает настоящий PNG 8000 × 5000 пикселей
  • THEN ответ 202, и вложение становится ready

Scenario: Данные длиннее размеров

  • WHEN участник загружает PNG 100 × 100, данные изображения которого распаковываются в сотни мегабайт
  • THEN ответ 415 unsupported_media_type, а сервис не распаковывает данные дальше заявленного размера изображения

Requirement: Тип по содержимому

Тип вложения SHALL определяться по первым байтам содержимого: сигнатура PNG — image/png, маркер начала JPEG — image/jpeg. Ответ SHALL быть 415 unsupported_media_type, если:

  • Content-Type запроса нет или его тип не image/png и не image/jpeg; параметры типа и регистр букв не учитываются;
  • содержимое не PNG и не JPEG, в том числе пустое тело;
  • тип содержимого не совпадает с Content-Type запроса (подмена MIME).

Scenario: Не изображение

  • WHEN участник загружает текст, тело GIF и пустое тело с Content-Type: image/png
  • THEN каждый ответ 415 unsupported_media_type

Scenario: Подмена MIME

  • WHEN участник загружает настоящий JPEG с Content-Type: image/png и настоящий PNG с Content-Type: image/jpeg
  • THEN оба ответа 415 unsupported_media_type

Scenario: Неподходящий Content-Type

  • WHEN участник загружает настоящий PNG с Content-Type application/octet-stream, text/plain и без Content-Type, а затем с Content-Type: IMAGE/PNG; charset=binary
  • THEN первые три ответа 415, последний — 202

Requirement: Повреждённое изображение

Сервис SHALL проверять целостность структуры изображения без декодирования пикселей и отвечать 415 unsupported_media_type на заведомо повреждённое.

  • PNG:
    • первым идёт IHDR с допустимыми полями;
    • каждый чанк целиком в файле, и его CRC верна;
    • неизвестных критичных чанков нет;
    • данные изображения (IDAT) идут подряд, их поток zlib завершён и распаковывается ровно в объём, который следует из размеров, глубины цвета и чересстрочности;
    • тип фильтра каждой строки допустим;
    • IEND есть.
  • JPEG:
    • маркеры и длины сегментов разбираются до конца, у таблиц квантования (DQT) и Хаффмана (DHT) допустимые номер и точность, и таблицы заполняют сегмент ровно;
    • кадр (SOF) один, с ненулевыми размерами, у каждой компоненты выборка 1–4 и номер таблицы квантования 0–3;
    • есть хотя бы один скан;
    • компоненты скана есть в кадре и не повторяются в нём, у прогрессивного скана допустимы полоса коэффициентов и сдвиги;
    • к началу скана определены таблицы, которые он использует: квантования — у его компонент (у кадра без потерь их нет), Хаффмана — кроме таблиц 0 и 1 непрогрессивного кадра;
    • у скана с кодами Хаффмана есть сжатые данные;
    • есть маркер конца EOI.

Байты после IEND или EOI повреждением не считаются: они входят в оригинал, в его размер и SHA-256. Искажения внутри сжатых данных скана JPEG, которые не нарушают структуру, сервис не обнаруживает: у формата нет контрольной суммы. Таблицы Хаффмана 0 и 1 непрогрессивного кадра без DHT декодеры берут стандартные (кадры Motion JPEG), поэтому такой JPEG принимается. Пустые данные скана с кодами Хаффмана — обрыв: код даёт хотя бы бит на блок. Изображение, которое прошло эту проверку, но не декодируется при обработке, становится failed (attachment-processing, «Постоянные ошибки и коды»).

Scenario: Обрезанный файл

  • WHEN участник загружает PNG и JPEG, обрезанные наполовину и без последних байтов
  • THEN каждый ответ 415 unsupported_media_type

Scenario: Испорченные данные PNG

  • WHEN участник загружает sample.png с одним изменённым байтом внутри IDAT и сигнатуру PNG, за которой случайные байты
  • THEN оба ответа 415 unsupported_media_type

Scenario: Недекодируемый JPEG

  • WHEN участник загружает с Content-Type: image/jpeg JPEG без таблиц квантования (в том числе 27 байт: SOI, SOF0 1 × 1, SOS без данных и EOI), прогрессивный JPEG без таблиц Хаффмана, JPEG со сканом компоненты, которой нет в кадре, прогрессивный AC-скан трёх компонент и JPEG без данных скана
  • THEN каждый ответ 415 unsupported_media_type

Scenario: Хвост после конца изображения

  • WHEN участник загружает PNG и JPEG, к которым дописаны байты после IEND и EOI
  • THEN оба ответа 202, size_bytes и sha256 учитывают дописанные байты, а скачанный оригинал готового вложения содержит их

Requirement: Имя файла

filename SHALL содержать от 1 до 255 Unicode code points. Ответ SHALL быть 400 invalid_request, если параметра нет, имя пустое, длиннее 255 code points, состоит из одних пробельных символов или содержит:

  • / или \;
  • управляющий символ — категория Unicode Cc: U+0000–U+001F, в том числе NUL, или U+007F–U+009F.

Отказ ограничен этим списком контракта (contracts/README.md). Прочие символы SHALL приниматься, в том числе:

  • символы форматирования и управления направлением текста (категория Cf, например U+202E и U+2066);
  • разделители строк и абзацев U+2028 и U+2029.

Имя в строке запроса SHALL быть корректным UTF-8 после процент-декодирования. Неверная последовательность байтов (например, %FF, обрезанная или закодированный суррогат) и байт вне ASCII в строке запроса — 400 invalid_request. Замена таких байтов символом U+FFFD MUST NOT превращать отказ в принятое имя.

Принятое имя SHALL храниться и возвращаться без изменений, без обрезки и нормализации. Имя только отображается: оно MUST NOT участвовать в ключе объекта и в пути на диске. Как безопасно показать имя, решает клиент.

Scenario: Имя не в UTF-8

  • WHEN участник загружает настоящий PNG с filename=a%FFb.png, filename=a%C3.png и filename=a%ED%A0%80b.png, а затем с filename=%C3%A9t%C3%A9.png
  • THEN первые три ответа 400 invalid_request, последний — 202 с filename été.png

Scenario: Опасное имя

  • WHEN участник загружает настоящий PNG с filename ../x.png, a/b.png, a\b.png, с NUL, с переводом строки, с DEL, с управляющим символом C1 U+0085, пустым, из одних пробелов и из 256 code points
  • THEN каждый ответ 400 invalid_request

Scenario: Имя в Unicode

  • WHEN участник загружает файл с filename из 255 code points: кириллица, emoji с ZWJ и пробелы по краям
  • THEN ответ 202, а filename в ответе загрузки и в метаданных совпадает с переданным

Scenario: Символы форматирования в имени

  • WHEN участник загружает файлы, в filename которых есть U+202E, U+2066 с U+2069, U+2028 и мягкий перенос U+00AD
  • THEN каждый ответ 202, а filename в ответе загрузки и в метаданных совпадает с переданным

Requirement: Порядок проверок загрузки

Если у загрузки несколько ошибок, ответ SHALL определяться первой из них по порядку:

  1. 401 — нет действительной сессии;
  2. 400 — неверный chat_id или filename;
  3. 404 — чата нет или пользователь в нём не состоит;
  4. 415 — Content-Type запроса;
  5. 413 — Content-Length запроса;
  6. 429 — незавершённых заданий не меньше предела (queue-overload, «Предел незавершённых заданий»);
  7. 429 — нет места для загрузки (требование «Одновременные загрузки реплики»);
  8. тело: 413 — прочитано больше лимита; 400 — тело не пришло за срок (требование «Срок передачи тела») или клиент оборвал передачу;
  9. 415 или 413 — содержимое: формат и целостность или число пикселей.

Тело MUST NOT читаться, пока не пройдены проверки 1–7. Загрузка, отклонённая на проверках 1–6, MUST NOT ждать места и занимать его. Ошибка клиента MUST NOT давать 500.

Scenario: Посторонний с большим файлом

  • WHEN Ева загружает 30 MiB в чат Алисы и Боба
  • THEN ответ 404 not_found, а не 413

Scenario: Без сессии с опасным именем

  • WHEN загрузка без Authorization идёт с filename a/b.png, а затем с допустимым именем
  • THEN оба ответа 401 unauthorized с WWW-Authenticate: Bearer

Scenario: Неверный тип и большой размер

  • WHEN участник загружает 30 MiB с Content-Type: text/plain
  • THEN ответ 415 unsupported_media_type

Scenario: Отказ раньше очереди

  • WHEN все места загрузки процесса заняты и очередь ожидания полна, и посторонний загружает файл в чат, участник загружает 30 MiB с Content-Length 31 457 280, а затем PNG с Content-Type: text/plain
  • THEN ответы 404, 413 и 415 приходят сразу, без ожидания места, а не 429

Requirement: Доступ к вложению

Метаданные и байты вложения SHALL быть доступны любому участнику чата вложения, а не только владельцу. Посторонний, неизвестный id и вложение, загрузка которого не завершена (ответа 202 ещё не было), SHALL получать одинаковый 404 not_found. Запрос без действительной сессии — 401, attachment_id не UUID — 400 invalid_request.

Scenario: Другой участник

  • WHEN Алиса загрузила вложение в чат с Бобом, оно стало ready, и Боб запрашивает его метаданные и байты
  • THEN оба ответа 200

Scenario: Посторонний и неизвестный id

  • WHEN Ева запрашивает метаданные и байты вложения чата Алисы и Боба, а Алиса — по случайному UUID
  • THEN все ответы 404 not_found с одинаковым message

Scenario: Неверный id вложения

  • WHEN участник запрашивает метаданные и байты по attachment_id 123 и abc
  • THEN каждый ответ 400 invalid_request

Scenario: Чтение без сессии

  • WHEN метаданные и байты вложения запрашиваются без Authorization
  • THEN оба ответа 401 unauthorized с WWW-Authenticate: Bearer

Requirement: Метаданные вложения

GET /api/v1/attachments/{attachment_id} SHALL отвечать 200 с объектом Attachment во всех состояниях queued, processing, ready и failed (attachment-processing, «Состояния вложения»). Поля id, chat_id, owner_id, filename, content_type, size_bytes, sha256 и created_at SHALL совпадать с ответом на загрузку. size_bytes, sha256 и content_type всегда описывают оригинал, у вариантов — свои поля. status, variants, error_code и updated_at SHALL отражать текущее состояние. У готового вложения variants содержит каждый записанный вариант: у вложений этого уровня — thumbnail, crop и optimized. Вложение, ставшее готовым до обработки вариантов, вариантов не имеет, а ставшее готовым на уровне 3 — только thumbnail.

Scenario: Метаданные равны ответу загрузки

  • WHEN Алиса загрузила вложение, а Боб запрашивает его метаданные
  • THEN ответ 200, поля, описывающие оригинал, совпадают с ответом на загрузку, а когда вложение становится ready, — error_code null и непустые variants

Requirement: Скачивание оригинала

GET /api/v1/attachments/{attachment_id}/content SHALL отвечать 200 с байтами оригинала без изменений, если вложение ready: их размер и SHA-256 равны size_bytes и sha256 вложения. Заголовки ответа:

  • Content-Type — content_type вложения без параметров;
  • Content-Length — размер оригинала;
  • X-Content-Type-Options: nosniff.

Байты SHALL отдавать API, ответ MUST NOT быть перенаправлением. Параметр variant SHALL принимать original, thumbnail, crop и optimized, по умолчанию original. Любое другое значение — 400 invalid_request. Ключ объекта, адрес и учётные данные S3 MUST NOT попадать ни в тело, ни в заголовки ответов API.

Если вложение queued, processing или failed, ответ на любой variant SHALL быть 409 conflict без обращения к S3.

Если у готового вложения нет объекта в S3 или его размер не равен size_bytes, а сверка хранилищ это ещё не подтвердила, это непредвиденное расхождение. Скачивание SHALL отвечать 500 internal_error без деталей, причина пишется в журнал. Если сверка уже пометила оригинал потерянным (capability storage-consistency, «Потерянный оригинал»), скачивание SHALL отвечать участнику 404 not_found, как отсутствующий вариант готового объекта, — без обращения к S3. Метаданные такого вложения SHALL отвечать 200 тем же Attachment, что и до пометки. Ссылка на него в новом сообщении принимается, как на любое готовое вложение. Когда сверка снимает пометку, скачивание снова отдаёт байты.

Scenario: Побайтный оригинал

  • WHEN Боб скачивает готовые PNG и JPEG, загруженные Алисой
  • THEN каждый ответ 200, не перенаправление, байты совпадают с загруженными, Content-Type — image/png и image/jpeg, Content-Length равен размеру, есть X-Content-Type-Options: nosniff

Scenario: Вариант original

  • WHEN участник скачивает готовое вложение с variant=original, а затем с variant=big и с пустым variant
  • THEN первый ответ 200 с теми же байтами, остальные — 400 invalid_request

Scenario: Без следов хранилища в ответе

  • WHEN участник загружает вложение, читает метаданные и скачивает байты готового вложения и его thumbnail
  • THEN в телах ответов нет полей вне схемы контракта, а в заголовках нет Location и заголовков x-amz-*

Scenario: Потерянный оригинал

  • WHEN объект готового вложения удалён мимо API, затем сверка с --apply пометила его оригинал потерянным
  • THEN скачивание до сверки — 500 internal_error, после неё — 404 not_found
  • AND метаданные и до, и после — 200 с тем же JSON

Scenario: Скачивание до готовности

  • WHEN участник скачивает вложение в queued, processing и failed, без variant, с variant=original и с variant=thumbnail
  • THEN каждый ответ 409 conflict в формате ошибки

Requirement: Где хранятся вложения

Метаданные вложения SHALL храниться в PostgreSQL, байты — объектами в приватном bucket S3 (object-storage). Байты MUST NOT храниться ни в PostgreSQL, ни в файлах реплики API и worker. Ключ объекта назначает сервер, filename в него MUST NOT входить:

  • устойчивый staging — <база>/staging/<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 выполняться по шагам:

  1. проверки и чтение тела;
  2. запись метаданных в статусе «загружается» (pending) вместе с ключами объектов, фиксация в PostgreSQL;
  3. запись оригинала в staging;
  4. статус queued и задание обработки — одной транзакцией;
  5. ответ 202.

К брокеру загрузка MUST NOT обращаться: задание до него доводит relay (job-outbox).

Объект, который записал API, SHALL быть известен PostgreSQL до записи в S3: без зафиксированных метаданных объект не записывается. Вложение в статусе pending MUST NOT быть видно через API: его метаданные и байты — 404, ссылка на него в сообщении — 404.

Сбой после шага 2 из-за отказа хранилища SHALL давать 503 unavailable, а не 500. Отказ — S3 или PostgreSQL недоступен, не ответил за срок или отказал. Метаданные «загружается» при этом остаются. Их и объект убирает уборщик после grace period (capability storage-consistency). Компенсация — сверх этого:

  • объект записан, а шаг 4 не удался до того, как фиксация отправлена в PostgreSQL. API SHALL удалить записанный объект до ответа. Удаление не гарантировано: если оно не удалось, объект убирает уборщик;
  • исход фиксации шага 4 неизвестен: связь оборвалась во время фиксации. API MUST NOT удалять объект — вложение могло стать queued, и тогда его доведёт до ready relay и worker, хотя клиент получил 503;
  • к шагу 4 метаданных «загружается» уже нет или уборщик уже начал их уборку, потому что загрузка длилась дольше grace. Ответ SHALL быть 503 unavailable, и API SHALL удалить записанный объект.

Если запись метаданных на шаге 2 не удалась, объект MUST NOT записываться; отказ PostgreSQL при этом — 503 unavailable. Загрузка, которую отклонили до шага 2 (401, 400, 404, 413, 415) или клиент оборвал посреди тела, MUST NOT оставлять ни метаданных, ни объекта.

Scenario: Запись в S3 не удалась

  • WHEN S3 остановлен, и участник загружает настоящий PNG
  • THEN ответ 503 unavailable, в PostgreSQL появилось одно новое вложение — в статусе «загружается», заданий и принятых не прибавилось
  • AND текстовое сообщение в тот же чат — 201, а после возврата S3 та же загрузка — 202

Scenario: Отклонённая загрузка ничего не оставляет

  • WHEN участник и посторонний отправляют загрузки, которые отклоняются с 404, 413 по Content-Length, 413 по счётчику, 413 по пикселям, 415 по типу и 415 по целостности
  • THEN в PostgreSQL не появилось ни одного нового вложения, а в bucket — ни одного нового объекта вложения

Scenario: Незавершённая загрузка не видна

  • WHEN загрузка при остановленном S3 оставила вложение в статусе «загружается», и участник чата по его id запрашивает метаданные и байты и отправляет сообщение со ссылкой на него
  • THEN все три ответа 404 not_found с тем же message, что у неизвестного id

Scenario: Сбой записи метаданных

  • WHEN PostgreSQL отказывает при записи метаданных новой загрузки
  • THEN ответ 503 unavailable, а нового вложения нет ни в PostgreSQL, ни в bucket

Scenario: Фиксация задания не удалась

  • WHEN объект вложения записан в staging, а PostgreSQL отказывает при переводе вложения в queued
  • THEN ответ 503 unavailable, а не 500, и объекта этого вложения в bucket уже нет, а задания у него нет
  • AND вложение остаётся в статусе «загружается» до уборщика, а по API его не видно

Scenario: Фиксация ready не удалась

  • WHEN worker записал объекты вложения, а PostgreSQL отказывает при фиксации ready
  • THEN вложение не готово: метаданные — queued или processing, скачивание — 409 conflict, а следующая попытка доводит его до ready

Scenario: Исход фиксации неизвестен

  • WHEN объект вложения записан в staging, а фиксация перевода в queued обрывается отказом PostgreSQL
  • THEN ответ 503 unavailable, вложение в статусе «загружается» и по API не видно, а его объект в bucket остаётся: API его не удаляет
  • AND после grace уборщик убирает и метаданные, и объект, а в bucket нет объектов вложений без метаданных

Scenario: Брокер не подтвердил задание

  • WHEN брокер остановлен, и участник загружает настоящий PNG
  • THEN ответ 202, а не 503, вложение queued, у его задания нет времени подтверждения брокером, а объект — в staging
  • AND после запуска брокера вложение становится ready

Scenario: Обрыв передачи тела

  • WHEN клиент обрывает соединение посреди тела загрузки
  • THEN нового вложения нет ни в PostgreSQL, ни в bucket, а следующая загрузка того же участника — 202

Requirement: Недоступность S3

Если S3 недоступен, не ответил за срок вызова или отказал (object-storage), загрузка и скачивание байтов SHALL отвечать 503 unavailable в формате ошибки. Ответ SHALL приходить не позже срока вызова S3 с запасом, а не 500 и не зависанием. Без S3 SHALL работать:

  • метаданные вложения;
  • история чата с attachment_ids;
  • отправка сообщений, в том числе со ссылкой на готовое вложение;
  • /health/ready.

После возврата S3 загрузка и скачивание SHALL проходить без перезапуска API. Что делает при этом worker — attachment-processing, «Ограниченные повторы».

503 на загрузке и скачивании SHALL означать только такой отказ S3: недоступен, не ответил за срок или отказал. Доступный S3 MUST NOT давать 503 из-за того, что реплика какое-то время не обращалась к нему, в том числе после скачивания больших оригиналов.

Scenario: S3 остановлен

  • WHEN вложение стало ready, затем S3 остановлен, и участник скачивает байты, читает метаданные, отправляет сообщение с этим вложением и запрашивает /health/ready
  • THEN скачивание — 503 unavailable, метаданные — 200, сообщение — 201, готовность — 200
  • AND после возврата S3 скачивание — 200 с теми же байтами

Scenario: S3 завис

  • WHEN контейнер S3 заморожен (docker pause), и участник загружает файл и скачивает байты готового вложения
  • THEN оба ответа 503 unavailable не позже срока вызова S3 с запасом, а после разморозки скачивание — 200

Scenario: Загрузка после простоя S3

  • WHEN участники одновременно скачали оригинал в несколько MiB, затем реплика дольше срока вызова S3 не обращалась к S3, а S3 всё это время доступен, и участник одну за другой загружает файлы
  • THEN каждая загрузка — 202, ни одной 503
  • AND скачанные байты совпадают с загруженными

Requirement: Вложение доступно через любую реплику

Метаданные любого принятого вложения и байты готового SHALL читаться через любую реплику API за балансировщиком, в том числе после остановки реплики, которая его приняла. Метаданные, оригинал и варианты SHALL переживать перезапуск стенда (scripts/restart.sh, вместе с S3) с сохранёнными volumes и читаться прежним токеном.

Scenario: Скачивание через другую реплику

  • WHEN вложение загружено через балансировщик, ответ дала реплика с одним X-Instance-Id, и оно стало ready
  • THEN байты скачиваются через реплику с другим X-Instance-Id и совпадают с загруженными

Scenario: Принявшая реплика остановлена

  • WHEN вложение загружено через балансировщик, затем реплика с X-Instance-Id ответа на загрузку остановлена scripts/stop-one.sh
  • THEN метаданные — 200 от другой реплики, вложение становится ready, байты через балансировщик — 200, SHA-256 совпадает с загруженным, посторонний получает 404

Scenario: Рестарт стенда

  • WHEN вложение стало ready, затем выполнен scripts/restart.sh
  • THEN прежним токеном метаданные — 200, а байты совпадают с загруженными по SHA-256

Requirement: Одновременные загрузки реплики

Каждый процесс API SHALL обрабатывать одновременно не больше [uploads] max_concurrent загрузок (service-configuration, «Параметры загрузок»): у процесса столько мест загрузки. Загрузка занимает место после проверок 1–5 требования «Порядок проверок загрузки» и до чтения тела. Место SHALL освобождаться при любом исходе загрузки: 202, ошибка, обрыв клиента, истёкший срок, отмена запроса.

Загрузка, которой места нет, SHALL ждать его в очереди процесса по порядку прихода, но не дольше [uploads] wait_timeout_seconds. В очереди SHALL быть не больше [uploads] max_waiting загрузок. Если очередь полна, ответ SHALL отдаваться сразу. Если за срок ожидания место не освободилось, ответ SHALL отдаваться по его истечении. Ответ в обоих случаях — 429 rate_limited в формате ошибки с заголовком Retry-After — положительным целым числом секунд. Такая загрузка MUST NOT оставлять ни метаданных, ни объекта. Ожидающая загрузка MUST NOT держать соединение с PostgreSQL.

Места считает каждый процесс отдельно. Балансировщик ответ 429 на другой реплике не повторяет (load-balancing), загрузку повторяет клиент после Retry-After.

Память загрузок процесса SHALL ограничиваться числом мест, а не числом клиентов. Ожидающее или отклонённое соединение SHALL держать в памяти процесса и в буферах его сокетов не больше 1 MiB, каким бы ни было тело.

Scenario: Загрузки в пределах лимита

  • WHEN 10 участников одного чата одновременно загружают по настоящему PNG около 1 MiB, а параметры загрузок — по умолчанию
  • THEN все ответы 202 с разными id, и каждое вложение становится ready и скачивается с тем же SHA-256

Scenario: Все места заняты

  • WHEN все места загрузки процесса заняты загрузками, тела которых ещё идут, приходит ещё одна загрузка, и место за срок ожидания не освобождается
  • THEN ответ 429 rate_limited с Retry-After не меньше 1 приходит не раньше срока ожидания, а нового вложения нет ни в PostgreSQL, ни в bucket

Scenario: Очередь ожидания полна

  • WHEN все места загрузки процесса заняты, и очередь ожидания полна
  • THEN следующая загрузка сразу получает 429 rate_limited с Retry-After, без ожидания

Scenario: Ожидание места

  • WHEN место занято загрузкой, которая заканчивается раньше срока ожидания, а следующая загрузка ждёт его в очереди
  • THEN ожидавшая загрузка получает 202, и её вложение становится ready и скачивается с тем же SHA-256

Scenario: Место освобождается

  • WHEN загрузка на единственном месте процесса заканчивается 413 по счётчику, 415 по содержимому, 400 по сроку тела, обрывом клиента или 503 при остановленном S3
  • THEN после каждой такой загрузки следующая получает место сразу: ответ 202 без ожидания (после 503 — когда S3 вернулся)

Scenario: Память не растёт с числом загрузок

  • WHEN 10, 20 и 40 клиентов одновременно и без пауз загружают по 10 MiB в одну реплику с параметрами по умолчанию (профиль загрузок стенда bench/, вариант «с лимитом»)
  • THEN пик памяти реплики в каждом случае не больше половины лимита контейнера, при 20 и 40 клиентах он выше, чем при 10, не больше чем на 1 MiB на каждого клиента сверх 10, реплика не завершена из-за памяти, лишние загрузки получают 429, а ответов 5xx нет

Requirement: Срок передачи тела

Тело загрузки SHALL приходить целиком не позже [uploads] body_timeout_seconds после того, как загрузка заняла место. Иначе ответ SHALL быть 400 invalid_request в формате ошибки. Загрузка при этом MUST NOT оставлять ни метаданных, ни объекта, и её место освобождается. Тело, которое пришло в срок, SHALL приниматься, как бы мелко его ни делил клиент и какие бы паузы ни делал.

Scenario: Медленный клиент

  • WHEN участник шлёт настоящий PNG частями так, что тело идёт дольше срока передачи
  • THEN ответ 400 invalid_request, нового вложения нет ни в PostgreSQL, ни в bucket, а следующая загрузка — 202 без ожидания места

Scenario: Медленная передача в срок

  • WHEN участник шлёт настоящий PNG мелкими частями с паузами и укладывается в срок передачи
  • THEN ответ 202, а size_bytes и sha256 совпадают с файлом

Requirement: Скачивание варианта

GET /api/v1/attachments/{attachment_id}/content?variant=<имя> у готового вложения SHALL отвечать 200 с байтами варианта thumbnail, crop или optimized через API, без перенаправления. Заголовки ответа: Content-Type — content_type варианта, Content-Length — его размер, X-Content-Type-Options: nosniff. Размер и SHA-256 байтов равны полям варианта в метаданных. Доступ — как у оригинала (требование «Доступ к вложению»).

Вариант, которого у готового вложения нет, SHALL давать 404 not_found. Это вложения, ставшие готовыми раньше: до обработки вариантов — любой вариант, на уровне 3 — crop и optimized. Нет объекта варианта в S3 или размер другой — 500 internal_error без деталей, причина в журнале.

Scenario: Скачивание thumbnail

  • WHEN Боб скачивает variant=thumbnail готового вложения, загруженного Алисой
  • THEN ответ 200, не перенаправление, Content-Type: image/jpeg, Content-Length равен size_bytes варианта, есть X-Content-Type-Options: nosniff, а SHA-256 равен sha256 варианта

Scenario: Скачивание crop и optimized

  • WHEN Боб скачивает variant=crop и variant=optimized готового вложения, загруженного Алисой
  • THEN оба ответа 200, не перенаправление, Content-Type — image/jpeg и image/webp, Content-Length равен size_bytes варианта, есть X-Content-Type-Options: nosniff, а SHA-256 равен sha256 варианта

Scenario: Отсутствующий вариант

  • WHEN у готового вложения нет метаданных варианта crop, потому что оно стало готовым раньше этого уровня, и участник скачивает variant=crop
  • THEN ответ 404 not_found в формате ошибки, а остальные варианты скачиваются

Scenario: Вариант для постороннего

  • WHEN Ева скачивает variant=thumbnail вложения чата Алисы и Боба
  • THEN ответ 404 not_found с тем же message, что у неизвестного id