Files
mtusi2026labs/openspec/specs/lab4-attachments/spec.md
T
ArtyomandClaude Opus 5.5 d2744bc1ac Archive the upload resilience change
Grade 4 of lab 4 is closed. A failed ready commit after the object
write is compensated at once under a row lock, intents abandoned by a
crash or a lost write are swept with their objects after a 900 s grace
period by every replica with SKIP LOCKED, and nothing younger, nothing
ready and nothing referenced is touched. A client abort is a 400 and a
stalled body a 503 after 8 s, both leaving nothing behind. Three upload
slots per worker, capped socket buffers in the balancer and the API
and a fixed glibc mmap threshold keep 40 concurrent 10 MiB uploads at
330 of 512 MiB per replica with every upload succeeding, while without
the slots the same load hits the limit and loses 37 of 80. 36 user
errors through the balancer give no 5xx, and 23 checks prove the
bucket private, the API key limited, the console closed and the
bootstrap idempotent.

For the defence: run make upload-faults to show the negative suite,
the compensation, the killed replica with its leftover swept after the
grace period while the fresh one stays, and the abort and stall; show
the memory summary and make s3-check.

The lab4-upload-resilience spec is added, and the write order of
lab4-attachments and the console and API key requirements of
lab4-object-storage are updated in the main specs.

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

13 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
  • 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

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. Все ответы, включая бинарный 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, событие пишется в журнал без ключа объекта

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