# 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` — change `upload-consistency`. - Ключ объекта назначает сервер: `<имя базы>/attachments//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`.