Files
mtusi2026lab5/openspec/specs/lab4-attachments/spec.md
T

17 KiB
Raw Blame History

lab4-attachments Specification

Purpose

Определяет вложения-изображения чата: синхронную загрузку оригинала PNG/JPEG с лимитами и проверкой содержимого, метаданные, скачивание оригинала через API, доступ только участникам чата, порядок записи PostgreSQL ↔ S3 и поведение при недоступном S3.

Requirements

Requirement: Загрузка оригинала в чат

Сервис SHALL принимать POST /api/v1/chats/{chat_id}/attachments?filename=<имя> от участника чата с телом из сырых байтов одного изображения (не multipart, не JSON) и заголовком Content-Type: image/png или image/jpeg и возвращать 202 с объектом Attachment — снимком в момент приёма: status ровно queued, variants [], error_code null, chat_id из пути, owner_id вызывающего, size_bytes равен длине тела, sha256 — lowercase hex SHA-256 тела, content_type — тип, определённый по содержимому, filename — переданное имя. Ответ 202 SHALL выдаваться только после того, как полный проверенный оригинал записан в приватный staging-префикс bucket, а вложение и задание его обработки зафиксированы в PostgreSQL; снимок SHALL NOT перечитываться после фиксации, даже если worker уже взял задание. API SHALL NOT обрабатывать изображение (строить варианты) в запросе. Ключ объекта SHALL назначаться сервером и SHALL NOT зависеть от filename и попадать в ответ. Повтор того же запроса SHALL создавать новое вложение.

Scenario: Fixture загружена

  • WHEN участник загружает tests/fixtures/sample.png с Content-Type: image/png и ?filename=sample.png
  • THEN ответ 202, тело соответствует схеме Attachment, status queued, variants [], error_code null, size_bytes 111817, sha256 равен SHA-256 файла, chat_id и owner_id — чат и загрузивший

Scenario: JPEG загружен

  • WHEN участник загружает корректный JPEG с Content-Type: image/jpeg
  • THEN ответ 202, content_type image/jpeg

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

  • WHEN worker остановлен, а участник загружает файл
  • THEN ответ 202 приходит за время, не зависящее от размера изображения в пикселях, вложение остаётся queued

Scenario: Посторонний загружает в чужой чат

  • WHEN пользователь, не входящий в чат, или любой пользователь в несуществующий чат отправляет корректное изображение
  • THEN ответ 404 с кодом not_found, ничего не сохраняется

Scenario: Доступ проверяется раньше содержимого

  • WHEN посторонний отправляет в чужой чат тело, не являющееся изображением, или опасный filename
  • THEN ответ 404, а не 400 или 415

Scenario: Без аутентификации

  • WHEN upload приходит без Authorization или с Basic
  • THEN ответ 401 с WWW-Authenticate: Bearer realm="messenger"

Requirement: Лимиты размера до неограниченного чтения и декодирования

Тело SHALL быть не больше MAX_UPLOAD_BYTES (10 485 760) байт, а изображение — не больше MAX_IMAGE_PIXELS (40 000 000) пикселей по заголовку. Превышение SHALL давать 413 с кодом payload_too_large. Объявленный Content-Length больше лимита SHALL отклоняться без чтения тела, тело без Content-Length SHALL читаться не дальше лимита плюс один байт, а число пикселей SHALL проверяться по заголовку изображения до декодирования. Реплика SHALL NOT записывать тело на свой диск.

Scenario: Ровно 10 MiB

  • WHEN загружается корректный PNG размером ровно 10 485 760 байт
  • THEN ответ 201 и size_bytes 10485760

Scenario: На байт больше с Content-Length

  • WHEN загружается тело размером 10 485 761 байт с заголовком Content-Length
  • THEN ответ 413 с кодом payload_too_large

Scenario: На байт больше без Content-Length

  • WHEN тело размером 10 485 761 байт передаётся chunked, без Content-Length
  • THEN ответ 413 с кодом payload_too_large, вложение не создаётся

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

  • WHEN загружается корректный PNG 8000×5000
  • THEN ответ 201

Scenario: Больше 40 млн пикселей

  • WHEN загружается PNG 8001×5000 или сжатый PNG огромных размеров весом несколько килобайт
  • THEN ответ 413 с кодом payload_too_large, изображение не декодируется

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

Сервис SHALL принимать только Content-Type image/png и image/jpeg (параметры заголовка и регистр не важны) и SHALL проверять, что сигнатура и структура файла соответствуют заявленному типу, а файл читается без ошибок. Иной или отсутствующий Content-Type, несовпадение заявленного типа и содержимого, пустое тело, обрезанный или повреждённый файл, GIF, WebP и текст SHALL давать 415 с кодом unsupported_media_type.

Scenario: Подмена MIME

  • WHEN JPEG, GIF или текст отправлены с Content-Type: image/png
  • THEN ответ 415 с кодом unsupported_media_type

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

  • WHEN отправлена первая половина корректного PNG или JPEG с верным Content-Type
  • THEN ответ 415

Scenario: Неподдерживаемый Content-Type

  • WHEN корректный PNG отправлен с Content-Type: application/octet-stream или без Content-Type
  • THEN ответ 415

Scenario: Повреждённый поток пикселей при корректных CRC

  • WHEN участник отправляет PNG с корректными CRC и IEND, но ошибочным zlib-потоком IDAT, его контрольной суммой, числом байтов строк или кодом фильтра
  • THEN POST /api/v1/chats/{chat_id}/attachments отвечает 415 с кодом unsupported_media_type, X-Request-Id и X-Instance-Id; строка вложения и объект не создаются

Scenario: Корректные варианты PNG

  • WHEN участник загружает корректный PNG в пределах лимитов, в том числе Adam7, с разрешёнными глубиной цвета и фильтрами, а IDAT разделён на несколько чанков
  • THEN ответ 202 queued; после обработки worker вложение становится ready, скачивание другим участником возвращает исходные байты

Scenario: Неоднозначный заголовок PNG

  • WHEN участник отправляет PNG с повторным IHDR до IEND, даже при одинаковых размерах и корректных CRC, или с IHDR не первым чанком
  • THEN POST /api/v1/chats/{chat_id}/attachments отвечает 415 с кодом unsupported_media_type, X-Request-Id и X-Instance-Id; строка вложения и объект не создаются

Requirement: Безопасное отображаемое имя

filename SHALL быть обязательным параметром длиной 1–255 Unicode code points после percent-декодирования, SHALL NOT состоять только из пробельных символов и SHALL NOT содержать /, \, NUL и другие управляющие символы. Нарушение SHALL давать 400 с кодом invalid_request. Имя SHALL использоваться только для отображения и возвращаться без изменений.

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

  • WHEN filename равен ../a.png, a/b.png, a\b.png, содержит %00, %01 или %7F
  • THEN ответ 400 с кодом invalid_request

Scenario: Пустое, пробельное, длинное или отсутствующее имя

  • WHEN filename пустой, из пробелов, длиной 256 code points или не передан
  • THEN ответ 400

Scenario: Имя на кириллице

  • WHEN filename равен фото 1.png длиной до 255 code points
  • THEN ответ 201 и filename в ответе совпадает с переданным

Requirement: Метаданные и скачивание только участникам

GET /api/v1/attachments/{attachment_id} SHALL возвращать 200 Attachment с текущим состоянием любому участнику чата вложения. GET /api/v1/attachments/{attachment_id}/content SHALL возвращать участнику 200 с байтами, истинным Content-Type и Content-Length, через API, без redirect, вне зависимости от заголовка Accept: для variant=original (по умолчанию) — исходные байты оригинала, для variant=thumbnail, crop и optimized — байты варианта опубликованной версии, описанного в метаданных. Для вложения в queued, processing или failed /content SHALL отвечать 409 с кодом conflict для любого допустимого variant, включая original. Для ready-вложения, у опубликованной версии которого нет запрошенного варианта (вложение, готовое до лабы 5), SHALL отвечать 404. Посторонний и неизвестный id SHALL получать 404 с кодом not_found, не раскрывающим существование вложения; невалидный UUID и variant вне original|thumbnail|crop|optimized — 400. Все ответы, включая бинарный 200, SHALL нести X-Request-Id и X-Instance-Id.

Scenario: Второй участник скачивает оригинал

  • WHEN второй участник чата запрашивает /content готового вложения с Accept: application/json
  • THEN ответ 200, Content-Type: image/png, байты совпадают с загруженными, SHA-256 равен sha256 метаданных

Scenario: Второй участник скачивает thumbnail

  • WHEN второй участник чата запрашивает /content?variant=thumbnail готового вложения
  • THEN ответ 200, Content-Type: image/jpeg, длина и SHA-256 равны метаданным варианта

Scenario: Crop и optimized

  • WHEN второй участник запрашивает /content?variant=crop и /content?variant=optimized готового вложения
  • THEN ответы 200 с Content-Type: image/jpeg и image/webp, длина и SHA-256 равны метаданным вариантов

Scenario: Вложение ещё не готово

  • WHEN участник запрашивает /content или /content?variant=thumbnail вложения в queued или processing
  • THEN ответ 409 с кодом conflict

Scenario: Вложение в failed

  • WHEN участник запрашивает /content?variant=original вложения в failed
  • THEN ответ 409 с кодом conflict, метаданные показывают failed и error_code

Scenario: Посторонний

  • WHEN пользователь вне чата запрашивает метаданные или /content
  • THEN оба ответа 404 с кодом not_found

Scenario: Варианта нет

  • WHEN запрошен /content?variant=crop вложения, ставшего ready в лабе 4 без вариантов
  • THEN ответ 404 с кодом not_found

Scenario: Неизвестный вариант

  • WHEN запрошен /content?variant=preview
  • THEN ответ 400 с кодом invalid_request

Scenario: Объект пропал из хранилища

  • WHEN метаданные готового вложения есть, а объекта в bucket нет
  • THEN /content отвечает 404, событие пишется в журнал без ключа объекта

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

Сервис SHALL фиксировать намерение (метаданные со статусом, невидимым клиентам) до записи оригинала в staging и SHALL переводить вложение в queued вместе с записью задания только после подтверждённой записи объекта. Сбой на любом шаге SHALL NOT давать 202 и SHALL NOT оставлять видимого клиентам вложения без объекта. Обрыв клиента до конца тела SHALL NOT оставлять ни объекта, ни строки. Намерение и объект, оставшиеся после сбоя, SHALL удаляться компенсацией сразу или уборкой по истечении grace period (capability lab4-upload-resilience), поэтому объект без строки-намерения в bucket не остаётся.

Scenario: S3 отказал при записи

  • WHEN запись объекта в staging завершилась ошибкой
  • THEN ответ 503 с кодом unavailable, вложение не видно ни в метаданных, ни в сообщениях, задания нет, а строка-намерение удаляется уборкой после grace period

Scenario: Клиент оборвал загрузку

  • WHEN клиент закрыл соединение, отправив часть тела
  • THEN в bucket нет нового объекта и в PostgreSQL нет новой строки вложения

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

Недоступность S3 SHALL превращаться в 503 unavailable в общем формате ошибки за ограниченное время (меньше REQUEST_TIMEOUT_SECONDS) для upload и скачивания. Метаданные, тексты сообщений и GET /health/ready SHALL продолжать работать: готовность реплики от S3 не зависит. После возврата S3 ранее загруженные файлы SHALL скачиваться без изменений.

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

  • WHEN выполняется docker compose stop s3 и клиент загружает и скачивает файл, отправляет текст и проверяет готовность
  • THEN upload и /content отвечают 503 с X-Request-Id и X-Instance-Id быстрее REQUEST_TIMEOUT_SECONDS, текстовое сообщение — 201, метаданные и /health/ready — 200

Scenario: S3 вернулся

  • WHEN S3 снова запущен
  • THEN ранее загруженный файл скачивается с тем же SHA-256