Files
mtusi2026lab4/openspec/changes/attachments/proposal.md
T
2026-10-20 23:44:50 +03:00

141 lines
9.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/<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`.