- upload, metadata and download endpoints for PNG/JPEG attachments:
limits before reading and decompression, type by content,
structural integrity check without decoding pixels, safe filename
- write order: pending row with object key -> PUT to S3 -> ready;
per-step DB sessions so no pool connection is held during transfers
- attachment_ids in messages (validation, idempotency hash, history);
whitespace-only text allowed with an attachment (teacher, 2026-10-20)
- migration: attachments and message_attachments tables, text length
CHECK relaxed with NOT VALID
- student tests, fault checks and driver commands for attachments;
rollout profile starts from e1161f7 and checks the commit first
- sync attachments deltas into main specs; rules, AGENTS.md, PLAN.md
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
26 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 быть 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,
statusready,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 ответ 201,
content_typeimage/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-Length31 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-Typeapplication/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 храниться и возвращаться без изменений, без обрезки и нормализации. Имя только отображается: оно MUST NOT участвовать в ключе объекта и в пути на диске. Как безопасно показать имя, решает клиент.
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 определяться первой из них по порядку:
- 401 — нет действительной сессии;
- 400 — неверный
chat_idилиfilename; - 404 — чата нет или пользователь в нём не состоит;
- 415 —
Content-Typeзапроса; - 413 —
Content-Lengthзапроса; - 413 — число прочитанных байтов;
- 415 или 413 — содержимое: формат и целостность или число пикселей.
Тело MUST NOT читаться, пока не пройдены проверки 1–5. Ошибка клиента 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
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_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, равным ответу на загрузку этого вложения.
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 выполняться по шагам:
- проверки и чтение тела;
- запись метаданных в статусе «загружается» (
pending) вместе с ключом объекта, фиксация в PostgreSQL; - запись объекта в S3;
- статус
ready, фиксация; - ответ 201.
Объект, который записал API, SHALL быть известен PostgreSQL до записи в
S3. Вложение не в статусе ready MUST NOT быть видно через API: его
метаданные и байты — 404, ссылка на него в сообщении — 404. Если не
удались запись в S3 или фиксация ready, ответ SHALL быть 503
unavailable, строка «загружается» остаётся. Её и объект убирает
уборщик (change upload-consistency). Загрузка, отклонённая до шага 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 не изменились
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