Grade 3 of lab 4 is closed. RustFS with a private bucket runs in the stand, metadata lives in PostgreSQL and the bytes only in the bucket, uploads answer 201 ready after the object write and the commit, and the original is served byte for byte to chat members only. The smoke test passes from a fresh clone; limits of 10 MiB and 40 MP, content type by content and dangerous names are covered by 325 own tests; an upload survives the stop of the replica that took it, both replicas fail over under writes in under 3.1 s, a full restart keeps metadata and bytes, and with S3 stopped uploads and downloads answer 503 within 2.6 s while texts, metadata and readiness keep working. 22 checks show the bucket is private outside the API and the API key is limited. For the defence: upload the fixture, send it in a message, download it as the second member and compare SHA-256, get 404 as a stranger and 403 for an anonymous GET in S3, then run persistence, failover and the upload failover scenario. The lab4-attachments and lab4-object-storage specs are added, and message sending, history, idempotent replay, the restart hook and stand persistence are updated in the main specs. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
12 KiB
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,statusready,size_bytes111817,sha256равен SHA-256 файла,chat_idиowner_id— чат и загрузивший
Scenario: JPEG загружен
- WHEN участник загружает корректный JPEG с
Content-Type: image/jpeg - THEN ответ
201,content_typeimage/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_bytes10485760
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 оставлять ни объекта, ни строки.
Scenario: S3 отказал при записи
- WHEN запись объекта завершилась ошибкой
- THEN ответ
503с кодомunavailable, вложение не видно ни в метаданных, ни в сообщениях
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