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>
31 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 быть корректным 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 определяться первой из них по порядку:
- 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.
Сбой после шага 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