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
14 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, в том числе с объявленным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_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. Вложение, помещённое сверкой в карантин (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