9.8 KiB
Proposal
Why
Рубрика «3» лабы 4 почти целиком про вложения (README.md): метаданные
в PostgreSQL, байты в приватном bucket, 201 ready после сохранения,
побайтный download только участникам, attachment_ids в сообщении,
реальные PNG/JPEG с лимитами до чтения и распаковки, файл переживает
остановку принявшей его реплики и рестарт стенда. Рубрика «4» требует
негативных тестов: большой файл, повреждённое изображение, подмена MIME,
чужое attachment_id, вложение другого чата, ни одной пользовательской
ошибки в 500. Хранилище и клиент S3 готовы (change s3-storage), а
домена вложений нет.
Без него красные публичные make test, make test-persistence и
make test-failover (с LAB=4 они загружают файл) и 32 теста make student_test (контракт лабы 4 требует attachment_ids в Message). Сверка
покрытия красная, пока четыре файла исключений не сняты на стенде лабы 4.
What Changes
- Домен
attachmentво всех слоях и три ручки контракта:POST /api/v1/chats/{chat_id}/attachments?filename=…— сырые байты PNG/JPEG,201 Attachmentсоstatus=ready;GET /api/v1/attachments/{id}— метаданные;GET /api/v1/attachments/{id}/content— оригинал потоком из S3, с истиннымContent-Type, без redirect.
- Проверки загрузки до чтения и распаковки:
Content-Lengthбольше 10 MiB — 413 до чтения тела, без него — счётчик байтов при чтении;- тип — по сигнатуре содержимого, расхождение с
Content-Type— 415; - число пикселей — из заголовка изображения до распаковки, больше 40 млн — 413;
- целостность — структурная проверка без декодирования пикселей. Память проверки не зависит от числа пикселей, «бомба» отсекается по заявленному размеру;
- опасный
filename— 400.
- Порядок записи: проверка → строка
pendingс ключом объекта (commit) → PUT в S3 → строкаready(commit) → 201. Объект, записанный API, известен БД до записи. Компенсация и уборщик зависшихpending— changeupload-consistency. - Ключ объекта назначает сервер:
<имя базы>/attachments/<id>/original.filenameтолько отображается и ни в ключ, ни в путь не попадает. - Загрузка и скачивание не держат соединение пула PostgreSQL на время передачи тела. Короткие транзакции открываются только на шаги с БД.
- Сообщение принимает
attachment_ids(0–10 уникальных). Каждое вложение должно быть готовым вложением этого чата, иначе 404.text=""допустим только с вложением. Сообщение, история и повтор по ключу отдаютattachment_idsв исходном порядке. - Хэш тела для идемпотентности учитывает
attachment_ids, пустой список его не меняет (PLAN.md, решение 6). - Миграция только расширяет схему: таблицы
attachmentsиmessage_attachments, ограничение длины текста сообщения ослаблено до 0–4000. - Отказ S3 — 503 только на путях вложений. Метаданные, текстовые
сообщения и
/health/readyработают. student-tests/test_attachments.py: рубрика «4» и все сценарии нового спека. Новые проверки отказов: S3 остановлен и заморожен при загрузке и скачивании.- Драйвер скилла
run-mtusi-messenger:upload,downloadс SHA-256 и сценарийattachment-failover— остановить реплику, принявшую файл, и скачать его через другую.flowзагружает и скачивает вложение. - Профиль
rolloutстендаbench/стартует с commit лабы 4 до этого change (e1161f7), а не с commit лабы 3 (KNOWN_ISSUES.md). Правило выбора commit — вbench.md. Evidence замены — со старого образа на схему с вложениями. - Evidence:
evidence/attachments/; четыре файла исключений сверки переснимаются на стенде лабы 4;evidence/tests/— зелёные прогоны.
Не входит:
- компенсация, уборщик и тесты отказов посреди загрузки —
upload-consistency; - лимит одновременных загрузок, сроки чтения тела и профиль
uploads—upload-memory; - reconciler — трек 2;
- presigned upload, lab5 (202, превью).
Capabilities
New Capabilities
attachments: вложения-изображения — загрузка с лимитами до чтения и распаковки, тип по содержимому, целостность,filename, доступ только участникам, метаданные, побайтный download, где лежат байты и метаданные, порядок записи, отказ S3, доступность через любую реплику и после рестарта.
Modified Capabilities
api-conventions: пары 413 —payload_too_largeи 415 —unsupported_media_type; строгий UUID на входе и дляattachment_idв пути иattachment_idsв теле.messages:attachment_idsв отправке, ответе и истории; пустой текст с вложением; проверка вложений сообщения.idempotency: тело включаетattachment_ids. Отсутствующее поле равно[], порядок значим, повтор отдаёт те же вложения.data-storage: метаданные вложений и связи с сообщениями — в PostgreSQL, байты — не в БД; целостность связей в БД; вложения переживают рестарт.db-migrations: ослабление ограничения — допустимое расширение схемы, без скана таблицы под эксклюзивной блокировкой.service-logging: имя файла и байты вложений не пишутся в журнал.service-configuration: лимиты вложений — константы контракта, а не настройки; соответствиеMAX_UPLOAD_BYTESиMAX_IMAGE_PIXELS— вREPORT.md.student-tests: сверка покрытия включаетattachments; тесты рубрики «4» лабы 4; проверки отказов S3 на путях вложений.load-benchmark: прежний commit профиля замены — commit текущей лабы, без него отказ до стенда.
Impact
- Код:
src/api/routers/v1/attachment.py,src/api/schemas/attachment.py;message.pyв API, сервисе, repo и DTO;dependencies.py— сессия БД на шаг и вход без удержания сессии;errors.py— 413 и 415;src/core/services/attachment.py,src/core/repos/attachment.py,attachment_object.py(ключ и объект в S3),src/core/exceptions/attachment.py;src/schemas/— DTO и enum вложений;src/utils/image.py— структурная проверка PNG/JPEG (только stdlib);src/utils/constants.py— лимиты контракта;- модели
src/infra/db/models/attachment.py, ревизия alembic.
- Зависимости:
pillowтолько в dev-группе — генерация JPEG в тестах. В образ и в приложение не входит. - Тесты:
student-tests/test_attachments.py,test_failures.py,api_client.py,contract.py,spec_coverage.py,fault_hook.py. - Стенды:
bench/run.py(rollout_from);- регресс
make bench_quick(запрос истории изменился) и быстрых профилейfailover,rollout,restore.
- Документы:
- правила
api-contract.md,api-layer.md,service-layer.md,repo-layer.md,dto.md,migrations.md,logging.md,student-tests.md,bench.md,settings.md; AGENTS.mdи скиллrun-mtusi-messenger;REPORT.md— вложения, порядок записи, ответы на вопросы защиты, соответствиеMAX_UPLOAD_BYTESиMAX_IMAGE_PIXELS;KNOWN_ISSUES.md— запись оrollout_fromзакрывается;PLAN.md.
- правила