Files
mtusi2026lab2/openspec/specs/lab4-attachments/spec.md
T
ArtyomandClaude Opus 5.5 adca7c6edc Archive the attachment boundaries change
Upload checks the token before the declared size, a slow but steady
transfer outlives the request timeout while a stalled one is still cut,
the API and the reconciler hold separate minimal S3 keys, and the
one-off services run as non-root with an init process. On the stand a
3 MiB upload at 256 KiB/s took 12.1 s at the replica and got 201, a
3 MiB download at 192 KiB/s took 12.8 s and matched the SHA-256, the
API key is denied a bucket listing, and docker stop ends a hanging
reconciler pass in 0.13 s with exit code 143. student-test (345),
test-faults (19), persistence, failover and the lab 4 scenarios pass.
The requirements are synced into lab4-attachments, lab4-upload-resilience
and lab4-object-storage.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V1d3RLHNBBMA6UqBLLJv27
2026-10-30 08:53:53 +03:00

14 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 и возвращать 201 с объектом Attachment: status ready, variants [], error_code null, chat_id из пути, owner_id вызывающего, size_bytes равен длине тела, sha256 — lowercase hex SHA-256 тела, content_type — тип, определённый по содержимому, filename — переданное имя. Ответ 201 SHALL выдаваться только после того, как оригинал записан в приватный bucket и метаданные зафиксированы в PostgreSQL. Ключ объекта SHALL назначаться сервером и SHALL NOT зависеть от filename и попадать в ответ. Повтор того же запроса SHALL создавать новое вложение.

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

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

Scenario: JPEG загружен

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

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

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

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

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

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

  • WHEN upload приходит без Authorization или с Basic, в том числе с объявленным Content-Length больше MAX_UPLOAD_BYTES
  • THEN ответ 401 с WWW-Authenticate: Bearer realm="messenger", а не 413: аутентификация проверяется раньше любых проверок запроса

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

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 SHALL принимать только original (по умолчанию). Посторонний, неизвестный id и ещё не готовое вложение SHALL получать 404 с кодом not_found, не раскрывающим существование вложения; невалидный UUID и неизвестный variant — 400. Вложение, помещённое сверкой в карантин (capability lab4-storage-reconciler), SHALL отдавать метаданные как прежде, а /content SHALL отвечать 404 без обращения к S3, чтобы клиент не получил байты, расходящиеся с sha256 метаданных. Все ответы, включая бинарный 200, SHALL нести X-Request-Id и X-Instance-Id.

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

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

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

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

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

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

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

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

Scenario: Вложение в карантине

  • WHEN сверка поместила вложение в карантин из-за расхождения байтов с метаданными
  • THEN метаданные отвечают 200 с прежними полями, /content — 404 с кодом not_found

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

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

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

  • WHEN запись объекта завершилась ошибкой
  • 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