Files
mtusi2026lab4/openspec/specs/attachments/spec.md
T
ricoromaandClaude Opus 5.5 87c48b940b fix: address upload-consistency verify findings
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>
2026-10-21 21:27:47 +03:00

31 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 быть 201 с объектом Attachment без других полей:

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

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

Scenario: Загрузка PNG

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

Scenario: Загрузка JPEG

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Scenario: Подмена MIME

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

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

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

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

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

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

Байты после IEND или EOI повреждением не считаются: они входят в оригинал, в его размер и SHA-256. Искажения внутри сжатых данных скана JPEG, которые не нарушают структуру, сервис не обнаруживает: у формата нет контрольной суммы.

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

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

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

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

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

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

Requirement: Имя файла

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

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

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

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

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

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

Scenario: Имя не в UTF-8

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

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

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

Scenario: Имя в Unicode

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

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

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

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

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

  1. 401 — нет действительной сессии;
  2. 400 — неверный chat_id или filename;
  3. 404 — чата нет или пользователь в нём не состоит;
  4. 415 — Content-Type запроса;
  5. 413 — Content-Length запроса;
  6. 413 — число прочитанных байтов;
  7. 415 или 413 — содержимое: формат и целостность или число пикселей.

Тело MUST NOT читаться, пока не пройдены проверки 1–5. Ошибка клиента MUST NOT давать 500.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

GET /api/v1/attachments/{attachment_id} SHALL отвечать 200 с объектом Attachment, равным ответу на загрузку этого вложения.

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

  • WHEN Алиса загрузила вложение, а Боб запрашивает его метаданные
  • THEN ответ 200, JSON совпадает с ответом на загрузку во всех полях

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

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

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

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

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

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

Scenario: Вариант original

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

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

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

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

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

Scenario: Байты не в БД и не на диске API

  • WHEN после загрузок через балансировщик проверяющий смотрит схему таблиц вложений, ключи объектов в PostgreSQL, объекты в bucket и изменения файловой системы контейнеров реплик API
  • THEN в таблицах нет колонки с байтами изображения, ключ каждого объекта имеет вид <база>/attachments/<id>/original и не содержит filename, объект с этим ключом есть в bucket, анонимный GET его ключа — 403, а в контейнерах реплик нет файлов оригиналов

Scenario: Повторная загрузка

  • WHEN участник дважды загружает один и тот же файл
  • THEN оба ответа 201 с разными id и одинаковым sha256, и оба вложения скачиваются

Requirement: Порядок записи

Загрузка SHALL выполняться по шагам:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

После возврата S3 загрузка и скачивание SHALL проходить без перезапуска API.

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

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

Scenario: S3 завис

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

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

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

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

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

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

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

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

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